cesm_hawc.simulation¶

source

Run the HAWC ALI simulator on WACCM columns.

Uses the ideal_dolp_imager configuration of hawcsimulator’s IdealALISimulator. Requires the [sim] extra.

Attributes¶

• DEFAULT_PRODUCTS (tuple of str) — Simulator products for a run with the L2 retrieval.

• FORWARD_PRODUCTS (tuple of str) — Simulator products for a forward-model-only run.

products_for¶

def products_for(run_l2: bool) -> tuple

source

Choose which simulator products to request.

Parameters¶

• run_l2 (bool) — Whether the L2 retrieval should run.

Returns¶

• tuple of str — DEFAULT_PRODUCTS if run_l2, else FORWARD_PRODUCTS.

retrieval_wavelength_range¶

def retrieval_wavelength_range() -> tuple[float, float]

source

Return the wavelength range the L2 retrieval’s aerosol model covers.

Read from aliprocessing’s retrieval Mie database (aerosol_median_radius_db), building it on first use.

Returns¶

• tuple of float — Shortest and longest wavelength in the database [nm].

check_retrieval_wavelengths¶

def check_retrieval_wavelengths(wavelengths_nm) -> None

source

Check that wavelengths are within the L2 retrieval’s range.

Outside retrieval_wavelength_range(), the retrieval has no aerosol optical properties, so it would fit radiances it cannot model.

Parameters¶

• wavelengths_nm (array-like) — Simulated wavelengths [nm].

Raises¶

• ValueError — If any wavelength is outside the retrieval’s range.

run_ali_simulation_from_profiles¶

def run_ali_simulation_from_profiles(
    profiles: dict,
    alt_m: np.ndarray,
    sim_geometry: dict,
    *,
    simulator: 'IdealALISimulator | None' = None,
    products: tuple = DEFAULT_PRODUCTS,
    noise_model: ALINoiseModel,
    return_extinction: bool = False,
    truth_wavelengths_nm: np.ndarray | None = None,
)

source

Run the simulator on profiles that have already been extracted.

Use this when running many observations from one file: open one WACCMAtmosphere (and optionally one IdealALISimulator) and reuse them, rather than calling run_ali_simulation(), which reopens the file each time.

Parameters¶

• profiles (dict) — Result of cesm_hawc.waccm.WACCMAtmosphere.get_column_profiles().

• alt_m (numpy.ndarray) — Altitude grid [m], matching profiles["altitudes_m"].

• sim_geometry (dict) — Inputs for simulator.run(): tangent_latitude, tangent_longitude, altitude_grid, polarization_states, sample_wavelengths and time, plus either observer_latitude/observer_longitude/observer_altitude or tangent_solar_zenith_angle/tangent_solar_azimuth_angle. Must not include constituents or l1b_cfg, which this function sets.

• simulator (IdealALISimulator, optional) — Simulator to reuse. A new one is constructed if omitted.

• products (tuple of str, optional) — Products to request. Default DEFAULT_PRODUCTS.

• noise_model (hawcsimulator.noise.ALINoiseModel) — Required. Use cesm_hawc.noise.default_noise_model().

• return_extinction (bool, optional) — Also return the truth extinction. Default False.

• truth_wavelengths_nm (array-like, optional) — Wavelengths [nm] for the truth extinction. Default [745.0].

Returns¶

• data (dict) — The simulator.run() result, keyed by product name.

• true_extinction (dict) — Only if return_extinction is True; see cesm_hawc.constituents.build_waccm_constituents().

Raises¶

• ValueError — If noise_model is None (the ideal_dolp_imager instrument model has no noiseless mode), or if products includes "l2" and a wavelength is outside the retrieval’s range (see check_retrieval_wavelengths()).

run_ali_simulation¶

def run_ali_simulation(
    waccm_file: str,
    *,
    lat: float,
    lon: float,
    time_index: int = 0,
    sza_deg: float = 60.0,
    saa_deg: float = 0.0,
    obs_time: str | pd.Timestamp = '2035-01-01T12:00:00Z',
    wavelengths_nm: np.ndarray | None = None,
    alt_grid_m: np.ndarray | None = None,
    run_l2: bool = False,
    noise_model: ALINoiseModel,
) -> dict

source

Simulate one column of a WACCM history file at a fixed geometry.

Parameters¶

• waccm_file (str) — CAM history file (any stream, e.g. h0 or h2).

• lat, lon (float) — Tangent point [degrees].

• time_index (int, optional) — Time slice within the file. Default 0.

• sza_deg, saa_deg (float, optional) — Solar zenith and azimuth angles at the tangent point [degrees]. Defaults 60 and 0.

• obs_time (str or pandas.Timestamp, optional) — Observation time.

• wavelengths_nm (array-like, optional) — Simulated wavelengths [nm]. Default [470, 745, 1020].

• alt_grid_m (array-like, optional) — Altitude grid [m]. Default 0–65 km every 1 km.

• run_l2 (bool, optional) — Also run the L2 retrieval. Default False (forward model only).

• noise_model (hawcsimulator.noise.ALINoiseModel) — Required. Use cesm_hawc.noise.default_noise_model().

Returns¶

• dict — data: the simulator.run() result (l1b, plus l2 when run_l2). true_extinction: truth extinction at wavelengths_nm (see cesm_hawc.constituents.build_waccm_constituents()). burden: the column’s sulfate burden (see cesm_hawc.waccm.WACCMAtmosphere.sulfate_column_burden()).

Raises¶

• ValueError — If noise_model is None, or if run_l2 is True and a wavelength is outside the retrieval’s range (see check_retrieval_wavelengths()).

Examples¶

>>> from cesm_hawc.noise import default_noise_model
>>> result = run_ali_simulation(
...     "case.cam.h0.2035-02.nc", lat=30.6, lon=180.0,
...     run_l2=True, noise_model=default_noise_model(),
... )
>>> result["data"]["l2"]["stratospheric_aerosol_extinction_per_m"]