Simulation Compiler#

The SimulationCompiler turns an OpenVCAD design into a finite-element mesh plus cell-wise simulation data. The supported backends in this guide are:

  • GENERIC for a solver-neutral SimulationModel returned to Python or C++

  • FENICSX_XDMF for .xdmf + .h5 mesh/data bundles

  • ABAQUS_INP for .inp mesh export

  • LSDYNA_K for a geometry-only LS-DYNA keyword deck (.k)

This page is a hands-on guide to the exporter workflow. It is organized as five lessons: a volume-fractions export, an export-only direct-mechanical beam, a self-contained OpenVCAD-to-FEniCSx beam solve, generic in-memory model access, and an LS-DYNA keyword export. It covers tetrahedral XDMF/H5, hexahedral Abaqus, tetrahedral LS-DYNA, and both mesh families through Python objects. It also explains the two cell-data modes that matter most:

  • volume_fractions exported as both a stochastic material_id field and raw volume_fraction_* fields

  • direct scalar fields such as modulus, poissons_ratio, and density exported directly per element

Prerequisites#

The guide example files live under examples/compilers/simulation/:

  • 01_volume_fractions_export.py

  • 02_direct_mechanical_properties_export.py

  • 03_fenicsx_load_exported_design.py

  • 04_generic_in_memory_model.py

  • 05_lsdyna_graded_gyroid.py

What this compiler exports#

The simulation compiler always starts from the same ingredients:

  1. a prepared OpenVCAD design

  2. a target mesh type

  3. one transport backend

  4. the attributes you want carried into the simulation mesh

The backend selects transport, not meshing behavior. All backends consume the same compact prepared model, so callers can switch destinations without changing geometry or cell-data semantics. GENERIC creates no files; after compile(), call model() to access topology, nodes, flattened zero-based connectivity, cell centroids, material fields, volume fractions, and scalar fields:

settings = pvc.SimulationCompilerSettings()
settings.backend = pvc.SimulationBackend.GENERIC
settings.mesh_kind = pvc.SimulationMeshKind.HEX

hex_settings = pvc.SimulationHexMeshSettings()
hex_settings.voxel_size = pv.Vec3(1.0, 1.0, 1.0)
settings.hex_settings = hex_settings

compiler = pvc.SimulationCompiler(root, settings)
compiler.compile()
model = compiler.model()
print(model.cell_type, len(model.nodes), len(model.connectivity))
assert compiler.written_files() == []

The mesh itself can be:

  • hexahedral using a regular voxel-style grid

  • tetrahedral using a tet mesh with variable sized elements

For fixed geometry, mesh settings, dependency versions, and random_seed, the compiler emits deterministic compact node and element identity. Compact means that every returned or written node is referenced by at least one element.

The attribute path depends on what you attach to the model:

  • volume_fractions is treated as a multi-material mixture. The compiler samples the continuous mixture, performs a deterministic weighted stochastic draw per element, and writes the resulting material_id field. It also writes the raw volume_fraction_* cell fields for convenience.

  • direct scalar attributes such as modulus, poissons_ratio, and density are sampled directly as cell-wise values. There is no stochastic material draw in this path.

Why XDMF comes with an H5 file#

The .xdmf file is the lightweight descriptor that tells downstream tools where the mesh and cell datasets live. The bulk numeric arrays live in the paired .h5 file. In practice:

  • .xdmf describes the topology, geometry, and named attributes

  • .h5 stores the actual node coordinates, element connectivity, and cell-data arrays

That pairing is the normal way to move simulation-sized meshes into tools such as DOLFINx/FEniCSx and viewers such as ParaView.

Lesson 1: Volume fractions#

The script examples/compilers/simulation/01_volume_fractions_export.py builds a centered rectangular bar with a left-to-right material blend. It exports the same design three ways:

  • hex + Abaqus

  • tet + XDMF/H5 (high resolution)

  • tet + XDMF/H5 (low resolution)

import os
import shutil

import pyvcad as pv
import pyvcad_compilers as pvc
import pyvcad_rendering as viz

materials = pv.default_materials

bar_length = 30.0
bar_width = 10.0
bar_height = 10.0
half_length = 0.5 * bar_length

bar = pv.RectPrism(pv.Vec3(0, 0, 0), pv.Vec3(bar_length, bar_width, bar_height))
fractions = pv.VolumeFractionsAttribute(
    [
        (f"1 - clamp((x + {half_length}) / {bar_length}, 0, 1)", materials.id("red")),
        (f"clamp((x + {half_length}) / {bar_length}, 0, 1)", materials.id("blue")),
    ]
)
bar.set_attribute(pv.DefaultAttributes.VOLUME_FRACTIONS, fractions)
root = bar

output_dir = os.path.join(os.path.dirname(__file__), "output", "volume_fractions")

hex_settings = pvc.SimulationHexMeshSettings()
hex_settings.voxel_size = pv.Vec3(0.25, 0.25, 0.25)

