smoke_dust.core package

Subpackages

• smoke_dust.core.regrid package
  • Submodules
  • smoke_dust.core.regrid.common module
    • AbstractWrapper
      • AbstractWrapper.dims
    • Dimension
      • Dimension.coordinate_type
      • Dimension.lower
      • Dimension.name
      • Dimension.size
      • Dimension.staggerloc
      • Dimension.upper
    • DimensionCollection
      • DimensionCollection.get()
      • DimensionCollection.value
    • FieldWrapper
      • FieldWrapper.fill_nc_variable()
      • FieldWrapper.gwrap
      • FieldWrapper.value
    • GridSpec
      • GridSpec.create_grid_dims()
      • GridSpec.get_x_corner()
      • GridSpec.get_x_data()
      • GridSpec.get_y_corner()
      • GridSpec.get_y_data()
      • GridSpec.has_corners
      • GridSpec.x_center
      • GridSpec.x_corner
      • GridSpec.x_corner_dim
      • GridSpec.x_dim
      • GridSpec.x_index
      • GridSpec.y_center
      • GridSpec.y_corner
      • GridSpec.y_corner_dim
      • GridSpec.y_dim
      • GridSpec.y_index
    • GridWrapper
      • GridWrapper.corner_dims
      • GridWrapper.fill_nc_variables()
      • GridWrapper.spec
      • GridWrapper.value
    • NcToField
      • NcToField.create_field_wrapper()
      • NcToField.dim_time
      • NcToField.gwrap
      • NcToField.name
      • NcToField.path
    • NcToGrid
      • NcToGrid.create_grid_wrapper()
      • NcToGrid.path
      • NcToGrid.spec
    • load_variable_data()
    • mask_edges()
  • smoke_dust.core.regrid.processor module
    • SmokeDustRegridProcessor
      • SmokeDustRegridProcessor.log()
      • SmokeDustRegridProcessor.run()

Submodules

smoke_dust.core.common module

Contains common functionality used across smoke/dust.

create_descriptive_statistics(container: Dict[str, numpy.ma.MaskedArray], origin: Literal['src', 'dst_unmasked', 'dst_masked', 'derived'], path: Path) → pandas.DataFrame

Create a standard set of descriptive statistics using pandas.

Parameters:

• container – A dictionary mapping names to masked arrays.

• origin – A tag to indicate the data origin to add to the created dataframe.

• path – Path to the netCDF file where the container data originated.

Returns:

A dataframe containing descriptive statistics fields.

create_sd_coordinate_variable(nc_ds: netCDF4.Dataset, sd_variable: SmokeDustVariable) → None

Create a smoke/dust netCDF spatial coordinate variable.

Parameters:

• nc_ds – Dataset to update.

• sd_variable – Contains variable metadata.

create_sd_variable(nc_ds: netCDF4.Dataset, sd_variable: SmokeDustVariable, fill_first_time_index: bool = True) → None

Create a smoke/dust netCDF variable.

Parameters:

• nc_ds – Dataset to update

• sd_variable – Contains variable metadata

• fill_first_time_index – If True, fill the first time index with provided fill_value_float

create_template_emissions_file(nc_ds: netCDF4.Dataset, grid_shape: Tuple[int, int], is_dummy: bool = False)

Create a smoke/dust template netCDF emissions file.

Parameters:

• nc_ds – The target netCDF dataset object.

• grid_shape – The grid shape to create.

• is_dummy – Converted to a netCDF attribute to indicate if the created file is dummy emissions or will contain actual values.

open_nc(path: Path, mode: Literal['r', 'w', 'a'] = 'r', clobber: bool = False, parallel: bool = True) → netCDF4.Dataset

Open a netCDF file for various operations.

Parameters:

• path – Path to the target netCDF file.

• mode – Mode to open the file in.

• clobber – If True, overwrite an existing file.

• parallel – If True, open the netCDF for parallel operations.

Returns:

A netCDF dataset object.

smoke_dust.core.context module

Context object for smoke/dust holding external and derived parameters.

class EbbDCycle(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Emission forecast cycle method.

• 1: Estimate emissions and fire radiative power.

• 2: In addition to 1, also create inputs to forecast hourly wildfire potential.

ONE = '1'

TWO = '2'

class EmissionVariable(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Maps RAVE and smoke/dust variable names.

FRE = 'FRE'

FRP = 'FRP'

rave_name() → str

Convert to a RAVE name.

smoke_dust_name() → str

Convert to a smoke/dust name.

class LogLevel(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Logging level for the preprocessor.

DEBUG = 'debug'

INFO = 'info'

class PredefinedGrid(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Predefined grids supported by smoke/dust.

RRFS_CONUS_13KM = 'RRFS_CONUS_13km'

RRFS_CONUS_25KM = 'RRFS_CONUS_25km'

RRFS_CONUS_3KM = 'RRFS_CONUS_3km'

RRFS_NA_13KM = 'RRFS_NA_13km'

RRFS_NA_3KM = 'RRFS_NA_3km'

class RaveQaFilter(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Quality assurance flag filtering to apply to input RAVE data. RAVE QA filter values range from one to three.

• none: Do not apply any QA filtering.

• high: QA flag values less than 2 are set to zero for derived fire radiative energy

  fields.

HIGH = 'high'

NONE = 'none'

class SmokeDustContext(*args: Any, **kwargs: Any)

Bases: BaseModel

Context object for smoke/dust.

allow_dummy_restart: bool = True

beta: float = 0.3

create_dummy_emissions_file() → None

Create a dummy emissions file. This occurs if it is the first day of the forecast or there is an exception and the context is set to not exit on error.

property emissions_path: Path

Path to the output emissions files containing ICs for smoke/dust.

esmpy_debug: bool = False

property fcst_datetime: datetime

The starting datetime object parsed from the current_day.

fg_to_ug: float = 1000000.0

property grid_in: Path

Path to the grid definition for RAVE data.

property grid_out: Path

Path to the forecast grid definition.

grid_out_shape: tuple[int, int] = (0, 0)

property hourly_hwpdir: Path

Path to the root directory containing restart files.

log(msg, level=20, exc_info: Exception = None, stacklevel: int = 2)

Log a message.

Parameters:

• msg – The message to log.

• level – An optional override for the message level.

• exc_info – If provided, log this exception and raise an error if self.exit_on_error is True.

• stacklevel – If greater than 1, the corresponding number of stack frames are skipped when computing the line number and function name.

property rave_to_intp: str

File prefix for interpolated RAVE files.

should_calc_desc_stats: bool = False

to_s: int = 3600

vars_emis: tuple[str] = ('FRP_MEAN', 'FRE')

property veg_map: Path

Path to the vegetation map netCDF file which contains emission factors.

property weightfile: Path

Path to pre-calculated ESMF weights file mapping the RAVE grid to forecast grid.

smoke_dust.core.cycle module

Forecast cycle definitions for smoke/dust.

class AbstractSmokeDustCycleProcessor(context: SmokeDustContext)

Bases: ABC

Base class for all smoke/dust cycle processors.

abstract average_frp() → AverageFrpOutput

Calculate fire radiative power and smoke emissions from biomass burning.

Returns:

Fire radiative power and smoke emissions.

abstract create_start_datetime() → datetime

Creates the cycle’s start datetime. Used when searching for RAVE files to use for the forecast.

property cycle_dates: pandas.DatetimeIndex

Create the forecast dates for cycle.

property cycle_metadata: pandas.DataFrame

Create forecast metadata consisting of:

• forecast_date: The forecast timestep as a datetime object.

• rave_interpolated: To the date’s corresponding interpolated RAVE file. Null if not

  found.

• rave_raw: Raw RAVE data before interpolation. Null if not found.

finalize() → None

Optional override for subclasses.

abstract flag() → EbbDCycle

The cycle flag associated with the processor.

log(*args: Any, **kwargs: Any) → None

See SmokeDustContext.log.

abstract run() → None

Create smoke/dust ICs emissions file.

class AverageFrpOutput(*args: Any, **kwargs: Any)

Bases: BaseModel

Output expected from the average_frp method.

data: dict[str, numpy.ndarray]

model_config = {'arbitrary_types_allowed': True}

class SmokeDustCycleOne(context: SmokeDustContext)

Bases: AbstractSmokeDustCycleProcessor

Creates ICs consisting of fire radiative power and smoke emissions from biomass burning.

average_frp() → AverageFrpOutput

Calculate fire radiative power and smoke emissions from biomass burning.

Returns:

Fire radiative power and smoke emissions.

create_start_datetime() → datetime

Creates the cycle’s start datetime. Used when searching for RAVE files to use for the forecast.

flag = '1'

run() → None

Create smoke/dust ICs emissions file.

class SmokeDustCycleTwo(context: SmokeDustContext)

Bases: AbstractSmokeDustCycleProcessor

In addition to outputs from cycle 1, also creates ICs for forecasting hourly wildfire potential.

average_frp() → AverageFrpOutput

Calculate fire radiative power and smoke emissions from biomass burning.

Returns:

Fire radiative power and smoke emissions.

create_start_datetime() → datetime

Creates the cycle’s start datetime. Used when searching for RAVE files to use for the forecast.

expected_restart_varnames = ('totprcp_ave', 'rrfs_hwp_ave')

flag = '2'

run() → None

Create smoke/dust ICs emissions file.

create_cycle_processor(context: SmokeDustContext) → AbstractSmokeDustCycleProcessor

Factory function to create the smoke/dust cycle processor.

smoke_dust.core.preprocessor module

Smoke/dust preprocessor core implementation.

class SmokeDustPreprocessor(context: SmokeDustContext)

Bases: object

Implements smoke/dust preprocessing such as regridding and IC value calculations.

property cycle_dates: pandas.DatetimeIndex

See AbstractSmokeDustCycleProcessor.cycle_dates.

property cycle_metadata: pandas.DataFrame

See AbstractSmokeDustCycleProcessor.cycle_metadata.

finalize() → None

Finalize the preprocessor.

property is_first_day: bool

True if this is considered the “first day” of the simulation where there is no interpolated or raw RAVE data available.

log(*args: Any, **kwargs: Any) → None

See SmokeDustContext.log.

run() → None

Run the preprocessor.

smoke_dust.core.variable module

Variable definitions used by smoke/dust.

class SmokeDustVariable(*args: Any, **kwargs: Any)

Bases: BaseModel

Model for a smoke/dust variable.

class SmokeDustVariables(*args: Any, **kwargs: Any)

Bases: BaseModel

Canonical collection of smoke/dust variables.

get(name: str) → SmokeDustVariable

Get a smoke/dust variable from the collection.