Modules and Functions

srfm.ARIA_module module

Used to access the ARIA database.

For details see https://eodg.atm.ox.ac.uk/ARIA/.

  • Name: ARIA_module

  • Parent package: srfm

  • Author: Don Grainger

  • Contributors: Antonin Knizek

  • Date: 24 January 2025

class srfm.ARIA_module.RI

Bases: object

Class representing refractive index data.

expected_column_names = ['wavl', 'wavn', 'n', 'dn', 'k', 'dk']
expected_header_names = ['FORMAT', 'DESCRIPTION', 'DISTRIBUTEDBY', 'SUBSTANCE', 'SAMPLEFORM', 'TEMPERATURE', 'CONCENTRATION', 'REFERENCE', 'DOI', 'SOURCE', 'CONTACT', 'COMMENT']
load_refractive_indices(composition, wave=None, mode='wavelength', out_of_range='error')

Reads the refractive index data for a given ri file.

Interpolates to the wave values if provided, or returns full-resolution data if wave is None.

Parameters:

  • composition (str) –

    Any of:

    • an ARIA file name

    • an ARIA file group from the list below (NOT IMPLEMENTED)

    • ”ZASETSKY”, keyword temperature needs to be set so the retruned reractive indexx of water is interpolated to that temperature

    • a generic name from the list below:

      • ”ash”

      • ”ice”

      • ”sulphuric acid”

      • ”water”. (NOT IMPLEMENTED)

  • wave (list or array, optional) – The target wavelengths or wavenumbers to interpolate to. If None, returns data at full resolution.

  • mode (str) – ‘wavelength’ for wave in µm or ‘wavenumber’ for wave in cm⁻¹.

  • out_of_range (str) – Behavior for out-of-range values: ‘error’, ‘clip’, or ‘nan’.

Returns:

tuple – Two or three arrays: - If wave is None: (x_data, n, k), where x_data is wavl or wavn. - If wave is defined: (n, k), the interpolated real and imaginary parts of the refractive index.

read(filepathname)

Reads and parses an .ri file into the object’s attributes.

Parameters:

filepathname – Refractive index filepath.

select(wave=None, mode='wavelength', out_of_range='error')

Selects requested data.

Parameters:

  • wave – User input wave.

  • mode –

    Output mode. Can be “wavelength” or “wavenumber”. out_of_range: Defines how out-of-range values are handled. Could be:

    • error: Error is raised.

    • clip: Data is truncated.

    • nan: Data is interpolated.

exception srfm.ARIA_module.ReadError

Bases: Exception

Custom exception raised for errors in reading .ri files.

srfm.ARIA_module.find_ri_files(ARIA_path)

Finds .ri files in requested path.

Parameters:

ARIA_path (-) – Requested path.

Returns:

list – Path to .ri files.

srfm.ARIA_module.get_ri_filepathname(input_string)

Maps an input string to a file path.

Parameters:

input_string – either an ARIA filename or any of “ash”, “ice”, “sulphuric acid”

Returns:

path – absolute file path of the refractive indices file.

srfm.ARIA_module.read_ri_file(filepathname, wave=None, mode='wavelength', out_of_range='error')

Reads the refractive index data for a given ri file.

Interpolates to the wave values if provided, or returns full-resolution data if wave is None.

Parameters:

  • filepathname – an ARIA filename

  • wave (list or array, optional) – The target wavelengths or wavenumbers to interpolate to. If None, returns data at full resolution.

  • mode (str) – ‘wavelength’ for wave in µm or ‘wavenumber’ for wave in cm⁻¹.

  • out_of_range (str) – Behavior for out-of-range values: ‘error’, ‘clip’, or ‘nan’.

Returns:

Two or three arrays –

  • If wave is None: (x_data, n, k), where x_data is wavl or wavn depending on mode.

  • If wave is defined: (n, k), the interpolated real and imaginary parts of the refractive index.

srfm.disort_functions module

Provides functions that enable the user to work with DISORT from a python interface.

  • Name: disort_functions

  • Parent package: srfm

  • Author: Antonin Knizek

  • Contributors:

  • Date: 18 February 2025

srfm.disort_functions.get_pmom_from_disort(self, pmom, iphas, gg, nmom, lyrs=None)

Calculate phase function moments from disort.

Parameters:

  • pmom (array-like) – pmom array, can be all zeros.

  • iphas (int) – DISORT getmom parameter, phase function option, 1-7.

  • gg (int, float) – disort getmom parameter, assymetry parameter for Henyey_greenstein function.

  • nmom (int) – Index of the highest Legendre coefficient needed should equal maxmom (number of phase function moments).

  • lyrs (array-like) – Layers to perform calculation for if None, calculate for all layers.

Returns:

pmom (array-like) – Returns array with shape pmom.shape with Legendre polynomial coefficients for the selected phase function.

Raises:

  • TypeError – Raised when values in lyrs can’t be converted to ints or when layers are not list, tuple or set.

  • ValueError – Raised when invalid layer number in layers is encountered.

srfm.disort_functions.test_disort_input_format(maxcly, maxmom, maxcmu, maxumu, maxphi, maxulv, usrang, usrtau, ibcnd, onlyfl, prnt, plank, lamber, deltamplus, do_pseudo_sphere, dtauc, ssalb, pmom, temper, wvnmlo, wvnmhi, utau, umu0, phi0, umu, phi, fbeam, fisot, albedo, btemp, ttemp, temis, earth_radius, h_lyr, rhoq, rhou, rho_accurate, bemst, emust, accur, header, rfldir, rfldn, flup, dfdt, uavg, uu, albmed, trnmed)

Tests DISORT input parameters for format consistency.

Defines a passmark variable, which is False, then carries out the tests and if the input passes the test, the passmark is changed to True and returned.

Parameters:

  • maxcly (int) – Number of computational layers.

  • maxmom (int) – Number of phase function moments.

  • maxcmu (int) – Number of computational streams.

  • maxumu (int) – Number of output polar angles.

  • maxphi (int) – Number of output azimuthal angles.

  • maxulv (int) – Number of output optical depths.

  • usrang (bool) – User angles flag, if True, outputs at user output polar angles, if False, outputs returned at computational polar angles.

  • usrtau (bool) – User optical depths flag. If True, outputs at user-defined optical depths, if False, outputs returned at boundaries of each computational layer.

  • ibcnd (int) – Requested outputs flag. See DISORT documentation for full explanation.

  • onlyfl (bool) – If True, return only fluxes.

  • prnt (array) – Array of shape (5,) bool values, controls printing to terminal from DISORT.

  • plank (bool) – Thermal radiation in DISORT. True - on, False - off.

  • lamber (bool) – Bottom boundary in DISORT treated as Lambertian or not.

  • deltamplus – If True, use delta-M-plus approximation to calculate strongly forward-peaked phase functions. If False, use delta-M method.

  • do_pseudo_sphere (bool) – Do a spheric correction on the calculation.

  • dtauc (array-like) – Atmospheric optical depth structure (Layers’ optical depth).

  • ssalb (array-like) – Layers’ single scatter albedo.

  • pmom (array-like) – Scattering phase function Legendre polynomial expansion coefficients (normalised coefficients expected).

  • temper (array-like) – Atmospheric tempeature structure, defined in terms of levels.

  • wvnmlo (int, float) – Lower wavenumber for Planck function calculation.

  • wvnmhi (int, float) – Upper wavenumber for Planck function calculation.

  • utau (array-like) – User requested output optical depths.

  • umu0 (int, float) – Incoming direct beam polar angle.

  • phi0 (int,float) – Incoming direct beam azimuthal angle.

  • umu (array-like) – User requested output polar angles.

  • phi (array-like) – User requested output azimuthal angles.

  • fbeam (int, float) – Incoming direct beam intensity.

  • fisot (int, float) – Incoming diffuse radiation intensity.

  • albedo (int, float) – Surface albedo.

  • btemp (int, float) – Bottom boundary temperature.

  • ttemp (int, float) – Top boundary temperature.

  • temis (int, float) – Top boundary emmisivity.

  • earth_radius (int, float) – Earth radius, [km].

  • h_lyr (array-like) – layer vertical extent.

  • rhoq (array-like) – BDREF-related.

  • rhou (array-like) – BDREF-related.

  • rho_accurate (array-like) – BDREF-related.

  • bemst (array-like) – BDREF-related.

  • emust (array-like) – BDREF-related.

  • accur (int, float) – Convergence criterion for azimuthal (Fourier cosine) series.

  • header (str) – Header for terminal output printing. Max length 127 characters. The string “NO HEADER” will supress the printing completely.

  • rfldir (array-like) – Empty output array for downward direct flux.

  • rfldn (array-like) – Empty output array for downward diffuse flux.

  • flup (array-like) – Empty output array for upward diffuse flux.

  • dfdt (array-like) – Empty output array for flux divergence.

  • uavg (array-like) – Empty output array for average intensity.

  • uu (array-like) – Empty output array for intensity.

  • albmed (array-like) – Empty output array for albedo.

  • trnmed (array-like) – Empty output array for transmissivity.

Returns:

passmark (bool) – True if all inputs passed the test, False otherwise.

srfm.disort_functions.test_disort_input_integrity(maxmom, maxcmu, maxumu, maxphi, ibcnd, dtauc, ssalb, temper, wvnmlo, wvnmhi, utau, umu0, phi0, umu, phi, btemp, ttemp, temis)

Performs sanity checks for DISORT inputs.

Defines a passmark variable, which is False, then carries out the tests and if the input passes the test, the passmark is changed to True and returned. Parameters are not tested for format but for actual value and constraints that value must satisfy as defined in DISORT docs.

Parameters:

  • maxmom (int) – Number of phase function moments.

  • maxcmu (int) – Number of computational streams.

  • maxumu (int) – Number of output polar angles.

  • maxphi (int) – Number of output azimuthal angles.

  • ibcnd (int) – Requested outputs flag. See DISORT documentation for full explanation.

  • dtauc (array-like) – Atmospheric optical depth structure (Layers’ optical depth).

  • ssalb (array-like) – Layers’ single scatter albedo.

  • temper (array-like) – Atmospheric tempeature structure, defined in terms of levels.

  • wvnmlo (int, float) – Lower wavenumber for Planck function calculation.

  • wvnmhi (int, float) – Upper wavenumber for Planck function calculation.

  • utau (array-like) – User requested output optical depths.

  • umu0 (int, float) – Incoming direct beam polar angle.

  • phi0 (int,float) – Incoming direct beam azimuthal angle.

  • umu (array-like) – User requested output polar angles.

  • phi (array-like) – User requested output azimuthal angles.

  • btemp (int, float) – Bottom boundary temperature.

  • ttemp (int, float) – Top boundary temperature.

  • temis (int, float) – Top boundary emmisivity.

Returns:

passmark (bool) – True if all inputs passed the test, False otherwise.

srfm.disort_functions.update_maxcmu(maxcmu)

Checks and (optional) updates the value of maxcmu for DISORT.

Maxcmu must be and even number. If it is not, this function adds 1 to it so that it will be.

Parameters:

maxcmu (int) – Number of computational streams in DISORT.

Returns:

maxcmu (int) – Updated value of maxcmu.

srfm.disort_functions.update_maxulv(maxulv, usrtau, maxcly)

Check and updates the value of maxulv for DISORT.

If usrtau flag for user output optical depths in DISORT is False, results are returned at the boundary of each computational layer and therefore maxulv must be maxcly + 1. This function checks the usrtau flag and if usrtau == False, sets maxulv to (maxcly+1).

Parameters:

  • maxulv (int) – Number of user optical depths.

  • usrtau (bool) – Flag for optical depths, if True, return values at user optical depths, if False, return at boudnary of each computational layer.

  • maxcly (int) – Number of DISORT computational layers.

Returns:

maxulv (int) – Updated version of maxulv.

srfm.disort_functions.update_maxumu(maxumu, usrang, maxcmu)

Updates the value of maxumu.

If user angles are not requested, maxumu is set to equal maxcmu.

Parameters:

  • maxumu (int) – Number of user-requested output polar angles.

  • usrang (bool) – Are user angles requested or not?

  • maxcmu (int) – Number of computational streams.

Returns:

maxumu (int) – Updated version of maxumu.

srfm.forward_model module

Defines the base model class for the forward model and specific model subclasses.

  • Name: forward_model

  • Parent package: srfm

  • Author: Antonin Knizek

  • Contributors:

  • Date: 18 February 2025

class srfm.forward_model.DISORT(name='DISORT', disort_fldr=None, disort_input={}, disort_out={}, disort_fmt_passmark=True, disort_integrity_passmark=True, status='DISORT object created.', **parameters)

Bases: Fwd_model

Class that contains the DISORT forward model.

Is subclass of Fwd_model.

add_disort_empty_input()

Adds a dictionary with default and zero values as DISORT input.

The dictionary contains zeros where possible and minimum or basic values in other instances (such as maxcly, which is 1 for one computational layer - the simplest possible case), etc.

add_disort_input(d)

Add disort input parameters as a dictionary.

Parameters:

d (dict) – Dictionary with DISORT input parameters.

calc_bbt()

Converts radiance to brightness temperature.

calc_pmom(iphas, prec='double', gg=0)

Calculates phase function moments from disort using the getmom function.

Parameters:

  • iphas (int) – phase function option. Can be: - 1: Isotropic - 2: Rayleigh - 3: Henyey-Greenstein with asymmetry factor GG - 4: Haze L as specified by Garcia/Siewert - 5: Cloud C.1 as specified by Garcia/Siewert - 6: Aerosol as specified by Kokhanovsky - 7: Cloud as specified by Kokhanovsky

  • gg (int,float) – Assymetry factor for Heyney-Greenstein case. Default is 0.

  • prec (str) – Required precision mode, accepted values “single” or “double”. Default is double.

Raises:

ValueError – When invalid precision values is used.

calc_pmom_double(iphas, gg=0)

Calculates phase function moments from disort using the getmom function.

