4.5. Scripts Implementation

The scripts are the third part of the cice package. They support setting up cases, building, and running the cice stand-alone model.

4.5.1. File List

The directory structure under configure/scripts is as follows.

configuration/scripts/
Makefile primary makefile
cice.batch.csh creates batch scripts for particular machines
cice.build compiles the code
cice.decomp.csh computes a decomposition given a grid and task/thread count
cice.launch.csh creates script logic that runs the executable
cice.run.setup.csh sets up the run scripts
cice.settings defines environment, model configuration and run settings
cice.test.setup.csh creates configurations for testing the model
ice_in namelist input data
machines/ machine specific files to set env and Macros
makdep.c determines module dependencies
options/ other namelist configurations available from the cice.setup command line
parse_namelist.sh replaces namelist with command-line configuration
parse_namelist_from_settings.sh replaces namelist with values from cice.settings
parse_settings.sh replaces settings with command-line configuration
**setup_run_dirs.csh creates the case run directories
set_version_number.csh updates the model version number from the cice.setup command line
tests/ scripts for configuring and running basic tests

4.5.2. Strategy

The cice scripts are implemented such that everything is resolved after cice.setup is called. This is done by both copying specific files into the case directory and running scripts as part of the cice.setup command line to setup various files.

cice.setup drives the case setup. It is written in csh. All supporting scripts are relatively simple csh or sh scripts. See Scripts for additional details.

The file cice.settings specifies a set of env defaults for the case. The file ice_in defines the namelist input for the cice driver.

4.5.3. Preset Case Options

The cice.setup --set option allows the user to choose some predetermined cice settings and namelist. Those options are defined in configurations/scripts/options/ and the files are prefixed by either set_env or set_nml. When cice.setup is executed, the appropriate files are read from configurations/scripts/options/ and the cice.settings and/or ice_in files are updated in the case directory based on the values in those files.

The filename suffix determines the name of the -s option. So, for instance,

cice.setup -s diag1,debug,bgcISPOL

will search for option files with suffixes of diag1, debug, and bgcISPOL and then apply those settings.

parse_namelist.sh, parse_settings.sh, and parse_namelist_from_settings.sh are the three scripts that modify ice_in and cice.settings.

To add new options, just add new files to the configurations/scripts/options/ directory with appropriate names and syntax. The set_nml file syntax is the same as namelist syntax and the set_env files are consistent with csh setenv syntax. See other files for examples of the syntax.

4.5.4. Machines

Machine specific information is contained in configuration/scripts/machines. That directory contains a Macros file and an env file for each supported machine. One other files will need to be changed to support a port, that is configuration/scripts/cice.batch.csh. To port to a new machine, see Porting.

4.5.5. Test scripts

Under configuration/scripts/tests are several files including the scripts to setup the various tests, such as smoke and restart tests (test_smoke.script, test_restart.script) and the files the describe with options files are needed for each test (ie. test_smoke.files, test_restart.files). A baseline test script (baseline.script) is also there to setup the general regression and comparison testing. That directory also contains the preset test suites (ie. base_suite.ts) and a file that supports post-processing on the model output (timeseries.csh). There is also a script report_results.csh that pushes results from test suites back to the CICE-Consortium test results wiki page.

The directory configuration/scripts/tests/QC contains scripts related to the non bit-for-bit compliance testing described in Code Compliance Test (non bit-for-bit validation).

To add a new test (for example newtest), several files may be needed,

  • configuration/scripts/tests/test_newtest.script defines how to run the test. This chunk of script will be incorporated into the case test script
  • configuration/scripts/tests/test_newtest.files list the set of options files found in configuration/scripts/options/ needed to run this test. Those files will be copied into the test directory when the test is invoked so they are available for the test_newtest.script to use.
  • some new files may be needed in configuration/scripts/options/. These could be relatively generic set_nml or set_env files, or they could be test specific files typically carrying a prefix of test_nml.

Generating a new test, particularly the test_newtest.script usually takes some iteration before it’s working properly.