Repository

Quickstart

This page is the fastest way to run TARSA from code. The canonical quickstart script is examples/tutorial/minimal_code.jl.

It uses the Etna point-source case on real ERA5 meteorology, reuses the shipped tutorial files if they are already present, and otherwise downloads the same meteorology from Copernicus CDS.

What you need

You need:

  • Julia 1.12+
  • this repository cloned locally
  • the TARSA project instantiated with julia --project=. -e 'using Pkg; Pkg.instantiate()'

The repository already includes the exact ERA5 files for this quickstart in:

  • examples/tutorial/data/era5_2024_04_01_levels.nc
  • examples/tutorial/data/era5_2024_04_01_surface.nc
  • examples/tutorial/data/era5_2024_04_01_precip.nc

With those files in place, the run normally starts immediately and the actual computation takes about 1 minute. If you delete them and let TARSA download them again, budget roughly 10 minutes for the Copernicus transfer.

Fastest first run

From the repository root:

julia --project=. examples/tutorial/minimal_code.jl

This writes:

  • examples/tutorial/out/quickstart_etna.nc

If you want the slightly longer tutorial run that writes the GIF-ready plume NetCDF, continue with:

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

Quickstart script

The block below is the exact contents of examples/tutorial/minimal_code.jl.

#!/usr/bin/env julia
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,
)

What it does

This is the main TARSA pattern:

  1. prepare or reuse meteorology
  2. load it into TARSA.InputFields
  3. build emissions
  4. build and run the simulation
  5. save the result

In this specific quickstart:

  • TARSA.prepare_input_data(...) reuses examples/tutorial/data/ or downloads the ERA5 files for the Etna case
  • TARSA.load_input_data(...) loads the ERA5 fields into one InputFields object
  • TARSA.zero_emissions(...) allocates the model-sized emissions field
  • TARSA.add_point_source!(...) places a steady point source near Etna at 15.0E, 37.75N
  • TARSA.build_simulation(...) and TARSA.run!(...) run the explicit :dst_koren_rk3 transport solver
  • TARSA.save_results(...) writes quickstart_etna.nc with mixing_ratio and concentration

Credentials for ERA5 download

If the shipped tutorial NetCDF files are still present, this quickstart does not need credentials.

If they are missing, you can use either:

  • ~/.cdsapirc
  • the commented ENV["CDSAPI_URL"] and ENV["CDSAPI_KEY"] lines at the top of minimal_code.jl

For the full setup, see Guide / Data Access.

Next step

After this page, the most useful follow-ups are: