CLI Commands

make_storm_ensemble

/home/docs/checkouts/readthedocs.org/user_builds/ensembleperturbation/envs/latest/lib/python3.10/site-packages/geopandas/_compat.py:111: UserWarning: The Shapely GEOS version (3.11.3-CAPI-1.17.3) is incompatible with the GEOS version PyGEOS was compiled with (3.10.4-CAPI-1.16.2). Conversions between both will be slow.
  warnings.warn(
usage: make_storm_ensemble [-h] --number-of-perturbations
                           NUMBER_OF_PERTURBATIONS --storm-code STORM_CODE
                           [--start-date START_DATE] [--end-date END_DATE]
                           [--advisories [ADVISORIES ...]]
                           [--file-deck FILE_DECK]
                           [directory]

positional arguments:
  directory             output directory

options:
  -h, --help            show this help message and exit
  --number-of-perturbations NUMBER_OF_PERTURBATIONS
                        number of perturbations
  --storm-code STORM_CODE
                        storm name/code
  --start-date START_DATE
                        start date
  --end-date END_DATE   end date
  --advisories [ADVISORIES ...]
                        record type (i.e. `BEST`, `OFCL`)
  --file-deck FILE_DECK
                        letter of file deck, one of `a`, `b`, or `f`
ensembleperturbation.perturbation.atcf.perturb_tracks(perturbations: int | List[float] | List[Dict[str, float]], directory: PathLike | None = None, storm: str | PathLike | None = None, variables: List[VortexPerturbedVariable] | None = None, sample_from_distribution: bool = False, sample_rule: str = 'random', quadrature: bool = False, quadrature_order: int = 3, quadrature_rule: str = 'Gaussian', sparse_quadrature: bool = False, start_date: datetime | None = None, end_date: datetime | None = None, file_deck: ATCF_FileDeck | None = None, advisories: List[str] | None = None, overwrite: bool = False, parallel: bool = True)

write a set of perturbed storm tracks

Parameters:

  • perturbations – either the number of perturbations to create, or a list of floats meant to represent points on either the standard Gaussian distribution or a bounded uniform distribution

  • directory – directory to which to write

  • storm – ATCF storm ID, or file path to an existing fort.22 / ATCF file, from which to perturb

  • variables – vortex variables to perturb

  • sample_from_distribution – override given perturbations with random samples from the joint distribution

  • sample_rule – rule to use for the distribution sampling. Please choose from: random [default], sobol, halton,``hammersley``, korobov, additive_recursion, or latin_hypercube

  • quadrature – add perturbations along quadrature

  • quadrature_order – order of the quadrature

  • quadrature_rule – rule of the quadrature for generating abscissas and weights

  • sparse_quadrature – use Smolyak’s sparse grid instead of normal tensor product grid

  • start_date – model start time of ensemble

  • end_date – model end time of ensemble

  • file_deck – letter of file deck, one of a, b

  • advisories – record types (i.e. BEST, OFCL)

  • overwrite – overwrite existing files

  • parallel – generate perturbations concurrently

Returns:

mapping of track names to perturbation JSONs

perturb_tracks

perturb_tracks is an extension of initialize_adcirc from CoupledModelDriver

/home/docs/checkouts/readthedocs.org/user_builds/ensembleperturbation/envs/latest/lib/python3.10/site-packages/geopandas/_compat.py:111: UserWarning: The Shapely GEOS version (3.11.3-CAPI-1.17.3) is incompatible with the GEOS version PyGEOS was compiled with (3.10.4-CAPI-1.16.2). Conversions between both will be slow.
  warnings.warn(
usage: perturb_tracks [-h] --platform PLATFORM --mesh-directory MESH_DIRECTORY
                      --modeled-start-time MODELED_START_TIME
                      --modeled-duration MODELED_DURATION --modeled-timestep
                      MODELED_TIMESTEP [--nems-interval NEMS_INTERVAL]
                      [--modulefile MODULEFILE] [--forcings FORCINGS]
                      [--adcirc-executable ADCIRC_EXECUTABLE]
                      [--adcprep-executable ADCPREP_EXECUTABLE]
                      [--aswip-executable ASWIP_EXECUTABLE]
                      [--adcirc-processors ADCIRC_PROCESSORS]
                      [--job-duration JOB_DURATION]
                      [--output-directory OUTPUT_DIRECTORY] [--skip-existing]
                      [--absolute-paths] [--verbose] [--adcirc] [--schism]
                      [--perturbations PERTURBATIONS] [--variables VARIABLES]
                      [--sample] [--sample-rule SAMPLE_RULE] [--quadrature]

options:
  -h, --help            show this help message and exit
  --platform PLATFORM   HPC platform for which to configure
  --mesh-directory MESH_DIRECTORY
                        path to input mesh (`fort.13`, `fort.14`)
  --modeled-start-time MODELED_START_TIME
                        start time within the modeled system
  --modeled-duration MODELED_DURATION
                        duration within the modeled system
  --modeled-timestep MODELED_TIMESTEP
                        time interval within the modeled system
  --nems-interval NEMS_INTERVAL
                        main loop interval of NEMS run
  --modulefile MODULEFILE
                        path to modulefile to source before model execution`
  --forcings FORCINGS   comma-separated list of forcings to configure, from
                        ['tidal', 'atmesh', 'besttrack', 'owi', 'ww3data']
  --adcirc-executable ADCIRC_EXECUTABLE
                        filename of compiled `adcirc` or `NEMS.x`
  --adcprep-executable ADCPREP_EXECUTABLE
                        filename of compiled `adcprep` (mesh decomposition)
  --aswip-executable ASWIP_EXECUTABLE
                        filename of compiled `aswip` (preprocessing of best
                        track / ATCF file)
  --adcirc-processors ADCIRC_PROCESSORS
                        numbers of processors to assign for ADCIRC
  --job-duration JOB_DURATION
                        wall clock time for job
  --output-directory OUTPUT_DIRECTORY
                        directory to which to write configuration files
                        (defaults to `.`)
  --skip-existing       skip existing files
  --absolute-paths      write paths as absolute in configuration
  --verbose             show more verbose log messages
  --adcirc              Initialize ADCIRC simulation ensemble (default)
  --schism              Initialize SCHISM simulation ensemble
  --perturbations PERTURBATIONS
                        number of perturbations to create
  --variables VARIABLES
                        vortex variables to perturb
  --sample              override given perturbations with random samples from
                        the joint distribution
  --sample-rule SAMPLE_RULE
                        rule to use for the distribution sampling. Please
                        choose from: 'random' [default], 'sobol', 'halton',
                        'hammersley', 'korobov', 'additive_recursion', or
                        'latin_hypercube'
  --quadrature          add additional perturbations along the quadrature

The extension adds several new arguments: --perturbations, --variables, --quadrature, and --serial

perturb_tracks \
    --platform HERA \
    --mesh-directory /scratch2/COASTAL/coastal/save/shared/models/meshes/hsofs/250m/v1.0_fixed \
    --modeled-start-time "2018-09-11 06:00:00" \
    --modeled-duration "07:00:00:00" \
    --modeled-timestep "00:00:02" \
    --nems-interval "01:00:00" \
    --forcings tidal,besttrack \
    --tidal-spinup-duration "07:00:00:00" \
    --tidal-source TPXO \
    --tidal-path /scratch2/COASTAL/coastal/save/shared/models/forcings/tides/h_tpxo9.v1.nc \
    --besttrack-nws 8 \
    --besttrack-storm-id florence2018 \
    --adcirc-executable /scratch2/COASTAL/coastal/save/shared/repositories/CoastalApp_PaHM/ALLBIN_INSTALL/NEMS.x \
    --adcprep-executable /scratch2/COASTAL/coastal/save/shared/repositories/CoastalApp_PaHM/ALLBIN_INSTALL/adcprep \
    --perturbations 256 \
    --quadrature \
    --serial

combine_results

/home/docs/checkouts/readthedocs.org/user_builds/ensembleperturbation/envs/latest/lib/python3.10/site-packages/geopandas/_compat.py:111: UserWarning: The Shapely GEOS version (3.11.3-CAPI-1.17.3) is incompatible with the GEOS version PyGEOS was compiled with (3.10.4-CAPI-1.16.2). Conversions between both will be slow.
  warnings.warn(
usage: combine_results [-h] [--adcirc] [--schism] [--adcirc-like-output]
                       [--filenames [FILENAMES ...]] [--bounds BOUNDS]
                       [--max-depth MAX_DEPTH]
                       [--elevation-selection ELEVATION_SELECTION]
                       [--parallel] [--verbose]
                       [output] [directory]

positional arguments:
  output                output directory
  directory             directory containing completed `runs` directory

options:
  -h, --help            show this help message and exit
  --adcirc
  --schism
  --adcirc-like-output
  --filenames [FILENAMES ...]
                        Model output files to parse
  --bounds BOUNDS       bounding box in format `(minx,miny,maxx,maxy)`
  --max-depth MAX_DEPTH
                        maximum depth value to filter by
  --elevation-selection ELEVATION_SELECTION
                        filter elevation nodes based on sea level (one of
                        `wet`, `inundated`, `dry`)
  --parallel            load concurrently with Dask
  --verbose             log more verbose messages
ensembleperturbation.client.combine_results.combine_results(output: PathLike, model: str = 'adcirc', adcirc_like: bool = False, directory: PathLike | None = None, filenames: List[str] | None = None, bounds: Tuple[float, float, float, float] | None = None, max_depth: float | None = None, elevation_selection: ElevationSelection | ElevationSelection | None = None, parallel: bool = False, verbose: bool = False) → Dict[str, DataFrame]

plot_results

usage: plot_results [-h] filename

positional arguments:
  filename    filename (`*.h5`) generated by `combine_results`

options:
  -h, --help  show this help message and exit