JSON Configurations

coupledmodeldriver generates and reads various modular JSON files to store an overall configuration. These JSON files can be manually edited, swapped in and out, or removed entirely to modify the resulting configuration.

For example, consider the following simple NEMS-ADCIRC configuration:

  • configure_modeldriver.json

  • configure_nems.json

  • configure_adcirc.json

This can be turned into an ADCIRC-only configuration, that ingests tidal forcing and uses Slurm, by adding configure_tidal.json and configure_slurm.json, and removing configure_nems.json:

  • configure_modeldriver.json

  • configure_slurm.json

  • configure_adcirc.json

  • configure_tidal.json

Then, the configuration can be regenerated with generate_adcirc.

configure_modeldriver.json

class coupledmodeldriver.configure.base.ModelDriverJSON(platform: Platform, perturbations: Dict[str, Dict[str, Dict[str, Any]]] | None = None, **kwargs)

model driver configuration in configure_modeldriver.json

stores platform information and a dictionary of perturbations of other configurations per each run

configuration = ModelDriverJSON(
    platform=Platform.HERA,
    perturbations=None,
)
Parameters:

  • platform – platform on which to run

  • perturbations – dictionary of runs encompassing run names to parameter values

classmethod from_file(filename: PathLike) → ConfigurationJSON

read existing JSON file

Parameters:

filename – path to JSON file

Returns:

configuration object

classmethod from_string(string: str) → ConfigurationJSON

read JSON string

Parameters:

string – JSON string

Returns:

configuration object

move_paths(relative: PathLike)
Parameters:

relative – path to which to move Path attributes

to_file(filename: PathLike | None = None, absolute: bool = False, overwrite: bool = False)

write configuration to file

Parameters:

  • filename – path to output file

  • absolute – whether to write absolute paths

  • overwrite – whether to overwrite existing file

configure_slurm.json

class coupledmodeldriver.configure.base.SlurmJSON(account: str, tasks: int | None = None, partition: str | None = None, job_duration: timedelta | None = None, run_directory: PathLike | None = None, run_name: str | None = None, email_type: SlurmEmailType | None = None, email_address: str | None = None, log_filename: PathLike | None = None, modules: List[str] | None = None, path_prefix: Path | None = None, extra_commands: List[str] | None = None, launcher: str | None = None, nodes: int | None = None, **kwargs)

Slurm configuration parameters in configure_slurm.json

stores account and partition names, wall-clock time, email notification, etc.

configuration = SlurmJSON(
    account='coastal',
    tasks=602,
    job_duration=timedelta(hours=6),
)
classmethod from_file(filename: PathLike) → ConfigurationJSON

read existing JSON file

Parameters:

filename – path to JSON file

Returns:

configuration object

classmethod from_string(string: str) → ConfigurationJSON

read JSON string

Parameters:

string – JSON string

Returns:

configuration object

move_paths(relative: PathLike)
Parameters:

relative – path to which to move Path attributes

to_file(filename: PathLike | None = None, absolute: bool = False, overwrite: bool = False)

write configuration to file

Parameters:

  • filename – path to output file

  • absolute – whether to write absolute paths

  • overwrite – whether to overwrite existing file

configure_nems.json

class coupledmodeldriver.configure.base.NEMSJSON(executable_path: PathLike, modeled_start_time: datetime, modeled_end_time: datetime, interval: timedelta | None = None, connections: List[List[str]] | None = None, mediations: List[List[str]] | None = None, sequence: List[str] | None = None, **kwargs)

NEMS configuration in configure_nems.json

stores NEMS executable path, modeled times / interval, connections / mediations, and the order of the run sequence

model_entries = [
    AtmosphericForcingEntry('Wind_HWRF_SANDY_Nov2018_ExtendedSmoothT.nc'),
    WaveWatch3ForcingEntry('ww3.HWRF.NOV2018.2012_sxy.nc'),
    ADCIRCEntry(600),
]

connections = [['ATM', 'OCN'], ['WAV', 'OCN']]
mediations = None
sequence = [
    'ATM -> OCN',
    'WAV -> OCN',
    'ATM',
    'WAV',
    'OCN',
]