abaqus_settings = pvc.SimulationCompilerSettings()
abaqus_settings.output_directory = output_dir
abaqus_settings.file_prefix = "volume_fractions_hex"
abaqus_settings.backend = pvc.SimulationBackend.ABAQUS_INP
abaqus_settings.mesh_kind = pvc.SimulationMeshKind.HEX
abaqus_settings.hex_settings = hex_settings
abaqus_settings.random_seed = 42
abaqus_settings.material_defs = materials

high_fenics_settings = pvc.SimulationCompilerSettings()
high_fenics_settings.output_directory = output_dir
high_fenics_settings.file_prefix = "volume_fractions_tet_high"
high_fenics_settings.backend = pvc.SimulationBackend.FENICSX_XDMF
high_fenics_settings.mesh_kind = pvc.SimulationMeshKind.TET
high_fenics_settings.random_seed = 42
high_fenics_settings.material_defs = materials

high_tet_settings = pvc.SimulationTetFixedMeshSettings()
high_tet_settings.facet_size = 0.75
high_tet_settings.facet_distance = 0.5
high_tet_settings.cell_size = 0.75
high_fenics_settings.tet_fixed_settings = high_tet_settings

low_fenics_settings = pvc.SimulationCompilerSettings()
low_fenics_settings.output_directory = output_dir
low_fenics_settings.file_prefix = "volume_fractions_tet_low"
low_fenics_settings.backend = pvc.SimulationBackend.FENICSX_XDMF
low_fenics_settings.mesh_kind = pvc.SimulationMeshKind.TET
low_fenics_settings.random_seed = 42
low_fenics_settings.material_defs = materials

low_tet_settings = pvc.SimulationTetFixedMeshSettings()
low_tet_settings.facet_size = 2.25
low_tet_settings.facet_distance = 1.5
low_tet_settings.cell_size = 2.25
low_fenics_settings.tet_fixed_settings = low_tet_settings

pvc.SimulationCompiler(root, abaqus_settings).compile()
pvc.SimulationCompiler(root, high_fenics_settings).compile()
pvc.SimulationCompiler(root, low_fenics_settings).compile()

viz.Render(root, materials)

From the repository root, with the project virtual environment activated:

python examples/compilers/simulation/01_volume_fractions_export.py

This example highlights the settings you will change most often:

  • backend selects the output family

  • mesh_kind selects hex or tet

  • material_defs provides the base material ids used by the sampled material_id field

  • random_seed makes the weighted stochastic element selection repeatable

  • tet mesh sizing controls the amount of element-level mixing you can resolve

OpenVCAD preview#

This is the original continuous volume_fractions field before any stochastic element assignment:

OpenVCAD preview — volume_fractions

OpenVCAD preview of the volume-fraction gradient used by the simulation compiler guide

High-resolution tet export in ParaView#

The high-resolution tetrahedral export makes the stochastic material_id field look like a well-mixed gradient because there are enough elements to interdigitate the two materials. The raw volume_fraction_* fields stay smooth because they store the sampled continuous field directly. In this example the suffixes 1 and 3 come from the material ids assigned by pv.default_materials.

High-resolution ParaView — material_id

High-resolution tetrahedral simulation export showing the stochastic material_id field

High-resolution ParaView — volume_fraction_1

High-resolution tetrahedral simulation export showing the volume_fraction_1 field

High-resolution ParaView — volume_fraction_3

High-resolution tetrahedral simulation export showing the volume_fraction_3 field

Low-resolution tet export in ParaView#

The low-resolution export uses the same underlying gradient, but the stochastic material_id field is much harder to read as a smooth transition because there are fewer elements available to represent the mixing pattern. The raw volume_fraction_1 field still shows the same continuous ramp.

Low-resolution ParaView — material_id

Low-resolution tetrahedral simulation export showing the stochastic material_id field

Low-resolution ParaView — volume_fraction_1

Low-resolution tetrahedral simulation export showing the volume_fraction_1 field

The practical takeaway is simple:

  • if your downstream solver only has a discrete material assignment path, you may need a finer mesh so the stochastic material_id pattern captures the intended mixture behavior

  • if your downstream code can use the raw volume_fraction_* arrays directly, the exporter already saves them for you

ParaView exposes the available cell datasets directly in the attribute selector:

ParaView attribute list — volume fractions export

ParaView attribute list for the volume-fractions simulation export

Lesson 2: Direct mechanical property export#

The script examples/compilers/simulation/02_direct_mechanical_properties_export.py shows the direct scalar path. Here the bar carries:

  • modulus graded along x

  • poissons_ratio graded along z

This lesson is intentionally export-only. It uses a different beam than Lesson 3: here poissons_ratio varies through the beam height, while Lesson 3 uses a separate cantilever beam where both elastic fields vary along the beam length. Density is omitted so the walkthrough stays focused on the two scalar fields that are carried directly into the simulation mesh.

