CoupledModelDriver

coupledmodeldriver generates an overlying job submission framework and configuration directories for NEMS-coupled coastal ocean model ensembles.

It utilizes nemspy to generate NEMS configuration files, shares common configurations between runs, and organizes spinup and mesh partition into separate jobs for dependant submission.

Supported models and platforms

• models
  • circulation models
    • ADCIRC (uses adcircpy)
  • forcings
    • ATMESH
    • WW3DATA
• platforms
  • local
  • Slurm
    • Hera
    • Stampede2

Usage

Example scripts can be found at examples/<platform>

1. generate configuration directory

The following code (examples/hera/hera_shinnecock_ike.py) creates a configuration for coupling (ATMESH + WW3DATA) -> ADCIRC on Hera, over a small Shinnecock Inlet mesh:

from datetime import datetime, timedelta
from pathlib import Path

from adcircpy import Tides
from adcircpy.forcing.waves.ww3 import WaveWatch3DataForcing
from adcircpy.forcing.winds.atmesh import AtmosphericMeshForcing
from nemspy import ModelingSystem
from nemspy.model import ADCIRCEntry, AtmosphericMeshEntry, WaveMeshEntry

from coupledmodeldriver.adcirc import write_adcirc_configurations
from coupledmodeldriver.job_script import Platform

# directory containing input ADCIRC mesh nodes (`fort.14`) and (optionally) mesh values (`fort.13`)
MESH_DIRECTORY = Path('/scratch2/COASTAL/coastal/save/shared/models') / 'meshes' / 'shinnecock' / 'ike' / 'grid_v1'

# directory containing input atmospheric mesh forcings (`wind_atm_fin_ch_time_vec.nc`) and WaveWatch III forcings (`ww3.Constant.20151214_sxy_ike_date.nc`)
FORCINGS_DIRECTORY = Path('/scratch2/COASTAL/coastal/save/shared/models') / 'forcings' / 'shinnecock' / 'ike'

# directory to which to write configuration
OUTPUT_DIRECTORY = Path(__file__).parent.parent / 'data' / 'configuration' / 'hera_shinnecock_ike'

# dictionary defining runs with ADCIRC value perturbations - in this case, a single run with no perturbation
runs = {f'test_case_1': (None, None)}

# initialize `nemspy` configuration object with forcing file locations, start and end times,  and processor assignment
nems = ModelingSystem(
    start_time=datetime(2008, 8, 23),
    end_time=datetime(2008, 8, 23) + timedelta(days=14.5),
    interval=timedelta(hours=1),
    atm=AtmosphericMeshEntry(filename=FORCINGS_DIRECTORY / 'wind_atm_fin_ch_time_vec.nc', processors=1),
    wav=WaveMeshEntry(filename=FORCINGS_DIRECTORY / 'ww3.Constant.20151214_sxy_ike_date.nc', processors=1),
    ocn=ADCIRCEntry(processors=11),
)

# describe connections between coupled components
nems.connect('ATM', 'OCN')
nems.connect('WAV', 'OCN')
nems.sequence = [
    'ATM -> OCN',
    'WAV -> OCN',
    'ATM',
    'WAV',
    'OCN',
]

# initialize `adcircpy` forcing objects
tidal_forcing = Tides()
tidal_forcing.use_all()
wind_forcing = AtmosphericMeshForcing(nws=17, interval_seconds=3600)
wave_forcing = WaveWatch3DataForcing(nrs=5, interval_seconds=3600)

# send run information to `adcircpy` and write the resulting configuration to output directory
write_adcirc_configurations(
    nems,
    runs,
    MESH_DIRECTORY,
    OUTPUT_DIRECTORY,
    email_address='example@email.gov',
    platform=Platform.HERA,
    spinup=timedelta(days=12.5),
    forcings=[tidal_forcing, wind_forcing, wave_forcing],
    overwrite=True,
)

This code will generate a directory hera_shinnecock_ike/ with the following structure:

