Python API#

Everything below is importable from the top-level pyvista_frd package.

Reading#

pyvista_frd.read(path, *, time_point=None)[source]#

Read an FRD file into a pyvista.UnstructuredGrid.

Parameters:

path (str | os.PathLike) – File to read.
time_point (int, optional) – Which time step to build. Defaults to the first, matching PyVista.

Returns:

The mesh, with the chosen step’s arrays as point data.

Return type:

pyvista.UnstructuredGrid

Examples

>>> import pyvista_frd
>>> mesh = pyvista_frd.read('mesh.frd')

class pyvista_frd.FRDReader(path)[source]#

Reader for CalculiX FRD result files (.frd).

All four of the format’s encodings are read: both ASCII widths and both binary ones. Supported element types are HE8, PE6, PE15, TE4, HE20, TE10, TR3, TR6, QU4, QU8, BE2, BE3, PY5 and PY13.

For datasets containing 6-component tensors (e.g. STRESS or STRAIN), the reader pre-computes and appends the following derived point arrays:

<NAME>_Mises: equivalent von Mises magnitude.
<NAME>_sgMises: signed von Mises magnitude.
<NAME>_PS1, _PS2, _PS3: principal components, largest first.

Parameters:: path (str | os.PathLike) – File to read.
Warns:: pyvista.InvalidMeshWarning – Raised at construction, not at read, for elements carrying the wrong number of nodes or an unknown type. Construction is where the file is parsed, so it is also where anything wrong with it is known.

Examples

>>> import pyvista_frd
>>> reader = pyvista_frd.FRDReader('mesh.frd')
>>> reader.time_values
[0.5, 1.0]
>>> mesh = reader.read()

property number_time_points: int#: Return the total number of time points.

time_point_value(time_point)[source]#

Return the time value associated with the given time point.

Parameters:: time_point (int)
Return type:: float

property time_values: list[float]#: Return the list of available time values.

set_active_time_point(time_point)[source]#

Set the active time point.

Parameters:: time_point (int)
Return type:: None

set_active_time_value(time_value)[source]#

Set the active time value. An exact match is required.

Parameters:: time_value (float)
Return type:: None

property active_time_value: float#: Return the currently active time value, or 0.0 if there are none.

read()[source]#

Build the mesh for the active time step.

Returns:: Mesh with original_node_ids and every array of the active step attached as point data.
Return type:: pyvista.UnstructuredGrid

Writing#

pyvista_frd.write(path, mesh, *, binary=False, double=True, time=1.0, step=1)[source]#

Write a mesh and its point data to a CalculiX FRD file.

Parameters:

path (str | os.PathLike) – File to write.
mesh (pyvista.UnstructuredGrid) – The mesh. Every cell type must have a CalculiX element code; one that does not is an error rather than a silently dropped cell.
binary (bool, default: False) – Write the binary encoding rather than the ASCII one. Binary is about a third of the size and holds the values exactly; ASCII holds six significant digits and can be read by anything.
double (bool, default: True) – With binary, whether values are 64-bit. 32-bit halves the size of the result blocks and is what a float32 array can carry anyway.
time (float and int) – The time value and step number recorded in the result block header.
step (float and int) – The time value and step number recorded in the result block header.

Return type:

None

Notes

Point data is written; cell data is not, because FRD’s result blocks are nodal. An array that is neither scalar, 3-vector nor 6-tensor is written with a scalar kind code and its own component names.

The file identifies this library as its writer. It is not labelled as CalculiX output, which several checks in this repository – and possibly in yours – use to tell solver output from anything else.

Examples

>>> import pyvista_frd
>>> pyvista_frd.write('out.frd', mesh)

pyvista_frd.convert(source, target, *, binary=None, double=True)[source]#

Rewrite an FRD file, optionally changing its encoding.

With no binary argument every block keeps the encoding it had, which reproduces the input byte for byte – the property the writer is graded on against files CalculiX wrote.

The conversion is the useful direction: a binary FRD, which an ASCII-only reader cannot open at all, becomes one any of them can read. Going the other way costs precision, because ASCII holds six significant digits.

Raises:

FRDFormatError – If the document cannot be restated in the requested encoding – a block header that states no format code cannot be re-stamped, and converting its records anyway would leave the header describing an encoding they no longer use.

Parameters:

source (str | PathLike[str])
target (str | PathLike[str])
binary (bool | None)
double (bool)

Return type:

None

Examples

>>> import pyvista_frd
>>> pyvista_frd.convert('binary.frd', 'ascii.frd', binary=False)

Diagnostics#

class pyvista_frd.Diagnostic(kind, element_type, line, n_expected, n_actual)[source]#