import os
import shutil

import pyvcad as pv
import pyvcad_compilers as pvc
import pyvcad_rendering as viz

bar = pv.RectPrism(pv.Vec3(0, 0, 0), pv.Vec3(40.0, 12.0, 12.0))
bar.set_attribute(
    pv.DefaultAttributes.MODULUS,
    pv.FloatAttribute("1200 + 800 * clamp((x + 20.0) / 40.0, 0, 1)")
)
bar.set_attribute(
    pv.DefaultAttributes.POISSONS_RATIO,
    pv.FloatAttribute("0.20 + 0.15 * clamp((z + 6.0) / 12.0, 0, 1)")
)
root = bar

output_dir = "output"

direct_attributes = [
    pv.DefaultAttributes.MODULUS,
    pv.DefaultAttributes.POISSONS_RATIO,
]

fenics_settings = pvc.SimulationCompilerSettings()
fenics_settings.output_directory = output_dir
fenics_settings.file_prefix = "mechanical_tet"
fenics_settings.backend = pvc.SimulationBackend.FENICSX_XDMF
fenics_settings.mesh_kind = pvc.SimulationMeshKind.TET
fenics_settings.random_seed = 7
fenics_settings.direct_attributes = direct_attributes

tet_settings = pvc.SimulationTetFixedMeshSettings()
tet_settings.facet_size = 0.75
tet_settings.facet_distance = 0.75
tet_settings.cell_size = 0.75
fenics_settings.tet_fixed_settings = tet_settings

pvc.SimulationCompiler(root, fenics_settings).compile()
viz.Render(root)

Run the export with the fenicsx conda environment active:

conda activate fenicsx
python examples/compilers/simulation/02_direct_mechanical_properties_export.py

The key setting here is direct_attributes. It tells the compiler which non-volume-fraction fields to carry into the output mesh as direct cell data. Unlike the volume_fractions workflow, these attributes are not converted into a stochastic material assignment. Each element simply stores its sampled scalar value.

That means:

  • the exported fields remain smooth as long as the underlying field varies smoothly

  • mesh resolution still matters for how accurately the gradient is sampled

  • but resolution is no longer about representing a stochastic mixing pattern

OpenVCAD previews#

OpenVCAD preview — modulus

OpenVCAD preview of the modulus field used by the simulation compiler guide

OpenVCAD preview — poissons_ratio

OpenVCAD preview of the Poisson ratio field used by the simulation compiler guide

ParaView views of the exported cell fields#

ParaView — modulus

ParaView screenshot showing the exported modulus field from the simulation compiler

ParaView — poissons_ratio

ParaView screenshot showing the exported Poisson ratio field from the simulation compiler

Abaqus export from the same Lesson 2 beam#

The same Lesson 2 design can be exported to Abaqus by switching the backend and choosing a hexahedral mesh:

hex_settings = pvc.SimulationHexMeshSettings()
hex_settings.voxel_size = pv.Vec3(1.5, 1.5, 1.5)

abaqus_settings = pvc.SimulationCompilerSettings()
abaqus_settings.output_directory = "output"
abaqus_settings.file_prefix = "mechanical_hex"
abaqus_settings.backend = pvc.SimulationBackend.ABAQUS_INP
abaqus_settings.mesh_kind = pvc.SimulationMeshKind.HEX
abaqus_settings.random_seed = 7
abaqus_settings.direct_attributes = [
    pv.DefaultAttributes.MODULUS,
    pv.DefaultAttributes.POISSONS_RATIO,
]
abaqus_settings.hex_settings = hex_settings

pvc.SimulationCompiler(root, abaqus_settings).compile()

Think of the Abaqus path as the same mesh-and-attributes export idea written into .inp form instead of an XDMF/H5 bundle.

Lesson 3: Solving the exported beam in FEniCSx#

The script examples/compilers/simulation/03_fenicsx_load_exported_design.py is the full one-shot workflow. It loads a shared Lesson 3 beam definition, exports the FEniCSx XDMF/H5 bundle, reloads the exported cell-wise material fields inside DOLFINx, and solves a small-strain static cantilever problem.

Lesson 3 intentionally uses a different beam than Lesson 2. In this solved cantilever example, the left face stays stiff, the free right face becomes much softer, and poissons_ratio stays constant so the displacement trend is driven primarily by the graded modulus.

Install notes:

conda create -n fenicsx -c conda-forge fenics-dolfinx mpi4py h5py numpy
conda activate fenicsx

If you already have a working DOLFINx environment, h5py and numpy can also be installed with pip inside that environment.

OpenVCAD previews for the Lesson 3 beam#

The simulation script builds its beam from a shared helper before exporting it to FEniCSx. This preview shows the exact OpenVCAD modulus field used by the solve:

OpenVCAD preview — Lesson 3 modulus

OpenVCAD preview of the Lesson 3 modulus gradient used by the self-contained FEniCSx beam solve