configuration = NEMSJSON(
    executable_path='NEMS.x',
    modeled_start_time=datetime(2012, 10, 22, 6),
    modeled_end_time=datetime(2012, 10, 22, 6) + timedelta(days=14.5),
    interval=timedelta(hours=1),
    connections=connections,
    mediations=mediations,
    sequence=sequence,
)

modeling_system = configuration.to_nemspy(model_entries)
classmethod from_file(filename: PathLike) → ConfigurationJSON

read existing JSON file

Parameters:

filename – path to JSON file

Returns:

configuration object

classmethod from_string(string: str) → ConfigurationJSON

read JSON string

Parameters:

string – JSON string

Returns:

configuration object

move_paths(relative: PathLike)
Parameters:

relative – path to which to move Path attributes

to_file(filename: PathLike | None = None, absolute: bool = False, overwrite: bool = False)

write configuration to file

Parameters:

  • filename – path to output file

  • absolute – whether to write absolute paths

  • overwrite – whether to overwrite existing file

configure_adcirc.json

class coupledmodeldriver.generate.adcirc.base.ADCIRCJSON(adcirc_executable_path: PathLike, adcprep_executable_path: PathLike, modeled_start_time: datetime, modeled_end_time: datetime, modeled_timestep: timedelta, fort_13_path: PathLike, fort_14_path: PathLike, tidal_spinup_duration: timedelta | None = None, tidal_spinup_timestep: timedelta | None = None, forcings: List[Forcing] | None = None, aswip_executable_path: PathLike | None = None, source_filename: PathLike | None = None, slurm_configuration: SlurmJSON | None = None, use_original_mesh: bool = False, output_surface: bool = True, surface_output_interval: timedelta | None = None, output_stations: bool = False, stations_output_interval=None, stations_file_path: PathLike | None = None, output_spinup: bool = True, output_elevations: bool = True, output_velocities: bool = True, output_concentrations: bool = False, output_meteorological_factors: bool = False, processors: int = 11, nems_parameters: Dict[str, str] | None = None, attributes: Dict[str, Any] | None = None, **kwargs)

ADCIRC configuration in configure_adcirc.json

stores a number of ADCIRC parameters (ICS, IM, etc.) and optionally NEMS parameters

configuration = ADCIRCJSON(
    adcirc_executable_path='adcirc',
    adcprep_executable_path='adcprep',
    modeled_start_time=datetime(2012, 10, 22, 6),
    modeled_end_time=datetime(2012, 10, 22, 6) + timedelta(days=14.5),
    modeled_timestep=timedelta(seconds=2),
    fort_13_path=None,
    fort_14_path=INPUT_DIRECTORY / 'meshes' / 'shinnecock' / 'fort.14',
    tidal_spinup_duration=timedelta(days=12.5),
)
Parameters:

  • adcirc_executable_path – file path to adcirc or NEMS.x

  • adcprep_executable_path – file path to adcprep

  • aswip_executable_path – file path to aswip

  • modeled_start_time – start time in model run

  • modeled_end_time – edn time in model run

  • modeled_timestep – time interval between model steps

  • fort_13_path – file path to fort.13

  • fort_14_path – file path to fort.14

  • tidal_spinup_duration – tidal spinup duration for ADCIRC coldstart

  • tidal_spinup_timestep – tidal spinup modeled time interval for ADCIRC coldstart

  • forcings – list of Forcing objects to apply to the mesh

  • source_filename – path to modulefile to source

  • slurm_configuration – Slurm configuration object

  • use_original_mesh – whether to symlink / copy original mesh instead of rewriting with adcircpy

  • output_surface – write surface (entire mesh) to NetCDF

  • surface_output_interval – frequency at which output is written to file

  • output_stations – write stations to NetCDF (only applicable if stations file exists)

  • stations_output_interval – frequency at which stations output is written to file

  • stations_file_path – file path to stations file

  • output_spinup – write spinup to NetCDF

  • output_elevations – write elevations to NetCDF

  • output_velocities – write velocities to NetCDF

  • output_concentrations – write concentrations to NetCDF

  • output_meteorological_factors – write meteorological factors to NetCDF

  • processors – number of processors to use

  • nems_parameters – parameters to give to NEMS cap

  • attributes – attributes to set in adcircpy.AdcircRun object

