Skip to content

Quickstart

This page walks through a first JURASSIC run using the example projects included with the repository. The examples generate an atmosphere, create an observation geometry, run the forward model, compute finite difference Jacobians, and compare the simulated radiances with reference output.

For build instructions, see Installation. For a systematic description of command-line usage, see Running JURASSIC.

Prerequisites

Start from a compiled source tree. From the repository root, the main executables should be available in src/, for example:

ls src/formod src/kernel

The example scripts set the local library path for the bundled dependencies. If you installed libraries elsewhere, make sure your runtime environment can find GSL, netCDF, HDF5, and any other libraries used by your build.

gnuplot is optional for the model calculation itself, but the example scripts use it to generate diagnostic PNG plots.

Run an Example

The quickest end-to-end test is one of the example projects under projects/. Start from the repository root, then enter the project directory before running its script so the relative paths inside the script resolve correctly.

cd projects/nadir
./run.sh

A successful run ends with a comparison of the newly generated rad.tab file against the checked-in reference rad.org. If the files match, the script exits with status zero.

To run the other geometries, use the same pattern:

cd ../limb
./run.sh

cd ../zenith
./run.sh

What the Script Does

Each example script performs the same basic workflow:

  1. Generate an atmospheric state with climatology.
  2. Generate an observation geometry with limb, nadir, or zenith.
  3. Run the forward model with formod.
  4. Compute Jacobians with kernel.
  5. Compare rad.tab against the reference file rad.org.
  6. Generate diagnostic plots if gnuplot is available.

For the nadir example, the core commands are:

../../src/climatology nadir.ctl atm.tab
../../src/nadir nadir.ctl obs.tab
../../src/formod nadir.ctl obs.tab atm.tab rad.tab TASK time
../../src/kernel nadir.ctl obs.tab atm.tab kernel.tab

The limb and zenith examples use the same structure with limb.ctl or zenith.ctl and the corresponding geometry generator.

Example Output

The example projects generate radiance and transmittance plots for each viewing geometry:

Limb radiance example   Nadir radiance example   Zenith radiance example

They also generate finite difference Jacobian plots, such as these temperature kernels:

Limb temperature kernel example   Nadir temperature kernel example   Zenith temperature kernel example

Important Files

After an example has run, the project directory contains:

File Purpose
*.ctl Control file defining channels, lookup tables, emitters, geometry settings, and output options
atm.tab Atmospheric state used by the forward model
obs.tab Observation geometry and line-of-sight information
rad.tab Simulated radiances and transmittances
rad.org Reference radiance output used for comparison
kernel.tab Finite difference Jacobians computed by kernel
plot_*.png Diagnostic plots generated by gnuplot

Inspect the text files directly to see the column headers:

head -40 atm.tab
head -40 obs.tab
head -40 rad.tab
head -40 kernel.tab

The file formats are described in Atmospheric data, Radiance data, and Diagnostics & logs.

Verify the Full Test Suite

The example projects are useful as a first run. For a broader regression check, use the test suite from src/:

cd src
make check

This runs the tests under tests/, including tool, table, forward-model, and retrieval checks.

Troubleshooting

Missing shared libraries

If an executable fails to start because a shared library cannot be found, check LD_LIBRARY_PATH. The example scripts expect bundled libraries under libs/build/lib.

Missing lookup tables

Errors about lookup-table files usually mean that TBLBASE, TBLFMT, ND, NU[i], or EMITTER[i] in the control file do not match the available table files. Start from one of the example control files and modify it incrementally.

Plotting

If gnuplot is not installed, the radiative-transfer commands can still be run manually, but the example scripts will not create the diagnostic PNG files.

Next Steps

After the first examples, continue with: