Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Python

A bridge over the Rust library: open, read, edit and write EPC packages and their HDF5 files, ask for geometry and properties, export, check. Like the command line it knows nothing the library does not; every answer is a call an application would make itself in Rust.

The wheel is built with every schema version (all): nothing to choose from Python. The per-version Cargo features of the energyml crate concern Rust applications only (see The library).

You do not need h5py: arrays come out of the same HDF5 backend the command line uses. Binary wheels carry the HDF5 library, so the machine that installs one needs neither HDF5 nor a Rust toolchain.

Name and install

The distribution is energyml-rust and the import is energyml.rust - a room in the energyml.* namespace shared with the pure-Python generated model packages (energyml-resqml2-2 and siblings, energyml-utils), not a competitor to them:

from energyml.resqml.v2_2 import resqmlv2   # generated classes (other distribution)
from energyml.rust.epc import Epc           # this bridge

The wheel ships no energyml/__init__.py, so it never overwrites another distribution’s files.

pip install energyml-rust

To build a wheel from the repository instead (needs Rust and HDF5):

pip install maturin
maturin build -m crates/energyml-python/Cargo.toml --release

The wheel is abi3: one wheel per platform, not one per Python version. On Windows, a locally built wheel must be repaired so it carries HDF5 (see Troubleshooting, DLL load failed).

Out of scope on purpose: ETP. For a remote dataspace use the retp project.

The map

modulewhat is in it
energyml.rust.storagethe abstraction above every store; Epc is its first subclass
energyml.rust.epcopen, read, edit and write an EPC and its HDF5 files; ask its catalogue questions
energyml.rust.modelthe generated model by reflection: which types exist, what they hold, an empty object of one
energyml.rust.resqmlgeometry of a representation, values on it, export

Opening a package

from energyml.rust.epc import Epc

pkg = Epc.open("package/Lutetia.epc")
for one in pkg.objects():
    print(one.qualified_type, one.uuid, one.title)

The .h5 files are looked for beside the .epc. A summary is what is known without opening the part; a part that cannot be parsed keeps its row with an empty title (dropping it would say it is not in the package). Create an empty package with Epc.create("name.epc") and tell it where data files go with set_data_root(directory).

pkg.find("Representation")                  # by type, case-insensitive
pkg.find("Crs", "default")                  # and by title (both mean "and")

What points at what

for link in pkg.references(uri):
    print(link["qualified_type"], link["title"], link["path"], link["present"])

pkg.referenced_by(uri)        # the other direction (reads every object: no package indexes it)
needed, missing = pkg.needs([uri])   # the closure: what an extraction or a copy must carry

referenced_by and needs read every object, and refuse (an exception that names the unreadable objects) when one cannot be read: the unreadable part might be the one that points at the target, and “nothing depends on it” would be a wrong answer to give before a deletion or a cut. Repair or remove the named part first.

present says whether the package holds the target; a dangling reference keeps its entry. A well-known PropertyKind from the Energistics dictionary is never reported as dangling.

Taking objects into another package

small = Epc.create("small.epc")
small.set_data_root("out")
done = small.copy_from(pkg, [surface.uri])
done["added"]     # what came along: interpretation, feature, CRS...
done["arrays"]    # datasets that travelled
small.save_as("out/small.epc")

The set is closed on the way in: asking for a surface alone would give a package that opens and places it nowhere.

The model and making an object

from energyml.rust.model import describe, template, types

types("resqml")                       # every RESQML type this build carries
describe("resqml22.BoundaryFeature")  # fields, cardinality, documentation

There are no Python classes, by decision: one class per type per release would be a second copy of the generated model. You get the reflection and a skeleton:

import uuid
obj = template("resqml22.BoundaryFeature", str(uuid.uuid4()))
obj["Citation"].update(Title="Top Chalk", Originator="me",
                       Creation="2026-09-19T12:00:00Z", Format="energyml-rust")
pkg.put(obj)

The uuid is always given, never invented: nothing defaults to a random one, because a caller that derives identities from its source must get the same objects on a second run.

Objects travel as JSON

