Getting Started with CIMS

Welcome to the CIMS repository! This guide will help you set up and run the CIMS Python package for energy-economy modelling.

Prerequisites

Before you begin, ensure you have the following installed:

• uv: A Python package and environment manager. Install it with one command — no separate Python installation required.
  • Mac/Linux:

    curl -LsSf https://astral.sh/uv/install.sh | sh
    

  • Windows (PowerShell):

    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
    

• Git: Used to clone the repository. Follow the installation instructions for your operating system.
• Terminal or Command Prompt:
  • Windows: Git Bash or PowerShell
  • macOS/Linux: Terminal

Setup

1. Clone the Repository

Open your terminal and navigate to the directory where you want to work:

cd ~/Documents/projects/

Clone the repository:

git clone https://github.com/EMRG-SFU/cims.git
cd cims

2. Install Dependencies

From the cims directory, run:

uv sync --extra notebooks

This will automatically select a compatible Python version, create a virtual environment, and install all dependencies. You only need to do this once, or again when dependencies are updated.

3. Launch Marimo

uv run marimo edit

Marimo will open in your default browser. From there you can open, run, and edit notebooks.

Common Workflows

I want to...	Command
Set up or update my environment	uv sync --extra notebooks
Launch Marimo	uv run marimo edit
Run a Python script	uv run python my_script.py
Open a Python shell	uv run python
Use a specific Python version	uv sync --python 3.12 --extra notebooks

Subsequent Runs

To re-launch Marimo in future sessions, simply run from the cims directory:

uv run marimo edit

uv will use your existing environment and skip reinstalling dependencies unless something has changed.

Troubleshooting

• uv not found after install: Restart your terminal session so the uv command is available on your PATH.
• Dependency conflicts: Run uv sync --extra notebooks again to bring your environment up to date with the latest pyproject.toml.

Additional Resources

• Submit Issues: If you encounter any problems, please submit an issue on our GitHub Issues page.
• Data Pipeline: See data/README.md for information on the data pipeline and directory structure.