meshioplusplus 6.3.0

meshio++: I/O for many mesh formats (C++20 core + Python bindings)

I/O for mesh files.

There are various mesh formats available for representing unstructured meshes. meshio++ can read and write all of the following and smoothly converts between them:

Abaqus (.inp), ANSYS msh (.msh), Ansys/APDL coded database (.cdb, .inp), AVS-UCD (.avs), CGNS (.cgns), DOLFIN XML (.xml), COMSOL (.mphtxt), Exodus (.e, .exo), FLAC3D (.f3grid), FLUX (mesh .pf3, field .dex), FreeFem++ (.msh), H5M (.h5m), HMF (.hmf, experimental, meshio++-specific), I-deas Universal / UNV (.unv), ANSYS Fluent interpolation (.ip), Kratos/MDPA (.mdpa), Medit (.mesh, .meshb), MED/Salome (.med), Modulef (mesh .mfm, field .mff), Nastran (bulk data, .bdf, .fem, .nas), Netgen (.vol, .vol.gz), Neuroglancer precomputed format, Gmsh (format versions 2.2, 4.0, and 4.1, .msh), OBJ (.obj), OFF (.off), OpenFOAM polyMesh (.foam, read-only), PERMAS (.post, .post.gz, .dato, .dato.gz), PLY (.ply), STL (.stl), Tecplot .dat, TetGen .node/.ele, SVG (2D output only) (.svg), SU2 (.su2), UGRID (.ugrid), VTK (.vtk), VTU (.vtu), WKT (TIN) (.wkt), XDMF (.xdmf, .xmf).

meshio++ ships a C++20 core (built with pybind11 + scikit-build-core) that reads and writes most formats with zero-copy numpy at the I/O boundary, plus optional HDF5/netCDF acceleration and a selectable parallel backend (AUTO by default — prefers OpenMP, then STL+TBB, then sequential; override with -DMESHIOPLUSPLUS_PARALLEL_BACKEND=...). Every format has a pure-Python fallback, so behaviour and file compatibility are identical whether or not the native libraries are present. For a standalone C++ build use build/configure.sh (Linux/macOS) or build/configure.bat (Windows). Full docs (install, data model, per-format options, CLI) live at the documentation site (sources under doc/).

Install with

pip install meshioplusplus[all]

([all] pulls in all optional dependencies. By default, meshio++ only uses numpy.) You can then use the command-line tool

meshioplusplus convert    input.msh output.vtk   # convert between two formats

meshioplusplus info       input.xdmf             # show some info about the mesh

meshioplusplus compress   input.vtu              # compress the mesh file
meshioplusplus decompress input.vtu              # decompress the mesh file

meshioplusplus binary     input.msh              # convert to binary format
meshioplusplus ascii      input.msh              # convert to ASCII format

with any of the supported formats.

In Python, simply do

import meshioplusplus

mesh = meshioplusplus.read(
    filename,  # string, os.PathLike, or a buffer/open file
    # file_format="stl",  # optional if filename is a path; inferred from extension
    # see meshioplusplus convert --help for all possible formats
)
# mesh.points, mesh.cells, mesh.cells_dict, ...

# mesh.vtk.read() is also possible

to read a mesh. To write, do

import meshioplusplus

# two triangles and one quad
points = [
    [0.0, 0.0],
    [1.0, 0.0],
    [0.0, 1.0],
    [1.0, 1.0],
    [2.0, 0.0],
    [2.0, 1.0],
]
cells = [
    ("triangle", [[0, 1, 2], [1, 3, 2]]),
    ("quad", [[1, 4, 5, 3]]),
]

mesh = meshioplusplus.Mesh(
    points,
    cells,
    # Optionally provide extra data on points, cells, etc.
    point_data={"T": [0.3, -1.2, 0.5, 0.7, 0.0, -3.0]},
    # Each item in cell data must match the cells array
    cell_data={"a": [[0.1, 0.2], [0.4]]},
)
mesh.write(
    "foo.vtk",  # str, os.PathLike, or buffer/open file
    # file_format="vtk",  # optional if first argument is a path; inferred from extension
)

# Alternative with the same options
meshioplusplus.write_points_cells("foo.vtk", points, cells)

For both input and output, you can optionally specify the exact file_format (in case you would like to enforce ASCII over binary VTK, for example).

Time series

The XDMF format supports time series with a shared mesh. You can write times series data using meshio++ with

with meshioplusplus.xdmf.TimeSeriesWriter(filename) as writer:
    writer.write_points_cells(points, cells)
    for t in [0.0, 0.1, 0.21]:
        writer.write_data(t, point_data={"phi": data})

and read it with

with meshioplusplus.xdmf.TimeSeriesReader(filename) as reader:
    points, cells = reader.read_points_cells()
    for k in range(reader.num_steps):
        t, point_data, cell_data = reader.read_data(k)

