Installation And Getting Started
Overview
Depending on your experience level, you may be installing a bunch of tools, learning a new computation environment and/or getting acquainted with a new model. Our experience is that folks who take all of that on together tend to struggle. Here are ways you can break it:
This page lists the main items you will need to install or acquire.
Don’t mix learning the model and learning Linux if you are still familiarizing. Download the model and try the first couple tutorials on Hello SCHISM a simplified grid using Windows if that is your platform of preference. See the Learning Resources for Bay-Delta SCHISM.
Be aware of the learning resources page which is the hub for documentation for the project.
In particular, there is a Bay-Delta SCHISM User Guide. It contains details on how we set up the Bay-Delta SCHISM application, and the table of contents is a good reminder even for experienced users.
Explore the Python tools listed below. We will happily answer questions about what tools are available to avoid constant reinvention of the same functionality.
If you have just set up the model in a new computing environment, benchmark it on a working example. Download the code and the ready-to-run Complete Sample Inputs and use them to configure and test your target high performance computing (HPC) environment.
SCHISM Code or Binaries
Downloading
How you will obtain the model code depends on the operating system. If you are working on Windows (which is mostly useful for instruction or reduced size problems), compatible Windows binaries are available. This will underperform compared to a Linux cluster. For that, clone the SCHISM source code from the schism-dev GitHub repository and compile it for your high performance system. Manuals and build instructions are available on the SCHISM Web Site
Compile Settings
We compile for Linux using CMake using the SCHISM instructions for cmake
The bulk of the work is making sure you have a compiler and links to the required libraries.
For basic hydro-salinity runs we use the following cmake settings for which you will have to modify where GOTM is (also note our basic calibration doesn’t use GOTM):
$ cmake ../src -DPREC_EVAP=ON -DTVD_LIM=VL -DUSE_GOTM=ON -DGOTM_BASE=~/myscratch/gotm_home
Additional settings are needed to model age, sediment, biogeochemistry.
Git
Our materials are mostly distributed on our GitHub organization page
You will need Git. Instructions are widely available online. The basic operation on the command line for cloning a repository looks like this:
git clone https://github.com/CADWRDeltaModeling/BayDeltaSCHISM.git
Bay-Delta Package
Clone the Bay-Delta Package on GitHub
The package includes a simulation template corresponding to the calibration, preprocessing tools and several of the tutorials that we will be using in the January hands-on Bay-Delta workshop. Help on the preprocessor and model setup can be found in the schimpy documentation. The package includes a /bin directory that needs to be populated by building the source or grabbing windows binaries if you want to learn on a high quality pc.
- The current temporal coverage is calendar 2008-2023. There are several items in the distribution that are large and binary and distributed on the CNRA open data portal:
SCHISM-compatible atmospheric data which includes interpolated field data for wind, air pressure, and specific humidity, as well as reformatted North American Regional Reanalysis results for radiation and precipitation.
CenCOOS ROMS model output for forcing salinity and temperature on the boundary
Processed bathymetry data for populating the model. This is based on our Version 4.2 Bay-Delta Bathymetry release with added smoothing steps to eliminate subgrid curvature (it preserves slope).
Updates and transitions occur over the years. For instance, after 2020 we have moved from our own interpolated product to NOAA’s HRRR reanalysis product for wind. Also in 2020, we moved to Hycom for coastal salinity and temperature and other air properties (humidity, etc) and to Hycom for coastal data. We are still in the process of making these materials public and as we do so superseded links will carry messages.
One of the most common questions we get is “what is the official package”. If you are starting with SCHISM we recommend using the master branch of the repository for the latest (somewhat beta) product or, if replicability is paramount, a Git tagged version. It is always appropriate to ask this question. Our goal is that the sum of the VIMS code, our repo and the “big” data sources are enough not only to grid the model but also to do things
Required Python Packages
Our preprocessor is Python based. We recommend, and only support, conda <https://docs.conda.io/en/latest/> for package management. Please avoid Anaconda; it is too big and we can’t ensure compatibility between all the libraries if you include that much stuff. Instructions for managing Python environments are on our general Delta Modeling documentation page for Python.
You will want the following tools:
schimpy [project docs] [code repo] for managing spatial inputs and templates plus utilities
vtools3 [project docs] [code repo] for time series manipulation
dms-datastore [project docs] [code repo] | for managing data from common Bay-Delta sources.
Work tends to expand in a predictable way and we recommend a broader environment available at the Bay-Delta SCHISM repo <https://github.com/CADWRDeltaModeling/BayDeltaSCHISM/blob/master/schism_env.yml>. We can provide modest support for modern versions of the packages on fairly up-to-date Python platforms.
Bathymetry
The Bay-Delta Package already contains our latest bathymetry in geo-tiff form, processed as we use them to populate our mesh. Our bathymetry collection is available at the CNRA open portal bathymetry page. Note however, that what goes in the model is the processed bathymetry.
Complete Sample Inputs
Interested users may want to explore their options as far as clusters and high performance environments without the confounding challenge of learning the preprocessor.
A complete 21 day sample is under construction (March 2024).
VisIt SCHISM Plug-in
VisIt is a visualization toolkit for high performance numerical simulations. Note there is a visit-users forum and mailing list described at the visit-users.org web site. VisIt accesses specific data sources using plugins. At the time of writing, ours plugin works for SCHISM NetCDF UGRID 0.9 output from SCHISM. We do not distribute the base VisIt and since VisIt and the plugin version should be coordinated exactly.
SCHISM plugins: * Source code * Compiled Windows binaries for 2.13.3 * Compiled Windows binaries for 3.1.4 * Compiled Windows binaries for 3.3.1
You may notice Visit documentation is becoming antiquated but still usable – the software is supported by a vigorous wiki and forum on the VisIt community site. We also offer the document VisIT for SELFE users
Links to tools
These are mostly Windows or Linux tools. If you have information about analogous tools on other platforms we will gratefully share it.
We use Miniconda Python 3.9 through 3.11 64 bit. If you use other package management methods you will have to intall our libraries from github and manage dependencies.
Tools like MobaXTerm or VS Code that can make terminal connections to linux clusters, in some cases using the x11 windows system which allows applications with windows. Note this recommendation has gotten old and many users now prefer VS Code.
WinSCP for transfering files to and from linux servers.