classmethod from_file(filename: PathLike) → ConfigurationJSON

read existing JSON file

Parameters:

filename – path to JSON file

Returns:

configuration object

classmethod from_string(string: str) → ConfigurationJSON

read JSON string

Parameters:

string – JSON string

Returns:

configuration object

move_paths(relative: PathLike)
Parameters:

relative – path to which to move Path attributes

to_file(filename: PathLike | None = None, absolute: bool = False, overwrite: bool = False)

write configuration to file

Parameters:

  • filename – path to output file

  • absolute – whether to write absolute paths

  • overwrite – whether to overwrite existing file

configure_tidal.json

class coupledmodeldriver.configure.forcings.base.TidalForcingJSON(resource: PathLike | None = None, tidal_source: TidalSource | None = None, constituents: List[str] | None = None, **kwargs)

tidal configuration in configure_tidal.json

stores tidal database and constituent information

configuration = TidalForcingJSON(
    tidal_source='HAMTIDE',
    constituents='all',
)
property adcircpy_forcing: Forcing

create an ADCIRCpy forcing object with values from this configuration

classmethod from_adcircpy(forcing: Tides) → TidalForcingJSON

read configuration values from an ADCIRCpy forcing object

property pyschism_forcing: Tides

create an pySCHISM forcing object with values from this configuration

classmethod from_pyschism(forcing: Tides) → TidalForcingJSON

read configuration values from an pySCHISM forcing object

classmethod from_file(filename: PathLike) → ConfigurationJSON

read existing JSON file

Parameters:

filename – path to JSON file

Returns:

configuration object

classmethod from_string(string: str) → ConfigurationJSON

read JSON string

Parameters:

string – JSON string

Returns:

configuration object

move_paths(relative: PathLike)
Parameters:

relative – path to which to move Path attributes

to_file(filename: PathLike | None = None, absolute: bool = False, overwrite: bool = False)

write configuration to file

Parameters:

  • filename – path to output file

  • absolute – whether to write absolute paths

  • overwrite – whether to overwrite existing file

configure_besttrack.json

class coupledmodeldriver.configure.forcings.base.BestTrackForcingJSON(nhc_code: str | None = None, nws: int | None = None, interval: timedelta | None = None, start_date: datetime | None = None, end_date: datetime | None = None, fort22_filename: PathLike | None = None, dataframe: DataFrame | None = None, attributes: Dict[str, Any] | None = None, **kwargs)

storm best track configuration in configure_besttrack.json

stores storm NHC code, NWS parameter, forcing read interval, start and end dates, and optionally a path to an existing fort.22 file

configuration = BestTrackForcingJSON(nhc_code='florence2018')

configuration = BestTrackForcingJSON.from_fort22('./fort.22')

configuration.to_adcircpy().write('output.fort.22')
Parameters:

attributes – attributes to store

property adcircpy_forcing: BestTrackForcing

create an ADCIRCpy forcing object with values from this configuration

classmethod from_adcircpy(forcing: BestTrackForcing) → BestTrackForcingJSON

read configuration values from an ADCIRCpy forcing object

property pyschism_forcing: ModelForcing

create an pySCHISM forcing object with values from this configuration

classmethod from_pyschism(forcing: ModelForcing) → ForcingJSON

read configuration values from an pySCHISM forcing object

classmethod from_file(filename: PathLike) → ConfigurationJSON

read existing JSON file

Parameters:

filename – path to JSON file

Returns:

configuration object

classmethod from_string(string: str) → ConfigurationJSON

read JSON string

Parameters:

string – JSON string

Returns:

configuration object

move_paths(relative: PathLike)
Parameters:

relative – path to which to move Path attributes

to_file(filename: PathLike | None = None, absolute: bool = False, overwrite: bool = False)

