Get Started with C-SON Forge

Prerequisites¶

• Python 3.8 or higher

• Git

• Conda, Mamba, or Micromamba (the setup script will automatically install Micromamba if needed)

Setup¶

1. Fork the Repository¶

Create a fork of the repository at https://github.com/CWorthy-ocean/cson-forge.

2. Clone Your Fork¶

In your terminal, clone your forked repository:

git clone https://github.com/<YOUR_GITHUB_USERNAME>/cson-forge.git
cd cson-forge

Consider creating a branch to keep your work organized

git checkout -b <branch-name>

3. Run the Setup Script¶

Run the setup script:

./dev-setup.sh

Options:

• --clean: Remove and rebuild the environment if it already exists

• --batch or -f: Run without user prompts (useful for CI/automation)

Examples:

# Normal setup (will prompt for confirmation)
./dev-setup.sh

# Clean rebuild (removes existing environment first)
./dev-setup.sh --clean

# Automated setup without prompts
./dev-setup.sh --force

4. Verify Installation¶

To verify that everything is installed correctly:

a) Check that the Jupyter kernel is installed:

jupyter kernelspec list | grep cson-forge-v0

You should see cson-forge-v0 in the list. If not, the kernel installation may have failed.

b) Activate the environment and test the installation:

# Activate the environment (using micromamba or conda)
eval "$(./bin/micromamba shell hook --shell bash)"  # or use conda if micromamba not available
micromamba activate cson-forge-v0  # or: conda activate cson-forge-v0

# Test that cson_forge can be imported
cd workflows
python -c "import cson_forge; print('✓ cson_forge works')"

c) Check that the package can be imported in Python:

import cson_forge
print(f"System detected: {cson_forge.config.system}")

d) Inspect the configured paths:

The show-paths command displays the detected system and all configured data paths:

python -m cson_forge.config show-paths

This will show output like:

System tag : MacOS
Hostname   : your-hostname

Paths:
  here         -> /path/to/cson-forge/cson_forge
  model_configs -> /path/to/cson-forge/cson_forge/model-configs
  source_data  -> /path/to/source-data
  input_data   -> /path/to/input-data
  scratch      -> /path/to/scratch-directory
  ...

Register for data access¶

CSON Forge facilitates access to a collection of open datasets required to force regional oceanographic models. These data are documented in ROMS Tools here.

Access to most of the data is facilitated automatically.

• Sign up for access to the Copernicus Marine Service

• Sign up for access to TPXO data

Try running the CStarSpecBuilder Demo:¶

Once your environment is set up, you can try running the CStarSpecBuilder demo notebook to create a new domain and run a ROMS simulation:

1. Navigate to the workflows directory:

   cd workflows/generate-models

2. Start JupyterLab:

   jupyter lab

3. Open the demo notebook:

   • Open CStarSpecBuilder-demo.ipynb in Jupyter

   • Make sure the kernel is set to cson-forge-v0 (you can change it in the Kernel menu if needed)

4. Run the notebook:

   • Execute the cells sequentially to:

     • Set up the domain configuration (grid size, boundaries, partitioning)

     • Configure and build the ROMS model

     • Run the simulation

   • The notebook will automatically save a timestamped copy to executed/forge/{system_id}/ for reproducibility

For more details on using CStarSpecBuilder, see the Model Specification Introduction and Model Specification Example.