Skip to content

Results

pynumgeo.results

Readers for numgeo's result files (numpy and the standard library only).

  • :func:open_results -> :class:Results of one job: VTK frames (:meth:Results.frames), print output (:meth:Results.print_files, :meth:Results.print_series), the status file (:meth:Results.sta).
  • Single files: :func:read_vtu, :func:read_vtm, :func:read_pvd (:mod:~pynumgeo.results.vtk), :func:read_print_file, :func:read_print_blocks (:mod:~pynumgeo.results.printfiles), :func:read_sta, :func:read_msg_steps (:mod:~pynumgeo.results.sta).
  • :func:voigt_to_tensor: stresses/strains as tensors with explicit component order and shear.

Values are returned as numgeo writes them: total time, Voigt components in the file's order, strains with engineering shear, reaction forces with numgeo's sign. The format details and the source lines they come from are in the module docstrings.

Examples:

>>> import pathlib, tempfile
>>> d = pathlib.Path(tempfile.mkdtemp())
>>> (d / "sim-print-out").mkdir()
>>> _ = (d / "sim-print-out" / "SOIL.TOP_node_3.dat").write_text(
...     "    Time             U1             U2             U3\n"
...     ".500000000E+00   0.100000E-02   0.211464-100   0.000000E+00\n")
>>> s = open_results(d, "sim").print_series("soil.top", kind="node", index=3)
>>> s.columns, s.values.tolist()
(['U1', 'U2', 'U3'], [[0.001, 2.11464e-101, 0.0]])

PrintFileInfo(set_name, kind, index, path) dataclass

A print file found in <job>-print-out/.

Attributes:

Name Type Description
set_name str

set name as in the file name (upper case; INSTANCE.SET for instance sets).
kind PrintKind

node, element or ip.
index int

number in the file name: node label, or element position (= label for meshes numbered 1..n).
path Path

the file.

PrintFormatError

Bases: ValueError

The rows of a print file cannot be matched to its header (see the module docstring).

PrintSeries(columns, time, values, path, kind, ip=None, header=(), issues=()) dataclass

Contents of one print file.

Attributes:

Name Type Description
columns list[str]

names of the value columns in data order (time excluded).
time FloatArray

total time of each row.
values FloatArray

(rows, len(columns)).
path Path

the file.
kind PrintKind

node, element or ip.
ip tuple[int, ...] | None

integration point of each column (ip files), None otherwise.
header tuple[str, ...]

names as written in the header (time excluded), for reference.
issues tuple[Issue, ...]

what the reader had to interpret (dropped columns, header deviations).

column(name, ip=None)

Values of one column; the name is matched exactly, else case-insensitively.

Parameters:

Name Type Description Default
name str

column name (e.g. "U2", "STRESS11").

 required
ip int | None

integration point (required for ip files).

 None

Raises:

Type Description
KeyError

no such column.
ValueError

the name (and ip) matches more than one column.

Frame(path, time, step, counter, step_name=None, increment=None)

One written VTK frame (one <DataSet> of the .pvd); datasets are read on first use.

Attributes:

Name Type Description
path

the .vtm file.
time

total time from the .pvd (full precision).
step

step number from the file name <job>-all-results-<step>-<counter>.vtm (VTK_write_results_.f90:147-150), None if the name does not follow it.
counter

number of the frame within its step (starts at 1 in every step; it is not the increment).
step_name

step name (upper case) from the .msg file, None if unknown.
increment

increment of the frame, None if not determinable. numgeo does not write it into the VTK files; it is taken from the .sta rows of the same step that are not known to be rejected and whose total time equals :attr:time within the 4 digits of the .sta, if they name exactly one increment. Needs the .msg file for the step numbers.

The frame-level properties (:attr:points, :attr:cells, :meth:point_data, ...) concatenate the datasets of the block Model elements (1D elements, 2D elements, 3D elements) in this order. Each dataset has its own points, so a node shared by beam and solid elements appears in both (with the nodal averages of its own dataset, VTK_write_results_.f90:291-339). With EMBEDDED output, embedded regions and their guest beams are separate datasets; use :attr:datasets for them.

datasets property

All datasets of the .vtm in file order (with :attr:VtuData.name, :attr:VtuData.block).

model_datasets property

The datasets of the block Model elements.

points property

(n, 3) point coordinates of the model datasets.

cells property

Cells of the model datasets as (vtk_type, connectivity[k, nodes_per_cell]) blocks.

Connectivity indexes :attr:points (0-based); the blocks in order give the cells in the order of :meth:cell_data. VTK cell types are numgeo's (e.g. 3 line, 9 quad, 23 quad8, 12 hexahedron) and node order is numgeo's element node order (VTK_write_cells_.f90:87-104).

node_labels property

Node label of each point (NodeLabel).

element_labels property

Element label of each cell (ElementLabel).

point_names property

PointData names present in every model dataset (order of the first).

cell_names property

CellData names present in every model dataset (order of the first).

dataset(name)

The dataset with this name (e.g. "2D elements").

Raises:

Type Description
KeyError

no or more than one dataset with this name.

point_data(name)