📦 hera_shinnecock_ike/
┣ 📂 coldstart/
┃  ┣ 📜 fort.13
┃  ┣ 📜 fort.14
┃  ┗ 📜 fort.15
┣ 📂 runs/
┃  ┗ 📂 test_case_1/
┃    ┣ 📜 fort.13
┃    ┣ 📜 fort.14
┃    ┗ 📜 fort.15
┣ 📜 config.rc.coldstart
┣ 📜 config.rc.hotstart
┣ 📜 model_configure.coldstart
┣ 📜 model_configure.hotstart
┣ 📜 nems.configure.coldstart
┣ 📜 nems.configure.hotstart
┣ 📜 job_adcprep_hera.job
┣ 📜 job_nems_adcirc_hera.job.coldstart
┣ 📜 job_nems_adcirc_hera.job.hotstart
┗ 📜 run_hera.sh

Note: the required NEMS configuration files (nems.configure, model_configure) do not yet exist in the run directories (coldstart/, runs/test_case_1/). These will be populated in the next step.

2. run job submission script run_<platform>.sh

Run run_hera.sh:

sh run_hera.sh

This will first create symbolic links to populate configuration directories,

📦 hera_shinnecock_ike/
┣ 📂 coldstart/
┃  ┣ 📜 fort.13
┃  ┣ 📜 fort.14
┃  ┣ 📜 fort.15
┃  ┣ 🔗 config.rc -> ../config.rc.coldstart
┃  ┣ 🔗 model_configure -> ../model_configure.hotstart
┃  ┣ 🔗 nems.configure -> ../nems.configure.coldstart
┃  ┣ 🔗 hera_adcprep.job -> ../job_adcprep_hera.job
┃  ┗ 🔗 hera_nems_adcirc.job -> ../job_nems_adcirc_hera.job.coldstart
┣ 📂 runs/
┃  ┗ 📂 test_case_1/
┃    ┣ 📜 fort.13
┃    ┣ 📜 fort.14
┃    ┣ 📜 fort.15
┃    ┣ 🔗 config.rc -> ../../config.rc.hotstart
┃    ┣ 🔗 model_configure -> ../../model_configure.hotstart
┃    ┣ 🔗 nems.configure -> ../../nems.configure.hotstart
┃    ┣ 🔗 hera_adcprep.job -> ../../job_adcprep_hera.job
┃    ┗ 🔗 hera_nems_adcirc.job -> ../../job_nems_adcirc_hera.job.hotstart
┣ 📜 config.rc.coldstart
┣ 📜 config.rc.hotstart
┣ 📜 model_configure.coldstart
┣ 📜 model_configure.hotstart
┣ 📜 nems.configure.coldstart
┣ 📜 nems.configure.hotstart
┣ 📜 job_adcprep_hera.job
┣ 📜 job_nems_adcirc_hera.job.coldstart
┣ 📜 job_nems_adcirc_hera.job.hotstart
┗ 📜 run_hera.sh

and then submit the requested jobs to the queue:

squeue -u $USER -o "%.8i %.21j %.4C %.4D %.31E %.7a %.9P %.20V %.20S %.20e"
   JOBID                  NAME CPUS NODE                      DEPENDENCY ACCOUNT PARTITION          SUBMIT_TIME           START_TIME             END_TIME
16368044 ADCIRC_MESH_PARTITION    1    1                          (null) coastal      hera  2021-02-18T19:29:17                  N/A                  N/A
16368045      ADCIRC_COLDSTART   11    1  afterany:16368044(unfulfilled) coastal      hera  2021-02-18T19:29:17                  N/A                  N/A
16368046 ADCIRC_MESH_PARTITION    1    1  afterany:16368045(unfulfilled) coastal      hera  2021-02-18T19:29:17                  N/A                  N/A
16368047       ADCIRC_HOTSTART   13    1  afterany:16368046(unfulfilled) coastal      hera  2021-02-18T19:29:17                  N/A                  N/A