Required Files, Directory Structure and Recommended Study Practices

New users often want to simply know an inventory of what files are required to get one basic model run going. This section provides that list. The section also describes practices for organizing a study that is reproducible, and spans several hypothetical alternatives.

You will need to move data around. Users who are new to Linux or who are preprocessing on Windows and copying to Linux should check out the Linux Hints for SCHISM, which covers several types of transfer as well as the indispensible topic of symbolic links for organinzing files.

Required files and structure

SCHISM launch directory structure

A basic SCHISM launch directory has a top level directory, an outputs directory and a sflux directory:

studyname    # See inventory below
├── outputs  # Empty, but required
└── sflux    # Mostly generated links, see below

Launch directory

The table is an inventory of files needed for a typical Bay-Delta SCHISM run. All the spatial inputs and driver files are copied over by the preprocessor. This inventory will inevitably occur if we change, say, the number or names of hydraulic structures. It will also be expanded when you use new modules, as indicated elsewhere in the user guide. The items in bold are symbolic links. These links follow the required SCHISM name but point to more the similar but more detailed or version controlled names in brackets, the specific names of which evolve over time or are modified in accordance with the rest of the user gude. Some files (param.nml,`bctides.in`,`vgrid.in`,nudging) are almost always links and are described in the section on the barotropic warmup run. The links are currently created manually, although we are contemplating ways to make it more automatic.

Some of the most important files like the horizontal grid (hgrid.gr3) are covered extensively in this user guide. Others files are on more subjects like albedo, populated in very simple ways and seldom changed. For documentation, the interested user can consult the optional input page of the SCHISM Manual at VIMS.

Table 1 Files for a SCHISM Run
*.gr3/ic/ll	*.in	*.nc	*.prop	*.th	*.nml
albedo.gr3	bctides.in	elev2D.th.nc	fluxflag.prop	ccfb_gate.th	param.nml
diffmax.gr3	[bctides.in.2d]	[hotstart.20160427.0.nc]	tvd.prop	delta_cross_channel.th	[param.nml.clinic]
diffmin.gr3	[bctides.in.3d]	hotstart.nc		[flux_base.th]	[param.nml.tropic]
estuary.gr3	hydraulics.in	SAL_nu.nc		flux.th
hgrid.gr3	source_sink.in	[SAL_nu_obsroms.nc]		grantline_barrier.th
krvel.gr3	station.in	[SAL_nu_roms.nc]		grantline_culvert.th
manning.gr3	vgrid.in	TEM_nu.nc		grantline_weir.th
rough.gr3	[vgrid.in.2d]	[TEM_nu_obsroms.nc]		midr_culvert_l.th
[salinity_nudge_obsroms.gr3]	[vgrid.in.3d]	[TEM_nu_roms.nc]		midr_culvert_r.th
[salinity_nudge_roms.gr3]		uv3D.th.nc		midr_weir.th
SAL_nudge.gr3				montezuma_boat_lock.th
sav_cd.gr3				montezuma_flash.th
sav_D.gr3				montezuma_radial.th
sav_h.gr3				msource.th
sav_N.gr3				[msource_v20230206.th]
TEM_nudge.gr3				oldr_head_barrier.th
[temperature_nudge_obsroms.gr3]				oldr_tracy_culvert.th
[temperature_nudge_roms.gr3]				oldr_tracy_weir.th
watertype.gr3				SAL_1.th
windfactor.gr3				TEM_1.th
windrot_geo2proj.gr3				tom_paine_sl_culvert.th
xlsc.gr3				[vsink_20230206.th]
				vsink.th
				[vsource_20230206.th]
				vsource.th
				[west_false_river_barrier_leakage.th]

Output directory

SCHISM requires a directory called outputs. It will be empty at the beginning of the launch.

Atmospheric (sflux) directory

The atmostpheric input directory is called sflux. It is a bit distinctive:

It is the only place we put symbolic links to resources outside the immediate study directory

We share a common database across simulations from a similar era. These are on all our cluster file systems and we distribute on CNRA open data portal. Note that these often point to the original source as in the example below.

During the copying-over phase this directory initially only has two files:

sflux_inputs.txt which is boilerplate that never changes and

make_links_full.py which contains links that are adjusted to populate all the symbolic links.

So in the preprocessor you would have this:

copy_resources:
...
sflux/sflux_inputs.txt   # the boilerplate file
sflux/make_links_full.py # adjusted to point to the atmospheric files

Once you go to the study and run make_links_ful.py, the contents should look like this:

/sflux
├── make_links_full.py
├── sflux_air_1.0001.nc -> ../../../data/atmos/baydelta_sflux_v20220916/baydelta_schism_air_20160427.nc
├── sflux_air_1.0002.nc -> ../../../data/atmos/baydelta_sflux_v20220916/baydelta_schism_air_20160428.nc
├── sflux_air_1.0003.nc -> ../../../data/atmos/baydelta_sflux_v20220916/baydelta_schism_air_20160429.nc
├── ...
├── sflux_inputs.txt
├── sflux_rad_1.0001.nc -> ../../../data/atmos/NARR/2016_04/narr_prc.2016_04_27.nc
├── sflux_rad_1.0002.nc -> ../../../data/atmos/NARR/2016_04/narr_prc.2016_04_28.nc
├── sflux_rad_1.0003.nc -> ../../../data/atmos/NARR/2016_04/narr_prc.2016_04_29.nc
...
├── sflux_rad_1.0001.nc -> ../../../data/atmos/NARR/2016_04/narr_rad.2016_04_27.nc
├── sflux_rad_1.0002.nc -> ../../../data/atmos/NARR/2016_04/narr_rad.2016_04_28.nc
├── sflux_rad_1.0003.nc -> ../../../data/atmos/NARR/2016_04/narr_rad.2016_04_29.nc
├── ...