You can read this preview as the mechanical setup for the solve: the modulus is highest at the fixed left face and drops steadily toward the free right face. That means the beam is progressively easier to deform as you move toward the tip, so we should expect larger displacements there once the load is applied.

The lesson-3 beam definition lives in examples/compilers/simulation/lesson3_beam_definition.py so the FEniCSx example in this lesson can import the same geometry and attributes:

def build_design():
    beam = pv.RectPrism(pv.Vec3(0, 0, 0), pv.Vec3(60.0, 12.0, 12.0))
    beam.set_attribute(
        pv.DefaultAttributes.MODULUS,
        pv.FloatAttribute("2400.0 - 2000.0 * clamp((x + 30.0) / 60.0, 0, 1)")
    )
    beam.set_attribute(
        pv.DefaultAttributes.POISSONS_RATIO,
        pv.FloatAttribute("0.28")
    )
    return beam

Governing equations#

The solve is the standard 3D isotropic linear-elastic form with a spatially varying modulus E(x) and constant Poisson ratio nu:

\[\varepsilon(u) = \mathrm{sym}(\nabla u)\]
\[\sigma(u) = 2\mu(x)\varepsilon(u) + \lambda(x)\,\mathrm{tr}(\varepsilon(u)) I\]

with Lame parameters reconstructed from the exported OpenVCAD fields:

\[\mu(x) = \frac{E(x)}{2(1 + \nu)} \qquad \lambda(x) = \frac{E(x)\nu}{(1 + \nu)(1 - 2\nu)}\]

The weak form is:

\[\int_{\Omega} \sigma(u) : \varepsilon(v)\,dx = \int_{\Gamma_{\mathrm{load}}} t \cdot v\,ds\]

with the left beam face fixed (u = 0) and a uniform end traction t = (0, 0, -5) applied on the right beam face. Because the beam gets softer toward the loaded end, the displacement magnitude ramps up more sharply than in a uniform cantilever and is easy to inspect in ParaView.

Because the exported tetrahedral surface is slightly perturbed from the exact analytic box, the script locates the left and right beam faces using a small 0.05 mm threshold around the mesh bounding box instead of relying on exact x == min/max comparisons.

Key implementation snippets#

The full script lives at examples/compilers/simulation/03_fenicsx_load_exported_design.py. The snippets below show the important stages without reproducing the whole file.

1. Export once on rank 0#

script_dir = os.path.dirname(os.path.abspath(__file__))
output_dir = os.path.join(script_dir, "output")

export_error = None
if comm.rank == 0:
    try:
        root = build_design()
        fenics_settings = pvc.SimulationCompilerSettings()
        fenics_settings.output_directory = output_dir
        fenics_settings.file_prefix = "simulation_results"
        fenics_settings.backend = pvc.SimulationBackend.FENICSX_XDMF
        fenics_settings.mesh_kind = pvc.SimulationMeshKind.TET
        fenics_settings.direct_attributes = [
            pv.DefaultAttributes.MODULUS,
            pv.DefaultAttributes.POISSONS_RATIO,
        ]
        pvc.SimulationCompiler(root, fenics_settings).compile()
    except Exception as exc:
        export_error = str(exc)

export_error = comm.bcast(export_error, root=0)
if export_error is not None:
    raise RuntimeError(f"OpenVCAD export failed on MPI rank 0: {export_error}")

2. Reload the exported cell fields with MPI-safe cell indexing#

The example uses beam_mesh.topology.original_cell_index so each MPI rank pulls the correct subset of the exported cell arrays back into its local DG0 storage.

with XDMFFile(comm, xdmf_path, "r") as xdmf:
    beam_mesh = xdmf.read_mesh(name="OpenVCADMesh")

cell_space = fem.functionspace(beam_mesh, ("DG", 0))
modulus = fem.Function(cell_space, name="modulus")
poissons_ratio = fem.Function(cell_space, name="poissons_ratio")

with h5py.File(h5_path, "r") as h5:
    modulus_data = np.asarray(h5["/CellData/modulus"])
    poissons_ratio_data = np.asarray(h5["/CellData/poissons_ratio"])

original_cell_index = np.asarray(beam_mesh.topology.original_cell_index, dtype=np.int64)
modulus.x.array[:] = modulus_data[original_cell_index]
poissons_ratio.x.array[:] = poissons_ratio_data[original_cell_index]

modulus.x.scatter_forward()
poissons_ratio.x.scatter_forward()

3. Solve and patch the exported file in place#

After reloading the DG0 fields, the script reconstructs the Lam’e parameters, solves the cantilever problem, evaluates DG0 von Mises stress, gathers the result arrays to rank 0, and updates the original OpenVCAD export in place. That means examples/compilers/simulation/output/simulation_results.xdmf keeps the same mesh but gains three new fields:

  • displacement as a node-centered vector field

  • displacement_magnitude as a node-centered scalar field

  • von_mises as a cell-centered scalar field

