pycontrails 0.59.0__cp314-cp314-macosx_10_15_x86_64.whl

pycontrails/models/apcemm/inputs.py

@@ -0,0 +1,226 @@
+"""Thin python wrapper over native APCEMM interface."""
+
+from __future__ import annotations
+
+import dataclasses
+import os
+import pathlib
+
+import numpy as np
+
+#: Assumed default APCEMM root directory
+APCEMM_DEFAULT_ROOT = os.path.expanduser("~/APCEMM")
+
+
+@dataclasses.dataclass
+class APCEMMInput:
+    """Parameters for APCEMM input YAML file.
+
+    Physical parameters in this class are defined using MKS units, and units are converted
+    as required at the time of YAML file generation.
+
+    Parameters without default values must be provided each time a YAML file is generated.
+    :class:`APCEMM` provides a convenient interface for determining parameter values
+    based in flight and meterology data.
+
+    Parameters with default values are set to sensible defaults, based in part on
+    values provided in example input YAML files in the
+    `APCEMM GitHub repository <https://github.com/MIT-LAE/APCEMM>`__, but users may
+    with to override default parameters when configuring APCEMM simulations.
+
+    This class exposes many but not all of the parameters in APCEMM YAML files. To request
+    that additional parameters be exposed,
+    `open an issue on GitHub <https://github.com/contrailcirrus/pycontrails/issues>`__
+    and provide:
+    - a short description of each parameter (suitable for a docstring), and
+    - a sensible default value for each parameter.
+    """
+
+    # =================================
+    # Parameters without default values
+    # =================================
+
+    #: Initial longitude [WGS84]
+    longitude: float
+
+    #: Initial latitude [WGS84]
+    latitude: float
+
+    #: Day of year at model initialization
+    day_of_year: int
+
+    #: Fractional hour of day at model initialization
+    hour_of_day: float
+
+    #: Initial pressure [:math:`Pa`]
+    air_pressure: float
+
+    #: Initial air temperature [:math:`K`]
+    air_temperature: float
+
+    #: Initial RH over liquid water [dimensionless]
+    rhw: float
+
+    #: Initial contrail-normal wind shear [:math:`1/s`]
+    normal_shear: float
+
+    #: Initial Brunt-Vaisala frequency [:math:`1/s`]
+    brunt_vaisala_frequency: float
+
+    #: Engine NOx emissions index [:math:`kg(NO2)/kg`]
+    nox_ei: float
+
+    #: Engine CO emissions index [:math:`kg/kg`]
+    co_ei: float
+
+    #: Engine unburned hydrocarbons emissions index [:math:`kg/kg`]
+    hc_ei: float
+
+    #: Engine SO2 emissions index [:math:`kg/kg`]
+    so2_ei: float
+
+    #: Engine soot emissions index [:math:`kg/kg`]
+    nvpm_ei_m: float
+
+    #: Emitted soot aerosol radius [:math:`m`]
+    soot_radius: float
+
+    #: Fuel flow [:math:`kg/s`]
+    fuel_flow: float
+
+    #: Aircraft mass [:math:`kg`]
+    aircraft_mass: float
+
+    #: Aircraft true airspeed [:math:`m/s`]
+    true_airspeed: float
+
+    #: Number of engines
+    n_engine: int
+
+    #: Wingspan [:math:`m`]
+    wingspan: float
+
+    #: Engine core exit temperature [:math:`K`]
+    core_exit_temp: float
+
+    #: Engine core exit area [:math:`m^2`]
+    core_exit_area: float
+
+    # ==============================
+    # Parameters with default values
+    # ==============================
+
+    #: Number of APCEMM threads
+    n_threads: int = 1
+
+    #: Maximum APCEMM simulation time
+    max_age: np.timedelta64 = np.timedelta64(20, "h")
+
+    #: Output directory name (relative to APCEMM simulation directory)
+    output_directory: pathlib.Path | str = "out"
+
+    #: Overwrite existing output directories
+    overwrite_output: bool = True
+
+    #: Enable APCEMM netCDF outputs
+    do_apcemm_nc_output: bool = True
+
+    #: Indices of aerosol species to include in APCEMM netCDF output
+    apcemm_nc_output_species: tuple[int] = (1,)
+
+    #: APCEMM netCDF output frequency
+    dt_apcemm_nc_output: np.timedelta64 = np.timedelta64(1, "m")
+
+    #: Path to background conditions input file (distributed with APCEMM)
+    input_background_conditions: pathlib.Path | str = os.path.join(
+        APCEMM_DEFAULT_ROOT, "input_data", "init.txt"
+    )
+
+    #: Path to engine emissions input file (distributed with APCEMM)
+    input_engine_emissions: pathlib.Path | str = os.path.join(
+        APCEMM_DEFAULT_ROOT, "input_data", "ENG_EI.txt"
+    )
+
+    #: Background NOx volume mixing ratio [nondim]
+    nox_vmr: float = 5100e-12
+
+    #: Background HNO3 volume mixing ratio [nondim]
+    hno3_vmr: float = 81.5e-12
+
+    #: Background O3 volume mixing ratio [nondim]
+    o3_vmr: float = 100e-9
+
+    #: Background CO volume mixing ratio [nondim]
+    co_vmr: float = 40e-9
+
+    #: Background CH4 volume mixing ratio [nondim]
+    ch4_vmr: float = 1.76e-6
+
+    #: Background SO2 volume mixing ratio [nondim]
+    so2_vmr: float = 7.25e-12
+
+    #: Horizontal diffusion coefficient [:math:`m^2/s`]
+    horiz_diff: float = 15.0
+
+    #: Vertical diffusion coefficient [:math:`m^2/s`]
+    vert_diff: float = 0.15
+
+    #: Engine SO2 to SO4 conversion factor [dimensionless]
+    so2_to_so4_conversion: float = 0.02
+
+    #: APCEMM transport timestep
+    dt_apcemm_transport: np.timedelta64 = np.timedelta64(1, "m")
+
+    #: Enable gravitational settling
+    do_gravitational_setting: bool = True
+
+    #: Enable solid coagulation
+    do_solid_coagulation: bool = True
+
+    #: Enable liquid coagulation
+    do_liquid_coagulation: bool = False
+
+    #: Enable ice growth
+    do_ice_growth: bool = True
+
+    #: APCEMM coagulation timestep
+    dt_apcemm_coagulation: np.timedelta64 = np.timedelta64(1, "m")
+
+    #: APCEMM ice growth timestep
+    dt_apcemm_ice_growth: np.timedelta64 = np.timedelta64(1, "m")
+
+    #: Path to meteorology input
+    input_met_file: pathlib.Path | str = "input.nc"
+
+    #: Time step of input met data
+    dt_input_met: np.timedelta64 = np.timedelta64(1, "h")
+
+    #: Number of horizontal gridpoints
+    nx: int = 200
+
+    #: Number of vertical gridpoints
+    ny: int = 180
+
+    #: Initial distance to right edge of domain [:math:`m`]
+    xlim_right: float = 1000.0
+
+    #: Initial distance to left edge of domain [:math:`m`]
+    xlim_left: float = 1000.0
+
+    #: Initial distance to top of domain [:math:`m`]
+    ylim_up: float = 300.0
+
+    #: Initial distance to bottom of domain [:math:`m`]
+    ylim_down: float = 1500.0
+
+    #: Offset applied to initial contrail depth [:math:`m`]
+    initial_contrail_depth_offset: float = 0.0
+
+    #: Scale factor applied to initial contrail depth [dimensionless]
+    initial_contrail_depth_scale_factor: float = 1.0
+
+    #: Offset applied to initial contrail width [:math:`m`]
+    initial_contrail_width_offset: float = 0.0
+
+    #: Scale factor applied to initial contrail width [dimensionless]
+    initial_contrail_width_scale_factor: float = 1.0

