:tocdepth: 3

.. _dev_scripts:

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.

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

.. _dev_strategy:

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 :ref:`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.


.. _dev_options:

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.

.. _dev_machines:

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 :ref:`porting`.  

.. _dev_testing:

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 :ref:`compliance`.

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.