ParaView plugin

*A Gmsh file opened with ParaView.*

If you have downloaded a binary version of ParaView, you may proceed as follows.

• Install meshio++ for the Python major version that ParaView uses (check pvpython --version)
• Open ParaView
• Find the file paraview-meshioplusplus-plugin.py of your meshio++ installation (on Linux: ~/.local/share/paraview-5.9/plugins/) and load it under Tools / Manage Plugins / Load New
• Optional: Activate Auto Load

You can now open all meshio++-supported files in ParaView.

Benchmarks

How much does the C++ core help? The benchmark/ folder times read/write conversions against the original pure-Python meshio on the formats both support (same in-memory mesh, same machine). The headline input is the bundled example.msh — a real Gmsh bracket (~52k nodes, ~293k cells).

meshio++'s biggest wins are the parallel and text paths: VTU binary+zlib ~16× write (the zlib blocks run across cores via an OpenMP backend with dynamic scheduling — hybrid P+E-core CPUs load-balance too), VTU ASCII ~7× write / ~5× read, and mixed-topology XDMF read ~10×. The binary and HDF5 formats that used to be slower — VTK/Gmsh binary, UGRID, and MED — are now at or above parity after an optimisation pass (bulk-buffered binary I/O, single-instruction bswap endianness conversion, a real parallel backend, an Eigen-backed MED transpose, zero-copy cell reconstruction that moves the connectivity buffer straight into the mesh, and uninitialised reader buffers + thread-parallel block copies so nothing is written twice); binary reads now match or beat numpy's fromfile — Gmsh ~1.7×, single-type VTK ~1.45×, and even mixed-topology VTK ~1.1×. Output stays byte-identical throughout.

The speedup is per-element: text/parallel formats climb out of the small-mesh regime and plateau (large meshes realise the full speedup):

Full methodology and a reproducible notebook are on the Benchmarks doc page (source: benchmark/01_benchmark.ipynb).

Installation

meshio++ is available from the Python Package Index, so simply run

pip install meshioplusplus

to install.

Additional dependencies (netcdf4, h5py) are required for some of the output formats and can be pulled in by

pip install meshioplusplus[all]

For JavaScript / browser use, the C++ core also ships as a WebAssembly npm package covering 29 of the formats above:

npm install @meshioplusplus/wasm

See the WebAssembly / JavaScript doc page for usage and the format-support table.

C / Fortran API

For HPC codes written in C or Fortran, the C++ core also builds as an installable shared library (libmeshioplusplus, pure-C99 header, pkg-config + find_package support) with a modern OO Fortran 2008 module on top:

./build/configure.sh --fortran --tests --build     # --c-api for the C API alone
cmake --install build/cpp-release --prefix /opt/meshioplusplus

mio_mesh* m = mio_read("in.msh", NULL);
printf("%lld points\n", (long long)mio_mesh_num_points(m));
mio_write("out.vtu", m, NULL);
mio_mesh_free(m);

use meshioplusplus
type(mio_mesh) :: m
call m%read("in.msh")
call m%write("out.vtu")
call m%free()

Full mesh access (build meshes from raw arrays, zero-copy readback) is covered on the C API and Fortran doc pages.

Single-header C++

The whole C++ core is also amalgamated into one self-contained, STB-style header — single_include/meshioplusplus/meshioplusplus.hpp — with pugixml bundled and no external dependencies by default. Drop it in, no CMake or linking required:

// in exactly ONE .cpp:
#define MESHIOPLUSPLUS_IMPLEMENTATION
#include "meshioplusplus/meshioplusplus.hpp"
// elsewhere: just #include it (declarations only)

g++ -std=c++20 -I single_include main.cpp

It is generated by ./tools/amalgamate.sh and kept in sync by CI. See the single-header doc page (optional HDF5/netCDF/zlib formats via MESHIOPLUSPLUS_HAS_* macros).

C++ mesh backends

Standalone C++ builds (no Python) can swap the in-memory mesh structure at compile time via MESHIOPLUSPLUS_MESH_BACKEND — every format works identically under each backend:

• MESHIO (default; the Python extension and PyPI wheels always use it) — mirrors the Python meshio.Mesh;
• NATIVE — the fastest pure-C++ structure (canonical Float64/Int64 storage, cell-type enum, CSR ragged blocks); the WebAssembly build uses it;
• KRATOS — a Kratos Multiphysics-style ModelPart (Nodes/Elements/Conditions/SubModelParts) plus a header-only templated bridge that populates a real Kratos::ModelPart with no Kratos build dependency.

./build/configure.sh --mesh-backend NATIVE --tests --build

See the C++ mesh backends doc page.

Testing

To run the meshio++ unit tests, check out this repository, install it with the test extras, and type

pytest tests/

License

meshio++ is published under the MIT license.