Model¶

class zen_creator.model.Model¶

Bases: object

Structured representation of the ZEN-garden input data.

This class stores the input data for the ZEN-garden energy system model in a structured way. It provides methods to build, modify, validate, and write the model to the input data.

config¶

The configuration object for the model.

Type:: Config

name¶

The name of the model.

Type:: str

output_folder¶

The folder where the model output will be saved.

Type:: Path

source_path¶

The path to the source data.

Type:: Path

energy_system¶

Object representing all data in the “energy_system” folder of the ZEN-garden input data.

Type:: EnergySystem

elements¶

Dictionary of elements (carriers and technologies) present in the model.

Type:: dict[str, Element]

Overview¶

Model is the central container for ZEN-creator input data. It can be initialized either from a configuration file or from an existing ZEN-garden model folder, then built, validated, and written to disk.

Use Cases¶

Import and modify an existing ZEN-garden input model.
Build a new model from configuration for collaborative workflows.
Programmatically add and remove sectors or elements before exporting.

from zen_creator.model import Model

model = Model.from_config("./config.yaml")
model.build()
model.write()

See method docstrings (for example Model.from_config and Model.from_existing) for more detailed examples.

Summary

`Model.from_config`	Initialize a new Model instance.
`Model.from_existing`	Construct a model from an ZEN-garden input folder.
`Model.build`	Builds the model by calling build() method of all elements.
`Model.validate`	Validate the model for completeness and consistency.
`Model.write`	Write the model to disk.

Constructors

Model.__init__() → None¶: Initialize a new Model instance.

classmethod Model.from_config(config: Config | str | Path)¶

Initialize a new Model instance.

Parameters:: config (Config | str | Path) – The configuration for the model. Can be a Config object, or a path to a config file.
Returns:: A new Model instance initialized from the configuration.
Return type:: Model
Raises:: TypeError – If config is not a valid type.

Examples

>>> from pathlib import Path
>>> from zen_creator.model import Model
>>> model = Model.from_config(Path("./config.yaml"))
>>> model.build()
>>> model.write()

classmethod Model.from_existing(existing_model_path: Path | str, config: Config | str | Path | None = None)¶

Construct a model from an ZEN-garden input folder.

This method loads the data of an existing ZEN-garden model into the data structure. The existing model must be in the proper data format for ZEN-garden.

If not config is specified, a configuration file is created from the default configurations. The system configurations, unit configurations, model name, and output folder are then taken directly from the existing model.

This function performs the following steps:

Create a Model object using the configuration file. This object only has the elements (technologies and carriers) specified in the configurations.
Overwrite the Model elements using data from the existing model. Once again, only elements specified in the configuration file are included in the model.

Parameters:

existing_model_path (Path | str) – Path to the existing model.
config (Config | str | Pat | None) – Configuration file for the new model.Can be a Config object, or a path to a config file. If a configuration file is created from the default configurations. The name

Returns:

A new Model instance initialized from the existing model.

Return type:

Model

Raises:

ValueError – If the existing model path does not exist.

Examples

>>> from pathlib import Path
>>> from zen_creator.model import Model
>>> existing = Path("./existing_model")
>>> model = Model.from_existing(existing)
>>> model.name = "updated_model"
>>> model.write()

Core Methods

Model.build() → None¶: Builds the model by calling build() method of all elements.

Model.validate() → None¶

Validate the model for completeness and consistency.

This method checks that the energy system is defined and that all carriers used in technologies are present in the model.

Model.write() → None¶

Write the model to disk.

This method validates the model, removes any existing output directory, writes the system file, and saves all elements.

Examples

>>> model = Model.from_config("./config.yaml")
>>> model.build()
>>> model.validate()
>>> model.write()

Model.write_system_file() → None¶

Write the system.json file for the model.

This method generates the system configuration dictionary and writes it to system.json in the output directory.

Element and Sector Management

Model.add_sector_by_name(sector: str) → None¶

Add a sector to the model by its name.

Parameters:

sector (str) – The name of the sector to add.