PointData array over all model datasets (names as numgeo writes them, blanks stripped).

cell_data(name)

CellData array over all model datasets (names as numgeo writes them, blanks stripped).

Results(workdir, job='job')

Result files of one job in one folder (see :func:open_results).

pvd_path property

<job>-all-results.pvd (VTK_type.f90:1204).

print_dir property

<job>-print-out (print_type.f90:93).

sta_path property

<job>.sta (report_construct_.f90:51).

msg_path property

<job>.msg (report_construct_.f90:53).

step_names()

Step number -> name (upper case) of the executed steps, from the .msg file ({} without it).

sta()

Increment rows of <job>.sta (see :func:pynumgeo.results.read_sta), with step numbers from the .msg file when it exists.

Raises:

Type Description
FileNotFoundError

no .sta file.

frames()

All VTK frames in the order of the .pvd.

Raises:

Type Description
FileNotFoundError

no .pvd (the run wrote no VTK field output).

print_files()

The print files of the run ([] if there is no <job>-print-out folder).

print_series(set_name, kind='node', index=None, *, columns=None)

Read the print file of one set member.

Parameters:

Name Type Description Default
set_name str

set name, compared case-insensitively (numgeo upper-cases it); sets of an instance are named "Instance.Set".

 required
kind PrintKind

node, element or ip.

 'node'
index int | None

node label or element number in the file name; may be omitted if the set has one file.

 None
columns Sequence[str] | None

column names to use instead of the header (see :func:pynumgeo.results.read_print_file).

 None

Raises:

Type Description
FileNotFoundError

no such file (the message lists what exists).
ValueError

index omitted but the set has several files.

StaRow(step, step_type, step_number, increment, iterations, total_time, step_time, dt, rejection, accepted, fos=None, dfos=None, max_disp=None, cpu_time=None, dt_crit=None, critical_element=None) dataclass

One increment attempt of the .sta file.

Attributes:

Name Type Description
step str

step name as written (upper case).
step_type str

GEOSTATIC, STATIC, TRANSIENT, DYNAMIC, EXPLICIT DYNAMIC, TRANSIENT CRITICAL or REDUCTION.
step_number int | None

number of the step in the input, if known (from the .msg file, see :func:read_sta), else None.
increment int | None

increment number (None if the field overflowed).
iterations int | None

equilibrium iterations (None for explicit rows or an overflowed field).
total_time float | None

total time (None in strength reduction rows).
step_time float | None

step time (None in strength reduction rows).
dt float | None

time increment (None in strength reduction rows).
rejection str

rejection text as written, "" if none.
accepted bool | None

True/False by the rule of :func:read_sta, None where the file does not tell (strength reduction rows; a labelled last attempt of an unfinished step).
fos, (dfos, max_disp)

factor of safety, its increment and max. |u - u_0| (REDUCTION only).
cpu_time float | None

CPU time of the step (EXPLICIT DYNAMIC only).
dt_crit, critical_element

critical time increment and element (TRANSIENT CRITICAL only).

DataArray(name, vtk_type, values, component_names=()) dataclass

One DataArray of a PointData or CellData section.

Attributes:

Name Type Description
name str

array name with leading/trailing blanks removed.
vtk_type str

VTK scalar type as declared (Float64, Int32, UInt8, ...).
values NDArray[Any]

shape (n,) for one component, (n, components) otherwise.
component_names tuple[str, ...]

ComponentName<i> attributes (numgeo writes them for the nset/elset membership arrays, VTK_write_DataArray_.f90:403-426), empty otherwise.

components property

Number of components.

PvdEntry(time, file, part) dataclass

One <DataSet> of a .pvd collection.

Attributes:

Name Type Description
time float

timestep attribute: numgeo writes the total time (cdb%time; cdb%time0 for a frame of increment 0), VTK_write_results_.f90:151-157.
file Path

referenced file, resolved against the folder of the .pvd.
part int

part attribute (numgeo writes 0).

VtmEntry(name, block, file) dataclass

One <DataSet> with a file in a .vtm multiblock file.

Attributes:

Name Type Description
name str

dataset name ("1D elements", "Beam", "Interaction surface").
block tuple[str, ...]

names of the enclosing blocks, outermost first.
file Path

referenced .vtu, resolved against the folder of the .vtm.

VtuData(path, points, connectivity, offsets, types, point_arrays, cell_arrays, name=None, block=()) dataclass

Contents of one .vtu file (one Piece).

Attributes:

Name Type Description
path Path

the file.
points FloatArray

(n, 3) coordinates (z = 0 in 2D models).
connectivity IntArray

0-based point indices of all cells, concatenated (numgeo node order).
offsets IntArray

end position of each cell in connectivity (VTK convention).
types NDArray[uint8]

VTK cell type per cell (e.g. 23 for an 8-node quadrilateral).
point_arrays tuple[DataArray, ...]

PointData arrays in file order.
cell_arrays tuple[DataArray, ...]

CellData arrays in file order.
name str | None

dataset name in the .vtm ("2D elements"), None if read directly.
block tuple[str, ...]

names of the enclosing .vtm blocks, outermost first (("Model elements",)).