write configuration to file

Parameters:

  • filename – path to output file

  • absolute – whether to write absolute paths

  • overwrite – whether to overwrite existing file

configure_owi.json

class coupledmodeldriver.configure.forcings.base.OWIForcingJSON(interval: timedelta | None = None, **kwargs)

OWI forcing configuration in configure_owi.json

stores NWS parameter and forcing read interval

property adcircpy_forcing: OwiForcing

create an ADCIRCpy forcing object with values from this configuration

classmethod from_adcircpy(forcing: OwiForcing) → OWIForcingJSON

read configuration values from an ADCIRCpy forcing object

property pyschism_forcing: ModelForcing

create an pySCHISM forcing object with values from this configuration

classmethod from_pyschism(forcing: ModelForcing) → ForcingJSON

read configuration values from an pySCHISM forcing object

classmethod from_file(filename: PathLike) → ConfigurationJSON

read existing JSON file

Parameters:

filename – path to JSON file

Returns:

configuration object

classmethod from_string(string: str) → ConfigurationJSON

read JSON string

Parameters:

string – JSON string

Returns:

configuration object

move_paths(relative: PathLike)
Parameters:

relative – path to which to move Path attributes

to_file(filename: PathLike | None = None, absolute: bool = False, overwrite: bool = False)

write configuration to file

Parameters:

  • filename – path to output file

  • absolute – whether to write absolute paths

  • overwrite – whether to overwrite existing file

configure_atmesh.json

class coupledmodeldriver.configure.forcings.base.ATMESHForcingJSON(resource: PathLike, nws: int | None = None, interval: timedelta | None = None, processors: int | None = None, nems_parameters: Dict[str, str] | None = None, **kwargs)

atmospheric mesh (ATMESH) configuration in configure_atmesh.json

stores NWS parameter, forcing read interval, and optionally NEMS parameters

configuration = ATMESHForcingJSON(
    resource='Wind_HWRF_SANDY_Nov2018_ExtendedSmoothT.nc',
    nws=17,
    interval=timedelta(hours=1),
)
property adcircpy_forcing: Forcing

create an ADCIRCpy forcing object with values from this configuration

classmethod from_adcircpy(forcing: AtmosphericMeshForcing) → ATMESHForcingJSON

read configuration values from an ADCIRCpy forcing object

property pyschism_forcing: ModelForcing

create an pySCHISM forcing object with values from this configuration

classmethod from_pyschism(forcing: ModelForcing) → ForcingJSON

read configuration values from an pySCHISM forcing object

classmethod from_file(filename: PathLike) → ConfigurationJSON

read existing JSON file

Parameters:

filename – path to JSON file

Returns:

configuration object

classmethod from_string(string: str) → ConfigurationJSON

read JSON string

Parameters:

string – JSON string

Returns:

configuration object

move_paths(relative: PathLike)
Parameters:

relative – path to which to move Path attributes

to_file(filename: PathLike | None = None, absolute: bool = False, overwrite: bool = False)

write configuration to file

Parameters:

  • filename – path to output file

  • absolute – whether to write absolute paths

  • overwrite – whether to overwrite existing file

configure_ww3data.json

class coupledmodeldriver.configure.forcings.base.WW3DATAForcingJSON(resource: PathLike, nrs: int | None = None, interval: timedelta | None = None, processors: int | None = None, nems_parameters: Dict[str, str] | None = None, **kwargs)

WaveWatch III output file configuration in configure_ww3data.json

stores NRS parameter, forcing read interval, and optionally NEMS parameters

configuration = WW3DATAForcingJSON(
    resource='ww3.HWRF.NOV2018.2012_sxy.nc',
    nrs=5,
    interval=timedelta(hours=1),
)
property adcircpy_forcing: Forcing

create an ADCIRCpy forcing object with values from this configuration

classmethod from_adcircpy(forcing: WaveWatch3DataForcing) → WW3DATAForcingJSON

read configuration values from an ADCIRCpy forcing object

property pyschism_forcing: ModelForcing

