Repository

TARSA

TARSA is a Julia finite-volume transport model for aerosol and trace-gas forward simulations driven by prescribed meteorology. It is designed to be simple to run from code, transparent in its numerics, and directly usable for real-meteorology regional transport cases.

Quickstart

If you only want to install TARSA as a Julia package:

curl -fsSL https://install.julialang.org | sh
julia -e 'using Pkg; Pkg.add(url="https://code.grasp-open.com/grasp-models/tarsa.git")'

If 40 lines enough to run your custon simulations:

using TARSA

# Minimal TARSA quickstart:
# - uses a small ERA5 domain around Etna for 2024-04-01 to 2024-04-02,
# - reuses cached files from examples/tutorial/data or downloads them from Copernicus CDS,
# - injects a simple point source near Etna,
# - runs the explicit transport solver,
# - saves the result to examples/tutorial/out/quickstart_etna.nc.
# Optional: set Copernicus CDS credentials here instead of ~/.cdsapirc
# ENV["CDSAPI_URL"] = "https://cds.climate.copernicus.eu/api"
# ENV["CDSAPI_KEY"] = "<uid>:<api-token>"


levels_file, surface_file, _, _ = TARSA.prepare_input_data(
    34.0, 40.0,  # lat_min, lat_max
    12.0, 18.0,  # lon_min, lon_max
    2024,        # year
    4,           # month
    [1, 2];      # days
    download_cams=false,
    data_dir=joinpath(@__DIR__, "data"),
)
input = TARSA.load_input_data(levels_file, surface_file)
emissions = TARSA.zero_emissions(input)
TARSA.add_point_source!(
    emissions,
    input,
    15.0,   # source_lon
    37.75;  # source_lat
    rate_kg_s=8.0, injection_height=2500.0, sigma_z=600.0,
)
mixing_ratio = TARSA.run!(TARSA.build_simulation(
    input,
    emissions;
    solver=TARSA.ExplicitSolver(cfl=0.7, scheme=:dst_koren_rk3, dt=3600.0),
    lateral_bc=:neumann0,
    bottom_bc=:neumann0,
))

output_file = joinpath(@__DIR__, "out", "quickstart_etna.nc")
rm(output_file; force=true)
TARSA.save_results(
    output_file,
    input,
    mixing_ratio,
    emissions;
    template_file=levels_file,
    variables=["concentration"],
    save_emissions=false,
)

If you want the Etna tutorial run that writes the plume file used by the animation step:

julia --project=. examples/tutorial/01_run_point_source.jl
julia --project=. examples/tutorial/02_make_plume_gif.jl

The main TARSA pattern is always the same:

  1. load meteorology
  2. build emissions
  3. choose a solver
  4. build a simulation
  5. run it
  6. save the result

For the shortest code-first example, go to Guide / Quickstart. For the full ERA5 tutorial workflow, go to Examples / Tutorial.

Validation snapshots

The validation suite combines idealized verification, independent field comparisons, an aerosol remote-sensing anchor case, and replay-style consistency checks. The two main inert field-release cases are ETEX-1 over Europe and CAPTEX-1 over eastern North America; the aerosol anchor case is the FENNEC Saharan dust outbreak evaluated against GRASP/POLDER.

ETEX-1

ETEX-1 plume animation

ETEX-1 is the main independent long-range tracer evaluation in the documentation. The animation shows the near-surface plume transported from western France across western and central Europe.

ETEX-1 FMT comparison

The station-wise ETEX comparison includes the figure of merit in time

\[\mathrm{FMT}_s = 100 \; \frac{\sum_k \min\!\left(C^{\mathrm{mod}}_{s,k},\, C^{\mathrm{obs}}_{s,k}\right)} {\sum_k \max\!\left(C^{\mathrm{mod}}_{s,k},\, C^{\mathrm{obs}}_{s,k}\right)},\]

which measures how strongly the modeled and observed receptor time series overlap at each station. The current home-page comparison overlays TARSA with the published LMD-ZT(high) and DERMA reference curves for the standard 11-station ETEX subset. The ETEX-1 page gives the full set of arrival-time, dosage, maximum-concentration, and timing diagnostics: Validation / ETEX-1.

CAPTEX-1

CAPTEX plume animation

CAPTEX-1 provides an independent field-release evaluation over eastern North America with interval-averaged station observations and a different release geometry from ETEX-1.

CAPTEX average-rank comparison

For CAPTEX, the home page highlights the average-rank comparison against published results for NAME, HYSPLIT, STILT, and FLEXPART. The current TARSA value is 2.134, which sits inside the published model range. The CAPTEX page explains the pointwise statistics, the station-wise plots, and the rank definition: Validation / CAPTEX-1 field comparison.

FENNEC Saharan dust (aerosol anchor)

POLDER / TARSA / MERRA-2 daily dust-column triptych

FENNEC is the aerosol-oriented remote-sensing case: a five-bin Saharan dust outbreak (June 2011) evaluated against the GRASP/POLDER coarse-insoluble dust-column product. It exercises TARSA's aerosol-process extension (sedimentation, dry and wet deposition) and the satellite-collocation workflow under prescribed MERRA-2 emissions. The full pipeline and diagnostics are on the Examples / FENNEC dust page.

Where to go next