Skip to content
iiasaPublic

About

The official public repository for the compact Earth system model OSCAR

Resources

Stars

4 stars

Watchers

1 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

Repository files navigation

OSCAR 🌍

We are excited to announce the release of OSCAR v4! OSCAR is an open-source, reduced-complexity Earth system model (ESM) designed to probabilistically emulate the coupled climate–carbon–chemistry system. This latest version introduces enhanced numerical stability, modular submodels, and recalibration using AR6, CMIP6, and TRENDY datasets, among other things.

Important

⚠️ Beta Version - Active Development

This package is currently in Beta (v4-beta3). We are actively refining features and documentation.

We expect a stable v4.0 by the end of 2026.

Action Required: Expect frequent updates in the coming months; please keep your package up to date.

Support & Feedback:

  • Technical Issues: For bug reports or feature suggestions, please open an issue on the Issue Board.
  • Scientific Collaboration: For research inquiries, contact the OSCAR model team at OSCAR_model@iiasa.ac.at.

📖 Scientific Background

OSCAR v4 bridges comprehensive ESMs and simpler reduced-complexity approaches, providing rapid, policy-relevant, probabilistic climate projections.

Key Improvements:

  • User-oriented functionalities.
  • Modularized code for independent submodel execution.
  • Robust Monte Carlo & Latin hypercube sampling for improved probabilistic ensembles.
  • Benchmarked via the Reduced Complexity Model Intercomparison Project (RCMIP) phase 3.

References:

v4.0 | Gasser et al., in preparation.

v3.1 | Gasser, T., L. Crepin, Y. Quilcaille, R. A. Houghton, P. Ciais & M. Obersteiner. "Historical CO2 emissions from land-use and land-cover change and their uncertainty." Biogeosciences 17: 4075–4101 (2020). doi:10.5194/bg-17-4075-2020

v2.2 | Gasser, T., P. Ciais, O. Boucher, Y. Quilcaille, M. Tortora, L. Bopp & D. Hauglustaine. "The compact Earth system model OSCAR v2.2: description and first results." Geoscientific Model Development 10: 271-319 (2017). doi:10.5194/gmd-10-271-2017


🚀 Installation

OSCAR can be installed via pip or uv. We recommend uv for a faster and cleaner environment setup.

Option 1: Using uv (Recommended)

Requires uv.

# Create a virtual environment and install OSCAR
uv venv
uv pip install git+https://github.com/iiasa/OSCAR.git

# Run the verification model
uv run oscar run

Option 2: Using standard pip

# Install directly from GitHub
pip install git+https://github.com/iiasa/OSCAR.git

# Run the verification model
oscar run

🔎 Discovery, Help & Run Modes

OSCAR is self-documenting and supports multiple run levels.
You can both inspect a mode and execute it from the Terminal or Python.

Mode Purpose Inspect (Terminal) Inspect (Python) Run (Terminal) Run (Python) Status
General Package overview & guidance oscar oscar.info() — — ✅ Available
Standard Instant verification simulation oscar info standard oscar.info("standard") oscar run oscar.run() ✅ Available
Configured Official scenario library runs oscar info configured oscar.info("configured") oscar run -m configured oscar.run(mode="configured") ✅ Available
Customized User-defined research workflows oscar info customized oscar.info("customized") oscar run -m customized --project <project-id> --experiment <experiment-id> oscar.run(mode="customized", project=..., experiment=...) ✅ Available
Advanced Run options for close collaborators oscar info advanced oscar.info("advanced") — — 🔒 On request

Note: Configured and Customized modes download their data library on first use.


🛠 Usage Examples

Terminal (Standard Mode)

Run the verification simulation with a single command:

oscar run

Python (Configured Mode)

Run CMIP7 scenarios from the official library (projections to 2100):

import oscar

# CMIP7 history and IAMC_R5 regions by default; see oscar.info("configured") for the options
oscar.run(
    mode="configured",
    scenario=["scen7-VL", "scen7-H"],
    variables=["D_Tg"]
)

Customized Mode

Run your own scenarios on top of a baseline scenario:

  1. Create a project with its first experiment; this downloads the templates and examples on first use:
    oscar project my-project --experiment my-experiment
    This creates the project folder (its path is printed) with settings_my-experiment.yaml, INFO.md, inputs/ and results/.
  2. Put your inputs in inputs/ and edit settings_my-experiment.yaml. Without inputs, the baseline scenario runs alone.
  3. Check, then run:
    oscar validate my-project --experiment my-experiment
    oscar run -m customized --project my-project --experiment my-experiment
    Alternatively, use Python instead of the terminal steps:
    import oscar
    
    oscar.create_project("my-project", experiment="my-experiment")
    oscar.validate_project("my-project", "my-experiment")
    oscar.run(mode="customized", project="my-project", experiment="my-experiment")

Results go to the project's results/. A second experiment in the same project: oscar project my-project --experiment another-experiment. See INFO.md in the project, or oscar.info("customized"), for all options and input rules.


🗑 Uninstallation

To remove OSCAR and its associated files:

Target Command / Action
Package (uv) Delete the .venv folder and the project directory.
Package (pip) Run pip uninstall oscar.
Data Library Manually delete the data folder you initialized during setup.

About

The official public repository for the compact Earth system model OSCAR

Resources

Stars

4 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages