Legacy scenario handler deprecation#

SiennaScenario, PlexosScenario, ReEDsScenario, FileScenario, and MultiScenario are the original v0 scenario handler classes. They still work and will continue to work for the v1 release cycle, but direct instantiation is deprecated. Construct scenarios through gat.load() instead.

What changed#

Each legacy handler now emits a DeprecationWarning from its __init__:

DeprecationWarning: PlexosScenario is deprecated and will be migrated to a
duckdb-backed implementation in a future release. New code should use
`gat.load(...)` to obtain a scenario object via the supported v1 entry
point.

The warning’s stacklevel is set so it points at the caller’s line — your PlexosScenario(...) call, not GAT internals.

What to do#

Writing new code#

Use gat.load():

import gat

scenario, palette, project = gat.load(
    project="my-analysis",
    scenario="base_2035",
)

# Same DataFrame-returning API as before.
dispatch = scenario.get_area_dispatch()

The returned scenario object exposes the same public methods (get_load, get_area_dispatch, get_generation, etc.) you used to call directly on SiennaScenario/PlexosScenario. The construction path is the only thing changing now; the public DataFrame contract is preserved across the broader duckdb migration that follows.

If you don’t have a project set up yet, see Scenario quick start.

Maintaining existing code#

No immediate action required. The legacy classes keep working until the duckdb migration completes, at which point a future release will remove them. The deprecation warning is your signal to start moving callers over to gat.load() at a comfortable pace.

To silence the warning in code you don’t own, use the standard warnings.simplefilter:

import warnings
warnings.filterwarnings(
    "ignore",
    category=DeprecationWarning,
    module=r"gat\.scenariohandlers\..*",
)

The GAT test suite uses an autouse pytest fixture in tests/conftest.py that does the same thing — tests intentionally instantiate the legacy classes for regression coverage and don’t want the warnings to clutter output.

Why deprecate now, before the duckdb migration is complete?#

Two reasons:

Signal direction. The deprecation tells everyone (humans and IDEs) that gat.load() is the supported entry point. Without it, the parallel v1 architecture (in gat.systems, gat.simulations, gat.backends) isn’t discoverable.
Constraint on new code. The deprecation makes it harder to accidentally build on top of the legacy path going forward, which keeps the migration scope bounded.

The legacy classes themselves still execute the same pandas/h5py code they always have. Phase 5 of the migration replaced their construction story without touching their internals; the duckdb-backed internals will land incrementally, validated against the regression snapshots in tests/handlers/test_plexos_regression.py and tests/handlers/test_sienna_regression.py.

Migration timeline (rough)#

Now (v1.x): Legacy classes work, deprecation warns, gat.load() is the supported path. v1 architecture proven on Plexos via tests/handlers/test_plexos_v1_migration.py.
Subsequent v1.x releases: Legacy get_* methods migrated to route through GATDatabase under the hood. Snapshots gate correctness. Public API unchanged.
v2.0: Legacy classes removed. gat.load() and the v1 architecture are the only path.

Legacy scenario handler deprecation

Contents