Skip to content

Reading input files with GemsPy

GemsPy supports two loading strategies: a directory-based approach that reads an entire study at once, and a file-by-file approach for programmatic control.

When your study follows the standard directory layout, use load_study():

my_study/
├── input/
│   ├── system.yml
│   ├── optim-config.yml
│   ├── model-libraries/
│   │   └── *.yml
│   └── data-series/
│       ├── modeler-scenariobuilder.dat   ← optional
│       └── *.txt / *.csv

from pathlib import Path
from gems.study.folder import load_study

study = load_study(Path("my_study"))

load_study() returns a Study object that bundles the resolved System, the DataBase with all parameter values, and the ScenarioBuilder loaded from input/data-series/modeler-scenariobuilder.dat (if present).

File-by-file loading (programmatic)

Use the lower-level functions when you want to load files individually or build parts of the study from in-memory data.

Loading the library and the system

from gems.model.parsing import parse_yaml_library
from gems.model.resolve_library import resolve_library
from gems.study.parsing import parse_yaml_components
from gems.study.resolve_components import resolve_system, build_data_base
from pathlib import Path

with open("simple_library.yml") as lib_file:
    input_libraries = [parse_yaml_library(lib_file)]

with open("system_example.yml") as compo_file:
    input_system = parse_yaml_components(compo_file)

result_lib = resolve_library(input_libraries)
system = resolve_system(input_system, result_lib)

Loading timeseries data

database = build_data_base(input_system, Path(series_dir))

build_data_base() reads all timeseries files referenced by the system (.txt or .csv) from series_dir.

Assembling a Study

Once you have system and database, wrap them in a Study:

from gems.study import Study

study = Study(system=system, database=database)

This study object can then be passed directly to build_problem() or SimulationSession.