On rank 0 the example also prints five equal-length x bins with their mean displacement magnitude, which gives you a quick terminal-side check that the response increases from the fixed end to the soft tip.

Run the full one-shot workflow with the fenicsx environment active:

conda activate fenicsx
python examples/compilers/simulation/03_fenicsx_load_exported_design.py

ParaView inspection workflow#

  1. Open examples/compilers/simulation/output/simulation_results.xdmf

  2. Click Apply

  3. Switch the coloring dropdown between modulus, poissons_ratio, displacement_magnitude, and von_mises

  4. Use Warp By Vector with displacement if you want a deformed beam view

In the displacement-magnitude result, the figure should get brighter toward the right-hand tip, and the warped shape should bend more strongly there. That is the direct visual signature of the softer material: the fixed end stays comparatively stiff, while the lower-modulus tip accumulates more displacement under the same applied traction.

ParaView — displacement magnitude result

ParaView screenshot of the deformed cantilever beam colored by displacement magnitude

ParaView — von Mises stress result

ParaView screenshot of the cantilever beam colored by von Mises stress

Lesson 4: Generic in-memory models#

The script examples/compilers/simulation/04_generic_in_memory_model.py compiles the same graded bar to both HEX8 and TET4 without writing an intermediate file. Select GENERIC, call compile(), and then retrieve the prepared SimulationModel with model().

settings = pvc.SimulationCompilerSettings()
settings.backend = pvc.SimulationBackend.GENERIC
settings.mesh_kind = pvc.SimulationMeshKind.HEX

hex_settings = pvc.SimulationHexMeshSettings()
hex_settings.voxel_size = pv.Vec3(1.0, 1.0, 1.0)
settings.hex_settings = hex_settings

compiler = pvc.SimulationCompiler(root, settings)
compiler.compile()
model = compiler.model()

SimulationModel exposes:

  • cell_type: SimulationCellType.HEX8 or SimulationCellType.TET4

  • nodes_per_cell: 8 or 4

  • nodes: compact Vec3 coordinates

  • connectivity: flattened, zero-based node indices

  • cell_centroids: one Vec3 per element

  • material_ids and material_names

  • volume_fraction_fields and scalar_fields

Reshape connectivity conceptually into consecutive groups of nodes_per_cell. All cell fields align with that element order. The model is owned by its compiler, so keep the compiler alive while using the returned Python object. model() is available only after compiling with GENERIC, and written_files() is empty for that backend.

Lesson 5: LS-DYNA keyword export#

The LSDYNA_K backend writes <file_prefix>.k, an LS-DYNA keyword deck of the meshed design. It is a geometry-only export: nodes, solid elements, one part per material, placeholder elastic materials, and part sets. It does not write loads, boundary conditions, contact, or control cards; you add those in your own LS-DYNA model.

Verified with LS-DYNA R16.1, SMP double precision

Checked:

  • Input phase. Decks of tetrahedra (ELFORM 13, 10, 4, 60) and hexahedra (ELFORM 1, 2), with one and two materials, with and without void elements, and in long format (automatic and forced), read and initialise without errors.

  • What LS-DYNA reports matches the export. Node and element counts, the part, section and material IDs, ELFORM, the *MAT_ELASTIC values, and the part masses agree with the exported element volumes to 1e-6.

  • Short explicit run. With a test-only main deck that fixes the bottom, presses the top, and runs for 2 ms, the tetrahedral cube, the hexahedral cubes and the graded gyroid block of this lesson terminate normally. The energy ratio stays within 1.000 to 1.003, and hourglass energy on ELFORM 1 hexahedra stays below 0.01 % of the internal energy.

Not checked: real material models, contact, impact or test validation, single-precision builds, and MPP builds.

The script examples/compilers/simulation/05_lsdyna_graded_gyroid.py builds a 20 x 20 x 10 mm gyroid block. Its walls thicken along x, and its material blends from a soft polymer at the bottom to a stiff polymer at the top. The script exports the block as linear tetrahedra:

import os

import pyvcad as pv
import pyvcad_compilers as pvc
import pyvcad_metamaterials as mm
import pyvcad_rendering as viz

script_dir = os.path.dirname(os.path.abspath(__file__))

# The material table names the two parts. Its optional density (tonne/mm^3),
# modulus (MPa) and poissons_ratio entries fill the placeholder *MAT_ELASTIC
# cards; materials without them get the writer defaults.
materials = pv.MaterialDefs(os.path.join(script_dir, "lsdyna_materials.json"))

block_min = pv.Vec3(-10.0, -10.0, -5.0)
block_max = pv.Vec3(10.0, 10.0, 5.0)
cell_map = mm.rectangular_cell_map((block_min, block_max), cells=(2, 2, 1))