obj = pkg.get(uri)                 # a dict
obj["Citation"]["Title"] = "Renamed"
pkg.put(obj)                       # back in; returns the URI it wrote

The $type key makes the JSON re-readable. A dict is checked against the schema and a refusal names the field and value. pkg.get(uri) on an existing object of the type you want to write is the best way to learn a shape.

Arrays

for ref in pkg.arrays(uri):
    print(ref.file, ref.path_in_file, pkg.array_shape(ref))

values, dimensions = pkg.read_array(ref)          # flat numpy array and the shape beside it
points = values.reshape(dimensions)
values, dimensions = pkg.read_array_part(ref, start=[1, 0], count=[1, 3])   # a slice

pkg.write_array(ref, np.asarray(points, dtype=np.float64).ravel(), [len(points), 3])

An HDF5 string dataset comes out as a list[str], not a numpy array.

Arrays are flat copies (a view would outlive the memory it points to). The dtype decides what is written (float32/64, int8-64, uint8-64); anything else is refused by name. A shape that disagrees with the number of values is refused, naming both counts.

Geometry, properties and export

from energyml.rust.resqml import geometry_of, mesh_of, properties_of, export_of, formats

shape = geometry_of(pkg, uri)                 # placed points and topology, by patch
points, triangles = mesh_of(pkg, uri, "metres")
values, problems = properties_of(pkg, uri)    # values hanging on this shape, with colour ramps
open("model.obj", "wb").write(export_of(pkg, [uri], "obj"))

geometry_of returns what the file says, patch by patch, with a topology key (points, triangles, quads, polygons, polylines, segments, hexahedra, polyhedra, grid), and index, the patch’s number. An IJK grid’s hexahedra add cells (8 node indices per cell), dimensions and cell_index, the RESQML number of each cell - empty when every cell is there, in order: a cell the file marks undefined is left out, and the cells after it no longer sit at their own number. placement is local, projected (the default) or metres; an unknown name is refused with the list, and metres is refused when the unit cannot be converted. mesh_of merges and triangulates, and says so in its name. properties_of returns the values that fit the shape, checked against the geometry, and a second list of those that did not fit. A colour ramp is empty when the package states none: no default is invented.

export_of returns bytes. The list of formats is the exporter registry’s own. A format that cannot write an object refuses, naming it.

Judging and saving a package

r = pkg.check()
print(r["errors"], r["warnings"], r["sound"])     # the same numbers `energyml check` prints

diagnostics = pkg.save_as("copy.epc")             # returned, never swallowed

check(schema=False) returns checked: False: not checked is not the same as clean.

Renaming the data file

quote = pkg.plan_rename("survey.h5", "survey_2026.h5")   # changes nothing
done = pkg.rename_data_file("survey.h5", "survey_2026.h5")

Quote first; the operation refuses as a whole rather than doing part.

Repairing the declared data files

files = pkg.array_files()                 # what `energyml h5` prints; changes nothing
# [{"declared": "survey.h5", "pointers": 12, "found": {"path": ..., "origin": ..., "agrees": False},
#   "example": "/RESQML/...", "proxies": [...]}, ...]   ("found" is None when the search failed)
pkg.pin_data_file("survey.h5", "/data/dataset_7.dat")   # say where a missing file is, then ask again
done = pkg.repair_arrays("fixed.epc")     # what `energyml h5 --fix` does; None = nothing to fix
print(done["renamed"], done["declarations"], done["lost"])

The bridge carries no logic of its own: the survey, the rewrite and the verdict are energyml_storage::repair’s, the same ones the command line uses. lost is read back from the written package; non-zero means the repair did not repair (the package uses an externalResource relationship the writer does not reproduce).

referenced_by(uri) answers for that uri: when a package holds two versions of one uuid, an object that names version 2 is not reported as pointing at version 1.

Examples

Worked examples live in the bridge’s examples/ folder, crates/energyml-python/examples/, and are run by its tests (tests/examples.rs): adding a surface to an existing package (01_add_a_surface.py), and building a package from nothing (feature, interpretation, point set, property: 02_a_package_from_nothing.py).