number_of_points property

Number of points.

number_of_cells property

Number of cells.

cells property

Cells as blocks (vtk_type, connectivity[k, nodes_per_cell]).

Consecutive cells with the same VTK type and node count form one block, so concatenating the blocks in order gives the cells in file order (the order of :meth:cell_data).

point_names property

Names of the PointData arrays in file order.

cell_names property

Names of the CellData arrays in file order.

node_labels property

Node labels of the points (PointData NodeLabel, VTK_write_results_.f90:1009-1029).

element_labels property

Element labels of the cells (CellData ElementLabel, VTK_write_results_.f90:1034-1053).

point_data(name)

Values of a PointData array (see :func:find_array for the name lookup).

cell_data(name)

Values of a CellData array (see :func:find_array for the name lookup).

list_print_files(directory)

All files of a <job>-print-out folder named <SET>_<kind>_<n>.dat, sorted by set, kind, n.

read_print_blocks(path, *, kind=None)

Read a print file whose row width changes, as one series per run of equal-width rows.

numgeo writes the header once, for the variables of the first step that defines the file (:126-134), and the rows of each step with that step's variables (:384). Blocks that match the header are named from it; other blocks get the names col1, col2, ... and a warning issue.

read_print_file(path, *, kind=None, columns=None)

Read one print file.

Parameters:

Name Type Description Default
path str | Path

the .dat file.

 required
kind PrintKind | None

node, element or ip; default from the file name.

 None
columns Sequence[str] | None

names of the value columns (time excluded) to use instead of the header; their number must equal the row width.

 None

Raises:

Type Description
PrintFormatError

rows of different widths (variables changed between steps; use :func:read_print_blocks), or rows that do not match the header.

read_print_rows(path)

Raw access: header lines and every data row (time first) as written.

Node and element files have one header line, integration-point files two (decided from the file name; a file not named *_ip_<n>.dat is treated as a node/element file).

open_results(workdir, job='job')

Open the results of job job in workdir.

Raises:

Type Description
FileNotFoundError

workdir is not a folder, or it holds none of <job>-all-results.pvd, <job>-print-out/, <job>.sta.

read_msg_steps(path)

Step numbers and names of the executed steps from a .msg file, in order.

Reads the Step <n>: <NAME> line that follows a rule of 100 = (report_convergence_.f90:66-68).

read_sta(path, *, step_numbers=None)

Read all increment rows of a .sta file.

Parameters:

Name Type Description Default
path str | Path

the .sta file.

 required
step_numbers Sequence[int] | None

step number of the 1st, 2nd, ... step block of the file (e.g. from :func:read_msg_steps); sets :attr:StaRow.step_number.

 None

Acceptance, :attr:StaRow.accepted:

  • a row followed by another row of its step: rejected if that row repeats the increment number (a cut-back keeps the number, src/main.f90:574-579), else accepted, whatever the rejection text (under NOCUTBACK a non-converged attempt is accepted, src/main.f90:950-970);
  • the last row of a step: accepted without rejection text, or with rejected (niter > maxiter) when the step ended with Step sucessfully terminated (the text is also printed for attempts that converged in the last iteration); else None. Not visible in the .sta: a step that ran out of increments ends after a rejected attempt number maxinc + 1 (src/main.f90:555), and is still reported as terminated; such a last row is then wrongly taken as accepted. :func:pynumgeo.run knows maxinc from the deck and decides this case correctly;
  • strength reduction rows: None; the factor-of-safety logic decides (src/database/step_ty_.f90:330-440).

voigt_to_tensor(values, *, order, engineering_shear)

Symmetric 3x3 tensors from Voigt vectors.

Parameters:

Name Type Description Default
values ArrayLike

shape (..., 6).

 required
order VoigtOrder

"numgeo" (print files, [11, 22, 33, 12, 13, 23]) or "vtk" (VTK tensor arrays, [11, 22, 33, 12, 23, 13]).

 required
engineering_shear bool

True for numgeo strains (shear components are gamma = 2 epsilon and are halved), False for stresses.

 required

Returns:

Type Description
NDArray[float64]

Array of shape (..., 3, 3).

Raises:

Type Description
ValueError

if the last axis does not have 6 components or order is unknown.

read_pvd(path)

Read a ParaView collection file (<job>-all-results.pvd), entries in file order.

Raises:

Type Description
ValueError

if the file is not a Collection or an entry lacks timestep/file.

read_vtm(path)

Read a vtkMultiBlockDataSet file: all datasets with a file, in document order.

Raises:

Type Description
ValueError

if the file is not a vtkMultiBlockDataSet.

read_vtu(path, *, name=None, block=())

Read an UnstructuredGrid .vtu file as numgeo writes it (ASCII or raw appended binary).

Parameters:

Name Type Description Default
path str | Path

the file.

 required
name str | None

dataset name to record (from the .vtm).

 None
block tuple[str, ...]

enclosing block names to record (from the .vtm).

 ()

Raises:

Type Description
ValueError

for anything numgeo does not write (several pieces, compression, base64, unknown types) or inconsistent sizes.