# Gyroid walls grow from 0.8 mm at x = -10 to 2.0 mm at x = +10.
wall_thickness = pv.FloatAttribute("0.8 + 1.2 * (x + 10.0) / 20.0")
gyroid = mm.gyroid(cell_map, wall_thickness=wall_thickness)

# Soft polymer at the bottom (z = -5), stiff polymer at the top (z = +5).
gyroid.set_attribute(
    pv.DefaultAttributes.VOLUME_FRACTIONS,
    pv.VolumeFractionsAttribute(
        [
            ("1 - clamp((z + 5.0) / 10.0, 0, 1)", materials.id("soft_polymer")),
            ("clamp((z + 5.0) / 10.0, 0, 1)", materials.id("stiff_polymer")),
        ]
    ),
)
root = gyroid

tet_settings = pvc.SimulationTetFixedMeshSettings()
tet_settings.facet_size = 0.6
tet_settings.facet_distance = 0.1
tet_settings.cell_size = 0.6

settings = pvc.SimulationCompilerSettings()
settings.output_directory = os.path.join(script_dir, "output")
settings.file_prefix = "graded_gyroid"
settings.backend = pvc.SimulationBackend.LSDYNA_K
settings.mesh_kind = pvc.SimulationMeshKind.TET
settings.tet_fixed_settings = tet_settings
settings.random_seed = 7
settings.material_defs = materials

# LS-DYNA options: tets are written as degenerate 8-node solids. ELFORM 13 is
# the default, but the two polymers have different bulk moduli and share
# nodes, which ELFORM 13 does not allow, so this deck gets
# mixed_material_tet_element_formulation (ELFORM 10). Void elements are
# dropped by default.
settings.lsdyna_settings.title = "OpenVCAD graded gyroid block"
settings.lsdyna_settings.tet_element_formulation = 13
settings.lsdyna_settings.mixed_material_tet_element_formulation = 10

compiler = pvc.SimulationCompiler(root, settings)
compiler.compile()
print("LS-DYNA deck:", compiler.written_files())
print("Nodes:", compiler.node_count(), "Elements:", compiler.element_count())

viz.Render(root, materials)

From the repository root, with the project virtual environment activated:

python examples/compilers/simulation/05_lsdyna_graded_gyroid.py

It writes examples/compilers/simulation/output/graded_gyroid.k, with about 39,000 tetrahedra in two parts. compiler.element_count() counts the whole mesh; the deck header states how many elements were written and how many void elements were left out.

OpenVCAD preview — volume_fractions

Gyroid block whose walls thicken along x, blending from an orange soft polymer at the bottom to a blue stiff polymer at the top

What the deck contains#

Keyword

Content

*KEYWORD, *TITLE

First card, then lsdyna_settings.title. A comment header states the units, the placeholder materials, the element formulation, the counts, and what was checked in LS-DYNA.

*PART

One per material. The heading is the material name.

*SECTION_SOLID

One per part, with the element formulation (ELFORM).

*MAT_ELASTIC

One placeholder elastic material per part (density, Young’s modulus, Poisson’s ratio).

*SET_PART_LIST_TITLE

One set per part, plus one set (all_parts) that holds every part, which is handy for single-surface contact.

*NODE, *ELEMENT_SOLID

The mesh.

*END

End of input.

Part i uses section i, material i, and part set i, so the IDs always match. The set with every part has the next ID after the last part.

Elements and formulations#

Tetrahedra (TET) are written as degenerate 8-node solids: nodes 5 to 8 repeat node 4, which is how *ELEMENT_SOLID takes 4-node tetrahedra.

  • ELFORM 13 (default, tet_element_formulation) is the 1-point tetrahedron with nodal pressure averaging. It resists volumetric locking, so it suits soft, nearly incompressible polymers.

  • ELFORM 13 averages pressures over all tetrahedra around a node. The LS-DYNA Keyword Manual (Vol. I, *SECTION_SOLID, remark 12) states that ELFORM 13 parts with different bulk moduli must not share nodes, and LS-DYNA prints warning 30490 for such decks. In a check with LS-DYNA R16.1, the graded gyroid block above developed negative internal energy within 0.2 ms with ELFORM 13, and its time step collapsed near 0.8 ms. With equal bulk moduli, or with ELFORM 10, it ran stably. The exporter therefore writes mixed_material_tet_element_formulation (default 10, the plain 1-point tetrahedron, which LS-DYNA’s warning suggests) when the parts’ bulk moduli E / (3 (1 - 2 nu)) differ and the parts share nodes. The deck header says so. Decks with one material, or with equal bulk moduli (for example the placeholder defaults), keep ELFORM 13.

  • ELFORM 10 has no pressure averaging, so it can lock with nearly incompressible materials. ELFORM 60 averages too and, unlike 13, allows shared nodes between different bulk moduli (remark 15; explicit analysis, still under development for implicit). In the same gyroid press, ELFORM 60 also ran stably. It needed about half the internal energy of ELFORM 10 for the same top displacement, a sign that ELFORM 10 locks with the poissons_ratio = 0.45 soft polymer, and it took about three times as long. For explicit runs of nearly incompressible graded materials, set mixed_material_tet_element_formulation = 60.

  • Any other tet_element_formulation is written as given. ELFORM 4, 10, 13 and 60 were checked with LS-DYNA R16.1.

  • ELFORM 16 and 17 are 10-node tetrahedra (remark 11). LS-DYNA stops with error 21299 when they are used on 4-node tetrahedra, so the exporter raises an error instead.

