atlas-model 0.1.1

Status: under active development — no stable release yet.

Overview

ATLAS simulates electricity market mechanisms across the full trading horizon. It models the sequential decisions of market participants — from order formulation ahead of the auction to market clearing and portfolio optimisation — using a modular, configurable architecture.

Each module is an independent computation unit that reads from a shared dataset and produces structured changes applied by the orchestrator. Modules are chained into workflows, where the output of each step feeds into the next.

Market Chains

Modules are grouped into market chains, each representing a full simulation cycle.

Day-Ahead — available

Intraday — available

Both chains reuse the same Market Clearing and Portfolio Optimisation modules — only the parameters and the position they hold in the workflow differ.

Stack

• Python 3.13+, managed with uv
• OR-Tools for optimisation, Pydantic for data models, Polars for data processing
• Typer for the CLI, Ruff for linting, mypy for type checking, pytest for tests

Installation

pip install atlas-model

# or with uv
uv add atlas-model

Quick Example

1. Build a dataset

from atlas import AtlasDataset, ControlBlock, MarketArea, Node, Portfolio, Thermal, Timeseries

cb = ControlBlock(name="cb_fr")
area = MarketArea(name="fr", control_block=cb)
node = Node(name="node_fr", control_block=cb, market_area=area)
portfolio = Portfolio(name="gen_fr", control_block=cb, market_area=area)

variable_cost = Timeseries.from_index(
    start_date="2024-01-01 00:00:00",
    frequency="1h",
    end_date="2024-01-02 00:00:00",
    default_value=45.0,
)

nuclear = Thermal(
    name="fr_nuclear",
    node=node,
    portfolio=portfolio,
    installed_capacity=1584.0,
    variable_cost=variable_cost,
)

dataset = AtlasDataset(
    control_block=[cb],
    market_area=[area],
    node=[node],
    portfolio=[portfolio],
    thermal=[nuclear],
)
dataset.to_directory("./data/input/")

2. Configure parameters

# parameters.yaml
temporal:
  start_date: "2024-01-01 00:00:00"
  end_date: "2024-01-02 00:00:00"
  execution_date: "2023-12-31 12:00:00"
  timestep: "PT1H"
solver:
  solver_name: "SCIP"
load_price: 3000

3. Run a module

atlas module list # See available modules

atlas module run DayAheadOrders -p parameters.yaml -d ./data/input/

Or from Python:

from atlas import AtlasDataset, ModuleRun

result = ModuleRun(
    module="DayAheadOrders",
    dataset="./data/input/",
    parameters="parameters.yaml",
).run()

4. Run a full day-ahead workflow

# workflow.yaml
name: day-ahead
dataset_path: ./data/input/
output_dataset_path: ./data/output/
output_dir: ./results/
steps:
  - module: DayAheadOrders
    parameters_path: ./parameters/day_ahead_orders.yml
  - module: MarketClearing
    parameters_path: ./parameters/market_clearing.yml
  - module: PortfolioOptimisation
    parameters_path: ./parameters/portfolio_optimisation.yml

atlas workflow list workflow.yaml # List all workflow steps

atlas workflow run workflow.yaml

5. Run a full intraday workflow

The intraday chain starts from a price forecast and re-optimises the portfolio twice — once against the forecast prices, once against the intraday cleared position. The same module can appear several times in a workflow with different parameters.

# intraday_workflow.yaml
name: intraday
dataset_path: ./data/input/
output_dataset_path: ./data/output/
output_dir: ./results/
steps:
  - module: IntradayPriceForecast
    parameters_path: ./parameters/intraday_price_forecast.yml
  - module: PortfolioOptimisation
    parameters_path: ./parameters/portfolio_optimisation_1.yml
  - module: IntradayOrders
    parameters_path: ./parameters/intraday_orders.yml
  - module: MarketClearing
    parameters_path: ./parameters/market_clearing.yml
  - module: PortfolioOptimisation
    parameters_path: ./parameters/portfolio_optimisation_2.yml

atlas workflow run intraday_workflow.yaml

A runnable example is available in the test dataset:

uv run atlas workflow run tests/dataset/parameters/intraday/workflow.yml

Documentation

Full documentation: atlas-model.readthedocs.io

Contributing

See CONTRIBUTING.

Changelog

See CHANGELOG.

Authors

See AUTHORS.