ps.io

ps.io.deck_files

ps.io.deck_files(path: str | Path) -> dict[str, str]

Return every file a deck reads, the deck first, as {relpath: sha256}.

The INCLUDE stanzas are followed as Flow follows them, before any keyword is read: a path is read from the deck’s own folder, and one found only beside the including file is refused as Flow refuses it; a PATHS alias is expanded; an INCLUDE inside a SKIP span or after an ENDINC is not opened. Each file is named as the deck’s INCLUDE text names it from the deck’s folder (INCLUDE/GRID.INC, ../shared/PVT.INC), and its digest is of its bytes as read. A file that cannot be read, an INCLUDE cycle or an unclosed skip span is refused with DeckImportError, as the importer refuses it.

Parameters

path : str or Path The deck’s main file.

Returns

dict The relative path of each file read, in the order it was opened, to the hex sha256 of its bytes.

ps.io.read_grdecl

ps.io.read_grdecl(path: str | Path) -> CornerPoint

Read a GRDECL file’s corner-point geometry into a ps.grid.CornerPoint.

SPECGRID, COORD and ZCORN are read, ACTNUM and MAPAXES when stated (MAPAXES: a point on the map’s y axis, the origin, a point on its x axis, becomes the grid’s map_axes); any other keyword is refused by name. ps.io.write_grdecl writes the file this reads back. The values are read as written: bare numbers, in the length unit of the model that takes the grid.

Parameters

path : str or Path The GRDECL file.

Returns

CornerPoint The grid, its provenance naming the file and its checksum.

Raises

ValueError A keyword other than these, one of the three required ones missing or one stated twice, a SPECGRID stating fewer than three dimensions, more than one reservoir or a grid type other than F, a MAPAXES that is not three different points, or a COORD, ZCORN or ACTNUM whose count does not fit SPECGRID’s dimensions. OSError The file cannot be read.

ps.io.read_sheet

ps.io.read_sheet(path: str | Path) -> tuple[Any, dict[str, Any]]

Read a sheet back: (frame, metadata), the inverse of ps.io.write_sheet.

ps.io.read_sheet("tables/wells.parquet") gives the frame and the metadata its writer stamped. Nothing is checked here: write_sheet(schema=) checks a sheet before it writes it, and ps.bundle.open(root).sheet(kind) as it reads it.

Parameters

path : str or Path The parquet file.

Returns

tuple of (polars.DataFrame, dict) The rows, and what the writer stamped under the writer’s own names: key (the key columns), units (each column’s unit word) and schema (the schema id, or None).

Raises

OSError There is no file at path.

ps.io.write_grdecl

ps.io.write_grdecl(grid: CornerPoint | Cartesian, *, path: str | Path) -> Path

Write a grid’s corner-point geometry as the GRDECL file ps.io.read_grdecl reads back.

MAPAXES when the grid carries a map frame, SPECGRID, COORD, ZCORN, and ACTNUM when it states active cells. Every value is spelled as the deck writer spells a number, so reading the file back gives the same arrays, and a value that is no number is refused. A Cartesian grid is written as the corner-point grid it describes: vertical pillars on its column edges, and each cell’s top at its column’s top plus the layers above it (its pore-volume scale, which a geometry does not hold, is left out).

Parameters

grid : CornerPoint or Cartesian The grid whose geometry is written. path : str or Path The file to write; its folders are created.

Returns

Path The file written.

ps.io.write_sheet

ps.io.write_sheet(frame: Any, *, path: str | Path, key: Sequence[str] | str, units: Mapping[str, str] | None = None, schema: str | None = None) -> Path

Write frame to path as a pinned parquet sheet and return the path.

ps.io.write_sheet(frame, path="tables/wells.parquet", key="well", schema="wells@0.1") writes the frame as the wells sheet, its rows sorted by well. The file’s bytes are a function of its rows and its stamp alone, so a sheet written twice is the same file.

Parameters

frame : polars.DataFrame, mapping or list of dict The rows: a polars DataFrame, a mapping of columns (each a list, a tuple, a numpy array or a polars Series) or a list of records (dicts). path : str or Path The file to write (tables/<kind>.parquet in a bundle); its folders are created. key : str or sequence of str The column or columns that tell the rows apart; the rows are written sorted by them. units : mapping of str to str, optional Each numeric column’s unit word ({"depth": "m"}), stamped into the file. schema : str, optional The registered schema the sheet satisfies ("wells@0.1"): the frame is checked with the door’s own checks before a byte is written, and the id is stamped into the file.

Returns

Path The file written.

Raises

BundleRefusal Under a schema, the door’s refusals: bundle.frame.form for a frame of another form, and each check of the schema by its code (bundle.column.missing, bundle.key.duplicate, …). ValueError With no schema, a frame of another form (wrap it: pl.DataFrame(x)), a key column the frame lacks or a key that does not tell every row apart; with or without one, units naming a column the frame lacks, rows that do not build one frame, or a lone surrogate in a text.