Hexahedra (HEX) are written natively (hex_element_formulation):

  • ELFORM 1 (default) is the constant-stress solid, with one integration point. Watch hourglass energy in long or large-deformation runs.

  • ELFORM 2 is the fully integrated solid.

  • Tetrahedron formulations (4, 10, 13, 60) and 20-node or higher-order formulations (23 to 29) raise an error, because LS-DYNA cannot use them on 8-node hexahedra.

Units#

Keyword decks store no units; they only have to be consistent. The exporter uses this set, which is stated in every deck header:

Quantity

Unit

Length

mm

Time

s

Mass

tonne (1000 kg)

Force

N

Stress, Young’s modulus

MPa (N/mm²)

Density

tonne/mm³ (1.2e-9 is 1200 kg/m³)

Energy

mJ (N·mm)

Velocity

mm/s

OpenVCAD node coordinates are in millimetres. If your main deck uses another consistent set, convert the material values, or scale the mesh, to match.

Placeholder materials and how to replace them#

The *MAT_ELASTIC cards are placeholders that keep the deck complete and let it initialise. For each material, the values come from its entry in material_defs when the entry has density (tonne/mm³), modulus (MPa), or poissons_ratio keys. Missing values use default_density (1e-9), default_modulus (100) and default_poissons_ratio (0.3). The example’s material table looks like this:

{
    "materials": [
        {"name": "soft_polymer", "r": 235, "g": 120, "b": 40, "a": 255,
         "density": 1.1e-9, "modulus": 30.0, "poissons_ratio": 0.45},
        {"name": "stiff_polymer", "r": 40, "g": 110, "b": 210, "a": 255,
         "density": 1.2e-9, "modulus": 1500.0, "poissons_ratio": 0.35}
    ]
}

To use real materials, replace each *MAT_ELASTIC card with your own material card (for example a foam or hyperelastic model) and keep the same material ID, which is the part ID. Every *PART already points at its material and section by that ID. If you change materials in your own deck rather than in the material table, check the ELFORM choice above: it was made from the placeholder bulk moduli.

Per-element direct_attributes are not written to the deck. LS-DYNA assigns materials per part, so graded properties need your own binning into parts.

Void elements and IDs#

Void elements. Elements whose sampled material is void (material ID 0, including boundary elements whose centroid sample has no material) are left out by default, together with nodes that only they use. Set include_void_elements = True to keep them as their own part (named void, with the placeholder material). The example drops 32 such boundary elements. Both variants were checked with LS-DYNA R16.1.

IDs. Node IDs are the node index + 1 and element IDs are the element index

  • 1, so they match the GENERIC model and the Abaqus export. Dropped void elements leave gaps, which LS-DYNA allows. node_id_offset, element_id_offset, and part_id_offset shift the IDs so the deck can be included in a larger model without clashes.

Large IDs. Standard keyword fields hold node and element IDs up to 99,999,999. If any ID is larger, the whole deck switches to long format (*KEYWORD LONG=Y, 20-column fields). Set long_format = True to force it. IDs above 2,147,483,647 are rejected with an error.

Limits#

  • Linear elements only: 4-node tetrahedra (as degenerate solids) and 8-node hexahedra. 10-node formulations are rejected.

  • One part per material, and at most 255 materials. Grading inside a material is not carried into the deck.

  • Placeholder *MAT_ELASTIC only. No loads, boundary conditions, contact, controls, or output requests.

  • Tetrahedral meshes can contain thin elements that set the explicit time step. The example block’s smallest step is about 3e-8 s with the placeholder stiff polymer. LS-DYNA lists the smallest steps under 100 smallest timesteps in d3hsp. Coarser meshing, or mass scaling in your own main deck, raises it.

Using the deck in an LS-DYNA model#

Keep the exported file unchanged and include it from your own main deck, which adds the analysis setup:

*KEYWORD
*TITLE
Drop test using the OpenVCAD gyroid block
*INCLUDE
graded_gyroid.k
$ ... your *CONTROL, *BOUNDARY, *LOAD, *CONTACT and output cards ...
*END

The exported file ends with *END, which ends an included file.

Checking a deck in LS-DYNA#

The exported deck runs on its own as an input check. Without *CONTROL_TERMINATION, LS-DYNA reads it, initialises every element, writes the model summary, and stops at time 0:

python examples/compilers/simulation/05_lsdyna_graded_gyroid.py
cd examples/compilers/simulation/output
<path to ls-dyna> i=graded_gyroid.k ncpu=1 memory=200m