pycontrails/models/apcemm/static/apcemm_yaml_template.yaml

@@ -0,0 +1,183 @@
+SIMULATION MENU:
+        
+    OpenMP Num Threads (positive int): {n_threads_int}
+    
+    PARAM SWEEP SUBMENU:
+        Parameter sweep (T/F): T
+        Run Monte Carlo (T/F): F
+        Num Monte Carlo runs (int): -1
+    
+    OUTPUT SUBMENU:
+        Output folder (string): {output_folder_str}
+        Overwrite if folder exists (T/F): {overwrite_output_bool}
+    
+    Use threaded FFT (T/F): F
+    
+    FFTW WISDOM SUBMENU:
+        Use FFTW WISDOM (T/F): F
+        Dir w/ write permission (string): n/a
+    
+    Input background condition (string): {input_background_conditions_str}
+    Input engine emissions (string): {input_engine_emissions_str}
+    
+    SAVE FORWARD RESULTS SUBMENU:
+        Save forward results (T/F): F
+        netCDF filename format (string): n/a
+    
+    ADJOINT OPTIMIZATION SUBMENU:
+        Turn on adjoint optim. (T/F): F
+        netCDF filename format (string): n/a
+    
+    BOX MODEL SUBMENU:
+        Run box model (T/F): F
+        netCDF filename format (string): n/a            
+    
+PARAMETER MENU:
+    
+    Plume Process [hr] (double): {max_age_hr}
+    
+    METEOROLOGICAL PARAMETERS SUBMENU:
+        Temperature [K] (double): {temperature_k}
+        R.Hum. wrt water [%] (double): {rhw_percent}
+        Pressure [hPa] (double): {pressure_hpa}
+        Horiz. diff. coeff. [m^2/s] (double): {horiz_diff_coeff_m2_per_s}
+        Verti. diff. [m^2/s] (double): {vert_diff_coeff_m2_per_s}
+        Wind shear [1/s] (double): {wind_shear_per_s}
+        Brunt-Vaisala Frequency [s^-1] (double): {brunt_vaisala_frequency_per_s}
+    
+    LOCATION AND TIME SUBMENU:
+        LON [deg] (double): {longitude_deg}
+        LAT [deg] (double): {latitude_deg}
+        Emission day [1-365] (int): {emission_day_dayofyear}
+        Emission time [hr] (double): {emission_time_hourofday}
+           
+    BACKGROUND MIXING RATIOS SUBMENU:
+        NOx [ppt] (double): {nox_ppt}
+        HNO3 [ppt] (double): {hno3_ppt}
+        O3 [ppb] (double): {o3_ppb}
+        CO [ppb] (double): {co_ppb}
+        CH4 [ppm] (double): {ch4_ppm}
+        SO2 [ppt] (double): {so2_ppt}
+    
+    EMISSION INDICES SUBMENU:
+        NOx [g(NO2)/kg_fuel] (double): {nox_g_per_kg}
+        CO [g/kg_fuel] (double): {co_g_per_kg}
+        UHC [g/kg_fuel] (double): {uhc_g_per_kg}
+        SO2 [g/kg_fuel] (double): {so2_g_per_kg}
+        SO2 to SO4 conv [%] (double): {so2_to_so4_conv_percent}
+        Soot [g/kg_fuel] (double): {soot_g_per_kg}
+        
+    Soot Radius [m] (double): {soot_radius_m}
+    Total fuel flow [kg/s] (double): {total_fuel_flow_kg_per_s}
+    Aircraft mass [kg] (double): {aircraft_mass_kg}
+    Flight speed [m/s] (double): {flight_speed_m_per_s}
+    Num. of engines [2/4] (int): {num_of_engines_int}
+    Wingspan [m] (double): {wingspan_m}
+    Core exit temp. [K] (double): {core_exit_temp_k}
+    Exit bypass area [m^2] (double): {exit_bypass_area_m2}
+    
+TRANSPORT MENU:
+    
+    Turn on Transport (T/F): T
+    Fill Negative Values (T/F): T
+    Transport Timestep [min] (double): {transport_timestep_min}
+    
+    PLUME UPDRAFT SUBMENU:
+        Turn on plume updraft (T/F): F
+        Updraft timescale [s] (double): -1
+        Updraft veloc. [cm/s] (double): -1
+    
+CHEMISTRY MENU:
+    
+    Turn on Chemistry (T/F): F
+    Perform hetero. chem. (T/F): F
+    Chemistry Timestep [min] (double): -1
+    Photolysis rates folder (string): n/a
+    
+AEROSOL MENU:
+    
+    Turn on grav. settling (T/F): {gravitational_settling_bool}
+    Turn on solid coagulation (T/F): {solid_coagulation_bool}
+    Turn on liquid coagulation (T/F): {liquid_coagulation_bool}
+    Coag. timestep [min] (double): {coag_timestep_min}
+    Turn on ice growth (T/F): {ice_growth_bool}
+    Ice growth timestep [min] (double): {ice_growth_timestep_min}
+    
+METEOROLOGY MENU:
+    
+    METEOROLOGICAL INPUT SUBMENU:
+        Use met. input (T/F): T
+        Met input file path (string): {met_input_file_path_str}
+        Time series data timestep [hr] (double): {time_series_data_timestep_hr}
+        Init temp. from met. (T/F): T
+        Temp. time series input (T/F): T
+        Interpolate temp. met. data (T/F): T
+        Init RH from met. (T/F): T
+        RH time series input (T/F): T
+        Interpolate RH met. data (T/F): T
+        Init wind shear from met. (T/F): T
+        Wind shear time series input (T/F): T
+        Interpolate shear met. data (T/F): T
+        Init vert. veloc. from met. data (T/F): F
+        Vert. veloc. time series input (T/F): F
+        Interpolate vert. veloc. met. data (T/F): F
+    
+        HUMIDITY SCALING OPTIONS:
+            Humidity modification scheme (none / constant / scaling): none
+            Constant RHi [%] (double): -1
+            Humidity scaling constant a (double): -1
+            Humidity scaling constant b (double): -1
+    
+    
+    IMPOSE MOIST LAYER DEPTH SUBMENU:
+        Impose moist layer depth (T/F): F
+        Moist layer depth [m] (double): -1
+        Subsaturated air RHi [%] (double): -1
+    
+    IMPOSE LAPSE RATE SUBMENU:
+        Impose lapse rate (T/F): F
+        Lapse rate [K/m] (T/F): -1
+        
+    Add diurnal variations (T/F): F
+            
+    TEMPERATURE PERTURBATION SUBMENU:
+        Enable Temp. Pert. (T/F): F
+        Temp. Perturb. Amplitude (double): -1
+        Temp. Perturb. Timescale (min): -1
+    
+DIAGNOSTIC MENU:
+    
+    netCDF filename format (string): trac_avg.apcemm.hhmm
+    
+    SPECIES TIMESERIES SUBMENU:
+        Save species timeseries (T/F): F
+        Inst timeseries file (string): n/a
+        Species indices to include (list of ints): -1
+        Save frequency [min] (double): -1
+    
+    AEROSOL TIMESERIES SUBMENU:
+        Save aerosol timeseries (T/F): {save_aerosol_timeseries_bool}
+        Inst timeseries file (string): ts_aerosol_hhmm.nc
+        Aerosol indices to include (list of ints): {aerosol_indices_list_int}
+        Save frequency [min] (double): {save_frequency_min}
+    
+    PRODUCTION & LOSS SUBMENU:
+        Turn on P/L diag (T/F): F
+        Save O3 P/L (T/F): F
+    
+ADVANCED OPTIONS MENU:
+    
+    GRID SUBMENU:
+        NX (positive int): {nx_pos_int}
+        NY (positive int): {ny_pos_int}
+        XLIM_RIGHT (positive double): {xlim_right_pos_m}
+        XLIM_LEFT (positive double): {xlim_left_pos_m}
+        YLIM_UP (positive double): {ylim_up_pos_m}
+        YLIM_DOWN (positive double): {ylim_down_pos_m}
+    INITIAL CONTRAIL SIZE SUBMENU:
+        Base Contrail Depth [m] (double): {base_contrail_depth_m}
+        Contrail Depth Scaling Factor [-] (double): {contrail_depth_scaling_factor_nondim}
+        Base Contrail Width [m] (double): {base_contrail_width_m}
+        Contrail Width Scaling Factor [-] (double): {contrail_width_scaling_factor_nondim}
+    Ambient Lapse Rate [K/km] (double): -1
+    Tropopause Pressure [Pa] (double): -1