Metadata-Version: 2.4
Name: pyvista-frd-reader
Version: 0.2.2
Summary: Read CalculiX FRD result files into PyVista, backed by a C++ core with a C ABI.
Author-email: The PyVista developers <info@pyvista.org>
License-Expression: MIT
Project-URL: Home, https://github.com/pyvista/pyvista-frd-reader
Project-URL: Issues, https://github.com/pyvista/pyvista-frd-reader/issues
Keywords: calculix,fea,frd,pyvista,vtk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: pyvista>=0.45.0
Provides-Extra: docs
Requires-Dist: linkify-it-py>=2.0; extra == "docs"
Requires-Dist: matplotlib>=3.7; extra == "docs"
Requires-Dist: myst-parser>=3.0; extra == "docs"
Requires-Dist: pydata-sphinx-theme>=0.15; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
Requires-Dist: sphinx-design>=0.5; extra == "docs"
Requires-Dist: sphinx-gallery>=0.16; extra == "docs"
Requires-Dist: sphinx>=7.2; extra == "docs"
Provides-Extra: tests
Requires-Dist: pytest-cov>=5.0.0; extra == "tests"
Requires-Dist: pytest>=6.2.0; extra == "tests"
Dynamic: license-file

pyvista-frd-reader
==================

Read and write CalculiX FRD files with PyVista. The Python API returns a
``pyvista.UnstructuredGrid``; the C API exposes the same parser without a
Python dependency.

.. code:: python

   import pyvista_frd

   mesh = pyvista_frd.read("result.frd")
   mesh.plot(scalars="STRESS_Mises")

Install
-------

.. code:: bash

   pip install pyvista-frd-reader

Wheels are available for Linux, macOS, and Windows. Linux wheels require
glibc 2.28 or newer. A source build requires CMake and a C++17 compiler.
There is no pure-Python fallback.

Read time steps
---------------

Use ``FRDReader`` when a file contains more than one result step:

.. code:: python

   reader = pyvista_frd.FRDReader("transient.frd")
   print(reader.time_values)

   reader.set_active_time_point(3)
   mesh = reader.read()

The reader implements PyVista's time-reader interface. Result blocks are
indexed when the file is opened and parsed when their step is first read.

Write and convert files
-----------------------

.. code:: python

   pyvista_frd.write("result_ascii.frd", mesh)
   pyvista_frd.write("result_binary.frd", mesh, binary=True)

   # Convert the records without building a PyVista mesh.
   pyvista_frd.convert("result_binary.frd", "result_ascii.frd", binary=False)

ASCII output stores six significant digits. Binary output is smaller and
retains the stored floating-point values. See
`Writing FRD <https://frd-reader.pyvista.org/writing.html>`_ for format and
round-trip details.

Supported FRD data
------------------

The reader supports the two ASCII encodings and the ``float32`` and
``float64`` binary encodings. It reads short and long element records,
including fixed-width records whose node IDs have no separating spaces.

Supported element types are HE8, PE6, PE15, TE4, HE20, TE10, TR3, TR6, QU4,
QU8, BE2, BE3, PY5, and PY13. PY5 and PY13 are the experimental CalculiX
pyramid types C3D5 and C3D13.

For each six-component array whose name contains ``STRESS`` or ``STRAIN``, the
reader adds:

- ``<NAME>_Mises``: von Mises magnitude
- ``<NAME>_sgMises``: von Mises magnitude signed by the tensor trace
- ``<NAME>_PS1``, ``_PS2``, and ``_PS3``: principal values, largest first

Invalid and unsupported elements produce ``pyvista.InvalidMeshWarning`` with
the source line number. Points use ``float64`` storage. VTK cell connectivity
uses 32-bit storage when it fits, otherwise 64-bit storage.

Relationship to PyVista
-----------------------

PyVista includes a Python FRD reader. This package provides a separate C++
implementation and does not replace ``pyvista.FRDReader`` or register itself
as the handler for ``pyvista.read``.

The conformance suite compares the two readers file by file and array by
array. The current external sweep covers 1,766 files with no undocumented
divergences. The principal-value comparison uses a numerical tolerance because
the implementations use different eigensolvers. Binary FRD is checked against
paired ASCII and binary output from CalculiX because PyVista's reader supports
ASCII only.

See `Parity <https://frd-reader.pyvista.org/parity.html>`_ for the corpus,
method, results, and limitations. See
`Divergences <https://frd-reader.pyvista.org/divergences.html>`_ for the exact
behavioral and numerical differences.

C API
-----

The public header is ``cpp/include/pvfrd/pvfrd.h``. It uses a C ABI and can be
called from C, C++, or another language with a foreign-function interface.

.. code:: bash

   cmake -S cpp -B build -DCMAKE_BUILD_TYPE=Release
   cmake --build build

.. code:: c

   #include <pvfrd/pvfrd.h>

   pvfrd_file *file = NULL;
   if (pvfrd_open("mesh.frd", &file) != PVFRD_OK) { /* handle error */ }

   const double *points = pvfrd_points(file);
   uint64_t n_points = pvfrd_n_points(file);

   pvfrd_close(file);

The shared library has no additional link dependencies. Static linking with
GCC or Clang also requires ``-lstdc++ -lm``.

Development
-----------

.. code:: bash

   cmake -S cpp -B cpp/build -DPVFRD_BUILD_TESTS=ON
   cmake --build cpp/build
   ./cpp/build/pvfrd_tests

   pip install -e .[tests]
   pytest

The C++ and Python suites share the fixtures in ``tests/fixtures``.
``tools/mutate.py`` applies known parser and writer defects and verifies that
the intended tests fail.

Documentation
-------------

The `documentation <https://frd-reader.pyvista.org>`_ includes installation,
examples, the Python and C APIs, format notes, and verification results.

Credit
------

Rafal (`@3rav <https://github.com/3rav>`_) wrote PyVista's original FRD reader
in `pyvista#8255 <https://github.com/pyvista/pyvista/pull/8255>`_. This package
reimplements that behavior and vendors the PyVista reader as its conformance
reference. Guido Dhondt and Klaus Wittig created CalculiX and its FRD format.
See `History and credit <https://frd-reader.pyvista.org/history.html>`_.

License
-------

This project is MIT licensed. The vendored ``fast_float`` header is available
under Apache-2.0, MIT, or BSL terms.
