Release notes

Attention

This project is still in an early phase of development.

The python API is not yet stable, and some aspects of the schema for the blueprint and workplan will likely evolve. Therefore whilst you are welcome to try out using the package, we cannot yet guarantee backwards compatibility. We expect to reach a more stable version in 2026.

Release notes#

v0.3.0#

This is a bug-fix release focused on stabilizing the orchestration of blueprints.

Breaking Changes#

  • Environment variables CSTAR_HOME and CSTAR_OUTDIR are deprecated in favor of CSTAR_CONFIG_HOME and CSTAR_STATE_HOME

  • Relocated command conversion functions from cstar.orchestration.launch.slurm to cstar.orchestration.converter

  • Promote blueprint overrides to always-on, deprecate and remove feature flag CSTAR_FF_ORCH_TRX_OVERRIDE

New features#

  • Add remote repository caching for re-use across simulations

  • XDG base directory standard is implemented

Security Fixes#

  • N/A

Bug Fixes#

  • Fix path concatenation bug resulting in invalid source data paths

  • Fix indentation creating an unreachable code block in git utils

  • Add conda installation of rsync to environment.yml (fixes bug related to a flag used in newer ucla-roms makefiles that is not available in MacOS’s default rsync installation)

  • Reimplement CSTAR_CLOBBER_WORKING_DIR for single-blueprint cases

  • Fix bug handling user-relative paths in JobFileSystemManager

Improvements#

  • Avoid automatic failures by retrying failed git clone operations

  • Add informational logging when tasks fail and additional tasks are cancelled

  • Update default log format to include file name and line number

  • Add constants for the set of available feature flags

  • Implement CSTAR_LOG_LEVEL env-var

  • Automatically retry partitioning without coarse dims if it fails when they are included

  • Enable orchestrated simulation execution using the local runner

Miscellaneous#

  • Additional details added in docstrings

  • Silence OMP warning originating from numba

  • Modify a blueprint in the tests directory for a refactored layout in the remote data repository

  • Move env-var handling methods to separate module to avoid circular imports

  • Remove __init__-based import shortcuts

  • Adjust error handling and presentation in the worker/service layer

—

For more details, please refer to the commit history.

v0.1.0#

New features#

  • Add support for river forcing

  • Add support for forcing corrections (used in legacy ROMS configurations)

Breaking Changes#

  • Merge Case and Component classes into a single class, Simulation, simplifying internal/blueprint structure. Remove old Case and Component modules.

  • Rename caseroot to directory

  • Rename BaseModel to ExternalCodeBase

  • Remove start_time and end_time parameters from InputDataset.get(), these are now obtained from the corresponding attributes

  • Rename ROMSComponent.namelists to ROMSSimulation.runtime_code and ROMSComponent.additional_source_code to ROMSSimulation.compile_time_code

Internal Changes#

  • Update calls to roms-tools to reflect latest changes in API

  • Update internal/test blueprints to reflect new structure

  • New backend data retrieval system cstar.io

  • Add ROMSRuntimeSettings class with ability to parse and create roms .in files

  • Save partitioned ROMSInputDatasets in the same directory as their un-partitioned versions, rather than a subdirectory “PARTITIONED”

Documentation#

  • Run most examples in documentation locally (unless HPC-specific), so HPC access is not required

  • Add ‘How-to Guides’ section

  • Remove tutorial page on using roms-tools

  • Replace all URLs to other doc pages with relative links

Bugfixes#

  • Complete missing unit test coverage from Case and Component in new Simulation modules

  • Add expanduser to Path instances to allow tildes to represent root in paths

  • Correct issue where AdditionalCode.modified_files list indices did not correspond to AdditionalCode.files

v0.0.8-alpha#

New features#

  • Add Case.persist() and Case.restore() methods to allow continuation of work in a new session

  • Add ExecutionHandler class to track tasks run locally (LocalProcess subclass) or submitted to a job scheduler (SchedulerJob subclass)

  • Improved tracking of local InputDataset and AdditionalCode files to prevent repeat fetching

  • Add ability to read blueprints from URL

  • Remote yaml files are now accessed via requests rather than Pooch, negating need for hash checks

Bugfixes#

  • git and DataSource information are now read-only attributes throughout

v0.0.3-alpha (9th Dec 2024)#

New features#

  • Add support for SDSC Expanse HPC

Bugfixes#

  • Fix bug where in certain circumstances environment variables were checked for before being set, prompting user to install already installed externals

v0.0.1-alpha (6th Dec 2024)#

The first release of C-Star!

This release provides basic functionality, including the ability to create, import, and export a “blueprint” for reproducible ocean model simulations (a C-Star “Case”) using supported ocean models (ROMS, optionally with MARBL biogeochemistry) and run those Cases locally or on supported HPC systems (via Slurm and PBS). There is support for using existing model input data in netCDF format, or creating new input data via integration with the roms-tools library.

Note that the python API is not yet stable, and some aspects of the schema for the blueprint will likely evolve. Therefore whilst you are welcome to try out using the package, we cannot yet guarantee backwards compatibility. We expect to reach a more stable version in 2026.