Study layout

The overall structure of a study is discretionary. There are workflows that make transfer, sharing and reuse easier. The examples here are starting points – ultimately what you change depends on whether you have physical changes (e.g. restoration) or forcing changes (years, operations). Your choices also may depend on whether you are prepping on Windows and moving to Linux (see example below) or doing everything on Linux.

It is recommended, and a standard in the Delta Modeling Section, that you isolate isolate the preprocessing template input (e.g. yaml) from the SCHISM native input (e.g. gr3).

Here a possible study layout, commonly used in our group, for a simple study with one mesh, two sets of inputs time series run for each of two widely separated years, so a total of four simulations (base_2010, base_2020, alt_2010, alt_2020):

/study_dir.
├───preprocessing           # bay_delta template, modified for study
│   ├───geometry_name       # stage your spatial inputs generated by `prepare_schism` here
├───hotstart_nudge          # stage hotstart and nudging yaml files, csv, and hotstart/nudging inputs here
│   │───20100312            # example of different specific start dates for hotstart and nudging files
│   └───20200120            # example of different specific start dates for hotstart and nudging files
└───th_files
|   │───repo                # Copy repository timeseries data here
│   │───elapsed             # Could collect and stage your elapsed time series here and move them (e.g. Windows) or do it in simulation directory
│   │   ├───with_alt            # Alternative scenario time series converted to elapsed time and staged here
│   │   └───without_action      # Baseline scenario time series converted to elapsed time and staged here
│   └───project             # Preprocessed, datetime stamped files go here
│       ├───with_alt            # Alternative scenario time series with datetime stamps
│       └───without_action      # Baseline scenario time series with datetime stamps
├───simulations             # schism launch directories for each simulation go here
│   ├───base_2010           # schism launch directory for one alternative
│   │   │───sflux
│   │   │───outputs
│   │   └───outputs.tropic  # Generated during the barotropic warmup run and moved
│   ├───base_2020           # schism launch dir for second alternative
...
│   └───alt_2020            # schism launch dir for nth alternative
└───postprocessing          # postprocessing scripts
    ├───base_2010           # postprocessing outputs for one alternative
    ├───base_2020           # postprocessing outputs for second alternative
...
    └───alt_2020            # postprocessing outputs for nth alternative

Note

The preprocessor prepare_schism has a key word prepro_output_dir which is set to “../prepro_out” in the main_bay_delta.yaml template. You might consider changing this to the run directory but please don’t use “.”.

For a run that has two different physical domains (e.g. with and without restoration) studied over one period you might do something like this:

study_dir
├───preprocessing
│   ├───base
│   └───restoration
├───hotstart_nudging
│   ├───base
│   │   ├───20100312
│   │   └───20200120
│   └───restoration
│       ├───20100312
│       └───20200120
├───simulations
│   ├───base
│   │   ├───outputs
│   │   ├───outputs.tropic
│   │   └───sflux
│   └───restoration
│       ├───outputs
│       ├───outputs.tropic
│       └───sflux
├───th_files
│   ├───elapsed
│   └───project
└───postprocessing
  ├───base
  └───restoration

Input/Output Units

File Units

SCHISM input and output files are described in the SCHISM manual, however the input file units and output file units are not always clear. The following table summarizes the units for the most commonly used input and output files.

Table 2 Common SCHISM Input/Output Units
Variable	Unit	Relevant Inputs	Relevant Outputs
Water Surface Elevation	m (positive up)	elev2D.th, elev.ic, uv3D.th.nc	staout_1 (water surface elevation), out2d_*.nc
Bathymetry	m (positive down)	hgrid.gr3	out2d_*.nc
Velocity (u, v)	m/s	sflux_air_1.*.nc (wind speed), uv3D.th.nc (water velocity)	horizontalVelX_.nc, horizontalVelY_.nc, staout_3 (wind u), staout_4 (wind v), staout_7 (hydro u), staout_8 (hydro v), staout_9 (hydro w)
Salinity	PSU	SAL_*.th, SAL_nu.nc	salinity_*.nc, staout_6 (salinity)
Water Temperature	°C	TEM_*.th, TEM_nu.nc	temperature_*.nc, staout_5 (water temperature)
Generic Tracer	1 (unitless. volumetric fraction)	gen_*.th
Air Temperature	K (2m AGL)	sflux_air_1.*.nc	N/A
Specific Humidity	1 (2m AGL)	sflux_air_1.*.nc	N/A
Atmospheric pressure	Pa (reduced to MSL)	sflux_air_1.*.nc	staout_2 (air pressure)
Precipitation	kg/m²/s (flux)	sflux_prc_1.*.nc	N/A
Shortwave radiation	W/m² (long- and short-wave)	sflux_rad_1.*.nc	N/A
Evaporation	kg/m²/s (flux)	N/A	out2d_*.nc
Suspended Sediment Concentration (ssc)	kg/m³	SED_hvar_[class].ic (initial condition for ssc for each size class, in kg/m³), bed_frac_[class].ic (initial bed composition fraction for each size class, unitless), bedthick.ic (initial bed thickness, in m), imorphogrid.gr3 (scale applied to depth change at each node, unitless, used only when imorpho==1).	sedConcentration_[class]_*.nc

Coordinate System

The geospatial projection for BayDeltaSCHISM uses NAD83 UTM Zone 10N with horizontal coordinates in meters. Vertical coordinates are against NAVD88. Time is in seconds since whichever start date specified in the param.nml.