One questionable element, as the parser saw it.

Parameters:

kind (int)
element_type (int)
line (int)
n_expected (int | None)
n_actual (int | None)

class pyvista_frd.DiagnosticKind[source]#: Why an element was reported as questionable.

Errors#

Every exception this package raises is both an FRDError and the built-in a caller would have expected, so except ValueError and except FRDError both work.

exception pyvista_frd.FRDError(status, detail='')[source]#

The native library reported a failure.

The base of every error this package raises from the native core, so except FRDError catches all of them. The subclasses below also inherit the built-in exception a Python caller would reach for – an index out of range is an IndexError, running out of memory is a MemoryError – because a C status code is the wrong shape for Python’s except and making callers match on err.status is asking them to write a switch where the language already has one.

Parameters:

status (int)
detail (str)

Return type:

None

exception pyvista_frd.FRDFormatError(status, detail='')[source]#

The bytes were not a readable FRD document.

Parameters:

status (int)
detail (str)

Return type:

None

exception pyvista_frd.FRDRaggedArrayError(status, detail='')[source]#

One result block gave two nodes different component counts.

A subclass of the format error rather than a sibling: it is a statement about the file, and a caller who only wants to know “is this file readable” should not have to name it separately.

Parameters:

status (int)
detail (str)

Return type:

None

exception pyvista_frd.FRDRangeError(status, detail='')[source]#

A step, array or element index was out of range.

Parameters:

status (int)
detail (str)

Return type:

None

exception pyvista_frd.FRDInvalidArgumentError(status, detail='')[source]#

An argument the native core rejected.

Parameters:

status (int)
detail (str)

Return type:

None

exception pyvista_frd.FRDMemoryError(status, detail='')[source]#

The native core could not allocate.

Parameters:

status (int)
detail (str)

Return type:

None

exception pyvista_frd.FRDInternalError(status, detail='')[source]#

A fault inside the native library, not a property of the file.

Distinct from FRDFormatError on purpose. Reporting a library bug as a bad file sends the reporter to inspect a file that is fine. If you see this, it is worth an issue.

Parameters:

status (int)
detail (str)

Return type:

None

exception pyvista_frd.NativeUnavailableError[source]#: The native library could not be loaded on this machine.

Constants#

An attribute docstring is only visible to autodoc in the module that makes the assignment, so these are documented from there. Both are importable from the top-level package.

pyvista_frd.reader.ELEMENT_TYPE_NAMES#

CalculiX element codes and their names, keyed by the code an FRD file uses.

The code is the second field of an element’s -1 record. The names are what the reference reader prints in its warnings, so they are message text rather than an internal table – PY5 and PY13 are CalculiX’s experimental pyramids, C3D5 and C3D13.

pyvista_frd._capi.ABI_VERSION = 2#: ABI this binding speaks. A library reporting anything else is refused.

pyvista_frd.library_path()[source]#

Return the file the native core was loaded from.

Return type:: str

Below the Python layer#

NativeFile is the thin ctypes binding over the C ABI. It is public so that a caller who wants the arrays without a pyvista.UnstructuredGrid around them – or who is measuring what the Python layer costs – does not have to reach into a private module.

class pyvista_frd.NativeFile(path, *, wedge_order=0)[source]#

An open FRD document.

Thin: it owns the handle and converts native buffers to NumPy. Everything about PyVista lives a layer up, so this class is usable without PyVista installed and is what the conformance suite drives directly.

Parameters:

path (str | os.PathLike[str])
wedge_order (int)

classmethod from_bytes(data, *, wedge_order=0)[source]#

Open a document already in memory, without a temporary file.

Parameters:

data (bytes)
wedge_order (int)

Return type:

NativeFile

close()[source]#

Release the document. Idempotent.

Return type:: None

array_infos(step)[source]#

Return (name, n_components, kind) for every array in a step.

One call across the boundary rather than one per array. A step holds an array per result block plus five more for every tensor, so the per-call cost of a foreign-function layer was being paid a dozen times to move a few hundred bytes.

Parameters:: step (int)
Return type:: list[tuple[str, int, int]]

array(step, index)[source]#

Return array index of step, shaped (n_points,) or 2-D.

Parameters:

step (int)
index (int)

Return type:

NDArray[np.float64]

property steps_parsed: int#

Number of times a step’s values have been parsed.

Zero until a step is asked for, and thereafter equal to the number of distinct steps requested. Exposed so that both halves of the lazy step path – parsed on demand, and parsed at most once – are things a test can assert rather than things the documentation asserts.

find_array(step, name)[source]#

Index of name within step, or -1.

Parameters:

step (int)
name (str)

Return type:

int