Vignette: Hindcast Bay Delta SCHISM at Delta Modeling Section with Preprocessor

The process for starting a Bay Delta SCHISM run from scratch involves some pre-processing work on a Windows machine using the schimpy library (https://github.com/CADWRDeltaModeling/schimpy).

You’ll want to have a conda environment which has the latest version of schimpy in it. For this example that environment is called ‘schism’.

Note

Although instructions here may change over time, we will always keep the template updated in the GitHub repository at BayDeltaSCHISM/templates/bay_delta and you can always refer to that for the most up to date files. The most important file is the main_bay_delta.yaml file which contains the parameters for the prepare_schism command which generates the spatial model input files.

Note

This process is up-to-date as of 2026-4-10, but may be subject to change as we update the model and input files.

Windows

  1. Clone the Bay Delta SCHISM repository to your Windows machine (ex: D:/schism/bdsch_scratch)

    git pull

  2. Create a study directory

    Create your model folder where all preprocessing, hotstart/nudging, and simulation runs will go (ex: “./baydeltaschism_startup”). See the study layout section for an example of how to organize your model folders.

    Then create a folder where you’ll build model inputs (“./baydeltaschism_startup/preprocessing”) and copy the following files into it:

    • From “./BayDeltaSCHISM”:

      • “./BayDeltaSCHISM/templates/bay_delta” folder contents

      • “./BayDeltaSCHISM/data/flow_station_xsects.yaml”

      • “./BayDeltaSCHISM/data/stations” folder contents

      • “./BayDeltaSCHISM/scripts/multi_clip.py”

    • You’ll need a .2dm file for the pre-processor, copy this into the baydeltainputs folder

    • Launch file for submitting jobs

      • This can be a .pbs file, .slurm file, or a cloud launch file depending on where you will be running the model.

      • In the launch file you will specify things like how many cores per node, scribe nodes, compute nodes, etc.

  3. Edit input files

    • main_bay_delta.yaml
      • prepro_out_dir

        • Set prepro_out_dir to the folder where you want the spatial input files generated by prepare_schism to be output. We suggest nesting it in the preprocessing directory so your inputs are separate from your outputs (ex: “baydeltaschism_startup/preprocessing/delta_geom_2009”).

      • mesh section
        • dem_list:

          • If modifying the bathymetric data, you can add a yaml with the heading dem_list which contains the list of DEM files you want to use. Then in main_bay_delta.yaml you can point to that yaml file in the mesh/dem_list/include: parameter. This is helpful for keeping track of modifications to the bathymetric data and also allows you to easily switch between different bathymetric datasets.

        • mesh_inputfile

          • change mesh/mesh_inputfile: parameter to match the .2dm file you copied into the project folder

      • vgrid section

        • check that the vgrid section contains a vgrid_version: variable set to the SCHISM version being used (5.8 or 5.10)

          • ex: vgrid_version: ‘5.10’ # Note that quotation marks are necessary

    • check the other .yaml files in the template folder for any file paths that would not be found on your machine and edit those as necessary. For instance, in the dem yamls there will be references to the location of DEM files found in the Modeling Support Office’s data repository which may not be found on your machine. You can substitute the paths for ones suitable for your machine.

    • multi_clip.py

      • Set the following variables according to your simulation start date (this example uses May 1, 2009)

        start=dtm.datetime(2009,5,1)
bds_home = "<BAYDELTASCHISM REPOSITORY LOCATION>"
    • param.nml.tropic & param.nml.clinic

      • Set start_year, start_month, start_day, start_hour, and utc_start according to the simulation start date

      • Edit byear, eyear, bmonth, emonth, bday, eday to have the full date range of the simulation

      • Edit rnday for runtime

  4. Run scripts:

    • multi_clip.py

      • Creates a list of .th files necessary for the run to execute found in simulation directory by calculating the seconds elapsed since the start date for each .th file found in the data/time_history folder.

      • typically you can copy the repository datetime stamped timeseries (.th) files into “./baydeltaschism_startup/th_files/repo” and set the output directory in multi_clip.py to “./baydeltaschism_startup/th_files/elapsed”

      • Once the elapsed th files are created, you can copy them into your simulations directory (ex: “baydeltaschism_startup/simulations/basic_baydelta_2009”)

    • prepare_schism

      • In a conda environment with schimpy installed, go to simulation directory and run:

      prepare_schism main_bay_delta.yaml

      • This creates the spatial input files for the model run including hgrid.gr3, vgrid.in.2d, vgrid.in.3d, and the various boundary condition files. It also creates a prepare_schism.log file which contains the output from the prepare_schism command which can be helpful for troubleshooting if there are issues with the input files.

      • After you have confirmed that the files have been created without issue, you can copy the outputs into the simulation directory (ex: “baydeltaschism_startup/simulations/basic_baydelta_2009”)

  5. Create hotstart and nudging datasets

    • If you’re only running a 2D/Barotropic simulation then you don’t need to create these files!

    • Create a sub-folder (ex: ./baydeltaschism_startup/hotstart_nudging) and copy files:

      • hotstart_nudging_data.py

      • hotstart_lat.py

      • clean_nudge.py

      • clean_polaris.py

      • hotstart.yaml

      • nudging.yaml

      • nudge_roms/nudge_obs_roms.yaml

      • nudge_roms/roms_nudge.py

      • shapefile/RegionsPolygon.*

      • USGS_polaris_station_locations_xy.csv

    Warning

    These files don’t exist somewhere publicly available yet

    • Download Polaris *.csv data from the USGS data query https://sfbay.wr.usgs.gov/water-quality-database/ or copy from shared file server.

      • Since the hotstart generates based on a USGS cruise, check “//nasbdo/Modeling_Data/usgs_cruise/cruise_inventory.csv” to see what dates are available. You’ll want your hotstart date to be near an available cruise date

      • Go to year, show all entries, and export data

      • Save as: hotstartUSGS_2009_saltemp.csv (where 2009 is whichever year you’ve downloaded)

      • Run clean_polaris.py or some other QA/QC on the USGS_2009_saltemp.csv file

        • This creates a copy of the file with _edit.csv as the extension

    • Edit files:
      • hotstart_nudging_data.py
        • Change nudging time to desired model run length

          • ex: nudgelen=days(60)

        • Set start time

          • ex: t0=pd.Timestamp(2009,5,1)

      • hotstart.yaml

        • Point to correct hgrid and vgrid _input files (../hgrid.gr3 & ../vgrid.in.3d generated from prepare_schism)

        • For all data using “extrude_casts:” method, replace with ./USGS_2009_saltemp_edit.csv

        • For all data using “obs_points:” method, replace with “./hotstart_data_{temperature/salinity}.csv” and variable: {temperature/salinity} depending on whether looking to set temperature or salinity. These files will be generated with hotstart_nudging_data.py

        • Set vgrid_version=’5.10’ # Note that the quotation marks are important

      • nudging.yaml
        • Change run days to whatever number of days you want the internal points to be nudged towards observation data

          • ex: rnday: 7

        • Set vgrid_version=’5.10’

        • Change temperature/salinity data: ./nudging_data_{temperature/salinity}_edit.csv based on which variable you’re setting

      • nudge_roms/nudge_obs_roms.yaml

        • start_date: 2009-05-01 (or whatever your start date is)

        • rnday: 60

        • Point to correct hgrid/vgrid files (../hgrid.gr3 & ../vgrid.in.3d)

      • hotstart_lat.py

        • Set vgrid_version=’5.10’

        • Set hgrid and vgrid to same filenames as hotstart.yaml (../hgrid.gr3 & ../vgrid.in.3d)

        • Set ini_date to correct start date

        • Set hotstart_fn to appropriate filename (ex: hotstart.20090501.nc or whatever your start date is)

    • Run files:

      • You’ll want to run these files in a conda environment that has dms_datastore installed

      • hotstart_nudging_data.py

        • Takes quite a long time, if the time period hasn’t changed then this step does not need to be repeated

        • Need to QA/QC hotstart and nudging csv data

          • Run clean_nudge.py to create nudging_data_{temperature/salinity}_edit.csv

      • hotstart.py
        • Creates:
          • salinity_nudge.gr3

            • temperature_nudge.gr3

            • hotstart.20090501.nc

            • SAL_nu_obsroms.nc

      • nudge_roms/roms_nudge.py

        • Takes a very long time. If the time period or grid hasn’t changed then this step does not need to be repeated

        • Rename SAL_nu_obsroms.nc and TEM_nu_obsroms.nc to be SAL_nu_roms.nc and TEM_nu_roms.nc

    • Copy output files out to the main simulation folder (ex: “./baydeltaschism_startup/simulations/basic_baydelta_2009”)

      • TEM_nu_obsroms.nc

      • SAL_nu_obsroms.nc

      • temperature_nudge.gr3

      • salinity_nudge.gr3

      • hotstart.20090501.nc

      • hgrid.nc

      • nudge_roms/TEM_nu_roms.nc

      • nudge_roms/SAL_nu_roms.nc

Linux

Create the folder where you will be running the model (ex: ./baydeltaschism_startup/simulations/basic_baydelta_2009) and copy the files from the Windows machine into it.

Barotropic Simulation

Before running the baroclinic model, it’s helpful to run a barotropic simulation first. This stabilizes the ocean boundary as detailed in the Ocean Boundary Stabilization section. The barotropic simulation is also a good way to check that your inputs are working correctly and to troubleshoot any issues before running the more expensive baroclinic simulation.

  1. Make symbolic links for sflux files

    • mkdir sflux

      • cd sflux

      • python ../make_links_full.py

      • cd ..

Then you’ll need a sflux_inputs.txt file within the sflux folder

Warning

The sflux_inputs.txt file does not exist somewhere publicly available yet

  1. Create elev2d.th.nc file. Run in conda environment with dms_datastore and schimpy installed:

    download_noaa --syear 2009 --eyear 2009 --param water_level noaa_stations.txt

    • Adjust start and end year based on simulation period

    gen_elev2d --outfile elev2D.th.nc --hgrid=hgrid.gr3 --stime=2009-5-1 --etime=2009-7-1 --slr 0.0 noaa_download/noaa_pryc1_9415020_water_level_2009_2010.csv noaa_download/noaa_mtyc1_9413450_water_level_2009_2010.csv

    • Again, be mindful of the years in the filenames as well as the stime and etime inputs

  2. Make symbolic links for the Barotropic run

    ln -sf msource_v20220825.th msource.th
ln -sf vsource_20220825_nows_leach1.th vsource.th
ln -sf vsink_20220825_nows_leach1_sscd1.5.th vsink.th
ln -sf TEM_1.th temp.th
ln -sf SAL_1.th salt.th
set_mode tropic

    1. Make the outputs directory

    mkdir outputs

    1. Run barotropic model

      Here you’ll submit your launch file with whichever command is appropriate for your system (ex: qsub launch.pbs). This will run the Barotropic model!

Baroclinic

At this stage the hotstart and nudging files created in the Windows portion are used on the temperature and salinity fields.

  1. Rename the outputs folder to outputs.tropic and create a new empty outputs folder

  2. Create uv3d.th.nc

    • run the bdschism utility bds uv3d to create the uv3D.th.nc file which contains the ocean boundary velocities interpolated to the 3D grid.

    bds uv3d

  3. Make symbolic links for the Baroclinic run .. code-block:: console

    ln -sf hotstart.20090501.nc hotstart.nc set_nudging obs_roms set_mode clinic

  4. Run model for period which the internal salinity/temperature nudging runs (in this example, the model will stop after 7 days)

    • See the nudging section for more details on how to set up and run the model with nudging, as well as why we use a warmup with internal nudging then switch to just coastal nudging for the rest of the run.

  5. After model stops, need to restart from hotstart outputs from the previous run

    • Run combine_hotstart7 on last timestep output to hotstart within the outputs

    combine_hotstart7.exe --iteration 4800

    Note that the iteration variable is based on variables in param.nml nhot_write which is set to 4800 in this example. 4800 x dt = 4800 x 90s = 5 days

    • Change links to hotstart and nudging data

    ln -sf outputs/hotstart_it\=4800.nc hotstart.nc
ln -sf SAL_nu_roms.nc SAL_nu.nc
ln -sf TEM_nu_roms.nc TEM_nu.nc
    • Edit param.nml.clinic

      • Change ihot to ihot = 2 to start outputs from the timestep in the new hotstart file

    • Run the model

    qsub launch.pbs