This is a class method because it contains a loop which is inconvenient in the main code (getmom calcualtes phase function moments for a 1D array/list, not a 2D array. This function uses the double precision version of DISORT.

Parameters:

  • iphas (int) – phase function option. Can be: - 1: Isotropic - 2: Rayleigh - 3: Henyey-Greenstein with asymmetry factor GG - 4: Haze L as specified by Garcia/Siewert - 5: Cloud C.1 as specified by Garcia/Siewert - 6: Aerosol as specified by Kokhanovsky - 7: Cloud as specified by Kokhanovsky

  • gg (int,float) – Assymetry factor for Heyney-Greenstein case. Default is 0.

  • prec (str) – Required precision mode, accepted values “single” or “double”. Default is double.

Returns:

pmom (array-like) – Legendre coefficients of the phase function (moments).

calc_pmom_single(iphas, gg=0)

Calculates phase function moments from disort using the getmom function.

This is a class method because it contains a loop which is inconvenient in the main code (getmom calcualtes phase function moments for a 1D array/list, not a 2D array. This function uses the single precision version of DISORT.

Parameters:

  • iphas (int) – phase function option. Can be: - 1: Isotropic - 2: Rayleigh - 3: Henyey-Greenstein with asymmetry factor GG - 4: Haze L as specified by Garcia/Siewert - 5: Cloud C.1 as specified by Garcia/Siewert - 6: Aerosol as specified by Kokhanovsky - 7: Cloud as specified by Kokhanovsky

  • gg (int,float) – Assymetry factor for Heyney-Greenstein case. Default is 0.

  • prec (str) – Required precision mode, accepted values “single” or “double”. Default is double.

Returns:

pmom (array-like) – Legendre coefficients of the phase function (moments).

initialize_disort_output_arrays()

Initializes empty output arrays for a single disort run.

run_disort(prec='double', adjust_maxcmu=True)

Calls function to run disort with required precision.

Parameters:

  • prec (str) – Determines Fortran precision to be used (single vs double). Default is double precision calculation.

  • adjust_maxcmu (bool) – If True, check the output intensity in the downward direction. If that turns out negative and close to zero, it’s likely caused by roundoff errors in the Delta-M+ algorithm. Increasing the number of computational streams usually fixes it, so in case this happens, the number of streams is automatically adjusted and DISORT run again.

run_disort_double(adjust_maxcmu)

Runs disort, double precision.

run_disort_single(adjust_maxcmu)

Runs disort, single precision.

save_model_pickle(filename=None, folder=None)

Saves the model with to a file with pickle.

Parameters:

  • filename (str) – Name of file to be saved. If None, then default name “model.pkl” is used. Default is None.

  • folder (str) – Location for the file to be saved to. If None, then save in the current folder. Default is None.

set_accur(accur)

Assigns the value of accur.

Parameters:

accur (int, float) – Convergence criterion for azimuthal (Fourier cosine) series.

set_albedo(albedo)

Assigns the value of albedo.

Parameters:

albedo (int, float) – Surface albedo.

set_bemst(bemst)

Assigns the value of bemst.

Parameters:

bemst (array-like) – Something to do with BDREF in DISORT?

set_btemp(btemp)

Assigns the value of btemp.

Parameters:

btemp (int, float) – Bottom boundary temperature.

set_deltamplus(deltamplus)

Assigns the value of deltamplus.

Parameters:

deltamplus – If True, use delta-M-plus approximation to calculate strongly forward-peaked phase functions. If False, use delta-M method.

set_do_pseudo_sphere(d_p_s)

Assigns the value of do_pseudo_sphere.

Parameters:

d_p_s (bool) – Do a spheric correction on the calculation.

set_dtauc(tau_g, tau_R, tau_p)

Calculate optical depth of model layers, delta tau (dtau).

Calculation according to the formula \(dtau = tau_g + tau_R + tau_p\) Value is assigned to the object.

Parameters:

  • tau_g (array-like) – layer optical depth from gas absorption

  • tau_R (array-like) – layer optical depth from Rayleigh scattering

  • tau_p (array-like) – layer optical depth from particle scattering

set_dtauc_manually(dtauc)

Assigns the value of dtauc.

Parameters:

dtauc (array-like) – Atmospheric optical depth structure (layers’ optical depth).

set_earth_radius(earth_radius)

Assigns the value of earth_radius.

Parameters:

earth_radius (int, float) – Earth radius, [km].

set_emust(emust)

Assigns the value of emust.

Parameters:

emust (array-like) – Something to do with BDREF in DISORT?

set_fbeam(fbeam)

Assigns the value of fbeam.

Parameters:

fbeam (int, float) – Incoming direct beam intensity.

set_fisot(fisot)

Assigns the value of fisot.

Parameters:

fisot (int, float) – Incoming diffuse radiation intensity.

set_h_lyr(h_lyr)

Assigns the value of h_lyr.

Parameters:

h_lyr (array-like) – layer vertical extent.

set_h_lyr_from_rfm(rfm)

Assigns the value of h_lyr from the RFM output.

Parameters:

rfm (obj) – Class RFM object which has attribute rfm_output.

Raises:

AttributeError – Raised when RFM object does not have rfm_output attribute.

set_header(header)

Assigns the value of header.

Parameters:

header (str) – Header for terminal output printing. The string “NO HEADER” will cause nothing to be printed out. Warning: If the input is an empty string (“”), a blank line will be printed. The string must have len < 127.

set_ibcnd(ibcnd)

Assigns the value of ibcnd.

Parameters:

ibcnd (int) – Specifices a combination of boundary conditions. For full documentation see DISORT documentation.

set_lamber(lamber)

Assigns the value of lamber.

Parameters:

lamber (bool) – Bottom boundary in DISORT treated as Lambertian or not.

set_maxcly(maxcly)

Assigns the value of maxcly.

Parameters:

maxcly (int) – Number of computational layers.

set_maxcly_from_rfm(rfm)

Sets maxcly from RFM.

Parameters:

rfm (obj) – Class RFM object and has attribute rfm_output.

Raises:

AttributeError – Raised when rfm does not have rfm_output attribute.

set_maxcmu(maxcmu)

Assigns the value of maxcmu.

Parameters:

maxcmu (int) – Number of computational streams.

set_maxmom(maxmom)

Assigns the value of maxmom.

Parameters:

maxmom (int) – Number of phase function moments.

set_maxphi(maxphi)

Assigns the value of maxphi.

Parameters:

maxphi (int) – Number of output azimuthal angles.

set_maxulv(maxulv)

Assigns the value of maxulv.

Parameters:

maxulv (int) – Number of output optical depths.

set_maxumu(maxumu)

Assigns the value of maxumu.

Parameters:

maxumu (int) – Number of output polar angles.

set_onlyfl(onlyfl)

Assigns the value of onlyfl.

Parameters:

onlyfl (bool) – If True, only fluxes output, elif False, full output.

set_phi(phi)

Assigns the value of phi.

Parameters:

phi (array-like) – User requested output azimuthal angles.

set_phi0(phi0)

Assigns the value of phi0.

Parameters:

phi0 (int,float) – Incoming direct beam azimuthal angle.

set_plank(planck)

Assigns the value of plank.

Parameters:

planck (bool) – Thermal radiation in DISORT. True - on, False - off.

set_pmom(pmom_R, tau_R, w_p, tau_p, pmom_p)

Calculate phase function coefficients according to Don (from ORAC).

The calculation formula is

\[\begin{eqnarray} x_i = \frac{w_g*\tau_g*x_{i,g} + w_R*\tau_R*x_{i,r} + w_p*\tau_p*x_{i,p}}{w_g*\tau_g + w_r*\tau_R + w_p*\tau_p} \end{eqnarray}\]
where:

  • \(x_i\): Legendre polynomial coefficient

  • \(w_g\): = 0 - gas single scatter albedo

  • \(x_{i,g}\): = 0, gas phase function moment

  • \(w_R\): = 1, Rayleigh scattering single scatter albedo

which makes the formula

\[\begin{eqnarray} x_i = \frac{tau_R*x_{i,r} + w_p*\tau_p*x_{i,p}}{tau_R + w_p*\tau_p} \end{eqnarray}\]

The function works on arrays, so \(x_i\) is replaced by array pmom.

Parameters:

  • pmom_R (array-like) – Array of phase function moments for Rayleigh scattering. 2D array, where columns are the atmospheric layers rows are the Legendre polynomial coefficients \(x_{1,R}\) to \(x_{n,R}\). Has shape (model_DISORT.disort_input[“maxmom”] + 1, model_DISORT.disort_input[“maxcly”]).

  • pmom_p (array-like) – Array of phase function coefficients for particle scattering. Same shape and meaning as pmom_R.

  • w_p (array-like) – Particle scattering single scatter albedo for each layer.

  • tau_p (array-like) – Particle scattering optical depth for each layer.

  • tau_R (array-like) – Rayleigh optical depths.

Raises:

  • ValueError – When inputs are incorrectly shaped.

  • TypeError – When inputs are not np.ndarrays.

set_pmom_manually(pmom)

Assigns the value of pmom.

Parameters:

pmom (array-like) – Scattering phase function Legendre polynomial expansion coefficients (normalised coefficients expected).

set_prnt(prnt)

Assigns the value of prnt.

Parameters:

prnt (array-like) – Array of shape (5,) bool values, controls printing to terminal from DISORT.

set_rho_accurate(rho_accurate)

Assigns the value of rho_accurate.

Parameters:

rhou (array-like) – Something to do with BDREF in DISORT?

set_rhoq(rhoq)

Assigns the value of rhoq.

Parameters:

rhoq (array-like) – Something to do with BDREF in DISORT?.

set_rhou(rhou)

Assigns the value of rhou.

Parameters:

rhou (array-like) – Something to do with BDREF in DISORT?

set_ssalb(tau_g, tau_R, tau_p, w_p)

Calculates and adds the single scatter albedo of the model layers.

The calculation formula is

\[\begin{eqnarray} w = \frac{w_g*\tau_g + w_R*\tau_R + w_p*\tau_p} {\tau_g + \tau_R + \tau_p} \end{eqnarray}\]
where:

  • w: layer single scatter albedo

  • w_g: layer single scatter albedo from gas absorption, == 0

  • w_R: layer Rayleigh scattering single scatter albedo, == 1

  • w_p: layer particle scattering single scatter albedo

  • tau_g: layer gas absorption optical depth

  • tau_R: layer Rayleigh scattering optical depth

  • tau_p: layer particle scattering optical depth

Parameters:

  • tau_g (array-like) – layer optical depth from gas absorption

  • tau_R (array-like) – layer optical depth from Rayleigh scattering

  • tau_p (array-like) – layer optical depth from particle scattering

  • w_p (array_like) – layer particle scattering single scatter albedo

set_ssalb_manually(ssalb)

Assigns the value of ssalb.

Parameters:

ssalb (array-like) – Layers’ single scatter albedo.

set_temis(temis)

Assigns the value of temis.

Parameters:

temis (int, float) – Top boundary emmisivity.

set_temper(temper)

Assigns the value of temper.

Parameters:

temper (array-like) – Atmospheric tempeature structure, defined in terms of levels.

set_temper_from_rfm(rfm)

Sets layer temperature for disort from the RFM output.

Takes upper temperatures from rfm_output for every layer. Adds the lowest layer lower temperature (adjacent to surface) as the last one.

Parameters:

rfm (obj) – Class RFM object which has attribute rfm_output.

set_ttemp(ttemp)

Assigns the value of ttemp.

Parameters:

ttemp (int, float) – Top boundary temperature.

set_umu(umu)

Assigns the value of umu.

Parameters:

umu (array-like) – User requested output polar angles.

set_umu0(umu0)

Assigns the value of umu0.

Parameters:

umu0 (int, float) – Incoming direct beam polar angle.

set_usrang(usrang)

Assigns the value of usrang.

Parameters:

usrang (bool) – If True, output at user-defined polar angles requested.

set_usrtau(usrtau)

Assigns the value of usrtau.

Parameters:

usrtau (bool) – If True, output at user-defined optical depths requested.

set_utau(utau)

Assigns the value of utau.

Parameters:

utau (array-like) – User requested output optical depths.

set_wvl(wvl)

Sets wavelength of the current run.

Parameters:

wvl (int, float) – wavelength [cm-1].

set_wvnm(wvnm)

Sets wavenumber of the current run.

Parameters:

wvnm (int, float) – wavenumber [cm-1].

set_wvnm_range(lo, hi)

Assigns the value of wvnmlo and wvnmhi.

Parameters:

  • lo (int, float) – Lower wavenumber for Planck function calculation.

  • hi (int, float) – Upper wavenumber for Planck function calculation.

test_disort_input_format()

Test disort input for correct formatting.

test_disort_input_integrity()

Tests if DISORT input satisfies basic logical integrity and code constraints.

class srfm.forward_model.Fwd_model(name=None, **parameters)

Bases: object

Base class for containing forward models.

Specific forward models are defined as subclasses of this superclass.

class srfm.forward_model.RFM(name='RFM', rfm_fldr=None, status='RFM model object created.', **parameters)

Bases: Fwd_model

Class that contains the RFM forward model.

Is subclass of Fwd_model.

add_rfm_opt_output(fldr, levels)

Load RFM output from files to the object as method.

Parameters:

  • fldr (str) – Path to RFM folder.

  • levels (array-like) – Specifies levels at which to load output.

Returns:

Loads RFM results to the object, updates status.

calc_col_dens_and_mass(species, M=None)

Determines total column density of a species in the atmosphere.

Integrates the species mixing ratio throughout the atmosphere to obtain total column density in units [molecules m\(^{-2}\) ] and Dobson units [DU]. If molar masses are provided, also calculates column masses in units [g m\(^{-2}\) ].

Function logic:

  1. checks if object has output_prf loaded.

  2. If not, tries to load it from a default directory.

  3. If 1 and 2 fail, error is raised.

  4. Checks if species are present as key in output_prf (and if not, then

    tries to add ppmv and check again).

  5. Integrates the profile for a given species (if they exist), returns dict

  6. If molar masses are provided, also calculates column masses.

Parameters:

  • species (list of str) – list of species. The code first checks if the species are present in the profile. Mind that the rfm profile uses ppmv. If a key is not found, e.g. CO, and attempt will be made to transform it to CO [ppmv].

  • M (list of floats, optional) – list of species’ molar masses. If None, column masses are not calculated. Default is None. Assumed units [g mol\(^{-1}\) ].

Returns:

  • col_den (dict) – Dictionary containing species and its column density, units [molecules m\(^{-2}\) ].

  • col_den_DU (dict) – Dictionary containing species and its column density, units [DU] (Dobson units).

  • col_mass (dict, optional) – Dictionary containing species and its column mass, units [g m\(^{-2}\) ].

Raises:

ValueError – Raised when requested species not found.

get_wnos_from_RFM()

Determine wavenumbers from RFM output.

Raises:

ValueError – Raised when rfm output is empty.

load_output_prf(fldr)

“Loads the output profile (default prf.asc) file from RFM.

Parameters:

fldr (str) – Path to RFM.

Returns:

Assings output_prf.

run_rfm(fldr, wipe=True)

Runs RFM from python.

Parameters:

  • fldr (str) – Path to the RFM folder (relative or absolute path).

  • wipe (bool) – If True, removes rfm results from the previous run. Default is True.

Returns:

Runs RFM, write its outputs to the fldr folder, updates object status.

class srfm.forward_model.SRFM(name='SRFM', **parameters)

Bases: Fwd_model

This class represents the final forward model.

The class object serves as a container for the outputs from various forward models, be it RFM + DISORT or other.

calc_bbt()

Converts radiance to brightness temperature.

Expects SRFM to have wavenumber/wavelength grid and radiances (uu) as attributes. Calculates brightness temperature array which matches the radiance array in shape.

convolve_with_iasi(filename)

Convolve radiance (uu) with IASI instrument line shape.

The SRFM object must contain radiances (uu) and a wavenumber grid. Assumes regular grid. Note that the convolved spectrum suffers from boundary effects (scipy interpolate does zero padding of the data at the boundaries). Best avoided by calculating your original spectra at a wider interval and then interpolating/ truncating. For interpolation (best used to get spectra at your simulated satellite grid) see the interp() function of this module.

Parameters:

filename (str) – filename of the iasi.ils file (IASI instrument line shape kindly provided by Anu Dudhia, in RFM format.)

initialize_srfm_output_arrays_from_disort(DISORT)

Initializes srfm output arrays to which disort outputs are appended.

Parameters:

DISORT (obj) – instance of srfm.forward_model.DISORT

Raises:

RuntimeError – Raised when the SRFM object doesn’t have wavenumber or wavelengths grid first.

interp(new_wvnm)

Interpolates radiances (uu) and brightness temperatures to a new grid.

Original intended use is to interpolate the calculated and already convolved spectra (i.e. at a lower effective resolution) to a satellite lower resolution grid.

The SRFM object must contain radiances (uu). If besides radiances also contains brightness temperatures (bbt), then these are interpolated as well.

Output is returned as updated attributes - new wavenumber and wavelength grids as well as new radiances and brightness temperatures (if originally present).

Parameters:

new_wvnm – new wavenumber grid to interpolate to, units [cm-1]

set_wvls(wvls)

Assigns wavelength grid to SRFM.

Parameters:

wvls (array-like) – Wavelength grid.

set_wvnm(wvnm)

Assigns wavenumber grid to SRFM.

Parameters:

wvnm (array-like) – Wavenumber grid.

store_disort_result(DISORT, wvl_idx)

Stores results from a single DISORT run into the SRFM object.

DISORT returns results for a given wavenumber/wavelength. If the overarching idea is to calculate a spectrum, which is it, DISORT is run in a lopp. This function takes results from a single DISORT run and inserts them in SRFM arrays in appropriate places (at appropriate indices).

Parameters:

  • DISORT (obj) – instance of srfm.forward_model.DISORT

  • wvl_idx (int) – Values are inserted into SRFM arrays at this index. The idea is that the DISORT calculation is performed at a certain wavenunmber. SRFM has initialized arrays of size matching the overall wavenumber grid and results from each DISORT run are inserted into the arrays at the index corresponding to the respective wavenumber.

srfm.layer module

Defines the Layer class and all its subclasses.

Used to contain scattering information for a single layer. - Name: layer - Parent package: srfm - Author: Antonin Knizek - Contributors: - Date: 26 Mar 2025

class srfm.layer.GreyBodyCloud(name=None, emis=1, **parameters)

Bases: Layer

Class that represents a grey body cloud.

Is subclass of Layer. The rationale for this class is to emulate the simplest possible case where a cloud is represented as a greybody emitter. No scattering is involved.

Unless changed, emissivity is 1 by default.

calc_grids()

Calculates spectral grids for the calculation of optical properties.

Calculates both wavelengths and wavenumbers.

calc_layer_extent()

This function attempts to calculate the layer vertical extent.

If layer center altitude and vertical extent are given, the lower and upper boundary altitudes are calculated. Else if lower and upper boundaries are given, the center altitude and vertical extent are calculated. All variables are in units [km].

Raises:

RuntimeError – Raised when inputs are insufficient.

calc_optical_properties()

Calculated optical properties.

In this case all it does is take inp_tau and stretches it over the spectral grid. The fact that this is a separate function is because the implementation mirrors implementation scheme in other srfm.layer.Layer() objects.

calculate_op()

Used to calculate the optical properties for the GreyBodyCloud class.

The function calls specialized functions to perform the actual calculations.

The structure is the following:

  1. Checks the inputs consistency and format and calculates what is missing.

  2. If emissivity not set, defaults to 1.

  3. Checks the inputs format (this is a little logically inconsistent because some checks must be performed in step one before missing properties are calculated).

  4. Calculate spectral grid.

  5. Calculate the optical properties, which are returned as class attributes.

Raises:

RuntimeError – Raised when input fails the format or input tests.

plot_diff(**kwargs)

Plots difference in calcualted optical properties.

Instance must have differences in optical properties calculated and stored as _diff attributes. For further information see srfm.layer.track_regrid_diff().

Returns:

fig (obj) – fig object

regrid(wvls, track_diff=False, diff_type='pct')

Linearly interpolates calculated values from ewp_hs to a new grid.

Instance must have the “tau” attribute.

Parameters:

  • wvls (aray-like) – new grid, units [\(\mu\)m]

  • track_diff (bool) – If True, calculates differences arising from interpolation.

Returns:

  • old attribute tau now as “tau_old”

  • new attribute “tau”

  • difference between old and new attribute “tau_diff”

Raises:

ValueError – Raised when any wavelength array is not monotonic.

set_alt_lim(alt_low, alt_upp)

Set lower and upper layer boundary (altitudes).

Parameters:

  • alt_low (int, float) – Layer lower boundary altitude, units [km].

  • alt_upp (int, float) – Layer upper boundary altitude, units [km].

set_center_alt(center_alt)

Set average (center) particle layer altitude.

Parameters:

center_alt (int, float) – Center particle layer altitude, units [km].

set_emis(e)

Set emissivity of the clouds.

Parameters:

e (int, float) – Grey body emissivity.

set_input_from_dict(inp_dict)

Set all necessary input_parameters from an input dictionary.

Parameters:

inp_dict (dict) –

Input dictonary with layer properties. Must contain all necessary keys (cannot be incomplete). Required keys are:

  • name

  • low_spc

  • upp_spc

  • spec_units

  • res

  • center_alt

  • thick

  • alt_upp

  • alt_low

  • emis

  • inp_tau

For explanation of each of those parameters please refer to the respective function which set them explicitly (set_{parameter name}).

set_name(name)

Assign a name to the layer.

Parameters:

name (str) – Layer name.

set_res(res)

Set spectral calculation grid resolution.

Parameters:

res (int, float) – Resolution of the spectral grid. Should be same units as values in set_spc_lim. This is not enforced, but is the only logically consistent option.

set_spc_lim(lo, hi)

Set spectral grid lower and upper limits.

Lo is the lower value and hi is the upper value, whatever the units. Units are then specified in set_spec_units, so this remains consistent with both wavenumbers and wavelengths.

Parameters:

  • lo (int, float) – Lower wavenumber or wavelength.

  • hi (int, float) – Upper wavenumber or wavelength.

set_spec_units(units)

Set spectral calculation grid units.

Parameters:

units (str) – Units. should be one of [\(\mu\)m, cm-1, nm]. This is not enforced but currently the rest of this package is unable to handle any other options.

set_tau(tau)

Set input layer optical depth.

Parameters:

tau (int, float) – Layer optical depth. The optical depth is uniform across all wavelengths (since this is class represents a grey body cloud).

set_thick(thick)

Set layer thickness (vertical extent).

Parameters:

thick (int, float) – Layer thickness (vertical extent), units [km].

test_complete_input_format()

Checks the input for correct format before running any calculation.

Tests all input variables. Creates a boolean value called passmark, which is initially False and if the test is passed, is changed to True and returned.

Returns:

passmark (bool) – If True, input has passed the format test.

Raises:

TypeError – Raised when test fails for each parameter separately.

test_input_values()

This function tests input values of the GreyBodyCloud class.

The tests written in this function are added as bugs are encountered. The test is far from exhaustive and the user is encouraged to sanity check their values independently. Creates a boolean value called passmark, which is initially False and if the test is passed, is changed to True and returned.

Returns:

passmark (bool) – If True, input has passed the format test.

Raises:

TypeError – Raised when test fails for each parameter separately.

track_regrid_diff(diff_type='pct')

Calculates the difference before and after interpolation.

Called by optical_properties.regrid().

Parameters:

diff_type (str) – “pct” (differences in percent from the old value) or “abs” (absolute difference)

Raises:

ValueError – Raised when diff_type is invalid.

class srfm.layer.Layer(name=None, **parameters)

Bases: object

Base superclass for an atmospheric layer.

class srfm.layer.MieLayer(name=None, **parameters)

Bases: Layer

Class that contains Mie scattering parameters, calculations and outputs.

Is subclass of Layer.

add_op_calc_output()

Assigns results from optical properties calculation as class attributes.

Takes results from optical properties calcualtion stored in a dictionary and assignes them as class attributes. This is a separate function so that when multiprocess is True, this step (adding results to class can be done after threads join in the main script in one command. This function deletes the original dictionary.

calc_grids()

Calculates spectral grids for the calculation of optical properties.

Calculates both wavelengths and wavenumbers.

calc_layer_extent()

This function attempts to calculate the layer vertical extent.

If layer center altitude and vertical extent are given, the lower and upper boundary altitudes are calculated. Else if lower and upper boundaries are given, the center altitude and vertical extent are calculated. All variables are in units [km].

Raises:

RuntimeError – Raised when inputs are insufficient.

calc_optical_properties()

Calculate optical layer properties.

Calls srfm.optical_properties_ewp_hs() to calculate extinction coefficient, single scatter albedo, phase function and (optional) Legendre polynomial coefficients.

Raises:

ValueError – Raised when multiprocess isn’t specified as attribute.

calc_size_distribution()

Calls functions to calculate the size distribution.

calc_tau()

Calculates optical depth from beta_ext and layer vertical extent.

Both beta_ext and layer boundary altitudes must be specified in the object instance.

calculate_op()

Used to calculate the optical properties for the MieLayer class.

The function calls specialized functions to perform the actual calculations.

The structure is the following:

  1. Checks the inputs consistency and format and calculates what is missing.

  2. Checks the inputs format (this is a little logically inconsistent because some checks must be performed in step one before missing properties are calculated).

  3. Calculate size distribution.

  4. Calculate spectral calculation grid.

  5. Calculate the optical properties, which are returned as class attributes.

Raises:

RuntimeError – Raised when input fails the format or input tests.

n_s_v()

Checks inputs for n, s or v.

Checks if particle either particle number concentration (n), surface area density (s_a_den) or v_den are set and calculates the missing of the three. Requires meand particle radius (r) and distribution spread (s) to be set. If none of the three are set, but particle mass loading (mass_loading) is set instead, n will be calculated from particle loading.

Raises:

RuntimeError – Raised when calculation fails due to insensible values.

nsv_or_ml()

Check input for size distribution.

Checks if either number concentration (n), surface area density (s_a_den) or volume density (v_den) are set or is mass loading (mass_loading) is set. The logic that s_a_den, v_den and n can be calculated from each other. mass_loading can be calculated from n and vice versa.

Raises:

RuntimeError – Raised if r and s are not set or if all values are missing.

plot_diff(**kwargs)

Plots difference in calcualted optical properties.

Instance must have differences in optical properties calculated and stored as _diff attributes. For further information see srfm.layer.track_regrid_diff().

Returns:

fig (obj) – fig object

regrid(wvls, track_diff=False, diff_type='pct')

Linearly interpolates calculated values from ewp_hs to a new grid.

Instance must have “beta_ext”, “ssalb”, “phase_function”, and “legendre_coefficient”.

Parameters:

  • wvls (aray-like) – new grid, units [\(\mu\)m]

  • track_diff (bool) – If True, calculates differences arising from interpolation.

Returns:

  • old attributes now as “_old”

  • new attributes “beta_ext”, “ssalb”, “phase_function” and

  • optional (“legendre_coefficient”)

  • difference between old and new attributes – “_diff” version of the new attributes

Raises:

ValueError – Raised when any wavelength array is not monotonic.

set_alt_lim(alt_low, alt_upp)

Set lower and upper layer boundary (altitudes).

Parameters:

  • alt_low (int, float) – Layer lower boundary altitude, units [km].

  • alt_upp (int, float) – Layer upper boundary altitude, units [km].

set_center_alt(center_alt)

Set average (center) particle layer altitude.

Parameters:

center_alt (int, float) – Center particle layer altitude, units [km].

set_comp(comp)

Set particle composition type.

Parameters:

comp (str) – One of accepted values by ARIA_module.get_ri_filepathname().

set_dist_type(dist_type)

Set particle size distribution type.

Parameters:

dist_type (str) – Particle size distribution type. Accepted values are lognormal and normal.

set_eta(eta=1e-06)

Set size distribution cut-off (eta value).

Parameters:

eta (int, float) – Size distribution cut-off value. The size distribution is a function that technically spans the (-inf,+inf) size interval. The eta value is a value of the size distribution beyond whose corresponding size (radius) the distribution is truncated. Default is 1e-6.

set_input_from_dict(inp_dict)

Set all necessary input_parameters from an input dictionary.

Parameters:

inp_dict (dict) –

Input dictonary with layer properties. Must contain all necessary keys (cannot be incomplete). Required keys are:

  • name

  • low_spc

  • upp_spc

  • spec_units

  • res

  • mass_loading

  • n

  • r

  • s

  • rho

  • s_a_den

  • v_den

  • dist_type

  • comp

  • center_alt

  • thick

  • alt_upp

  • alt_low

  • radii

  • eta

  • phase_quad_N

  • phase_quad_type

  • radii_quad_type

  • leg_coeffs

  • leg_coeffs_type

  • multiprocess

For explanation of each of those parameters please refer to the respective function which set them explicitly (set_{parameter name}).

set_leg_coeffs(leg_coeffs=True)

Toggle expansion of the phase fucntion into Legendre polynomials.

Parameters:

leg_coeffs (bool) – If True, Legendre polynomial expansion of the phase function is calculated by srfm.optical_properties.ewp_hs(). Default is True.

set_leg_coeffs_type(leg_coeffs_type='normalised')

Set type of requested Legendre polynomial expansion coefficients.

Parameters:

leg_coeffs_type (str) – Requested type of Legendre polynomial expansion coefficients. Accepted values are regular and normalised. Default is normalised.

set_mass_loading(load)

Set particle mass loading.

Parameters:

load (int, float) – Particle mass loading, units [g m-2].

set_multiproccess(multiprocess)

Toggle multiprocessing.

Parameters:

multiprocess (bool) – if True, then srfm.optical_properties.ewp_hs() is calculated in a separate subprocess. The output type of ewp_hs changes!!

set_n(n)

Set particle number concentration.

Parameters:

n (int, float) – Particle number concentration, units [cm-1].

set_name(name)

Assign a name to the layer.

Parameters:

name (str) – Layer name.

set_phase_quad_N(phase_quad_N=181)

Set number of points for the scattering quadrature.

The number of quadrature points is the number of scattering angles

Parameters:

phase_quad_N (int) – Number of quadrature points. Default is 181.

set_phase_quad_type(phase_quad_type='L')

Set quadrature type that will be used to calculate the phase fucntion.

Parameters:

phase_quad_type (str) – Quadrature type for the phase function. Accetped values are values implemented in the srfm.quadrature module. Currently implemented (Apr 2025) are “L” (Lobatto quadrature rule), “G” (Gauss), “R” (Radau) and “T” (Trapezium). Default is L.

set_r(r)

Set mean particle radius.

Parameters:

r (int, float) – Mean particle radius, units [\(\mu\)m]

set_radii(radii=200)

Set number of radii for size disitribution calculation.

Parameters:

radii (int) – Number of radii in size distribution. Default is 200.

set_radii_quad_type(radii_quad_type='T')

Set quadrature type for the calculation of the size distribution.

Parameters:

radii_quad_type (str) – Quadrature type for the radii calculation function. Accetped values are values implemented in the srfm.quadrature module. Currently implemented (Apr 2025) are “L” (Lobatto quadrature rule), “G” (Gauss), “R” (Radau) and “T” (Trapezium). Default is T.

set_res(res)

Set spectral calculation grid resolution.

Parameters:

res (int, float) – Resolution of the spectral grid. Should be same units as values in set_spc_lim. This is not enforced, but is the only logically consistent option.

set_rho(rho)

Set particle mean density.

Parameters:

rho (str, int, float) – Particle mean density units [kg m-3] or one of strings accepted by srfm.utilities.number_conc_from_mass_loading().

set_s(s)

Set particle size distribution spread.

Parameters:

s (int, float) – Particle size distribution spread.

set_s_a_den(s_a_den)

Set surface area density of the particles.

Parameters:

s_a_den (int, float) – Surface area density of the particles, units [\(\mu\)m2 cm-3].

set_spc_lim(lo, hi)

Set spectral calculation grid lower and upper limits.

Lo is the lower value and hi is the upper value, whatever the units. Units are then specified in set_spec_units, so this remains consistent with both wavenumbers and wavelengths.

Parameters:

  • lo (int, float) – Lower wavenumber or wavelength.

  • hi (int, float) – Upper wavenumber or wavelength.

set_spec_units(units)

Set spectral calculation grid units.

Parameters:

units (str) – Units. should be one of [\(\mu\)m, cm-1, nm]. This is not enforced but currently the rest of this package is unable to handle any other options.

set_thick(thick)

Set layer thickness (vertical extent).

Parameters:

thick (int, float) – Layer thickness (vertical extent), units [km].

set_v_den(v_den)

Set volume density of particles.

Parameters:

v_den (int, float) – Particle volume density, units [\(\mu\)m3 cm-3].

test_complete_input_format()

Checks the input for correct format before running any calculation.

Tests all input variables. Creates a boolean value called passmark, which is initially False and if the test is passed, is changed to True and returned.

Returns:

passmark (bool) – If True, input has passed the format test.

Raises:

TypeError – Raised when test fails for each parameter separately.

test_input_values()

This function tests input values of the MieLayer class.

The tests written in this function are added as bugs are encountered. The test is far from exhaustive and the user is encouraged to sanity check their values independently. Creates a boolean value called passmark, which is initially False and if the test is passed, is changed to True and returned.

Returns:

passmark (bool) – If True, input has passed the format test.

Raises:

TypeError – Raised when test fails for each parameter separately.

track_regrid_diff(diff_type='pct')

Calculates the difference before and after interpolation.

Called by optical_properties.regrid().

Parameters:

diff_type (str) – “pct” (differences in percent from the old value) or “abs” (absolute difference)

Raises:

ValueError – Raised when diff_type is invalid.

srfm.optical_properties module

Module for calculation of particle optical properties.

These are the extinction coefficient, scattering coefficient, scattering phase function and Legendre expansion coefficients for the phase function.

  • Name: optical_properties

  • Parent package: srfm

  • Author: Don Grainger

  • Contributors: Antonin Knizek

  • Date: 24 January 2025

srfm.optical_properties.calc_op_diff(first_dict, sec_dict, diff_type='pct', plot=True)

Calculates the difference between optical properties.

Used to get differences coming from different sources, i.e. one that’s calculated from ewp_hs at higher resolution and one that’s caluclated at lower resolution and interpolated. Assumes identical wavelength grids.

Parameters:

  • first_dict (dict) – dictionary with optical properties, op_dict from ewp_hs or equivalent

  • sec_dict (dict) – dictionary with optical properties, op_dict from ewp_hs or equivalent

  • diff_type (str) – Can be “pct” (differences in percent from the old value) or “abs” - absolute difference. Default is “pct”.

  • plot (bool) – If True, makes a plot.

Raises:

  • ValueError – Raised when a key is found in one dictionary that is missing from the other one (i.e. the two input dictionaries must have the same keys).

  • ValueError – Raised when incorrect value enountered in diff_type.

srfm.optical_properties.ewp_hs(wavelengths, composition, distribution, refractive_index=None, angle=None, legendre_coefficients_flag=False, legendre_coefficients_type='normalised', radii=200, eta=1e-06, phase_quad_N=181, phase_quad_type='L', radii_quad_type='T', return_dict=None, multiprocess=False)

Main function to calculate extinction, single scatter albedo and phase function.

The calculation is performed for a set of particles of given size distribution and compositon.

Parameters:

  • wavelengths (array-like) – wavelengths in \(\mu\)m

  • composition (str) – any of ash, sulphuric acid, ice or ARIA .ri filename

  • distribution (obj) – size distribution object from srfm.size_distribution module

  • refractive_index (array-like) – If compositon is “ri”, then refractive indices are required from the user. Default is None.

  • angle (array-like, float, int) – Scattering angles, if None, then phase function returned at (0,180) degrees with one degree spacing. Can’t be set when Legendre polynomial expansion of the phase function is requested (in the case quadrature angles are computed and used). Default is None.

  • legendre_coefficients_flag (bool) – If True, Legendre polynomial expansion of the phase function is performed and expansion coefficients are returned.

  • radii (int, float) – Number of radii of the particles in the distribution. Default is 200.

  • eta (float) – Cut-off number for the size distribution. Default is 1e-6.

  • legendre_coefficients_type (str) – Specifies the type of requested Legendre polynomial expansion coefficients. Can be normalised or regular. Default is normalised.

  • phase_quad_N (int) – Number of phase function moments (scattering angles), used when Legendre polynomial expansion requested. Default is 181.

  • phase_quad_type (str) – when Legendre polynomial expansion requested, this type of quadrature is used. Can be “G” (Gaussian), “R” (Radau) or “L” (Lobatto). Default is L.

  • radii_quad_type (str) – This type of quadrature is used to calculate the size distribution. Default is “T” (trapezium). Can be any quadrature accepted by srfm.quadrature module.

  • return_dict (multiprocess.Manager().dict()) – (optional) object to return values in when doing multiprocessing (parallel computations). Default is None.

  • multiprocess (bool) – If True, optical properties are calculated as a shell

  • different (subprocess and the output is)

Returns:

native_dict – Dictionary with calculated optical properties. Returned only if multiprocessing == False. Elif multiprocessing == True, returns an updated return_dict.

Raises:

ValueError – Raised when multiprocess has an invalid value.

srfm.optical_properties.get_quad(legendre_coefficients_flag=False, phase_quad_type='L', phase_quad_N=181, angle=None)

Calculates cosines of the angles to return the phase function at.

If Legendre expansion of the phase function is also requested (i.e. if legendre_coefficients_flag == True) the user angles are ignored. The quadrature points are calculated by the Quadrature module. There are several possible quadratures, here Lobatto is used by default and the angles are from 0 to 180 in steps of 1 degree. elif the Legendre expansion of the phase function is not required and angles are given, simply calculates the cosines, lastly, elif Legendre expansion is not needed and angles are not given, one angle is used. If angles are given, calculates the phase function at those angles otherwise use default 0 to 180 in steps of 1 degree (and flip).

Parameters:

  • legendre_coefficients_flag (bool) – If True, signifies that Legendre polynomial expansion is requested. Default is False.

  • angle (array-like, float, int) – Scattering angles. If None, then phase function returned at (0,180) degrees with one degree spacing. Can’t be set when Legendre polynomial expansion of the phase function is requested (in the case quadrature angles are computed and used). Default is None.

  • phase_quad_N (int) – Number of phase function moments (scattering angles). Used when Legendre polynomial expansion requested. Default is 181.

  • phase_quad_type (str) – when Legendre polynomial expansion requested, this type of quadrature is used. Can be “G” (Gaussian), “R” (Radau) or “L” (Lobatto). Default is L.

Returns:

  • cos_angle_value (array-like) – Cosines of scattering angle value of the quadrature.

  • cos_angle_weight (array-like) – Weight of the quadrature points.

  • angles (int) – Number of scattering angles (quarature points).

srfm.optical_properties.get_radii(distribution, eta=1e-06, radii_quad_type='T', radii=200)

Calculates the lower and upper particle radii from the distribution.

The upper and lower particle radii are calculated at points where \(n(r) = eta r_mode\). where eta is the cut-off and r_mode is the mode of the distribution.

Parameters:

  • distribution (obj) – An instance of srfm.size_distribution.SizeDistribution.

  • eta (int, float) – Size distribution cut-off value. The size distribution is a function that technically spans the (-inf,+inf) size interval. The eta value is a value of the size distribution beyond whose corresponding size (radius) the distribution is truncated. Default is 1e-6.

  • radii_quad_type (str) – Quadrature type for the radii calculation function. Accetped values are values implemented in the srfm.quadrature module. Currently implemented (Apr 2025) are “L” (Lobatto quadrature rule), “G” (Gauss), “R” (Radau) and “T” (Trapezium). Default is T.

  • radii (int) – Number of radii in size distribution. Default is 200.

Returns:

  • radius (array-like) – size distribution quadrature points

  • radius_weight (array-like) – quadrature weights

  • red_wt_sum (float) – sum of radius_weight, used to normalize relevant sums in the code.

srfm.optical_properties.get_ri(composition, refractive_index=None, wave=None, wave_size=None)

Load refractive indices.

Indices expected in the form (n - ik).

Parameters:

  • composition (str) – One of accepted values by ARIA_module.get_ri_filepathname().

  • refractive_index (array-like) – If compositon is “ri”, then refractive indices are required from the user. Default is None.

  • wave (array-like) – Wavelength grid. Default is None.

  • wave_size (int) – size of wave (equal to len(wave) is wave is list or 1D array and wave.size if wave is an array).

Returns:

refractive_index_arr (array-like) – Array of refractive indices. dtype complex.

Raises:

  • RuntimeError – Raised when composition is “ri”, but refractive index is not given.

  • ValueError – Raised when and imaginary part of a refractive index is > 0, because indices are expected in the form (n - ik).

srfm.optical_properties.legendre_polynomial_expansion(inp, qv, qw, phase)

Expands a function as a Legendre series.

The function is assumed to have been evaluated at Legendre quadrature points. The evaluation stops when the number of terms exceeds the number of quadrature points or when the absolute value of the Legendre coefficient is less than 1e-9. Uses the Bonnet’s recusion formula to generate the Legendre polynomials.

Parameters:

  • inp (int) – Number of points at which the phase function is evaluated.

  • qv (array-like) – Legendre points (points at which the phase function is evaluated, quadrature points).

  • qw (array-like) – Legendre weights, same shape as qv.

  • phase (array-like) – Input (phase) function.

Returns:

  • lc (array) – Legendre coefficients.

  • inlc (int) – Number of coefficients used.

Raises:

ValueError – Raised when >10,000 quadrature points requested.

srfm.optical_properties.loop_mie_over_radii(radii, sp, ri, angles, cos_angle_value)

Calculate the Mie scattering for a given wavelength over a range of radii.

Parameters:

  • radii (int) – Number of size distribution quadrature radii.

  • sp (array-like) – Array of size parameters.

  • ri (array-like) – Array of refractive indices.

  • angles (int) – Number of scattering angles (quadrature points).

  • cos_angle_value (array-like) – Cosines of scattering angles at which to calculate the scattering properties, comes from quadrature.

Returns:

  • Q_ext_value (array) – Extinction coefficients array, shape (radii,).

  • Q_sca_value (array) – Scattering coefficients array, shape (radii,).

  • phase_function_value (array) – Phase function array, shape (radii, angles).

srfm.optical_properties.loop_mie_over_wavelengths(wavelengths_size, radii, size_parameters, refractive_index_arr, angles, cos_angle_value, cos_angle_weight, radius_weight, radius, rad_wt_sum, legendre_coefficients_flag, legendre_coefficients_type, beta_ext, beta_sca, phase_function, legendre_coefficient)

Main computational loop for srfm.optical_properties.ewp_hs().

Loops over wavelengths and calcualtes optical properties.

Parameters:

  • wavelengths_size (int) – Number of wavelengths to loop over.

  • radii (int, float) – Number of radii of the particles in the distribution. Default is 200.

  • size_parameters (array-like) – Array of size parameters.

  • refractive_index_arr (array-like) – Array of refractive indices. dtype complex.

  • angles (int) – Number of scattering angles (quarature points).

  • cos_angle_value (array-like) – Cosines of scattering angle value of the quadrature.

  • cos_angle_weight (array-like) – Weight of the quadrature points.

  • radius (array-like) – size distribution quadrature points

  • radius_weight (array-like) – quadrature weights

  • red_wt_sum (float) – sum of radiu_weight, used to normalize relevant sums in the code.

  • legendre_coefficients_flag (bool) – If True, Legendre polynomial expansion of the phase function is performed and expansion coefficients are returned.

  • legendre_coefficients_type (str) – Specifies the type of requested Legendre polynomial expansion coefficients. Can be normalised or regular. Default is normalised.

  • beta_ext (array) – Empty array to store extinction coefficient in, shape (wavelengths_size,).

  • beta_sca (array) – Empty array to store extinction coefficient in, shape (wavelengths_size,).

  • phase_function (array) – Empty array to store the phase function in, shape (wavelengths_size, angles).

  • legendre_coefficient (array) – Empty array to store Legendre coefficients in, shape (wavelengths_size, _), where the second dimension is big enough to contain the Legendre coefficients. This needs to be guessed and eventually adapted by the user, because if the wavelengths_size is too big, then the total array size can cause overflows in memory. It is possible to use srfm.utilities.memory_safe_np_zeros_2d() to generate a 2D array with dimensions adapted to not overflow the available memory, but be advised that this may cause the array to have the second dimension too small, resulting in truncation of Legendre coefficients and loss of precision. Will not cause problems on high-RAM stations. Mind that in a np.zeros array the default data type is np.float64, which has a size of 8 bytes. The array size is number of elements*8 in bytes.

Raises:

ValueError – Raised when invalid input into legendre_coeffs_type is detected.

srfm.optical_properties.mie_ewp(Dx, SCm, Dqv)

Mie calculation (python version).

Parameters:

  • Dx (float) – Particle size parameter.

  • SCm (complex) – Particle refractive index.

  • Dqv (array-like) – Cosines of the scattering angles.

Returns:

  • Dqxt (float) – Extinction coefficient.

  • Dqsc (float) – Scattering coefficient.

  • pf (array) – Phase function.

Raises:

ValueError – Raised when size parameter greater than 105000 or when Nmx > Itermax.

srfm.optical_properties.normalised_legendre_polynomial_expansion(inp, qv, qw, phase)

Expands a function as a Legendre series.

The function is assumed to have been evaluated at Legendre quadrature points. The evaluation stops when the number of terms exceeds the number of quadrature points or when the absolute value of the Legendre coefficient is less than 1e-9. Uses the Bonnet’s recusion formula to generate the Legendre polynomials. Uses normalised Legendre polynomial coefficients (as in Wiscombe 1977).

Parameters:

  • inp (int) – Number of points at which the phase function is evaluated.

  • qv (array-like) – Legendre points (points at which the phase function is evaluated, quadrature points).

  • qw (array-like) – Legendre weights, same shape as qv.

  • phase (array-like) – Input (phase) function.

Returns:

  • lc (array) – Legendre coefficients.

  • inlc (int) – Number of coefficients used.

Raises:

ValueError – Raised when >10,000 quadrature points requested.

srfm.optical_properties.phase_from_legendre(inlc, lc, inp, qv)

Recomputes the phase function from Legendre polynomial expansion.

Parameters:

  • inlc (int) – Number of Legendre coefficients.

  • lc (array-like) – Legendre expansion coefficients.

  • inp (int) – Number of quadrature value, == number of angles.

  • qv (array-like) – Cos(angles).

Returns:

phase (array) – Recomputed phase function.

srfm.optical_properties.phase_from_normalised_legendre(inlc, lc, inp, qv)

Recomputes the phase function from Legendre polynomial expansion.

Parameters:

  • inlc (int) – Number of Legendre coefficients.

  • lc (array-like) – Normalised Legendre expansion coefficients.

  • inp (int) – Number of quadrature value, == number of angles.

  • qv (array-like) – Cos(angles).

Returns:

phase (array) – Recomputed phase function.

srfm.optical_properties.plot_diff_dict(diff_dict, **kwargs)

Plots diff_dict - difference in calcualted optical properties.

Parameters:

diff_dict (dict) – Dictionary with differences in optical properties, comes e.g. from calc_op_diff or track_regrid_diff.

Returns:

fig (object) – Figure object.

srfm.optical_properties.regrid(op_dict, wvls, track_diff=False, diff_type='pct')

Linearly interpolates calculated values from ewp_hs to a new grid.

Parameters:

  • op_dict (dict) –

    output from srfm.optical_properties.ewp_hs. Should have keys:

    • beta_ext

    • ssalb

    • phase_function

    • legendre_coefficient

    • wavelengths

    If ewp_hs changes in the future, this function needs to change as well.

  • wvls (array-like) – new grid, [\(\mu\)m]

  • track_diff (bool) – If True, calculates differences arising from interpolation

Returns:

  • op_dict (dict) – New version of op_dict on a new grid.

  • diff_dict (dict) – Difference between the interpolated and non-interpolated dictionaries. Same keys as op_dict.

Raises:

  • RuntimeError – Raised when invalid key encountered in op_dict.

  • ValueError – Raised when wavelength grid is not monotonic.

srfm.optical_properties.track_regrid_diff(old_dict, new_dict, diff_type='pct')

Calculates the difference before and after interpolation.

Called by optical_properties.regrid().

Parameters:

  • old_dict (dict) – op_dict before interpolation.

  • new_dict (dict) – op_dict after interpolation.

  • diff_type (str) – Can be “pct” (differences in percent from the old value) or “abs” - absolute difference. Default is “pct”.

Raises:

ValueError – Raised when invalid diff_type encountered.

srfm.plotting module

Provides functions useful for plotting data that are not default in python.

  • Name: plotting

  • Parent package: srfm

  • Author: Antonin Knizek

  • Contributors:

  • Date: 18 February 2025

srfm.plotting.map_extent(center_lon, center_lat, lon_span, lat_span)

Calculates cartopy map extent.

Calculation performed from a known centrepoint coordinates + span on each side. Units decimal degrees. Remember that central_longitude of the projection is now your 0.

Parameters:

  • center_lon (float) – Centrepoint longitude.

  • center_lat (float) – Centrepoint latitude.

  • lon_span (float) – Longitude span.

  • lat_span (flaot) – Latitude span.

Returns:

l (list of float) – list containing [longitude minimum, longitude maximum, latitude minimum, latitude maximum].

srfm.quadrature module

Calculates quadrature points.

Can do Gaussian, Lobatto, Radau, and Trapezium quadratures.

  • Name: quadrature

  • Parent package: srfm

  • Author: Don Grainger

  • Contributors: Antonin Knizek

  • Date: 24 January 2025

srfm.quadrature.bessel_zero(s)

Calculates BesselZero.

Parameters:

s (float) –

?

Returns:

bslz (float) – ?

srfm.quadrature.first_guess(quad_type, n, term)

Function to calculate first guess of the abscissa points.

Parameters:

  • quad_type (str) – Quadrature type. Accepted values are “G” (Gaussian), “R” (Radau), and “L” (Lobatto).

  • n (float) –

    ?

  • term (float) –

    ?

Returns:

fg (float) – First guess of the abscissa points.

srfm.quadrature.legendre(n, x)

Calculate the Legenedre polynomials using Bonnet’s recursion formula.

Parameters:

  • n (int) – number of points in the quadrature

  • x (float) – specific point in the quadrature

Returns:

  • pl (float) – Legendre polynomial \(P_{n-2}(x)\).

  • pm (float) – Legendre polynomial \(P_{n-1}(x)\).

  • pn (float) – Legendre polynomial \(P_{n}(x)\).

srfm.quadrature.newton_g(quad_type, n, x)

Performs Newton correction on the abscissa.

Parameters:

  • quad_type (str) – Quadrature type. Accepted values are “G” (Gaussian), “R” (Radau), and “L” (Lobatto).

  • n (float) –

    ?

  • x (float) –

    ?

Returns:

srfm.quadrature.quadrature(quad_type, n_pts, lower_bound, upper_bound)

Calls the appropriate quadrature function.

First calls a function to calculate the quadrature on a [-1,1] interval, then shifts the calculated quadrature and weigths.

Parameters:

  • quad_type (str) – Quadrature type. Accepted values are “G” (Gaussian), “R” (Radau), “L” (Lobatto), “T” (Trapezium), “S” (Simpson).

  • npts (int) – Number of abscissa points.

  • lower_bound (float) – Lower bound of the new interval.

  • upper_bound (float) – Upper bound of the new interval.

Returns:

  • abscissa_new (array) – New, shifted abscissa

  • weight_new (array) – New, shifted weights.

srfm.quadrature.quadrature101(quad_type, npts)

Asign npts abscissae and weights for integration on the interval [-1,1] for a variety of quadrature types.

Parameters:

  • quad_type (str) – Quadrature type. Accepted values are “G” (Gaussian), “R” (Radau), “L” (Lobatto), “T” (Trapezium), “S” (Simpson).

  • npts (int) – Number of abscissa points.

Returns:

  • abscissa (array) – Calculated abscissa.

  • weight (array) – Corresponding weights.

srfm.quadrature.shift_quadrature(abscissa, weight, lower_bound, upper_bound)

Shifts quadrature abscissa and weight.

Shifts from the interval [-1, 1] to [lower_bound, upper_bound].

Parameters:

  • abscissa (array) – Quadrature points on the interval [-1, 1].

  • weight (array) – Quadrature weight on the interval [-1, 1].

  • lower_bound (float) – Lower bound of the new interval.

  • upper_bound (float) – Upper bound of the new interval.

Returns:

  • new_abscissa (array) – New, shifted abscissa

  • new_weights (array) – New, shifted weights.

srfm.rfm_functions module

Provides functions that enable the user to work with RFM.

  • Name: rfm_functions

  • Parent package: srfm

  • Author: Antonin Knizek

  • Contributors:

  • Date: 18 February 2025

srfm.rfm_functions.compile_rfm(fldr)

Compiles RFM.

Parameters:

fldr (str) – Path to RFM folder (absolute or relative).

Raises:

OSError – Raised when directory is invalid.

srfm.rfm_functions.construct_rfm_driver_table(inp, fldr, force=True, **kwargs)

Constructs RFM driver table.

The table is a text file saved to fldr.

Parameters:

  • inp (dict) – Dictionary containing RFM driver table inputs.

  • fldr (str) – Path to RFM-containing folder.

  • force (bool) – If True, overwrites the current driver table. If False, save a copy of the old table first.

srfm.rfm_functions.construct_rfm_grid_file(wvnm, filename='grid.spc', rfm_fldr='./srfm/RFM')

Creates a grid.spc file for rfm.

The file is saved in rfm_fldr with the required filename.

RFM is run in the “irregular grid mode” where the SPC section in the driver table contains the filename of this file.

Parameters:

  • wvnm (array-like) – Wavenumbers, the calculation grid.

  • filename (str) – The output filename. Default is “grid.spc”.

  • rfm_fldr (str) – Path to RFM folder. Default is “./srfm/RFM”.

Raises:

TypeError – Raised when any of the input values have incorrect dtype.

srfm.rfm_functions.construct_rfm_output_levels_file(levels, fldr, fname='alts.lev', force=True)

Construct the levels file for RFM - specifies output levels.

Mind that the LEV flag for RFM must be enabled, or else this file will be ignored. Mind that the filename must be passed to RFM in the LEV section of the RFM driver table. A text file is created and saved with the required fname in fldr.

Parameters:

  • levels (array-like) – Required output levels. Doesn’t have to be sorted.

  • fldr (str) – output folder path

  • fname (str) – Required output filename, Default is “alts.lev”.

  • force (bool) – If True, overwrite current levels file, else saves a copy first.

Raises:

  • TypeError – Raised when levels has incorrect type.

  • ValueError – Raised when levels is an array, but has more than one dimension.

  • TypeError – Raised when fname is not a string.

  • FileNotFoundError – Raised if fldr does not exist.

  • ValueError – Raised when force is not bool.

srfm.rfm_functions.get_rfm_optical_depths(fldr, levels)

Calculates layer optical depths from RFM output.

This function is designed to calculate optical depths for layers in the atmosphere from RFM with the LEV and OPT flags set on. The basic idea is to load optical depth spectra and subtract the adjacent ones to get layer optical depth.

Parameters:

  • fldr (str) – Path to RFM folder.

  • levels (list) – levels to derive the layers from. The RFM can be output at more levels than necessary (which happens when internal RFM levels don’t match the required output levels, i.e. most of the time).

Returns:

df (Pandas.core.frame.Dataframe) – Pandas dataframe with the calculated layer optical depths and atmospheric structure.

Raises:

  • ValueError – Raised when the pressure profile read from prf.asc and the number of files don’t match. This is often invoked when some input parameters are changed, but RFM is not rerun.

  • ValueError – Raised when wavenumber grids for adjacent levels don’t match.

  • ValueError – Raised when delta_OD (layer optical depth) and int_OD (integrated optical depth) don’t match.

  • ValueError – Raised when the length of the wavenumber grid and delta_OD array don’t match.

srfm.rfm_functions.read_atm_file(filename)

This function reads the RFM .atm file.

Parameters:

filename – Path to RFM-format .atm filename.

Returns:

contents (dir) – Dictionary with the file contents.

Raises:

TypeError – Raised when a section label is not a string. Indicates that the file was not corectly read.

srfm.rfm_functions.read_output(filename)

Read output file from RFM into a dictionary.

Parameters:

filename (str) – rfm output file filename.

Returns:

contents (dict) – Dictionary containing RFM outputs. Contains the key “info”, which is a dictionary with the description of other parameters.

srfm.rfm_functions.read_output_prf(filename)

This function reads the RFM output profile prf.asc.

Parameters:

filename (str) – path, including filename, of the RFM prf.asc output file (and equivalents if that ever changes from the current RFM default).

Returns:

contents (dict) – Dictionary that stores the read values. Keys are section headers from the prf.asc file.

srfm.rfm_functions.write_atm_file(data, filename, header=None)

Write out a file with atmospheric profile in RFM’s .atm file format.

Saves an .atm file in the with the specified name.

Parameters:

  • data (dictionary) – Data to be written to the file.

  • filename (str) – Filename for the output file (has to be a path).

  • header (str) – Header for the file, optional, each line starts with “!”. Default is None.

srfm.size_distribution module

Creates or returns properties of a particle size distribution.

  • Name: size_disitribution.py

  • Parent package: srfm

  • Author: Don Grainger

  • Contributors: Antonin Knizek

  • Date: 3 January 2025

Units:

  • Particle size is expressed in \(\mu\)m.

  • The distribution (n) is in number per \(\mu\)m per cm3.

Integrated values are:

  • Number density is in number per cm3.

  • Surface area density is in \(\mu\)m2 cm-3.

  • Volume density is in \(\mu\)m3 cm-3.

class srfm.size_distribution.GaussianDistribution(n=None, r=None, s=None, surface_area_density=None, volume_density=None)

Bases: SizeDistribution

Creates a Gaussian distribution. NOT IMPLEMENTED

mean()

Calculate the mean of the distribution.

class srfm.size_distribution.LogNormalDistribution(n=None, r=None, s=None, surface_area_density=None, volume_density=None)

Bases: SizeDistribution

Creates a log-normal distribution.

Note although the distribution is usually defined by n, r & s, the code allows the distribution to be set via the surface area density and volume density.

Parameters:

  • n (int, float) – Concentration total particles per cm3. Default is None.

  • r (int, float) – Median radius, units [\(\mu\)m]. Default is None.

  • s (int, float) – Geometric standard deviation (spread). Default is None.

  • surface_area_density (int, float) – Surface area density of the particles, units [\(\mu\)m2 cm-3]. Default is None.

  • v_den (int, float) – Particle volume density, units [\(\mu\)m3 cm-3]. Default is None.

Raises:

  • ValueError – Raised when any of the input parameters is < 0.

  • ValueError – Raised if an invalid combination of parameters is used. Valid combinations are r, s and one of n, surface_area_density and volume_density.

mean()

Calculates mean of the distribution.

value(radii)

Evaluates the size distribution at given radii.

Parameters:

radii (int, float, aray-like) – Particle radius/radii at which the distribution is evaluated.

Returns:

val (float, array-like) – Value of the size distribution at given radius/radii.

class srfm.size_distribution.SizeDistribution(type)

Bases: ABC

Base class for size distributions.

abstractmethod mean()

Calculate the mean of the distribution.

srfm.size_distribution.create_distribution(dist_type, **kwargs)

Selector function for the size distribution.

Takes in distribution type and creates an instance of the appropriate class.

Parameters:

dist_type (str) – Distribution type, currently accepted values are log_normal and gaussian.

Raises:

ValueError – Raised when unknown dist_type is used.

srfm.units module

Provides functions for unit conversion.

  • Name: units

  • Parent package: srfm

  • Author: Antonin Knizek

  • Contributors:

  • Date: 18 February 2025

srfm.units.DU_to_col_den(du)

Convert a value in Dobson units to molecues m -2.

Parameters:

du (float) – Value in Dobson units.

Returns:

col_den (float) – Value in molecues m -2.

Raises:

TypeError – Raised when input is not int or float.

srfm.units.decimal_degree_to_DMS(dec)

Convert a value in decimal degrees to degree-minute-seconds.

Parameters:

dec (int, float) – Value in decimal degrees.

Returns:

dms (tuple of ints) – Tuple containing the result as (degrees, minutes, seconds).

srfm.units.inv_cm_to_micron(wavenumber)

Convert wavenumber in cm-1 to wavelength in micrometers.

Parameters:

wavenumber (int, float) – Wavenumber value, units [cm-1].

Returns:

um (float) – Wavelength value, units [\(\mu\)m].

srfm.units.inv_cm_to_nm(wavenumber)

Convert wavenumber in cm-1 to wavelength in nanometers.

Parameters:

wavenumber (int, float) – Wavenumber value, units [cm-1].

Returns:

nm (float) – Wavelength value, units [nm].

srfm.units.micron_to_inv_cm(wavelength)

Convert wavelength in \(\mu\)m to wavenumber in cm-1.

Parameters:

wavelength (float) – Wavelength value, units [\(\mu\)m].

Returns:

wvnm (int, float) – Wavenumber value, units [cm-1].

srfm.units.nm_to_inv_cm(wavelength)

Convert wavelength in nm to wavenumber in cm-1.

Parameters:

wavelength (float) – Wavelength value, units [nm].

Returns:

wvnm (int, float) – Wavenumber value, units [cm-1].

srfm.utilities module

Provides functions for srfm that do not fall in any other category.

Contains e.g. decorator functions, memory-safe declarations, some physical formulas, etc.

  • Name: utilities

  • Parent package: srfm

  • Author: Antonin Knizek

  • Contributors:

  • Date: 18 February 2025

srfm.utilities.add_lyr_from_Layer(lev, track_lev, new_lyr)

Adds a layer to an existing atmoshperic level structure.

Used to add layer properties from the srfm.layer.Layer() object Deletes any levels from the existing structure that would fall within the new layer. Updates a tracking array.

Parameters:

  • lev (list) – List of current layers.

  • track_lev (list) – Helper list to track inserted levels, None for all levels except those inserted from a scattering layer.

  • new_lyr (obj) – srfm.Layer.MieLayer object, which contains upper and lower layer boundary altitudes, alt_upp and alt_low.

Returns:

  • lev (list) – New atmospheric level structure.

  • track_lev (list) – Modified tracker list for level structure. None for all user specified levels, layer upper and lower boundary specifiers (MieLayer.name) for the new inserted levels.

srfm.utilities.calc_Rayleigh_opt_depths(ps, pl, pu, l)

Calculates optical depths from Rayleigh scattering.

Parameters:

  • ps (int, float) – Surface pressure.

  • pl (int, float) – Layer lower boundary pressure.

  • pu (int, float) – Layer upper boundary pressure.

  • l (int, float) – Wavenumber, [cm-1].

Returns:

tau_r (float) – Rayleigh optical depth.

srfm.utilities.calc_grids(lo, hi, res, units)

Calculates spectral grids.

Grids are calculated from a given lower and upper limit and resolution in given units. The output grids are regular in the input units.

Parameters:

  • lo (int, float) – Grid lower limit.

  • hi (int, float) – Grid upper limit.

  • res (int, float) – Grid resolution.

  • units (str) – Units of input parameters, can be “cm-1”, “nm”, or “\(\mu\)m”.

Returns:

  • wvnm (array) – Wavenumber grid, units [cm-1].

  • wvls (array) – Wavelength grid, units [\(\mu\)m].

Raises:

  • TypeError – Raised if inputs are incorrect dtypes.

  • ValueError – Raised if units is an unknown value.

  • ValueError – Raised if lo and hi exceed prescribed limits. The limits are set to match the limits of RFM.

srfm.utilities.calc_layer_bounds(u, l)

Calculate atmospheric layer center altitude and vertical extent.

Parameters:

  • u (int, float) – Upper boundary altitude.

  • l (int, float) – Lower boundary altitude.

Returns:

  • a (int, float) – Altitude of the center of the layer.

  • t (int, float) – Layer thickness.

Raises:

  • TypeError – Raised if inputs are incorrect dtype.

  • ValueError – Raised when input lower boundary is greated than the upper boundary.

srfm.utilities.calc_layer_extent(a, t)

Calculates the upper and lower boundary of a layer (e.g. aerosol layer).

Input and output units match.

Parameters:

  • a (int, float) – Altitude of the center of the layer.

  • t (int, float) – Layer thickness.

Returns:

Upper boundary altitude. l (int, float): Lower boundary altitude.

Return type:

u (int, float)

Raises:

TypeError – Raised if inputs are incorrect dtype.

srfm.utilities.calc_layer_opt_thick_Rayleigh(pl, pu, ps, tau0)

Calculates one layer optical thickness from Rayleigh scattering.

Formula from to Don, put ref here. The calculation formula is

\[\begin{eqnarray} \Delta \tau_R(\lambda,p_u,p_l) = \tau_0 \frac{(p_l-p_u)}{p_s} \end{eqnarray}\]
where:

  • \(\Delta \tau_R(\lambda,p_u,p_l)\) is the layer optical depth as a function of wavelength and layer upper and lower boundary pressures.

  • \(\tau_0\) is the total atmospheric Rayleight optical depth.

  • \(p_u, p_l\) are the layer upper and lower boundary pressures.

  • \(p_s\) is the surface pressure.

Parameters:

  • pl (int, float, array-like) – Layer bottom boundary pressure.

  • pu (int, float, array-like) – Layer upper boundary pressure.

  • ps (int, float) – Surface pressure.

  • tau0 (int, float) – total atmospheric Rayleigh optical depth.

Returns:

tau (float) – Layer Rayleigh optical depth.

srfm.utilities.calc_tot_Rayleigh_opt_depth(ps, l)

Calculates total atmospheric Rayleigh optical depth.

That is the optical Rayleight optical depth of the whole atmosphere. Formula from: (according to Don, put ref here)

Parameters:

  • ps (int, float) – Surface pressure in hPa/mbar.

  • l (int, float) – Wavelength in micrometers.

Returns:

tau (float) – Total Rayleigh optical depth.

srfm.utilities.calc_tot_dtauc(tau_g, tau_R, tau_p)

Calculate total optical depth of model layers.

Formula is:

\[\Delta \tau = \tau_g + \tau_R + \tau_p\]
where:

  • \(\Delta \tau\): Layer optical depth.

  • \(\tau_g\): Layer optical depth from gas absorption.

  • \(\tau_R\): Layer optical depth from Rayleigh scattering.

  • \(\tau_p\): Layer optical depth from particle scattering.

Parameters:

  • tau_g (int, float, array-like) – Layer optical depth from gas absorption.

  • tau_R (int, float, array-like) – Layer optical depth from Rayleigh scattering.

  • tau_p (int, float, array-like) – Layer optical depth from particle scattering.

Returns:

dtau (float, array-like) – Layer optical depths.

srfm.utilities.closest(lst_lon, lon, lst_lat, lat)

Find index of closest pixel to lon and lat from IASI L1c data.

Originally written to work with IASI data. IASI data are spectra which are taken at given longitude and latitude. This function takes in longitude and latitude from the user and finds an IASI spectrum closest to the query.

Can be used in general to find a pair of values closest to an existing pair in two list/2D array.

Note that this function exists because the longitude and latitude lists are attributes of a pixel and tue purpose is to find a closest pixel, i.e. it is not equal to finding a minimum in each of the two lists, but rather is about finding a pixel whose distance is minimum to the required (lon, lat).

Parameters:

  • lst_lon (array-like) – List of longitudes.

  • lon (int, float) – User-specified longitude.

  • lst_lat (array-like) – List of latitudes.

  • lat (int, float) – User-specified latitudes.

Returns:

ii (int) – Index of closest pixel. The longitude and latitude value of this pixel are simply lst_lon[ii] and lst_lat[ii], respectively.

srfm.utilities.convert_spectral_radiance_to_bbt(B, v)

Converts intensity (spectral radiance) to brightness temperature.

Calculated according to:

\[T_{BB} = \frac{h c \nu}{k_b \ln{(1 + \frac{2 h c^2 \nu^3}{B(T,\nu)})}}\]
where:

  • \(B(T,\nu)\): Intensity, spectral radiance, units [W m-2 sr-1 cm ], equiv. to [ kg s-3 sr-1 cm ].

  • \(T_{B}\): Brightness temperature (equiv. blackbody temperature), units [K].

  • h: Planck constant, 6.62607015 \(\times 10^{-34}\) kg m2 s-1.

  • c: speed of light, 2.99792458 \(\times 10^{10}\) cm s-1.

  • \(k_b\): Boltzmann constant, 1.380649 \(\times 10^{-19}\) kg cm2 s-2 K-1.

  • \(\nu\): Wavenumber, units [cm-1].

This expression was derived from Dudhia 2017, eq. 25 (and equally eq. 23).

Parameters:

  • B (int, float) – Intensity, spectral radiance, units [ W m-2 sr-1 cm ]. Note that the ‘cm’ comes from the intensity being per cm-1, i.e. \(\frac{1}{cm^{-1}}\).

  • v (int, float) – Wavenumber, units [cm-1].

Returns:

T (float) – Brightness temperature (equivalent black body temperature), units [K].

srfm.utilities.convolve_spectrum(spc, x, ils)

Convolves a calculated spectrum with an instrument line shape.

Note that the convolved spectrum suffers from boundary effects (scipy interpolate does zero padding of the data at the boundaries). Best avoided by calculating your original spectra at a wider interval and then interpolating/truncating. For interpolation (best used to get spectra at your simulated satellite grid).

Parameters:

  • spc (array-like) – Spectrum to be convolved. Could be as short as single value.

  • x (array-like) – Spectral grid (wavenumbers/wavelengths/..). Must be regularly spaced.

  • ils (str,) –

    Path to the instrument line shape. Make sure the units of the ils and spectrum grids are identical. If the file extension is .atm, then the file is assumed to be and RFM-formatted .atm file.

    If the file is in any other format, then the file is read through numpy.loadtxt, so must conform to that format with the first column being the grid and the second column the intensity/radiance.

Returns:

spc_conv (array-like) – Convolved spectrum.

srfm.utilities.find_prime_factors(num)

Find prime factors of a number.

Parameters:

num (int) – Input number.

Returns:

factors (list) – List of prime factors of num.

srfm.utilities.get_altitude_prf(p, T, z0=0, M=28.97, g=9.81)

Calculates atmospheric altitude profile given pressure and temperature profiles.

Manually integrates/sums the hydrostatic equation (using ideal gas law) to calculate atmospheric altitude profile given pressure and temperature profiles.

Calculation derived from a combination of:

..math:

p = z \rho g

and

..math:

p V = \frac{m R T}{M}
where:

  • \(p\): atmospheric pressure (Pa)

  • \(z\): altitude (m)

  • \(\rho\): air density

  • \(g\): gravity (\(m s^{-2}\))

  • \(M\): air molar mass (\(g mol^{-1}\))

  • \(R\): universal gas constant, \(8.314 J K mol^{-1}\)

  • \(V\): gas volume

  • \(T\): tempeature (K)

  • \(m\): mass (g)

The final calculation formula is then:

..math:

z_{i+1} = - \frac{\ln(\frac{p_{i+1}}{i}) R \frac{T_i + T_{i+1}}{2}}{M g} + z_i
Parameters:

  • p (list) – Atmospheric pressure profile, units [Pa]. Expected sorted from lower to higher altitudes.

  • T (list) – Atmospheric temperature profile, units [K]. Expected sorted from lower to higher altitudes.

  • z0 (float) – Surface altitude. Units [m]. Default is 0.

  • M (float) – Air molar mass. Units [\(g mol^{-1}\)]. Default is \(28.97 g mol^{-1}\). Note that air molar mass is considered independent of altitude (is constant). THis formula therefore fails above the homopause.

  • g (float) – Gravity. Units \(m s^{-2}\). Default is \(9.81 m s^{-2}\). Note that gravity is independent of altitude in this calculation.

Returns:

alt (list) – Atmospheric altitude profile. Units [km].

srfm.utilities.line_break_str(txt, chars, delim, indent=0)

This function adds line breaks at desired places in a string.

The original intention of this function is to ensure that no string is longer than {chars} characters for the RFM driver table, whose line length is limited to 200 characters. The function takes in a string txt, and finds the nearest lower occurence of the required delimiter. It then adds indent spaces and a line end character, so that if written to a txt file, the lines do not exceed chars characters.

Parameters:

  • txt (str) – String to be split

  • chars (int) – Number of character allowed per one line.

  • delim (str) – Character to split the string at.

  • indent (int) – The amount of spaces placed at the beginning of each split section. Default is 0.

Returns:

fin (str) – New string with line breaks inserted in appropriate places.

Raises:

TypeError – Raised when inputs are incorrect datatypes.

srfm.utilities.load_solar_spectrum_Gueymard20018()

Loads and converts solar spectrum from Gueymard 2018.

srfm.utilities.mass_loading_from_number_conc(n, thick, rho, s, dist_type, r=None, d=None)

Calculate particle mass loading from number concentration.

Either r or d has to be given.

Parameters:

  • n (int, float) – Particle number concentration, units [particles cm-3].

  • rho (int, float, str) –

    Particle density, units [kg m-3]. Uniform density is assumed. Can be either a value in [kg m-3] or one of the following strings:

    • ”pumice” - 950 kg m-3

    • ”glass” - 2400 kg m-3

    • ”mineral” - 3000 kg m-3

    • ”rock” - 2900 kg m-3

    Note that the densities are average densities from the USGS VAI.

    They in turn cite Shipley and Sarna_Wojcicki (1982).

    The same information is also repeated in Wilson et al. (2012).

    Using the strings should serve only an illustrative purpose and should not be relied on as the data in a given eruption may vary!

  • thick (int, float) – Particle layer thickness, units [km].

  • s (int, float) – Lognormal distribution spread. Default is None.

  • dist_type (str) – Size distribution type. If None, then a monodisperse distribution is implied and parameter s is not used. Other permitted value is “lognormal”. Default is None.

  • r (int, float) – Particle radius, units [\(\mu\)m]. Default is None.

  • d (int, float) – Particle diameter, units [\(\mu\)m], Default is None.

Returns:

l (int, float) – Particle column mass loading, units [g m-2].

Raises:

  • TypeError – Raised if inputs are incorrect format.

  • ValueError – Raised if neither r or d are given.

  • ValueError – Raised if both r and d are given, but d != 2*r.

  • ValueError – Raise if distribution type isn’t recognized or implemented.

srfm.utilities.memory_safe_np_zeros_2d(constraints=None, pct=99, max_sec_dim=10000)

Initialzes a numpy.zeros 2D array os size that does not overflow RAM.

Creates a numpy.zeros array of maximum allowed size so as not to overflow system RAM. Note that by default, a np.zeros array has dtype np.float64. Therefore each element of the array takes up 8 bytes. The size of the array in the memory is simply the number of elements times the 8 bytes.

Parameters:

  • constraints (array-like) – Constraints on mimimum required shape. Default is None.

  • pct (int, float) – Maximum allowed percentage of available RAM to be used, Defualt is 99%.

  • max_sec_dim (int) – 10,000.

Returns:

arr (np.ndarray) – Numpy.zeros array of appropriate shape.

Raises:

  • TypeError – Raised when inputs are incorrect dtype.

  • ValueError – Raised when the number of constraints exceeds two (the amount of output array dimensions.

  • RuntimeError – Raised when the size of array that would satisfy the required constraints would exceed the amount of available memory.

srfm.utilities.monotonic(x)

Check if list/1D array is monotonic and increasing or decreasing.

Parameters:

x (array-like) – input array/list, if array, then must be 1D.

Returns:

val (int) – Int value which signifies the result. Can be: - 0 - Input not monotonic. - 1 - Input strictly increasing. - 2 - Input strictly decreasing.

srfm.utilities.number_conc_from_mass_loading(l, rho, thick, s, dist_type, r=None, d=None)

Calculates particle number concentration from particle column loading.

Either r or d has to be given.

Parameters:

  • l (int, float) – Particle column mass loading, units [g m-2].

  • rho (int, float, str) –

    Particle density, units [kg m-3]. Uniform density is assumed. Can be either a value in [kg m-3] or one of the following strings:

    • ”pumice” - 950 kg m-3

    • ”glass” - 2400 kg m-3

    • ”mineral” - 3000 kg m-3

    • ”rock” - 2900 kg m-3

    Note that the densities are average densities from the USGS VAI.

    They in turn cite Shipley and Sarna_Wojcicki (1982).

    The same information is also repeated in Wilson et al. (2012).

    Using the strings should serve only an illustrative purpose and should not be relied on as the data in a given eruption may vary!

  • thick (int, float) – Particle layer thickness, units [km].

  • s (int, float) – Lognormal distribution spread. Default is None.

  • dist_type (str) – Size distribution type. If None, then a monodisperse distribution is implied and parameter s is not used. Other permitted value is “lognormal”. Default is None.

  • r (int, float) – Particle radius, units [\(\mu\)m]. Default is None.

  • d (int, float) – Particle diameter, units [\(\mu\)m], Default is None.

Returns:

n (float) – Particle number concentration, units [particles cm-3].

Raises:

  • TypeError – Raised if inputs are incorrect format.

  • ValueError – Raised if neither r or d are given.

  • ValueError – Raised if both r and d are given, but d != 2*r.

  • ValueError – Raise if distribution type isn’t recognized or implemented.

srfm.utilities.read_ils(filename)

Read instrument line shape file in RFM format.

The file is assumed to be in RFM’s ils format.

Parameters:

filename (str) – Filename of the instrument line shape file in RFM format.

Returns:

  • x (array) – Wavenumber/wavelength values.

  • y (array) – Intensity (line shape).

  • lo (int) – Lower wavenumber/wavelength (where the line shape starts).

  • hi (int) – Upper wavenumber/wavelength (where the line shape ends).

srfm.utilities.scale_solar_spectrum(spc, yday)

Scales solar spectrum to the correct year day number.

Input solar spectrum is assumed for to be for 1 AU Sun-Earth distance. Since the Sun-Earth distance changes throughout the year, the spectrum needs to be scaled accordingly. Calculation formula from Don Grainger.

Calculation formula:

\[F(d) = \left\{1 - 0.0167086 \cos\left[\frac{2\pi(d - 4)} {365.256363}\right]\right\}^{-2} F_0\]
where:

  • \(F(d)\): scaled flux

  • \(d\): year day number

  • \(F_0\): flux at 1 AU

Parameters:

  • spc (array) – Solar spectrum, assumed valid for 1 AU Sun-Earth distance.

  • yday (int, float) – Year day number, Jan 1 is day 1.

Returns:

sc_spc (array) – Input spectrum scaled to the input year day number.

Raises:

ValueError – Raised when 0 < yday < 366 is not True.

srfm.utilities.show_runtime(func)

Decorator function to time other functions.

srfm.utilities.track_lev_to_track_lyr(lev)

Converts a levels tracking list to layer tracking list.

In the levels tracking list, each element represents an atmospheric level and evaluates to None for all levels except the tracked level. The tracking list for layer follows the same logic.

Example logic: (L is the layer name in place of the lower and upper layer boundary altitudes.)

track_lev = [None, None, L, L, None, None]

is converted to

track_lyr = [None, None, L, None, None]

Parameters:

lev (list) – Levels tracking list.

Returns:

lyr (list) – Layers tracking array.

srfm.readers.read_iasi_l1c module

Utilities for working with IASI Level 1C orbit data.

This module exposes Iasi_L1c, a helper that reads .nat files produced by EUMETSAT/ESA and provides convenient methods to subset locations and extract individual spectra.

class srfm.readers.read_iasi_l1c.Iasi_L1c(iasifile, chkqal=(True, True, True), avhrr=False, latlim=None, lonlim=None, szalim=None, zenlim=None, saalim=None, azilim=None, cldlim=None, lndlim=None, mph_only=False)

Bases: object

Read and subset IASI Level 1C .nat files.

The class ingests v5 EUMETSAT IASI Level 1C orbit files, builds a list of usable locations (typically ~90k pixels), and exposes helpers to extract individual spectra or further subset the metadata.

Parameters:

  • iasifile (str) – Path to the .nat file to read.

  • chkqal (tuple[bool, bool, bool], optional) – Three flags controlling whether to exclude pixels with bad quality indicators in each spectral band (645-1210, 1210-2000, 2000-2760 cm-1). Defaults to (True, True, True).

  • avhrr (bool, optional) – Include AVHRR cluster analysis data when available.

  • latlim (tuple[float, float] | None) – Inclusive latitude limits in degrees.

  • lonlim (tuple[float, float] | None) – Inclusive longitude limits. The first value is treated as the western boundary so (170, -170) spans across the 180° meridian.

  • szalim (tuple[float, float] | None) – Solar zenith angle bounds in degrees.

  • zenlim (tuple[float, float] | None) – Satellite zenith angle bounds.

  • saalim (tuple[float, float] | None) – Solar azimuth angle bounds (0-360°).

  • azilim (tuple[float, float] | None) – Satellite azimuth angle bounds.

  • cldlim (tuple[float, float] | None) – Cloud-cover percentage bounds.

  • lndlim (tuple[float, float] | None) – Land-fraction percentage bounds.

  • mph_only (bool, optional) – When True, stop after reading the Main Product Header and populate mph only.

fail

Indicates whether a fatal read error occurred.

Type:

bool

errtxt

Description of the last fatal error.

Type:

str

file

Input Level 1C file name.

Type:

str

mph

Main Product Header entries.

Type:

dict[str, str]

nloc

Number of pixel locations retained after filtering.

Type:

int

loc

Metadata for each selected pixel, including geolocation, angles, quality flags, and spectral offsets.

Type:

list[dict[str, object]]

scale

Spectral scale factors read from GIADR records.

Type:

np.ndarray

stats

Summary counts of good/bad pixels and MDRs.

Type:

dict[str, int]

mdruse

Flags showing which Measurement Data Records are usable.

Type:

list[bool]

spectrum()

Return a single spectrum, optionally in brightness temperature.

subset()

Reduce loc to entries that match additional filters.

write_stats()

Print statistics about good/bad pixels and MDR usage.

Examples

from srfm.readers.read_iasi_l1c import Iasi_L1c

l1c = Iasi_L1c(
    "iasi_l1c.nat",
    latlim=(30.0, 60.0),
    lonlim=(0.0, 90.0),
    cldlim=(0.0, 10.0),
)
if l1c.fail:
    raise RuntimeError(l1c.errtxt)

brightness, wavenumber = l1c.spectrum(0, bright=True)
CDS = dtype([('day', '>u2'), ('millisec', '>u4')])
GRH = dtype([('record_class', 'i1'), ('instrument_group', 'i1'), ('record_subclass', 'i1'), ('record_subclass_version', 'i1'), ('record_size', '>u4'), ('record_start_time', [('day', '>u2'), ('millisec', '>u4')]), ('record_stop_time', [('day', '>u2'), ('millisec', '>u4')])])
GRH_SIZE = 20
IOFMDRB = 2364790
IOFSPC = 276790
MDR_A = dtype([('GRH', [('record_class', 'i1'), ('instrument_group', 'i1'), ('record_subclass', 'i1'), ('record_subclass_version', 'i1'), ('record_size', '>u4'), ('record_start_time', [('day', '>u2'), ('millisec', '>u4')]), ('record_stop_time', [('day', '>u2'), ('millisec', '>u4')])]), ('DEGRADED_INST_MDR', 'i1'), ('DEGRADED_PROC_MDR', 'i1'), ('GEPSIasiMode', '>i4'), ('GEPSOPSProcessingMode', '>i4'), ('GEPSIdConf', 'i1', (32,)), ('GEPSLocIasiAvhrr_IASI', 'i1', (1200,)), ('GEPSLocIasiAvhrr_IIS', 'i1', (7500,)), ('OBT', 'i1', (180,)), ('OnboardUTC', [('day', '>u2'), ('millisec', '>u4')], (30,)), ('GEPSDatIasi', 'i1', (180,)), ('GisfLinOrigin', '>i4', (2,)), ('GisfColOrigin', '>i4', (2,)), ('GisfPds1', '>i4', (2,)), ('GisfPds2', '>i4', (2,)), ('GisfPds3', '>i4', (2,)), ('GisfPds4', '>i4', (2,)), ('GEPS_CCD', 'i1', (30,)), ('GEPS_SP', '>i4', (30,)), ('GircImage', '>u2', (30, 64, 64)), ('GQisFlagQual', 'i1', (30, 4, 3)), ('GQisFlagQualDetailed', '>u2', (30, 4)), ('GQisFlagQualIndex', 'i1', (5,)), ('GQisFlagQualIndexIIS', 'i1', (5,)), ('GQisFlagQualIndexLoc', 'i1', (5,)), ('GQisFlagQualIndexRad', 'i1', (5,)), ('GQisFlagQualIndexSpect', 'i1', (5,)), ('GQisSysTecIISQual', '>u4'), ('GQisSysTecSondQual', '>u4'), ('GGeoSondLoc', '>i4', (30, 4, 2)), ('GGeoSondAnglesMETOP', '>i4', (30, 4, 2)), ('GGeoIISAnglesMETOP', '>i4', (30, 25, 2)), ('GGeoSondAnglesSun', '>i4', (30, 4, 2)), ('GGeoIISAnglesSun', '>i4', (30, 25, 2)), ('GGeoIISLoc', '>i4', (30, 25, 2)), ('EARTH_SATELLITE_DISTANCE', '>u4'), ('IDefSpectDWn1b', [('ibexp', 'i1'), ('i4man', '>i4')]), ('IDefNsfirst1b', '>i4'), ('IDefNslast1b', '>i4')])
MDR_B = dtype([('IDefCovarMatEigenVal1c', 'i1', (1000,)), ('IDEFCcsChannelID', '>i4', (6,)), ('GCcsRadAnalNbClass', '>i4', (30, 4)), ('GCcsRadAnalWgt', [('ibexp', 'i1'), ('i4man', '>i4')], (30, 4, 7)), ('GCcsRadAnalY', '>i4', (30, 4, 7)), ('GCcsRadAnalZ', '>i4', (30, 4, 7)), ('GCcsRadAnalMean', [('ibexp', 'i1'), ('i4man', '>i4')], (30, 4, 7, 6)), ('GCcsRadAnalStd', [('ibexp', 'i1'), ('i4man', '>i4')], (30, 4, 7, 6)), ('GCcsImageClassified', 'i1', (300000,)), ('IDefCcsMode', '>u4'), ('GCcsImageClassifiedNbLin', '>i2', (30,)), ('GCcsImageClassifiedNbCol', '>i2', (30,)), ('GCcsImageClassifiedFirstLin', [('ibexp', 'i1'), ('i4man', '>i4')], (30,)), ('GCcsImageClassifiedFirstCol', [('ibexp', 'i1'), ('i4man', '>i4')], (30,)), ('GCcsRadAnalType', 'i1', (30, 7)), ('GlacVarImagIIS', [('ibexp', 'i1'), ('i4man', '>i4')], (30,)), ('GlacAvgImagIIS', [('ibexp', 'i1'), ('i4man', '>i4')], (30,)), ('GEUMAvhrr1BCldFrac', 'i1', (30, 4)), ('GEUMAvhrr1BLandFrac', 'i1', (30, 4)), ('GEUMAvhrr1BQual', 'i1', (30, 4))])
MDR_SIZE = 2728908
NAVC = 6
NBND = 3
NCLS = 7
NPIX = 4
NSTP = 30
NWNO = 8461
RADFAC = 10000000.0
VI4 = dtype([('ibexp', 'i1'), ('i4man', '>i4')])
WNO1 = 645.0
WNOD = 0.25
spectrum(iloc, wnolim=(645, 2760), bright=False)

Read in spectra at selected locations

Parameters

iloc int : Index of pixel for spectrum wnolim (flt) : Min,Max wavenumber limits [cm-1] for extracted spectra bbt boo : True=return spec as brightness temps, False=radiances

Returns

[flt] : spectrum

Description

Assumes self.file contains name of required file which is reopened. The byte offsets of spectra within the file are saved in the self.iof list so this method can simply move to the correct location.

write_stats()

Write summary statistics to terminal

srfm.read_iasi_l2 module

Utilities for ingesting IASI Level 2 retrieval products.

The module provides Iasi_L2, which parses .nat Level 2 files and exposes geophysical profiles, column integrals, and optional FORLI/Brescia products for each pixel.

class srfm.readers.read_iasi_l2.Iasi_L2(l2fil, mph_only=False, forli=False, latlim=None, lonlim=None, loclim=None, **kwargs)

Bases: object

Parse EUMETSAT IASI Level 2 .nat orbit files.

The class reads a full-orbit Level 2 file, validates the MPH/IPR/GIADR structure, and returns geophysical retrievals and ancillary metadata for every pixel that satisfies the optional filters.

Parameters:

  • l2fil (str) – Path to the Level 2 .nat file.

  • mph_only (bool, optional) – When True, stop after reading the Main Product Header and leave retrieval lists empty.

  • forli (bool, optional) – Include the optional FORLI/Brescia CO, HNO3, O3, and SO2 products. Defaults to False.

  • latlim (tuple[float, float] | None) – Latitude limits [south, north].

  • lonlim (tuple[float, float] | None) – Longitude limits [west, east] where the first value is interpreted as the western boundary.

  • loclim (list[dict[str, float]] | None) – Specific locations (lat, lon, msclin, etc.) to retain. Only matching pixels are returned.

  • **kwargs – Additional MDR field/value filters (for example, flg_retcheck=0 keeps only retrievals with good checks).

fail

True when a fatal read error occurred.

Type:

bool

errtxt

Description of the fatal error, if any.

Type:

str | None

mph

Main Product Header entries.

Type:

dict[str, str]

grd

Profile grid definitions read from the GIADR.

Type:

dict[str, np.ndarray]

nloc

Number of locations retained after filtering.

Type:

int

fov

Field-of-view indices (1-120) for each selected pixel.

Type:

list[int]

lin

Scan line numbers (equivalent to MDR index).

Type:

list[int]

stp

Cross-scan step numbers (1-30).

Type:

list[int]

pix

Pixel numbers within each step (1-4).

Type:

list[int]

daylin

Julian day of each scan line start.

Type:

list[int]

msclin

Milliseconds from the orbit start at each scan line.

Type:

list[int]

lat

Latitudes of each selected profile [-90, 90].

Type:

list[float]

lon

Longitudes [-180, 180].

Type:

list[float]

sza

Solar zenith angle in degrees.

Type:

list[float]

zen

Satellite zenith angle in degrees.

Type:

list[float]

saa

Solar azimuth angle in degrees.

Type:

list[float]

azi

Satellite azimuth angle in degrees.

Type:

list[float]

tem_a, h2o_a, o3_a

First-guess temperature, water-vapour, and ozone profiles.

Type:

list[np.ndarray]

tem, h2o, o3

Retrieved temperature, water-vapour, and ozone profiles at the supplied grid levels.

Type:

list[np.ndarray]

sft, sft_a

Retrieved and first-guess surface temperatures.

Type:

list[float]

h2o_col, o3_col, n2o_col, co_col, ch4_col, co2_col

Column integrals for key trace gases.

Type:

list[float]

sfe

Surface emissivity at the wavelengths listed in grd[‘surface_emissivity_wavelengths’].

Type:

list[np.ndarray]

ncld, cld, ctt, ctp, cph

Cloud metrics such as number of formations, fractional cover, top temperature/pressure, and phase.

Type:

list

sfp

Surface pressure per profile.

Type:

list[float]

Note

A range of quality/flag fields CO/HNO3/O3/SO2 retrieval lists are initialised in _inivar. See that method for the full set of attributes made available on each instance.

Notes

Version history:

  • 05AUG25 AK Added solar and satellite azimuth angle readings.

  • 04AUG25 AD Corrections to reading Forli data.

  • 15MAR25 AD Modify _loclim to exclude invalid first-guess profiles.

  • 11FEB25 AD Rename from read_iasi_l2.py to iasi_l2_class.py.

  • 13JAN25 AD Correction to loclim implementation.

  • 11OCT24 AD Renamed from Iasi_L2.

  • 05SEP24 AD In _read_ipr only take first ipr_mdr if multiple exist.

  • 28AUG24 AD Add loclim parameter and rename from read_iasi_l2.

  • 04MAR24 AD Converted from IDL.

Reference: PDF_TEN_980760-EPS-IASI-L2.pdf.

Examples

from srfm.readers.read_iasi_l2 import Iasi_L2

l2 = Iasi_L2(
    "iasi_l2.nat",
    latlim=(30.0, 60.0),
    lonlim=(0.0, 90.0),
    flg_retcheck=0,
)
if l2.fail:
    raise RuntimeError(l2.errtxt)

print(l2.nloc)
print(l2.grd["pressure_levels_temp"])
print(l2.tem[0])
BADI2 = np.int16(32767)
BADU2 = np.uint16(65535)
BADU4 = np.uint32(4294967295)
CDS = dtype([('day', '>u2'), ('millisec', '>u4')])
CO_NBR = 50
GRH = dtype([('record_class', 'i1'), ('instrument_group', 'i1'), ('record_subclass', 'i1'), ('record_subclass_version', 'i1'), ('record_size', '>u4'), ('record_start_time', [('day', '>u2'), ('millisec', '>u4')]), ('record_stop_time', [('day', '>u2'), ('millisec', '>u4')])])
GRH_SIZE = 20
HNO3_NBR = 50
MDR = dtype([('grh', [('record_class', 'i1'), ('instrument_group', 'i1'), ('record_subclass', 'i1'), ('record_subclass_version', 'i1'), ('record_size', '>u4'), ('record_start_time', [('day', '>u2'), ('millisec', '>u4')]), ('record_stop_time', [('day', '>u2'), ('millisec', '>u4')])]), ('degraded_inst_mdr', 'i1'), ('degraded_proc_mdr', 'i1'), ('fg_atmospheric_temperature', '>u2', (120, 101)), ('fg_atmospheric_water_vapour', '>u4', (120, 101)), ('fg_atmospheric_ozone', '>u2', (120, 101)), ('fg_surface_temperature', '>u2', (120,)), ('fg_qi_atmospheric_temperature', 'u1', (120,)), ('fg_qi_atmospheric_water_vapour', 'u1', (120,)), ('fg_qi_atmospheric_ozone', 'u1', (120,)), ('fg_qi_surface_temperature', 'u1', (120,)), ('atmospheric_temperature', '>u2', (120, 101)), ('atmospheric_water_vapour', '>u4', (120, 101)), ('atmospheric_ozone', '>u2', (120, 101)), ('surface_temperature', '>u2', (120,)), ('integrated_water_vapour', '>u2', (120,)), ('integrated_ozone', '>u2', (120,)), ('integrated_n2o', '>u2', (120,)), ('integrated_co', '>u2', (120,)), ('integrated_ch4', '>u2', (120,)), ('integrated_co2', '>u2', (120,)), ('surface_emissivity', '>u2', (120, 12)), ('number_cloud_formations', 'u1', (120,)), ('fractional_cloud_cover', '>u2', (120, 3)), ('cloud_top_temperature', '>u2', (120, 3)), ('cloud_top_pressure', '>u4', (120, 3)), ('cloud_phase', 'i1', (120, 3)), ('surface_pressure', '>u4', (120,)), ('instrument_mode', 'i1'), ('spacecraft_altitude', '>u4'), ('angular_relation', '>i2', (120, 4)), ('earth_location', '>i4', (120, 2)), ('flg_amsubad', 'i1', (120,)), ('flg_avhrrbad', 'i1', (120,)), ('flg_cldfrm', 'i1', (120,)), ('flg_cldnes', 'i1', (120,)), ('flg_cldtst', '>u2', (120,)), ('flg_daynit', 'i1', (120,)), ('flg_dustcld', 'i1', (120,)), ('flg_fgcheck', '>u2', (120,)), ('flg_iasibad', 'i1', (120,)), ('flg_initia', 'i1', (120,)), ('flg_itconv', 'i1', (120,)), ('flg_lansea', 'i1', (120,)), ('flg_mhsbad', 'i1', (120,)), ('flg_numit', 'i1', (120,)), ('flg_nwpbad', 'i1', (120,)), ('flg_physcheck', 'i1', (120,)), ('flg_retcheck', '>u2', (120,)), ('flg_satman', 'i1', (120,)), ('flg_sunglnt', 'i1', (120,)), ('flg_thicir', 'i1', (120,))])
NCLD = 3
NERR = 30
NERRO = 55
NERRT = 406
NERRW = 171
NEVA_CO = 10
NEVA_HNO3 = 10
NEVA_O3 = 10
NEVE_CO = 190
NEVE_HNO3 = 190
NEVE_O3 = 190
NEW = 12
NFOV = 120
NLO = 101
NLQ = 101
NLT = 101
NL_CO = 19
NL_HNO3 = 19
NL_O3 = 40
NL_SO2 = 5
NPCO = 10
NPCT = 28
NPCW = 18
O3_NBR = 50
OSCALE = 0.006033333333333334
QSCALE = 0.16088888888888891
SCALEF_CO = 1e-13
SCALEF_HNO3 = 1e-11
SCALEF_O3 = 1e-14
TSCALE = 0.01
VI4 = dtype([('ibexp', 'i1'), ('i4man', '>i4')])
VUI2 = dtype([('ibexp', 'i1'), ('i2man', '>u2')])

srfm.rfm_helper module

Helpers for running the RFM Fortran model from Python.

  • Name: rfm_helper

  • Parent package: srfm

  • Author: Antonin Knizek

  • Contributors:

  • Date: 14 Nov 2025

class srfm.rfm_helper.DriverSectionInfo(key: str, mandatory: bool, summary: str, value_format: str, aliases: tuple[str, ...] = ())

Bases: object

Metadata describing a section within rfm.drv.

aliases: tuple[str, ...] = ()
key: str
mandatory: bool
summary: str
value_format: str
class srfm.rfm_helper.RunResult(status: int, removed_files: List[Path], output: Any | None = None, output_df: Any | None = None)

Bases: object

Encapsulates the outcome of a single RFM execution.

status

Exit status reported by the underlying executable or shared library (zero indicates success).

Type:

int

removed_files

Output artefacts deleted prior to the run when clean_before is enabled.

Type:

list[pathlib.Path]

output

Optional payload gathered from the run, such as captured optical-depth data or a mapping of output filenames to their in-memory contents.

Type:

Any | None

output_df

Optional dataframe payload reserved for optical-depth capture while still allowing output to represent file-based artefacts.

Type:

Any | None

property ok: bool

True when the RFM run completed successfully.

output: Any | None = None
output_df: Any | None = None
removed_files: List[Path]
status: int
class srfm.rfm_helper.SectionLine(*parts: Any)

Bases: object

Explicit list of tokens that form a single driver record.

parts

Token sequence written verbatim into the driver table line.

Type:

tuple[Any, …]

as_record() → str
parts: tuple[Any, ...]
class srfm.rfm_helper.SpectralFile(path: Path, label: str | None = None)

Bases: object

Reference to a pre-defined spectral range file for *SPC.

path

Path to the .spc file (coerced to Path).

Type:

pathlib.Path

label

Optional label written ahead of the filename.

Type:

str | None

as_record() → str
label: str | None = None
path: Path
class srfm.rfm_helper.SpectralRange(start: float, stop: float, spacing: float, label: str | None = None)

Bases: object

In-memory representation of a *SPC spectral range entry.

start

Lower bound of the spectral interval in cm^-1 (or GHz when the GHZ flag is set).

Type:

float

stop

Upper bound of the interval in cm^-1.

Type:

float

spacing

Sampling spacing (positive) or number of points per cm^-1 (>1).

Type:

float

label

Optional label written ahead of the range.

Type:

str | None

as_record() → str
label: str | None = None
spacing: float
start: float
stop: float
srfm.rfm_helper.clean_outputs(directory: Path | str | None = None, patterns: Sequence[str] | None = None) → List[Path]

Delete known RFM artefacts prior to a new run.

Parameters:

  • directory (Path | str | None) – Directory containing the outputs. Defaults to the current working directory.

  • patterns (Sequence[str] | None) – Filename glob patterns to remove. Defaults to ("*.asc", "rfm.log*").

Returns:

list[pathlib.Path] – Paths that were removed.

srfm.rfm_helper.get_captured_optical_depths(levels: Sequence[float], *, spectrum_index: int = 1, match_tol: float = 1e-06) → DataFrame

Return the optical-depth dataframe captured by the Fortran backend.

Parameters:

  • levels (Sequence[float]) – Altitude levels (km) defining layer bounds.

  • spectrum_index (int) – Spectral range index (1-based) to retrieve.

  • match_tol (float) – Absolute tolerance applied when matching requested levels to the captured grid.

Returns:

  • pandas.DataFrame – Layer metadata plus differential/integrated optical

  • depths mirroring the legacy ``*.opt`` parsing.

Raises:

  • ValueError – Raised when the provided levels are invalid or cannot be matched to the captured profile.

  • RuntimeError – Raised if the Fortran capture reports a failure.

srfm.rfm_helper.get_rfm_input_catalog() → dict[str, Any]

Compile metadata about supported driver sections and aliases.

Returns:

dict[str, Any] – Mapping with keys sections, mandatory_sections, optional_sections, flag_codes, and aliases.

srfm.rfm_helper.rfm_main(*, configuration: Mapping[str, Any] | None, driver_inputs: Mapping[str, Any], levels: Sequence[float], rfm_out_fldr: Path | str) → RunResult

Run the RFM model using dictionary-based configuration and inputs.

Parameters:

  • configuration (Mapping[str, Any] | None) – Optional overrides that control execution, including driver_path, generate_driver, clean_before, run_id, patterns, optical_spectrum_index, optical_match_tol, output_mode, capture_files_content, and verbose. When supplied, output_mode must be "capture" or "files".

  • driver_inputs (Mapping[str, Any]) – Structured representation of driver sections mirroring run_rfm_with_parameters().

  • levels (Sequence[float]) – Altitude levels (km) used when optical-depth capture is enabled via the OPT and LEV flags.

  • rfm_out_fldr (Path | str) – Directory in which the run should take place and where RFM writes its outputs.

Returns:

RunResult – The run status plus optional payloads. output holds the in-memory file map for capture runs (None for file-mode runs), while output_df is populated with the optical-depth dataframe when OPT and LEV are active under capture mode.

Raises:

  • FileNotFoundError – If the requested output directory does not exist.

  • NotADirectoryError – If rfm_out_fldr resolves to a file.

  • ValueError – If mandatory sections are missing, incompatible geometry inputs are provided, optical-depth capture requirements are not satisfied, or output_mode is invalid for the provided flags.

  • RuntimeError – If optical-depth capture is expected but a dataframe is not returned.

Notes

capture_files_content controls whether capture mode records the generated *.asc/log artefacts in memory (while deleting them on disk). When set to False the run still suppresses file creation but omits the in-memory payload, leaving only output_df (when applicable).

srfm.rfm_helper.run_rfm(run_id: str | None = None, *, clean_before: bool = False, directory: Path | str | None = None, patterns: Sequence[str] | None = None, driver_lines: Sequence[str] | None = None, driver_path: Path | str | None = None, output_mode: Literal['files', 'capture'] = 'files', enable_capture: bool | None = None, optical_levels: Sequence[float] | None = None, optical_spectrum_index: int = 1, optical_match_tol: float = 1e-06) → RunResult

Public wrapper that runs the Fortran backend in a fresh subprocess.

srfm.rfm_helper.run_rfm_with_parameters(*, header: str | Sequence[str], flags: Sequence[str], spectral: Any, gases: Any, atmosphere: Any, tangent: Any | None = None, tab_dimensions: Any | None = None, cia: Any | None = None, fin: Any | None = None, fov: Any | None = None, grd: Any | None = None, hit: Any | None = None, ils: Any | None = None, jac: Any | None = None, lev: Any | None = None, lut: Any | None = None, nte: Any | None = None, obs: Any | None = None, out: Any | None = None, phy: Any | None = None, rej: Any | None = None, sfc: Any | None = None, shp: Any | None = None, svd: Any | None = None, xsc: Any | None = None, extra_sections: Mapping[str, Any] | None = None, run_id: str | None = None, clean_before: bool = False, directory: Path | str | None = None, patterns: Sequence[str] | None = None, output_mode: Literal['files', 'capture'] = 'files', enable_capture: bool | None = None, optical_levels: Sequence[float] | None = None, optical_spectrum_index: int = 1, optical_match_tol: float = 1e-06) → RunResult

Run RFM by constructing inputs directly from Python structures.

Parameters:

  • header (str | Sequence[str]) – Text for the *HDR section.

  • flags (Sequence[str]) – Recognised three-letter flag codes (case-insensitive).

  • spectral (Any) – Entries for the *SPC section; accepts numbers, strings, SpectralRange, SpectralFile, SectionLine, mappings, or nested sequences.

  • gases (Any) – Content for *GAS (molecule names, filenames, wildcards, etc.).

  • atmosphere (Any) – Content for *ATM; either filenames or PARAM=value assignments.

  • tangent (Any | None) – Tangent path specification for *TAN (required unless the TAB flag is set).

  • tab_dimensions (Any | None) – *DIM records used when the TAB flag is enabled.

  • cia (Any | None) – Content for *CIA.

  • fin (Any | None) – Content for *FIN.

  • fov (Any | None) – Content for *FOV.

  • grd (Any | None) – Content for *GRD.

  • hit (Any | None) – Content for *HIT.

  • ils (Any | None) – Content for *ILS.

  • jac (Any | None) – Content for *JAC.

  • lev (Any | None) – Content for *LEV.

  • lut (Any | None) – Content for *LUT.

  • nte (Any | None) – Content for *NTE.

  • obs (Any | None) – Content for *OBS.

  • out (Any | None) – Content for *OUT.

  • phy (Any | None) – Content for *PHY.

  • rej (Any | None) – Content for *REJ.

  • sfc (Any | None) – Content for *SFC.

  • shp (Any | None) – Content for *SHP.

  • svd (Any | None) – Content for *SVD.

  • xsc (Any | None) – Content for *XSC.

  • extra_sections (Mapping[str, Any] | None) – Additional *KEY names mapped to section data.

  • run_id (str | None) – Identifier appended to output filenames.

  • clean_before (bool) – When True remove artefacts matching patterns before running.

  • directory (Path | str | None) – Working directory containing assets and outputs.

  • patterns (Sequence[str] | None) – Filename glob patterns passed to clean_outputs().

  • output_mode (Literal["files", "capture"]) – Pass "capture" to populate the returned RunResult with the in-memory optical-depth dataframe; otherwise rely on file outputs.

  • enable_capture (bool | None) – Override whether the shared-library execution enables optical-depth capture; defaults to mirroring output_mode == "capture".

  • optical_levels (Sequence[float] | None) – Output levels (km) required when output_mode is "capture".

  • optical_spectrum_index (int) – Spectral index used when retrieving captured optical depths (default 1).

  • optical_match_tol (float) – Matching tolerance (km) applied to the captured profile grid (default 1e-6).

Returns:

RunResult – Summary of the execution and optional in-memory output.

Raises:

  • ValueError – If required arguments are missing or mutually exclusive.

  • FileNotFoundError – If the requested working directory does not exist.

srfm.main module

Helpers for running the RFM Fortran model from Python.

  • Name: rfm_helper

  • Parent package: srfm

  • Author: Antonin Knizek

  • Contributors:

  • Date: 14 Nov 2025

class srfm.rfm_helper.DriverSectionInfo(key: str, mandatory: bool, summary: str, value_format: str, aliases: tuple[str, ...] = ())

Bases: object

Metadata describing a section within rfm.drv.

aliases: tuple[str, ...] = ()
key: str
mandatory: bool
summary: str
value_format: str
class srfm.rfm_helper.RunResult(status: int, removed_files: List[Path], output: Any | None = None, output_df: Any | None = None)

Bases: object

Encapsulates the outcome of a single RFM execution.

status

Exit status reported by the underlying executable or shared library (zero indicates success).

Type:

int

removed_files

Output artefacts deleted prior to the run when clean_before is enabled.

Type:

list[pathlib.Path]

output

Optional payload gathered from the run, such as captured optical-depth data or a mapping of output filenames to their in-memory contents.

Type:

Any | None

output_df

Optional dataframe payload reserved for optical-depth capture while still allowing output to represent file-based artefacts.

Type:

Any | None

property ok: bool

True when the RFM run completed successfully.

output: Any | None = None
output_df: Any | None = None
removed_files: List[Path]
status: int
class srfm.rfm_helper.SectionLine(*parts: Any)

Bases: object

Explicit list of tokens that form a single driver record.

parts

Token sequence written verbatim into the driver table line.

Type:

tuple[Any, …]

as_record() → str
parts: tuple[Any, ...]
class srfm.rfm_helper.SpectralFile(path: Path, label: str | None = None)

Bases: object

Reference to a pre-defined spectral range file for *SPC.

path

Path to the .spc file (coerced to Path).

Type:

pathlib.Path

label

Optional label written ahead of the filename.

Type:

str | None

as_record() → str
label: str | None = None
path: Path
class srfm.rfm_helper.SpectralRange(start: float, stop: float, spacing: float, label: str | None = None)

Bases: object

In-memory representation of a *SPC spectral range entry.

start

Lower bound of the spectral interval in cm^-1 (or GHz when the GHZ flag is set).

Type:

float

stop

Upper bound of the interval in cm^-1.

Type:

float

spacing

Sampling spacing (positive) or number of points per cm^-1 (>1).

Type:

float

label

Optional label written ahead of the range.

Type:

str | None

as_record() → str
label: str | None = None
spacing: float
start: float
stop: float
srfm.rfm_helper.clean_outputs(directory: Path | str | None = None, patterns: Sequence[str] | None = None) → List[Path]

Delete known RFM artefacts prior to a new run.

Parameters:

  • directory (Path | str | None) – Directory containing the outputs. Defaults to the current working directory.

  • patterns (Sequence[str] | None) – Filename glob patterns to remove. Defaults to ("*.asc", "rfm.log*").

Returns:

list[pathlib.Path] – Paths that were removed.

srfm.rfm_helper.get_captured_optical_depths(levels: Sequence[float], *, spectrum_index: int = 1, match_tol: float = 1e-06) → DataFrame

Return the optical-depth dataframe captured by the Fortran backend.

Parameters:

  • levels (Sequence[float]) – Altitude levels (km) defining layer bounds.

  • spectrum_index (int) – Spectral range index (1-based) to retrieve.

  • match_tol (float) – Absolute tolerance applied when matching requested levels to the captured grid.

Returns:

  • pandas.DataFrame – Layer metadata plus differential/integrated optical

  • depths mirroring the legacy ``*.opt`` parsing.

Raises:

  • ValueError – Raised when the provided levels are invalid or cannot be matched to the captured profile.

  • RuntimeError – Raised if the Fortran capture reports a failure.

srfm.rfm_helper.get_rfm_input_catalog() → dict[str, Any]

Compile metadata about supported driver sections and aliases.

Returns:

dict[str, Any] – Mapping with keys sections, mandatory_sections, optional_sections, flag_codes, and aliases.

srfm.rfm_helper.rfm_main(*, configuration: Mapping[str, Any] | None, driver_inputs: Mapping[str, Any], levels: Sequence[float], rfm_out_fldr: Path | str) → RunResult

Run the RFM model using dictionary-based configuration and inputs.

Parameters:

  • configuration (Mapping[str, Any] | None) – Optional overrides that control execution, including driver_path, generate_driver, clean_before, run_id, patterns, optical_spectrum_index, optical_match_tol, output_mode, capture_files_content, and verbose. When supplied, output_mode must be "capture" or "files".

  • driver_inputs (Mapping[str, Any]) – Structured representation of driver sections mirroring run_rfm_with_parameters().

  • levels (Sequence[float]) – Altitude levels (km) used when optical-depth capture is enabled via the OPT and LEV flags.

  • rfm_out_fldr (Path | str) – Directory in which the run should take place and where RFM writes its outputs.

Returns:

RunResult – The run status plus optional payloads. output holds the in-memory file map for capture runs (None for file-mode runs), while output_df is populated with the optical-depth dataframe when OPT and LEV are active under capture mode.

Raises:

  • FileNotFoundError – If the requested output directory does not exist.

  • NotADirectoryError – If rfm_out_fldr resolves to a file.

  • ValueError – If mandatory sections are missing, incompatible geometry inputs are provided, optical-depth capture requirements are not satisfied, or output_mode is invalid for the provided flags.

  • RuntimeError – If optical-depth capture is expected but a dataframe is not returned.

Notes

capture_files_content controls whether capture mode records the generated *.asc/log artefacts in memory (while deleting them on disk). When set to False the run still suppresses file creation but omits the in-memory payload, leaving only output_df (when applicable).

srfm.rfm_helper.run_rfm(run_id: str | None = None, *, clean_before: bool = False, directory: Path | str | None = None, patterns: Sequence[str] | None = None, driver_lines: Sequence[str] | None = None, driver_path: Path | str | None = None, output_mode: Literal['files', 'capture'] = 'files', enable_capture: bool | None = None, optical_levels: Sequence[float] | None = None, optical_spectrum_index: int = 1, optical_match_tol: float = 1e-06) → RunResult

Public wrapper that runs the Fortran backend in a fresh subprocess.

srfm.rfm_helper.run_rfm_with_parameters(*, header: str | Sequence[str], flags: Sequence[str], spectral: Any, gases: Any, atmosphere: Any, tangent: Any | None = None, tab_dimensions: Any | None = None, cia: Any | None = None, fin: Any | None = None, fov: Any | None = None, grd: Any | None = None, hit: Any | None = None, ils: Any | None = None, jac: Any | None = None, lev: Any | None = None, lut: Any | None = None, nte: Any | None = None, obs: Any | None = None, out: Any | None = None, phy: Any | None = None, rej: Any | None = None, sfc: Any | None = None, shp: Any | None = None, svd: Any | None = None, xsc: Any | None = None, extra_sections: Mapping[str, Any] | None = None, run_id: str | None = None, clean_before: bool = False, directory: Path | str | None = None, patterns: Sequence[str] | None = None, output_mode: Literal['files', 'capture'] = 'files', enable_capture: bool | None = None, optical_levels: Sequence[float] | None = None, optical_spectrum_index: int = 1, optical_match_tol: float = 1e-06) → RunResult

Run RFM by constructing inputs directly from Python structures.

Parameters:

  • header (str | Sequence[str]) – Text for the *HDR section.

  • flags (Sequence[str]) – Recognised three-letter flag codes (case-insensitive).

  • spectral (Any) – Entries for the *SPC section; accepts numbers, strings, SpectralRange, SpectralFile, SectionLine, mappings, or nested sequences.

  • gases (Any) – Content for *GAS (molecule names, filenames, wildcards, etc.).

  • atmosphere (Any) – Content for *ATM; either filenames or PARAM=value assignments.

  • tangent (Any | None) – Tangent path specification for *TAN (required unless the TAB flag is set).

  • tab_dimensions (Any | None) – *DIM records used when the TAB flag is enabled.

  • cia (Any | None) – Content for *CIA.

  • fin (Any | None) – Content for *FIN.

  • fov (Any | None) – Content for *FOV.

  • grd (Any | None) – Content for *GRD.

  • hit (Any | None) – Content for *HIT.

  • ils (Any | None) – Content for *ILS.

  • jac (Any | None) – Content for *JAC.

  • lev (Any | None) – Content for *LEV.

  • lut (Any | None) – Content for *LUT.

  • nte (Any | None) – Content for *NTE.

  • obs (Any | None) – Content for *OBS.

  • out (Any | None) – Content for *OUT.

  • phy (Any | None) – Content for *PHY.

  • rej (Any | None) – Content for *REJ.

  • sfc (Any | None) – Content for *SFC.

  • shp (Any | None) – Content for *SHP.

  • svd (Any | None) – Content for *SVD.

  • xsc (Any | None) – Content for *XSC.

  • extra_sections (Mapping[str, Any] | None) – Additional *KEY names mapped to section data.

  • run_id (str | None) – Identifier appended to output filenames.

  • clean_before (bool) – When True remove artefacts matching patterns before running.

  • directory (Path | str | None) – Working directory containing assets and outputs.

  • patterns (Sequence[str] | None) – Filename glob patterns passed to clean_outputs().

  • output_mode (Literal["files", "capture"]) – Pass "capture" to populate the returned RunResult with the in-memory optical-depth dataframe; otherwise rely on file outputs.

  • enable_capture (bool | None) – Override whether the shared-library execution enables optical-depth capture; defaults to mirroring output_mode == "capture".

  • optical_levels (Sequence[float] | None) – Output levels (km) required when output_mode is "capture".

  • optical_spectrum_index (int) – Spectral index used when retrieving captured optical depths (default 1).

  • optical_match_tol (float) – Matching tolerance (km) applied to the captured profile grid (default 1e-6).

Returns:

RunResult – Summary of the execution and optional in-memory output.

Raises:

  • ValueError – If required arguments are missing or mutually exclusive.

  • FileNotFoundError – If the requested working directory does not exist.

srfm.iasi_main module

Helpers for running the RFM Fortran model from Python.

  • Name: rfm_helper

  • Parent package: srfm

  • Author: Antonin Knizek

  • Contributors:

  • Date: 14 Nov 2025

class srfm.rfm_helper.DriverSectionInfo(key: str, mandatory: bool, summary: str, value_format: str, aliases: tuple[str, ...] = ())

Bases: object

Metadata describing a section within rfm.drv.

aliases: tuple[str, ...] = ()
key: str
mandatory: bool
summary: str
value_format: str
class srfm.rfm_helper.RunResult(status: int, removed_files: List[Path], output: Any | None = None, output_df: Any | None = None)

Bases: object

Encapsulates the outcome of a single RFM execution.

status

Exit status reported by the underlying executable or shared library (zero indicates success).

Type:

int

removed_files

Output artefacts deleted prior to the run when clean_before is enabled.

Type:

list[pathlib.Path]

output

Optional payload gathered from the run, such as captured optical-depth data or a mapping of output filenames to their in-memory contents.

Type:

Any | None

output_df

Optional dataframe payload reserved for optical-depth capture while still allowing output to represent file-based artefacts.

Type:

Any | None

property ok: bool

True when the RFM run completed successfully.

output: Any | None = None
output_df: Any | None = None
removed_files: List[Path]
status: int
class srfm.rfm_helper.SectionLine(*parts: Any)

Bases: object

Explicit list of tokens that form a single driver record.

parts

Token sequence written verbatim into the driver table line.

Type:

tuple[Any, …]

as_record() → str
parts: tuple[Any, ...]
class srfm.rfm_helper.SpectralFile(path: Path, label: str | None = None)

Bases: object

Reference to a pre-defined spectral range file for *SPC.

path

Path to the .spc file (coerced to Path).

Type:

pathlib.Path

label

Optional label written ahead of the filename.

Type:

str | None

as_record() → str
label: str | None = None
path: Path
class srfm.rfm_helper.SpectralRange(start: float, stop: float, spacing: float, label: str | None = None)

Bases: object

In-memory representation of a *SPC spectral range entry.

start

Lower bound of the spectral interval in cm^-1 (or GHz when the GHZ flag is set).

Type:

float

stop

Upper bound of the interval in cm^-1.

Type:

float

spacing

Sampling spacing (positive) or number of points per cm^-1 (>1).

Type:

float

label

Optional label written ahead of the range.

Type:

str | None

as_record() → str
label: str | None = None
spacing: float
start: float
stop: float
srfm.rfm_helper.clean_outputs(directory: Path | str | None = None, patterns: Sequence[str] | None = None) → List[Path]

Delete known RFM artefacts prior to a new run.

Parameters:

  • directory (Path | str | None) – Directory containing the outputs. Defaults to the current working directory.

  • patterns (Sequence[str] | None) – Filename glob patterns to remove. Defaults to ("*.asc", "rfm.log*").

Returns:

list[pathlib.Path] – Paths that were removed.

srfm.rfm_helper.get_captured_optical_depths(levels: Sequence[float], *, spectrum_index: int = 1, match_tol: float = 1e-06) → DataFrame

Return the optical-depth dataframe captured by the Fortran backend.

Parameters:

  • levels (Sequence[float]) – Altitude levels (km) defining layer bounds.

  • spectrum_index (int) – Spectral range index (1-based) to retrieve.

  • match_tol (float) – Absolute tolerance applied when matching requested levels to the captured grid.

Returns:

  • pandas.DataFrame – Layer metadata plus differential/integrated optical

  • depths mirroring the legacy ``*.opt`` parsing.

Raises:

  • ValueError – Raised when the provided levels are invalid or cannot be matched to the captured profile.

  • RuntimeError – Raised if the Fortran capture reports a failure.

srfm.rfm_helper.get_rfm_input_catalog() → dict[str, Any]

Compile metadata about supported driver sections and aliases.

Returns:

dict[str, Any] – Mapping with keys sections, mandatory_sections, optional_sections, flag_codes, and aliases.

srfm.rfm_helper.rfm_main(*, configuration: Mapping[str, Any] | None, driver_inputs: Mapping[str, Any], levels: Sequence[float], rfm_out_fldr: Path | str) → RunResult

Run the RFM model using dictionary-based configuration and inputs.

Parameters:

  • configuration (Mapping[str, Any] | None) – Optional overrides that control execution, including driver_path, generate_driver, clean_before, run_id, patterns, optical_spectrum_index, optical_match_tol, output_mode, capture_files_content, and verbose. When supplied, output_mode must be "capture" or "files".

  • driver_inputs (Mapping[str, Any]) – Structured representation of driver sections mirroring run_rfm_with_parameters().

  • levels (Sequence[float]) – Altitude levels (km) used when optical-depth capture is enabled via the OPT and LEV flags.

  • rfm_out_fldr (Path | str) – Directory in which the run should take place and where RFM writes its outputs.

Returns:

RunResult – The run status plus optional payloads. output holds the in-memory file map for capture runs (None for file-mode runs), while output_df is populated with the optical-depth dataframe when OPT and LEV are active under capture mode.

Raises:

  • FileNotFoundError – If the requested output directory does not exist.

  • NotADirectoryError – If rfm_out_fldr resolves to a file.

  • ValueError – If mandatory sections are missing, incompatible geometry inputs are provided, optical-depth capture requirements are not satisfied, or output_mode is invalid for the provided flags.

  • RuntimeError – If optical-depth capture is expected but a dataframe is not returned.

Notes

capture_files_content controls whether capture mode records the generated *.asc/log artefacts in memory (while deleting them on disk). When set to False the run still suppresses file creation but omits the in-memory payload, leaving only output_df (when applicable).

srfm.rfm_helper.run_rfm(run_id: str | None = None, *, clean_before: bool = False, directory: Path | str | None = None, patterns: Sequence[str] | None = None, driver_lines: Sequence[str] | None = None, driver_path: Path | str | None = None, output_mode: Literal['files', 'capture'] = 'files', enable_capture: bool | None = None, optical_levels: Sequence[float] | None = None, optical_spectrum_index: int = 1, optical_match_tol: float = 1e-06) → RunResult

Public wrapper that runs the Fortran backend in a fresh subprocess.

srfm.rfm_helper.run_rfm_with_parameters(*, header: str | Sequence[str], flags: Sequence[str], spectral: Any, gases: Any, atmosphere: Any, tangent: Any | None = None, tab_dimensions: Any | None = None, cia: Any | None = None, fin: Any | None = None, fov: Any | None = None, grd: Any | None = None, hit: Any | None = None, ils: Any | None = None, jac: Any | None = None, lev: Any | None = None, lut: Any | None = None, nte: Any | None = None, obs: Any | None = None, out: Any | None = None, phy: Any | None = None, rej: Any | None = None, sfc: Any | None = None, shp: Any | None = None, svd: Any | None = None, xsc: Any | None = None, extra_sections: Mapping[str, Any] | None = None, run_id: str | None = None, clean_before: bool = False, directory: Path | str | None = None, patterns: Sequence[str] | None = None, output_mode: Literal['files', 'capture'] = 'files', enable_capture: bool | None = None, optical_levels: Sequence[float] | None = None, optical_spectrum_index: int = 1, optical_match_tol: float = 1e-06) → RunResult

Run RFM by constructing inputs directly from Python structures.

Parameters:

  • header (str | Sequence[str]) – Text for the *HDR section.

  • flags (Sequence[str]) – Recognised three-letter flag codes (case-insensitive).

  • spectral (Any) – Entries for the *SPC section; accepts numbers, strings, SpectralRange, SpectralFile, SectionLine, mappings, or nested sequences.

  • gases (Any) – Content for *GAS (molecule names, filenames, wildcards, etc.).

  • atmosphere (Any) – Content for *ATM; either filenames or PARAM=value assignments.

  • tangent (Any | None) – Tangent path specification for *TAN (required unless the TAB flag is set).

  • tab_dimensions (Any | None) – *DIM records used when the TAB flag is enabled.

  • cia (Any | None) – Content for *CIA.

  • fin (Any | None) – Content for *FIN.

  • fov (Any | None) – Content for *FOV.

  • grd (Any | None) – Content for *GRD.

  • hit (Any | None) – Content for *HIT.

  • ils (Any | None) – Content for *ILS.

  • jac (Any | None) – Content for *JAC.

  • lev (Any | None) – Content for *LEV.

  • lut (Any | None) – Content for *LUT.

  • nte (Any | None) – Content for *NTE.

  • obs (Any | None) – Content for *OBS.

  • out (Any | None) – Content for *OUT.

  • phy (Any | None) – Content for *PHY.

  • rej (Any | None) – Content for *REJ.

  • sfc (Any | None) – Content for *SFC.

  • shp (Any | None) – Content for *SHP.

  • svd (Any | None) – Content for *SVD.

  • xsc (Any | None) – Content for *XSC.

  • extra_sections (Mapping[str, Any] | None) – Additional *KEY names mapped to section data.

  • run_id (str | None) – Identifier appended to output filenames.

  • clean_before (bool) – When True remove artefacts matching patterns before running.

  • directory (Path | str | None) – Working directory containing assets and outputs.

  • patterns (Sequence[str] | None) – Filename glob patterns passed to clean_outputs().

  • output_mode (Literal["files", "capture"]) – Pass "capture" to populate the returned RunResult with the in-memory optical-depth dataframe; otherwise rely on file outputs.

  • enable_capture (bool | None) – Override whether the shared-library execution enables optical-depth capture; defaults to mirroring output_mode == "capture".

  • optical_levels (Sequence[float] | None) – Output levels (km) required when output_mode is "capture".

  • optical_spectrum_index (int) – Spectral index used when retrieving captured optical depths (default 1).

  • optical_match_tol (float) – Matching tolerance (km) applied to the captured profile grid (default 1e-6).

Returns:

RunResult – Summary of the execution and optional in-memory output.

Raises:

  • ValueError – If required arguments are missing or mutually exclusive.

  • FileNotFoundError – If the requested working directory does not exist.

srfm.inputs module

Helpers for running the RFM Fortran model from Python.

  • Name: rfm_helper

  • Parent package: srfm

  • Author: Antonin Knizek

  • Contributors:

  • Date: 14 Nov 2025

class srfm.rfm_helper.DriverSectionInfo(key: str, mandatory: bool, summary: str, value_format: str, aliases: tuple[str, ...] = ())

Bases: object

Metadata describing a section within rfm.drv.

aliases: tuple[str, ...] = ()
key: str
mandatory: bool
summary: str
value_format: str
class srfm.rfm_helper.RunResult(status: int, removed_files: List[Path], output: Any | None = None, output_df: Any | None = None)

Bases: object

Encapsulates the outcome of a single RFM execution.

status

Exit status reported by the underlying executable or shared library (zero indicates success).

Type:

int

removed_files

Output artefacts deleted prior to the run when clean_before is enabled.

Type:

list[pathlib.Path]

output

Optional payload gathered from the run, such as captured optical-depth data or a mapping of output filenames to their in-memory contents.

Type:

Any | None

output_df

Optional dataframe payload reserved for optical-depth capture while still allowing output to represent file-based artefacts.

Type:

Any | None

property ok: bool

True when the RFM run completed successfully.

output: Any | None = None
output_df: Any | None = None
removed_files: List[Path]
status: int
class srfm.rfm_helper.SectionLine(*parts: Any)

Bases: object

Explicit list of tokens that form a single driver record.

parts

Token sequence written verbatim into the driver table line.

Type:

tuple[Any, …]

as_record() → str
parts: tuple[Any, ...]
class srfm.rfm_helper.SpectralFile(path: Path, label: str | None = None)

Bases: object

Reference to a pre-defined spectral range file for *SPC.

path

Path to the .spc file (coerced to Path).

Type:

pathlib.Path

label

Optional label written ahead of the filename.

Type:

str | None

as_record() → str
label: str | None = None
path: Path
class srfm.rfm_helper.SpectralRange(start: float, stop: float, spacing: float, label: str | None = None)

Bases: object

In-memory representation of a *SPC spectral range entry.

start

Lower bound of the spectral interval in cm^-1 (or GHz when the GHZ flag is set).

Type:

float

stop

Upper bound of the interval in cm^-1.

Type:

float

spacing

Sampling spacing (positive) or number of points per cm^-1 (>1).

Type:

float

label

Optional label written ahead of the range.

Type:

str | None

as_record() → str
label: str | None = None
spacing: float
start: float
stop: float
srfm.rfm_helper.clean_outputs(directory: Path | str | None = None, patterns: Sequence[str] | None = None) → List[Path]

Delete known RFM artefacts prior to a new run.

Parameters:

  • directory (Path | str | None) – Directory containing the outputs. Defaults to the current working directory.

  • patterns (Sequence[str] | None) – Filename glob patterns to remove. Defaults to ("*.asc", "rfm.log*").

Returns:

list[pathlib.Path] – Paths that were removed.

srfm.rfm_helper.get_captured_optical_depths(levels: Sequence[float], *, spectrum_index: int = 1, match_tol: float = 1e-06) → DataFrame

Return the optical-depth dataframe captured by the Fortran backend.

Parameters:

  • levels (Sequence[float]) – Altitude levels (km) defining layer bounds.

  • spectrum_index (int) – Spectral range index (1-based) to retrieve.

  • match_tol (float) – Absolute tolerance applied when matching requested levels to the captured grid.

Returns:

  • pandas.DataFrame – Layer metadata plus differential/integrated optical

  • depths mirroring the legacy ``*.opt`` parsing.

Raises:

  • ValueError – Raised when the provided levels are invalid or cannot be matched to the captured profile.

  • RuntimeError – Raised if the Fortran capture reports a failure.

srfm.rfm_helper.get_rfm_input_catalog() → dict[str, Any]

Compile metadata about supported driver sections and aliases.

Returns:

dict[str, Any] – Mapping with keys sections, mandatory_sections, optional_sections, flag_codes, and aliases.

srfm.rfm_helper.rfm_main(*, configuration: Mapping[str, Any] | None, driver_inputs: Mapping[str, Any], levels: Sequence[float], rfm_out_fldr: Path | str) → RunResult

Run the RFM model using dictionary-based configuration and inputs.

Parameters:

  • configuration (Mapping[str, Any] | None) – Optional overrides that control execution, including driver_path, generate_driver, clean_before, run_id, patterns, optical_spectrum_index, optical_match_tol, output_mode, capture_files_content, and verbose. When supplied, output_mode must be "capture" or "files".

  • driver_inputs (Mapping[str, Any]) – Structured representation of driver sections mirroring run_rfm_with_parameters().

  • levels (Sequence[float]) – Altitude levels (km) used when optical-depth capture is enabled via the OPT and LEV flags.

  • rfm_out_fldr (Path | str) – Directory in which the run should take place and where RFM writes its outputs.

Returns:

RunResult – The run status plus optional payloads. output holds the in-memory file map for capture runs (None for file-mode runs), while output_df is populated with the optical-depth dataframe when OPT and LEV are active under capture mode.

Raises:

  • FileNotFoundError – If the requested output directory does not exist.

  • NotADirectoryError – If rfm_out_fldr resolves to a file.

  • ValueError – If mandatory sections are missing, incompatible geometry inputs are provided, optical-depth capture requirements are not satisfied, or output_mode is invalid for the provided flags.

  • RuntimeError – If optical-depth capture is expected but a dataframe is not returned.

Notes

capture_files_content controls whether capture mode records the generated *.asc/log artefacts in memory (while deleting them on disk). When set to False the run still suppresses file creation but omits the in-memory payload, leaving only output_df (when applicable).

srfm.rfm_helper.run_rfm(run_id: str | None = None, *, clean_before: bool = False, directory: Path | str | None = None, patterns: Sequence[str] | None = None, driver_lines: Sequence[str] | None = None, driver_path: Path | str | None = None, output_mode: Literal['files', 'capture'] = 'files', enable_capture: bool | None = None, optical_levels: Sequence[float] | None = None, optical_spectrum_index: int = 1, optical_match_tol: float = 1e-06) → RunResult

Public wrapper that runs the Fortran backend in a fresh subprocess.

srfm.rfm_helper.run_rfm_with_parameters(*, header: str | Sequence[str], flags: Sequence[str], spectral: Any, gases: Any, atmosphere: Any, tangent: Any | None = None, tab_dimensions: Any | None = None, cia: Any | None = None, fin: Any | None = None, fov: Any | None = None, grd: Any | None = None, hit: Any | None = None, ils: Any | None = None, jac: Any | None = None, lev: Any | None = None, lut: Any | None = None, nte: Any | None = None, obs: Any | None = None, out: Any | None = None, phy: Any | None = None, rej: Any | None = None, sfc: Any | None = None, shp: Any | None = None, svd: Any | None = None, xsc: Any | None = None, extra_sections: Mapping[str, Any] | None = None, run_id: str | None = None, clean_before: bool = False, directory: Path | str | None = None, patterns: Sequence[str] | None = None, output_mode: Literal['files', 'capture'] = 'files', enable_capture: bool | None = None, optical_levels: Sequence[float] | None = None, optical_spectrum_index: int = 1, optical_match_tol: float = 1e-06) → RunResult

Run RFM by constructing inputs directly from Python structures.

Parameters:

  • header (str | Sequence[str]) – Text for the *HDR section.

  • flags (Sequence[str]) – Recognised three-letter flag codes (case-insensitive).

  • spectral (Any) – Entries for the *SPC section; accepts numbers, strings, SpectralRange, SpectralFile, SectionLine, mappings, or nested sequences.

  • gases (Any) – Content for *GAS (molecule names, filenames, wildcards, etc.).

  • atmosphere (Any) – Content for *ATM; either filenames or PARAM=value assignments.

  • tangent (Any | None) – Tangent path specification for *TAN (required unless the TAB flag is set).

  • tab_dimensions (Any | None) – *DIM records used when the TAB flag is enabled.

  • cia (Any | None) – Content for *CIA.

  • fin (Any | None) – Content for *FIN.

  • fov (Any | None) – Content for *FOV.

  • grd (Any | None) – Content for *GRD.

  • hit (Any | None) – Content for *HIT.

  • ils (Any | None) – Content for *ILS.

  • jac (Any | None) – Content for *JAC.

  • lev (Any | None) – Content for *LEV.

  • lut (Any | None) – Content for *LUT.

  • nte (Any | None) – Content for *NTE.

  • obs (Any | None) – Content for *OBS.

  • out (Any | None) – Content for *OUT.

  • phy (Any | None) – Content for *PHY.

  • rej (Any | None) – Content for *REJ.

  • sfc (Any | None) – Content for *SFC.

  • shp (Any | None) – Content for *SHP.

  • svd (Any | None) – Content for *SVD.

  • xsc (Any | None) – Content for *XSC.

  • extra_sections (Mapping[str, Any] | None) – Additional *KEY names mapped to section data.

  • run_id (str | None) – Identifier appended to output filenames.

  • clean_before (bool) – When True remove artefacts matching patterns before running.

  • directory (Path | str | None) – Working directory containing assets and outputs.

  • patterns (Sequence[str] | None) – Filename glob patterns passed to clean_outputs().

  • output_mode (Literal["files", "capture"]) – Pass "capture" to populate the returned RunResult with the in-memory optical-depth dataframe; otherwise rely on file outputs.

  • enable_capture (bool | None) – Override whether the shared-library execution enables optical-depth capture; defaults to mirroring output_mode == "capture".

  • optical_levels (Sequence[float] | None) – Output levels (km) required when output_mode is "capture".

  • optical_spectrum_index (int) – Spectral index used when retrieving captured optical depths (default 1).

  • optical_match_tol (float) – Matching tolerance (km) applied to the captured profile grid (default 1e-6).

Returns:

RunResult – Summary of the execution and optional in-memory output.

Raises:

  • ValueError – If required arguments are missing or mutually exclusive.

  • FileNotFoundError – If the requested working directory does not exist.

srfm.orography module

Helpers for running the RFM Fortran model from Python.

  • Name: rfm_helper

  • Parent package: srfm

  • Author: Antonin Knizek

  • Contributors:

  • Date: 14 Nov 2025

class srfm.rfm_helper.DriverSectionInfo(key: str, mandatory: bool, summary: str, value_format: str, aliases: tuple[str, ...] = ())

Bases: object

Metadata describing a section within rfm.drv.

aliases: tuple[str, ...] = ()
key: str
mandatory: bool
summary: str
value_format: str
class srfm.rfm_helper.RunResult(status: int, removed_files: List[Path], output: Any | None = None, output_df: Any | None = None)

Bases: object

Encapsulates the outcome of a single RFM execution.

status

Exit status reported by the underlying executable or shared library (zero indicates success).

Type:

int

removed_files

Output artefacts deleted prior to the run when clean_before is enabled.

Type:

list[pathlib.Path]

output

Optional payload gathered from the run, such as captured optical-depth data or a mapping of output filenames to their in-memory contents.

Type:

Any | None

output_df

Optional dataframe payload reserved for optical-depth capture while still allowing output to represent file-based artefacts.

Type:

Any | None

property ok: bool

True when the RFM run completed successfully.

output: Any | None = None
output_df: Any | None = None
removed_files: List[Path]
status: int
class srfm.rfm_helper.SectionLine(*parts: Any)

Bases: object

Explicit list of tokens that form a single driver record.

parts

Token sequence written verbatim into the driver table line.

Type:

tuple[Any, …]

as_record() → str
parts: tuple[Any, ...]
class srfm.rfm_helper.SpectralFile(path: Path, label: str | None = None)

Bases: object

Reference to a pre-defined spectral range file for *SPC.

path

Path to the .spc file (coerced to Path).

Type:

pathlib.Path

label

Optional label written ahead of the filename.

Type:

str | None

as_record() → str
label: str | None = None
path: Path
class srfm.rfm_helper.SpectralRange(start: float, stop: float, spacing: float, label: str | None = None)

Bases: object

In-memory representation of a *SPC spectral range entry.

start

Lower bound of the spectral interval in cm^-1 (or GHz when the GHZ flag is set).

Type:

float

stop

Upper bound of the interval in cm^-1.

Type:

float

spacing

Sampling spacing (positive) or number of points per cm^-1 (>1).

Type:

float

label

Optional label written ahead of the range.

Type:

str | None

as_record() → str
label: str | None = None
spacing: float
start: float
stop: float
srfm.rfm_helper.clean_outputs(directory: Path | str | None = None, patterns: Sequence[str] | None = None) → List[Path]

Delete known RFM artefacts prior to a new run.

Parameters:

  • directory (Path | str | None) – Directory containing the outputs. Defaults to the current working directory.

  • patterns (Sequence[str] | None) – Filename glob patterns to remove. Defaults to ("*.asc", "rfm.log*").

Returns:

list[pathlib.Path] – Paths that were removed.

srfm.rfm_helper.get_captured_optical_depths(levels: Sequence[float], *, spectrum_index: int = 1, match_tol: float = 1e-06) → DataFrame

Return the optical-depth dataframe captured by the Fortran backend.

Parameters:

  • levels (Sequence[float]) – Altitude levels (km) defining layer bounds.

  • spectrum_index (int) – Spectral range index (1-based) to retrieve.

  • match_tol (float) – Absolute tolerance applied when matching requested levels to the captured grid.

Returns:

  • pandas.DataFrame – Layer metadata plus differential/integrated optical

  • depths mirroring the legacy ``*.opt`` parsing.

Raises:

  • ValueError – Raised when the provided levels are invalid or cannot be matched to the captured profile.

  • RuntimeError – Raised if the Fortran capture reports a failure.

srfm.rfm_helper.get_rfm_input_catalog() → dict[str, Any]

Compile metadata about supported driver sections and aliases.

Returns:

dict[str, Any] – Mapping with keys sections, mandatory_sections, optional_sections, flag_codes, and aliases.

srfm.rfm_helper.rfm_main(*, configuration: Mapping[str, Any] | None, driver_inputs: Mapping[str, Any], levels: Sequence[float], rfm_out_fldr: Path | str) → RunResult

Run the RFM model using dictionary-based configuration and inputs.

Parameters:

  • configuration (Mapping[str, Any] | None) – Optional overrides that control execution, including driver_path, generate_driver, clean_before, run_id, patterns, optical_spectrum_index, optical_match_tol, output_mode, capture_files_content, and verbose. When supplied, output_mode must be "capture" or "files".

  • driver_inputs (Mapping[str, Any]) – Structured representation of driver sections mirroring run_rfm_with_parameters().

  • levels (Sequence[float]) – Altitude levels (km) used when optical-depth capture is enabled via the OPT and LEV flags.

  • rfm_out_fldr (Path | str) – Directory in which the run should take place and where RFM writes its outputs.

Returns:

RunResult – The run status plus optional payloads. output holds the in-memory file map for capture runs (None for file-mode runs), while output_df is populated with the optical-depth dataframe when OPT and LEV are active under capture mode.

Raises:

  • FileNotFoundError – If the requested output directory does not exist.

  • NotADirectoryError – If rfm_out_fldr resolves to a file.

  • ValueError – If mandatory sections are missing, incompatible geometry inputs are provided, optical-depth capture requirements are not satisfied, or output_mode is invalid for the provided flags.

  • RuntimeError – If optical-depth capture is expected but a dataframe is not returned.

Notes

capture_files_content controls whether capture mode records the generated *.asc/log artefacts in memory (while deleting them on disk). When set to False the run still suppresses file creation but omits the in-memory payload, leaving only output_df (when applicable).

srfm.rfm_helper.run_rfm(run_id: str | None = None, *, clean_before: bool = False, directory: Path | str | None = None, patterns: Sequence[str] | None = None, driver_lines: Sequence[str] | None = None, driver_path: Path | str | None = None, output_mode: Literal['files', 'capture'] = 'files', enable_capture: bool | None = None, optical_levels: Sequence[float] | None = None, optical_spectrum_index: int = 1, optical_match_tol: float = 1e-06) → RunResult

Public wrapper that runs the Fortran backend in a fresh subprocess.

srfm.rfm_helper.run_rfm_with_parameters(*, header: str | Sequence[str], flags: Sequence[str], spectral: Any, gases: Any, atmosphere: Any, tangent: Any | None = None, tab_dimensions: Any | None = None, cia: Any | None = None, fin: Any | None = None, fov: Any | None = None, grd: Any | None = None, hit: Any | None = None, ils: Any | None = None, jac: Any | None = None, lev: Any | None = None, lut: Any | None = None, nte: Any | None = None, obs: Any | None = None, out: Any | None = None, phy: Any | None = None, rej: Any | None = None, sfc: Any | None = None, shp: Any | None = None, svd: Any | None = None, xsc: Any | None = None, extra_sections: Mapping[str, Any] | None = None, run_id: str | None = None, clean_before: bool = False, directory: Path | str | None = None, patterns: Sequence[str] | None = None, output_mode: Literal['files', 'capture'] = 'files', enable_capture: bool | None = None, optical_levels: Sequence[float] | None = None, optical_spectrum_index: int = 1, optical_match_tol: float = 1e-06) → RunResult

Run RFM by constructing inputs directly from Python structures.

Parameters:

  • header (str | Sequence[str]) – Text for the *HDR section.

  • flags (Sequence[str]) – Recognised three-letter flag codes (case-insensitive).

  • spectral (Any) – Entries for the *SPC section; accepts numbers, strings, SpectralRange, SpectralFile, SectionLine, mappings, or nested sequences.

  • gases (Any) – Content for *GAS (molecule names, filenames, wildcards, etc.).

  • atmosphere (Any) – Content for *ATM; either filenames or PARAM=value assignments.

  • tangent (Any | None) – Tangent path specification for *TAN (required unless the TAB flag is set).

  • tab_dimensions (Any | None) – *DIM records used when the TAB flag is enabled.

  • cia (Any | None) – Content for *CIA.

  • fin (Any | None) – Content for *FIN.

  • fov (Any | None) – Content for *FOV.

  • grd (Any | None) – Content for *GRD.

  • hit (Any | None) – Content for *HIT.

  • ils (Any | None) – Content for *ILS.

  • jac (Any | None) – Content for *JAC.

  • lev (Any | None) – Content for *LEV.

  • lut (Any | None) – Content for *LUT.

  • nte (Any | None) – Content for *NTE.

  • obs (Any | None) – Content for *OBS.

  • out (Any | None) – Content for *OUT.

  • phy (Any | None) – Content for *PHY.

  • rej (Any | None) – Content for *REJ.

  • sfc (Any | None) – Content for *SFC.

  • shp (Any | None) – Content for *SHP.

  • svd (Any | None) – Content for *SVD.

  • xsc (Any | None) – Content for *XSC.

  • extra_sections (Mapping[str, Any] | None) – Additional *KEY names mapped to section data.

  • run_id (str | None) – Identifier appended to output filenames.

  • clean_before (bool) – When True remove artefacts matching patterns before running.

  • directory (Path | str | None) – Working directory containing assets and outputs.

  • patterns (Sequence[str] | None) – Filename glob patterns passed to clean_outputs().

  • output_mode (Literal["files", "capture"]) – Pass "capture" to populate the returned RunResult with the in-memory optical-depth dataframe; otherwise rely on file outputs.

  • enable_capture (bool | None) – Override whether the shared-library execution enables optical-depth capture; defaults to mirroring output_mode == "capture".

  • optical_levels (Sequence[float] | None) – Output levels (km) required when output_mode is "capture".

  • optical_spectrum_index (int) – Spectral index used when retrieving captured optical depths (default 1).

  • optical_match_tol (float) – Matching tolerance (km) applied to the captured profile grid (default 1e-6).

Returns:

RunResult – Summary of the execution and optional in-memory output.

Raises:

  • ValueError – If required arguments are missing or mutually exclusive.

  • FileNotFoundError – If the requested working directory does not exist.

srfm.oxharp_main module

Helpers for running the RFM Fortran model from Python.

  • Name: rfm_helper

  • Parent package: srfm

  • Author: Antonin Knizek

  • Contributors:

  • Date: 14 Nov 2025

class srfm.rfm_helper.DriverSectionInfo(key: str, mandatory: bool, summary: str, value_format: str, aliases: tuple[str, ...] = ())

Bases: object

Metadata describing a section within rfm.drv.

aliases: tuple[str, ...] = ()
key: str
mandatory: bool
summary: str
value_format: str
class srfm.rfm_helper.RunResult(status: int, removed_files: List[Path], output: Any | None = None, output_df: Any | None = None)

Bases: object

Encapsulates the outcome of a single RFM execution.

status

Exit status reported by the underlying executable or shared library (zero indicates success).

Type:

int

removed_files

Output artefacts deleted prior to the run when clean_before is enabled.

Type:

list[pathlib.Path]

output

Optional payload gathered from the run, such as captured optical-depth data or a mapping of output filenames to their in-memory contents.

Type:

Any | None

output_df

Optional dataframe payload reserved for optical-depth capture while still allowing output to represent file-based artefacts.

Type:

Any | None

property ok: bool

True when the RFM run completed successfully.

output: Any | None = None
output_df: Any | None = None
removed_files: List[Path]
status: int
class srfm.rfm_helper.SectionLine(*parts: Any)

Bases: object

Explicit list of tokens that form a single driver record.

parts

Token sequence written verbatim into the driver table line.

Type:

tuple[Any, …]

as_record() → str
parts: tuple[Any, ...]
class srfm.rfm_helper.SpectralFile(path: Path, label: str | None = None)

Bases: object

Reference to a pre-defined spectral range file for *SPC.

path

Path to the .spc file (coerced to Path).

Type:

pathlib.Path

label

Optional label written ahead of the filename.

Type:

str | None

as_record() → str
label: str | None = None
path: Path
class srfm.rfm_helper.SpectralRange(start: float, stop: float, spacing: float, label: str | None = None)

Bases: object

In-memory representation of a *SPC spectral range entry.

start

Lower bound of the spectral interval in cm^-1 (or GHz when the GHZ flag is set).

Type:

float

stop

Upper bound of the interval in cm^-1.

Type:

float

spacing

Sampling spacing (positive) or number of points per cm^-1 (>1).

Type:

float

label

Optional label written ahead of the range.

Type:

str | None

as_record() → str
label: str | None = None
spacing: float
start: float
stop: float
srfm.rfm_helper.clean_outputs(directory: Path | str | None = None, patterns: Sequence[str] | None = None) → List[Path]

Delete known RFM artefacts prior to a new run.

Parameters:

  • directory (Path | str | None) – Directory containing the outputs. Defaults to the current working directory.

  • patterns (Sequence[str] | None) – Filename glob patterns to remove. Defaults to ("*.asc", "rfm.log*").

Returns:

list[pathlib.Path] – Paths that were removed.

srfm.rfm_helper.get_captured_optical_depths(levels: Sequence[float], *, spectrum_index: int = 1, match_tol: float = 1e-06) → DataFrame

Return the optical-depth dataframe captured by the Fortran backend.

Parameters:

  • levels (Sequence[float]) – Altitude levels (km) defining layer bounds.

  • spectrum_index (int) – Spectral range index (1-based) to retrieve.

  • match_tol (float) – Absolute tolerance applied when matching requested levels to the captured grid.

Returns:

  • pandas.DataFrame – Layer metadata plus differential/integrated optical

  • depths mirroring the legacy ``*.opt`` parsing.

Raises:

  • ValueError – Raised when the provided levels are invalid or cannot be matched to the captured profile.

  • RuntimeError – Raised if the Fortran capture reports a failure.

srfm.rfm_helper.get_rfm_input_catalog() → dict[str, Any]

Compile metadata about supported driver sections and aliases.

Returns:

dict[str, Any] – Mapping with keys sections, mandatory_sections, optional_sections, flag_codes, and aliases.

srfm.rfm_helper.rfm_main(*, configuration: Mapping[str, Any] | None, driver_inputs: Mapping[str, Any], levels: Sequence[float], rfm_out_fldr: Path | str) → RunResult

Run the RFM model using dictionary-based configuration and inputs.

Parameters:

  • configuration (Mapping[str, Any] | None) – Optional overrides that control execution, including driver_path, generate_driver, clean_before, run_id, patterns, optical_spectrum_index, optical_match_tol, output_mode, capture_files_content, and verbose. When supplied, output_mode must be "capture" or "files".

  • driver_inputs (Mapping[str, Any]) – Structured representation of driver sections mirroring run_rfm_with_parameters().

  • levels (Sequence[float]) – Altitude levels (km) used when optical-depth capture is enabled via the OPT and LEV flags.

  • rfm_out_fldr (Path | str) – Directory in which the run should take place and where RFM writes its outputs.

Returns:

RunResult – The run status plus optional payloads. output holds the in-memory file map for capture runs (None for file-mode runs), while output_df is populated with the optical-depth dataframe when OPT and LEV are active under capture mode.

Raises:

  • FileNotFoundError – If the requested output directory does not exist.

  • NotADirectoryError – If rfm_out_fldr resolves to a file.

  • ValueError – If mandatory sections are missing, incompatible geometry inputs are provided, optical-depth capture requirements are not satisfied, or output_mode is invalid for the provided flags.

  • RuntimeError – If optical-depth capture is expected but a dataframe is not returned.

Notes

capture_files_content controls whether capture mode records the generated *.asc/log artefacts in memory (while deleting them on disk). When set to False the run still suppresses file creation but omits the in-memory payload, leaving only output_df (when applicable).

srfm.rfm_helper.run_rfm(run_id: str | None = None, *, clean_before: bool = False, directory: Path | str | None = None, patterns: Sequence[str] | None = None, driver_lines: Sequence[str] | None = None, driver_path: Path | str | None = None, output_mode: Literal['files', 'capture'] = 'files', enable_capture: bool | None = None, optical_levels: Sequence[float] | None = None, optical_spectrum_index: int = 1, optical_match_tol: float = 1e-06) → RunResult

Public wrapper that runs the Fortran backend in a fresh subprocess.

srfm.rfm_helper.run_rfm_with_parameters(*, header: str | Sequence[str], flags: Sequence[str], spectral: Any, gases: Any, atmosphere: Any, tangent: Any | None = None, tab_dimensions: Any | None = None, cia: Any | None = None, fin: Any | None = None, fov: Any | None = None, grd: Any | None = None, hit: Any | None = None, ils: Any | None = None, jac: Any | None = None, lev: Any | None = None, lut: Any | None = None, nte: Any | None = None, obs: Any | None = None, out: Any | None = None, phy: Any | None = None, rej: Any | None = None, sfc: Any | None = None, shp: Any | None = None, svd: Any | None = None, xsc: Any | None = None, extra_sections: Mapping[str, Any] | None = None, run_id: str | None = None, clean_before: bool = False, directory: Path | str | None = None, patterns: Sequence[str] | None = None, output_mode: Literal['files', 'capture'] = 'files', enable_capture: bool | None = None, optical_levels: Sequence[float] | None = None, optical_spectrum_index: int = 1, optical_match_tol: float = 1e-06) → RunResult

Run RFM by constructing inputs directly from Python structures.

Parameters:

  • header (str | Sequence[str]) – Text for the *HDR section.

  • flags (Sequence[str]) – Recognised three-letter flag codes (case-insensitive).

  • spectral (Any) – Entries for the *SPC section; accepts numbers, strings, SpectralRange, SpectralFile, SectionLine, mappings, or nested sequences.

  • gases (Any) – Content for *GAS (molecule names, filenames, wildcards, etc.).

  • atmosphere (Any) – Content for *ATM; either filenames or PARAM=value assignments.

  • tangent (Any | None) – Tangent path specification for *TAN (required unless the TAB flag is set).

  • tab_dimensions (Any | None) – *DIM records used when the TAB flag is enabled.

  • cia (Any | None) – Content for *CIA.

  • fin (Any | None) – Content for *FIN.

  • fov (Any | None) – Content for *FOV.

  • grd (Any | None) – Content for *GRD.

  • hit (Any | None) – Content for *HIT.

  • ils (Any | None) – Content for *ILS.

  • jac (Any | None) – Content for *JAC.

  • lev (Any | None) – Content for *LEV.

  • lut (Any | None) – Content for *LUT.

  • nte (Any | None) – Content for *NTE.

  • obs (Any | None) – Content for *OBS.

  • out (Any | None) – Content for *OUT.

  • phy (Any | None) – Content for *PHY.

  • rej (Any | None) – Content for *REJ.

  • sfc (Any | None) – Content for *SFC.

  • shp (Any | None) – Content for *SHP.

  • svd (Any | None) – Content for *SVD.

  • xsc (Any | None) – Content for *XSC.

  • extra_sections (Mapping[str, Any] | None) – Additional *KEY names mapped to section data.

  • run_id (str | None) – Identifier appended to output filenames.

  • clean_before (bool) – When True remove artefacts matching patterns before running.

  • directory (Path | str | None) – Working directory containing assets and outputs.

  • patterns (Sequence[str] | None) – Filename glob patterns passed to clean_outputs().

  • output_mode (Literal["files", "capture"]) – Pass "capture" to populate the returned RunResult with the in-memory optical-depth dataframe; otherwise rely on file outputs.

  • enable_capture (bool | None) – Override whether the shared-library execution enables optical-depth capture; defaults to mirroring output_mode == "capture".

  • optical_levels (Sequence[float] | None) – Output levels (km) required when output_mode is "capture".

  • optical_spectrum_index (int) – Spectral index used when retrieving captured optical depths (default 1).

  • optical_match_tol (float) – Matching tolerance (km) applied to the captured profile grid (default 1e-6).

Returns:

RunResult – Summary of the execution and optional in-memory output.

Raises:

  • ValueError – If required arguments are missing or mutually exclusive.

  • FileNotFoundError – If the requested working directory does not exist.