Raises:

TypeError – If sector is not a string.
ValueError – If the sector is not registered.

Examples

>>> model = Model.from_config("./config.yaml")
>>> model.add_sector_by_name("electricity")

Model.add_sector(sector_cls: Type[Sector]) → None¶

Add a sector to the model.

Parameters:: sector_cls (Type[Sector]) – The sector class to add.
Raises:: TypeError – If sector_cls is not a subclass of Sector.

Model.remove_sector(sector_cls: Type[Sector]) → None¶

Remove a sector from the model.

Parameters:: sector_cls (Type[Sector]) – The sector class to remove.
Raises:: TypeError – If sector_cls is not a subclass of Sector.

Model.add_element_by_name(element_name: str, generic: None | str = None) → None¶

Add an element to the model by its name.

Parameters:

element (str) – The name of the element to add.

Raises:

TypeError – If element is not a string.
ValueError – If the element is not registered. Elements get registered when their class definitions are imported.

Examples

>>> model = Model.from_config("./config.yaml")
>>> model.add_element_by_name("electricity", generic="carrier")

Model.add_element(element_cls: Type[Element]) → None¶

Add an element to the model.

Parameters:: element_cls (Type[Element]) – The element class to instantiate and add.
Raises:: TypeError – If element_cls is not a subclass of Element.

Model.remove_element_by_name(name: str) → None¶

Remove an element from the model by its name.

Parameters:: name (str) – The name of the element to remove.

Model.remove_element(element_cls: Type[Element]) → None¶

Removes an element from the model.

Parameters:: element_cls (Type[Element]) – The element class to remove.

Attributes and Properties

Instance attributes¶

Table 1 Model instance attributes¶
Attribute	Description
`name`	Model name used when writing output paths.
`config`	Configuration object used to initialize model behavior.
`elements`	Dictionary of model elements keyed by element name.

Properties¶

`Model.source_path`	Source path where model data is read from.
`Model.output_folder`	Output folder where model will be saved.
`Model.output_path`	Output path where model will be saved.
`Model.energy_system`	Return EnergySystem class of the model.
`Model.carriers`	Returns dictionary of all carriers in the current model.
`Model.technologies`	Dictionary of all technologies in the current model.
`Model.storage_technologies`	Dictionary of all storage technologies in the current model.
`Model.conversion_technologies`	Dictionary of all conversion technologies in the current model.
`Model.transport_technologies`	Dictionary of all transport technologies in the current model.
`Model.retrofitting_technologies`	Dictionary of all retrofitting technologies in the current model.

property Model.output_path: Path¶

Output path where model will be saved.

The output path consists of the output folder specified in the configurations and the model name.

Side effects:: Creates the folder corresponding to the output path if it does not exist.

property Model.carriers: dict[str, Carrier]¶

Returns dictionary of all carriers in the current model.

Returns:

Mapping of carrier names to: Carrier objects.

Return type:

dict[str, Carrier]

property Model.technologies: dict[str, Technology]¶

Dictionary of all technologies in the current model.

Returns:

Mapping of technology names to: Technology objects.

Return type:

dict[str, Technology]

property Model.storage_technologies: dict[str, StorageTechnology]¶

Dictionary of all storage technologies in the current model.

Returns:

Mapping of storage technology: names to objects.

Return type:

dict[str, StorageTechnology]

property Model.conversion_technologies: dict[str, ConversionTechnology]¶

Dictionary of all conversion technologies in the current model.

Returns:

Mapping of conversion: technology names to objects.

Return type:

dict[str, ConversionTechnology]

property Model.transport_technologies: dict[str, TransportTechnology]¶

Dictionary of all transport technologies in the current model.

Returns:

Mapping of transport: technology names to objects.

Return type:

dict[str, TransportTechnology]

property Model.retrofitting_technologies: dict[str, RetrofittingTechnology]¶

Dictionary of all retrofitting technologies in the current model.

Returns:

Mapping of retrofitting: technology names to objects.

Return type:

dict[str, RetrofittingTechnology]