Then look at the files LS-DYNA writes next to the deck:

  • messag and d3hsp end with N o r m a l    t e r m i n a t i o n, and messag has no *** Error lines. Warning 20006 (the d3plot output interval was reset) is expected for a geometry-only deck. Warning 30490 appears only when ELFORM 13 parts share nodes.

  • d3hsp lists number of nodal+scalar points and number of solid elements, which match Nodes: and Elements: in the deck header.

  • Each part block in d3hsp shows part id, section id and material id (all equal), material type 1 (*MAT_ELASTIC), and solid formulation (the ELFORM).

  • summary of mass in d3hsp gives the mass of each part, which is the part volume times its density.

An inverted or zero-volume element stops LS-DYNA in this input phase, so a normal termination also confirms the element orientation.

OpenVCAD includes this check as an opt-in test. It exports small cubes and the gyroid block, runs each deck alone, compares what LS-DYNA reports with the export, and runs the short explicit press through a test-only main deck that *INCLUDEs the export. It is skipped unless OPENVCAD_LSDYNA_EXE points at an LS-DYNA executable. Licensing comes from your usual LS-DYNA environment variables.

OPENVCAD_LSDYNA_EXE=/path/to/ls-dyna python -m pytest compilers/tests/python/test_simulation_lsdyna_solver.py -v

Checking a deck without LS-DYNA#

The Ansys PyDyna package reads keyword decks without a license:

pip install ansys-dyna-core
from ansys.dyna.core import Deck

deck = Deck()
with open("examples/compilers/simulation/output/graded_gyroid.k") as handle:
    result = deck.loads(handle.read())

print(result.get_summary() or "every keyword was recognised")
for keyword in deck.keywords:
    print(type(keyword).__name__)

PyDyna 0.12.1 reads every keyword this backend writes in standard format. For long-format decks it reads all of them except the *ELEMENT_SOLID fields, which it misreads (it cannot read its own long-format solids either). LS-DYNA itself reads them correctly.

LS-DYNA settings#

settings.lsdyna_settings is a SimulationLsDynaSettings object:

Setting

Default

Meaning

tet_element_formulation

13

*SECTION_SOLID ELFORM for tetrahedral meshes.

mixed_material_tet_element_formulation

10

ELFORM used instead of 13 when parts with different bulk moduli share nodes. Set it to 13 to keep 13.

hex_element_formulation

1

*SECTION_SOLID ELFORM for hexahedral meshes.

include_void_elements

False

Keep void elements as their own part.

long_format

False

Force *KEYWORD LONG=Y; chosen automatically for IDs above 99,999,999.

title

"OpenVCAD simulation export"

*TITLE text (up to 80 characters).

default_density

1e-9

Placeholder density in tonne/mm³.

default_modulus

100.0

Placeholder Young’s modulus in MPa.

default_poissons_ratio

0.3

Placeholder Poisson’s ratio.

node_id_offset

0

Added to every node ID.

element_id_offset

0

Added to every element ID.

part_id_offset

0

Added to every part, section, material, and part-set ID.

Practical settings reference#

Setting

Meaning

output_directory

Folder used by file backends; ignored by GENERIC.

file_prefix

Prefix used by file backends; ignored by GENERIC.

backend

Transport: GENERIC, FENICSX_XDMF, ABAQUS_INP, or LSDYNA_K.

mesh_kind

Element family: HEX or TET.

hex_settings.voxel_size

Regular hexahedral cell size in millimeters.

tet_fixed_settings.facet_size

Surface triangle size target for fixed tet meshing.

tet_fixed_settings.facet_distance

Surface approximation tolerance for fixed tet meshing.

tet_fixed_settings.cell_size

Interior tetrahedral size target.

random_seed

Seed used for deterministic tet generation and stochastic material assignment.

material_defs

Base material definitions used when exporting volume_fractions. LSDYNA_K also reads optional density, modulus, and poissons_ratio entries.

direct_attributes

List of scalar attributes to export directly as cell data.

lsdyna_settings

SimulationLsDynaSettings for the LSDYNA_K backend (see Lesson 5).

Further examples#

  • examples/compilers/simulation/01_volume_fractions_export.py — stochastic material assignment plus raw volume-fraction datasets

  • examples/compilers/simulation/02_direct_mechanical_properties_export.py — export-only direct scalar mechanical fields with poissons_ratio varying through z

  • examples/compilers/simulation/03_fenicsx_load_exported_design.py — self-contained DOLFINx/FEniCSx cantilever solve with a stiff-to-soft modulus gradient along x

  • examples/compilers/simulation/04_generic_in_memory_model.py — direct Python access to compact solver-neutral HEX8 and TET4 models

  • examples/compilers/simulation/05_lsdyna_graded_gyroid.py — geometry-only LS-DYNA keyword deck of a graded two-material gyroid block