monee io

native (OMEF JSON)

Native JSON (de)serialization for monee Network.

The native format is a plain dict (JSON-friendly) with this shape:

{
    "version": 2,
    "grids":    {name: {"model_type": str, "values": {...}}},
    "nodes":    [{"id", "grid_id", "child_ids", "position",
                  "active", "name", "values", "model_type"}],
    "childs":   [{"id", "active", "name", "values", "model_type"}],
    "branches": [{"id", "from_node", "to_node", "grid_id", "grid_ids",
                  "active", "name", "values", "model_type"}],
    "compounds":[{"id", "connected_to", "values", "model_type"}],
}

Each model attribute in a values block is encoded with full fidelity: plain scalars pass through unchanged, while Var, Const and Intermediate are tagged with a reserved __type__ key so they round-trip exactly (Var keeps its bounds, integer flag and name).

The reader stays backward compatible with the legacy format produced by older versions and by monee.io.matpower (untagged {"value", "max", "min"} Var dicts).

Both the public, solver-visible attributes of a model and its JSON-encodable private attributes (e.g. a storage’s _p_max / _lossy) are serialized, so models whose behaviour is configured through private state round-trip faithfully. Private attributes holding object references (grids, sub-models) are skipped on purpose - they are rebuilt by the compound create() / branch init() hooks.

Known limitations (not represented in the native format): user-supplied network.constraint / network.objective callables, network-level extensions registered via add_extension (linepack, LTC, islanding), and non-default formulations applied with apply_formulation - the latter are re-derived from the default formulation rules on load.

monee.io.native.FORMAT_VERSION = 2

Bumped whenever the on-disk structure changes in a non-additive way.

exception monee.io.native.PersistenceException

Bases: Exception

monee.io.native.branch_to_dict(branch, grids)

monee.io.native.child_to_dict(child)

monee.io.native.compound_to_dict(compound)

monee.io.native.fetch_grid_to_dict(grid_dict, grid_from_model)

monee.io.native.init_model(model_type, preprocessed_dict)

monee.io.native.iter_concrete_grids(grid)

Yield the concrete grid object(s) backing a component.

Single-grid components carry their grid directly. Multi-grid branches (coupling points that span e.g. a power and a gas grid) carry a dict mapping grid type -> grid (and sometimes a list of grids). Yield every distinct concrete grid that exposes a name, in a stable order.

monee.io.native.load_to_network(file)

Return type:

monee.model.network.Network

monee.io.native.model_to_dict(model)

Encode a model’s full state.

All public (solver-visible) attributes are serialized; private attributes are serialized only when JSON-encodable, since non-encodable ones hold object references that are rebuilt by create() / init() on load. A public attribute that cannot be encoded is a genuine gap and raises.

monee.io.native.native_dict_to_network(dict_struct)

Return type:

monee.model.network.Network

monee.io.native.network_to_native_dict(network: monee.model.network.Network)

Serialize network to the native, JSON-friendly dict form.

Return type:

dict

monee.io.native.node_to_dict(node, grids)

monee.io.native.preprocess_dict(model_dict)

monee.io.native.write_omef_network(file, network: monee.model.network.Network)

Serialize network to file as native JSON.

matpower

monee.io.matpower.as_controllable(start_value)

monee.io.matpower.fill_branch_dict(branch_mat, branch_dict_list)

monee.io.matpower.fill_child_dict(gen_mat, node_dict_list, child_dict_list)

monee.io.matpower.fill_node_dict(bus_mat, node_dict_list, child_dict_list)

monee.io.matpower.number_of_lines_with_from_to(from_node, to_node, branch_list)

monee.io.matpower.read_matpower_case(file)

monee.io.matpower.read_matpower_data(mat_data)

pandapower (experimental)

simbench (experimental)

CIM / CGMES (experimental)

class monee.io.from_cim.CimImportReport(buses: int = 0, lines: int = 0, transformers: int = 0, loads: int = 0, generators: int = 0, ext_grids: int = 0, skipped: dict = <factory>)

Bases: object

Summary of what was mapped and what was skipped, for transparency.

buses: int = 0

ext_grids: int = 0

generators: int = 0

lines: int = 0

loads: int = 0

log()

Return type:

None

skip(reason: str)

Return type:

None

skipped: dict

transformers: int = 0

monee.io.from_cim.cim_objects_to_network(objects, gen_sign=-1.0)

Build a monee Network from a {mRID: cim_object} mapping.

objects is CIMpy’s merged topology dict. gen_sign maps the CGMES SSH terminal sign convention to generation magnitude (default -1 treats a negative SSH p as generation). Returns (network, CimImportReport).

monee.io.from_cim.import_cim_files(file_list, cgmes_version='cgmes_v2_4_15', gen_sign=-1.0)

Import CGMES XML/zip files into a monee Network.

Parameters:

• file_list – Path(s) accepted by cimpy.cim_import - the EQ/TP/SSH (and optionally SV) profile files of one CGMES model.

• cgmes_version – CIMpy version tag, e.g. "cgmes_v2_4_15" or "cgmes_v3_0_0".

• gen_sign – Sign applied to SSH machine setpoints (see cim_objects_to_network()).

Returns:

The electrical Network and a CimImportReport.

Return type:

(network, report)

monee.io.from_cim.mx_base_kv(net, node_id)

base_kv of an already-created Bus node.

Return type:

float

monee.io.from_cim.net_base_mva(net)

System base MVA of the electrical grid (defaults to 1 like the model).

Return type:

float

ESDL (experimental)

class monee.io.from_esdl.EsdlImportReport(nodes: int = 0, el_branches: int = 0, gas_pipes: int = 0, heat_pipes: int = 0, loads: int = 0, sources: int = 0, skipped: dict = <factory>)

Bases: object

Summary of what was mapped and what was skipped, for transparency.

el_branches: int = 0

gas_pipes: int = 0

heat_pipes: int = 0

loads: int = 0

log()

Return type:

None

nodes: int = 0

skip(reason: str)

Return type:

None

skipped: dict

sources: int = 0

monee.io.from_esdl.esdl_system_to_network(es)

Build a monee Network from a loaded ESDL EnergySystem.

Returns (network, EsdlImportReport).

monee.io.from_esdl.import_esdl_file(path)

Import an .esdl file into a monee Network.

Returns (network, EsdlImportReport).