create an pySCHISM forcing object with values from this configuration

classmethod from_pyschism(forcing: ModelForcing) → ForcingJSON

read configuration values from an pySCHISM forcing object

classmethod from_file(filename: PathLike) → ConfigurationJSON

read existing JSON file

Parameters:

filename – path to JSON file

Returns:

configuration object

classmethod from_string(string: str) → ConfigurationJSON

read JSON string

Parameters:

string – JSON string

Returns:

configuration object

move_paths(relative: PathLike)
Parameters:

relative – path to which to move Path attributes

to_file(filename: PathLike | None = None, absolute: bool = False, overwrite: bool = False)

write configuration to file

Parameters:

  • filename – path to output file

  • absolute – whether to write absolute paths

  • overwrite – whether to overwrite existing file

abstract classes

configuration

class coupledmodeldriver.configure.base.ConfigurationJSON(fields: Dict[str, type] | None = None, **configuration)

abstraction of a configuration JSON, including getters and setters for values and a built-in schema of field types

move_paths(relative: PathLike)
Parameters:

relative – path to which to move Path attributes

classmethod from_string(string: str) → ConfigurationJSON

read JSON string

Parameters:

string – JSON string

Returns:

configuration object

classmethod from_file(filename: PathLike) → ConfigurationJSON

read existing JSON file

Parameters:

filename – path to JSON file

Returns:

configuration object

to_file(filename: PathLike | None = None, absolute: bool = False, overwrite: bool = False)

write configuration to file

Parameters:

  • filename – path to output file

  • absolute – whether to write absolute paths

  • overwrite – whether to overwrite existing file

class coupledmodeldriver.configure.base.AttributeJSON(attributes: Dict[str, Any] | None = None, **kwargs)

abstraction of a configuration with an arbitrary number of custom assignable attributes

Parameters:

attributes – attributes to store

classmethod from_file(filename: PathLike) → ConfigurationJSON

read existing JSON file

Parameters:

filename – path to JSON file

Returns:

configuration object

classmethod from_string(string: str) → ConfigurationJSON

read JSON string

Parameters:

string – JSON string

Returns:

configuration object

move_paths(relative: PathLike)
Parameters:

relative – path to which to move Path attributes

to_file(filename: PathLike | None = None, absolute: bool = False, overwrite: bool = False)

write configuration to file

Parameters:

  • filename – path to output file

  • absolute – whether to write absolute paths

  • overwrite – whether to overwrite existing file

NEMS

class coupledmodeldriver.configure.base.NEMSCapJSON(processors: int | None = None, nems_parameters: Dict[str, str] | None = None, **kwargs)

abtraction of an individual model configuration that implements a NEMS cap

stores NEMS-assigned processors and NEMS cap parameters

classmethod from_file(filename: PathLike) → ConfigurationJSON

read existing JSON file

Parameters:

filename – path to JSON file

Returns:

configuration object

classmethod from_string(string: str) → ConfigurationJSON

read JSON string

Parameters:

string – JSON string

Returns:

configuration object

move_paths(relative: PathLike)
Parameters:

relative – path to which to move Path attributes

to_file(filename: PathLike | None = None, absolute: bool = False, overwrite: bool = False)

write configuration to file

Parameters:

  • filename – path to output file

  • absolute – whether to write absolute paths

  • overwrite – whether to overwrite existing file

model

class coupledmodeldriver.configure.models.ModelJSON(model: Model, **kwargs)

abstraction of a model configuration

stores model information

classmethod from_file(filename: PathLike) → ConfigurationJSON

read existing JSON file

Parameters:

filename – path to JSON file

Returns:

configuration object

classmethod from_string(string: str) → ConfigurationJSON

read JSON string

Parameters:

string – JSON string

Returns:

configuration object

move_paths(relative: PathLike)
Parameters:

relative – path to which to move Path attributes

to_file(filename: PathLike | None = None, absolute: bool = False, overwrite: bool = False)

write configuration to file

Parameters:

  • filename – path to output file

  • absolute – whether to write absolute paths

  • overwrite – whether to overwrite existing file