Getting Started¶

This project requires a consistent setup for everyone, including compiled Fortran executables used by the extrapolation workflow. Follow this guide to install, build, and verify your environment.

Requirements¶

Python >= 3.10
A conda installation (we recommend Miniforge)
The conda-forge channel with strict priority

If you aren’t sure the conda-forge channel is set:

conda config --add channels conda-forge
conda config --set channel_priority strict

1) Install rattler-build in your base environment¶

Install once into your base conda environment to enable local package builds:

conda install -n base -c conda-forge rattler-build

2) Clone the repository¶

git clone https://github.com/ismip/ismip7-antarctic-ocean-forcing.git
cd ismip7-antarctic-ocean-forcing

3) Build a local conda package (with Fortran executables)¶

This produces a package that installs the Fortran executables used by i7aof.extrap:

# Build inside your current (base) environment; this sets a local channel path
LOCAL_CHANNEL=${CONDA_PREFIX}/conda-bld

# Pick the variant matching the Python you plan to use, e.g.:
VARIANT=conda/variants/linux_64_python3.13.____cp313.yaml

# Build the package (reads conda/recipe.yaml)
rattler-build build -m "$VARIANT" --output-dir "$LOCAL_CHANNEL" -r conda/recipe.yaml

This build provides two executables:

i7aof_extrap_horizontal
i7aof_extrap_vertical

4) Create the environment using the local package¶

Create your development environment pulling everything from conda-forge, with this package coming from your local channel (put it first):

conda create -y -n ismip7_dev -c "$LOCAL_CHANNEL" -c conda-forge --file dev-spec.txt ismip7-antarctic-ocean-forcing
conda activate ismip7_dev

Then install the repo in editable mode (keeps Python code live while preserving the compiled executables from the package):

pip install --no-deps --no-build-isolation -e .

Optional but recommended for consistent formatting and linting:

pre-commit install

5) Verify the setup¶

which i7aof_extrap_horizontal
which i7aof_extrap_vertical
python -c "import i7aof.extrap as ex; print(ex.load_template_text()[:120])"

If the which commands return paths inside the active environment and the Python import succeeds, your setup is correct.

6) Rebuilding after Fortran source changes¶

If you modify files under fortran/, rebuild and then recreate the environment with the newly built local package:

# ensure you're in the base environment
conda deactivate || true
conda deactivate || true
conda activate base

LOCAL_CHANNEL=${CONDA_PREFIX}/conda-bld

# delete any previously built packages for this project
rm -rf ${LOCAL_CHANNEL}/*/ismip7-antarctic-ocean-forcing*.conda

# pick the appropriate Python variant again, e.g.:
VARIANT=conda/variants/linux_64_python3.13.____cp313.yaml

# rebuild the package
rattler-build build -m "$VARIANT" --output-dir "$LOCAL_CHANNEL" -r conda/recipe.yaml

# recreate the environment
conda create -y -n ismip7_dev -c "$LOCAL_CHANNEL" -c conda-forge --file dev-spec.txt ismip7-antarctic-ocean-forcing
conda activate ismip7_dev

# reinstall the Python code in editable mode
pip install --no-deps --no-build-isolation -e .

Troubleshooting¶

If builds seem stale, remove build/ subdirectories under rattler-build’s cache (see its terminal output for cache paths) and rebuild.
Ensure conda-forge channel priority is strict, and your local channel is listed before conda-forge when creating the environment.
Use a variant file under conda/variants/ matching the Python version you want in your environment.