ExoVista

An extension of the Sandia exodusii library for exporting PyVista meshes to Exodus format with user-defined element blocks and side sets. This project focuses on a simpler interface for PyVista users (e.g., meshes created via meshio or PyVista's geometric utilities).

Note: This code was initially a fork of: https://github.com/sandialabs/exodusii

Features

• Element Blocks: Automatically split meshes by cell type and user-defined regions
• Side Sets: Define boundary conditions via surface meshes with region arrays
• 2D & 3D Support: Works with Quads, Triangles, Hexahedra, Tetrahedra, Wedges, Pyramids
• VTK Compatibility: Handles VOXEL and PIXEL cell types (auto-permuted to Exodus ordering)
• Node Arrays: Save point data arrays to the Exodus file
• Time-Varying Fields: Write a time history of node and element results (transient data)
• Compressed Output: Array data is zlib/deflate compressed by default (netCDF4), dramatically shrinking file size
• Named Blocks/Sets: Optionally provide custom names for element blocks and side sets
• Read Back to PyVista: Load an Exodus file straight into a PyVista UnstructuredGrid with read_exo (inverse of write_exo)

Installation

From PyPI

pip install exovista

Editable Install (Development)

git clone https://github.com/Interfluo/exovista.git
cd exovista
pip install -e .

Quick Start

import exovista
import numpy as np
import pyvista as pv

# Load a tetrahedral mesh
volume = pv.examples.download_letter_a()
volume.points -= volume.center

# Assign regions for element blocks
volume["region"] = 1 * (volume.cell_centers().points[:, 0] > 0)

# Extract surface and assign regions for side sets
surface = volume.extract_surface()
surface["region"] = 1 * (surface.cell_centers().points[:, 2] > 0)

# Write to Exodus file
exovista.write_exo("output.exo", volume, surface, region_key="region")

API Reference

exovista.write_exo

write_exo(
    filename: str,
    volume: pv.UnstructuredGrid,
    surface: pv.PolyData = None,
    region_key: str = "region",
    block_names: list[str] = None,
    side_set_names: list[str] = None,
    save_node_arrays: bool = True,
    times: np.ndarray | list = None,
    node_fields: dict = None,
    element_fields: dict = None,
)

Parameters:

Time-Varying Fields

Supply times together with node_fields and/or element_fields to write a transient result history. Each field array carries one row per time value; element fields are given in the original volume cell order and are automatically distributed to the correct element blocks. Static node arrays (from save_node_arrays) are broadcast across every time step.

import numpy as np

times = np.linspace(0.0, 1.0, 11)                 # 11 time steps

# (n_steps, n_nodes) node field and (n_steps, n_cells) element field
temperature = np.array([t * volume.points[:, 0] for t in times])
energy = np.outer(times, np.arange(volume.n_cells))

exovista.write_exo(
    "transient.exo",
    volume,
    times=times,
    node_fields={"temperature": temperature},
    element_fields={"energy": energy},
)

For a single time step a 1D array (length n_nodes or n_cells) is also accepted. The resulting file animates over time in ParaView.

exovista.read_exo

The inverse of write_exo: load an ExodusII database into a PyVista UnstructuredGrid.

read_exo(
    filename: str,
    *files: str,
    time_step: int = -1,
    read_node_variables: bool = True,
    read_element_variables: bool = True,
    read_side_sets: bool = False,
) -> pv.UnstructuredGrid | tuple[pv.UnstructuredGrid, pv.MultiBlock]

Parameters:

The returned grid reconstructs node coordinates (2D meshes are embedded in 3D with z = 0) and all element blocks, concatenated in block order. Each cell records its originating Exodus block via cell_data["exo_block_id"] and cell_data["exo_block_name"]. Node and element variables are sampled at the requested time_step, and the full time history is available in grid.field_data["times"] (grid.field_data["num_dim"] holds the original spatial dimension).

When read_side_sets=True, a second value is returned: a pv.MultiBlock with one pv.PolyData per side set (named after the side set), whose faces are rebuilt over the shared volume nodes. Each face carries orig_elem_id (1-based Exodus element id) and face_id (1-based local side id) cell data. 3D element faces become polygons; 2D element edges become line cells.

import exovista

mesh = exovista.read_exo("output.exo")          # last time step
mesh_t0 = exovista.read_exo("output.exo", time_step=1)  # first time step

# Also reconstruct side sets
mesh, side_sets = exovista.read_exo("output.exo", read_side_sets=True)
top_faces = side_sets["side_0"]

# Parallel decomposition (pass each part, or use exovista.File for globbing)
joined = exovista.read_exo("run.exo.4.0", "run.exo.4.1",
                           "run.exo.4.2", "run.exo.4.3")

Output Compression

When writing netCDF4 files (the default), array variables are stored with zlib/deflate compression, which typically shrinks output files by an order of magnitude with negligible effect on read performance. The behavior is controlled by an environment variable:

Compression only applies to the netCDF4 backend; it is skipped automatically for the netCDF3 fallback. Files remain standard ExodusII and are readable by ParaView, Sierra, and other Exodus tools without any changes.

Examples

Example scripts are located in the examples/ directory:

Run an example:

python examples/example_2d_quads.py

Development

Running Tests

The test suite uses pytest:

pip install -e . pytest
pytest test/

Tests that depend on upstream ExodusII reference files not redistributed with this fork (e.g. noh.exo, edges.base.exo) are skipped automatically when the files are absent. Continuous integration runs flake8 and the full test suite across Python 3.10–3.12 (see .github/workflows/ci.yml).

Cleaning Generated Files

python clean.py

This removes generated .exo files, __pycache__ directories, and temporary test outputs.

Copyright

This repo is a fork of https://github.com/sandialabs/exodusii and therefore inherits the below copyright:

Copyright 2022 National Technology & Engineering Solutions of Sandia, LLC
(NTESS). Under the terms of Contract DE-NA0003525 with NTESS, the U.S.
Government retains certain rights in this software.

SCR# 2748