graintrace.construct_voronoi_mesh#

Reconstruct FF-HEDM microstructures via NEPER Voronoi tessellation (VoronoiMeshBuilder).

class graintrace.construct_voronoi_mesh.VoronoiMeshBuilder(input_csv, output_dir, bounding_box, dim=3, weighted=False, auto_fix_bbox=False, bbox_fix_mode=None, bbox_tolerance=0.0, auto_rotate=False, rotate_angles=(0, 0, 0), rotate_convention='xyz', angle_identifier=None, orientation_descriptor='euler-bunge', orientation_active_convention=False, unit='deg', elastic_strain_identifier=None, ori_rotmat_identifier=None, strain_unit='microstrain', env=None, neper_path=None, auto_install=False)[source]#

Bases: object

Reconstruct a 3D microstructure from far-field (FF) HEDM grain centroids.

Wraps NEPER (Voronoi/CVT tessellation) and optionally GMSH to turn a per-grain FF CSV (positions, Euler orientations, elastic strains) into a .tess/.msh mesh, per-grain orientation and initial elastic-strain files, and a voxelized reconstruction: the inputs for a CPFE run or a grain graph. See examples/demonstrate_farfield.py and the /ff-reconstruction skill.

check_dependencies(neper_path=None, auto_install=False)[source]#

Locate NEPER (user-installed) and build its subprocess environment.

gmsh ships with graintrace via pip, so no gmsh handling is needed here. Returns (neper_bin, env). Raises RuntimeError with install guidance when NEPER cannot be found and auto_install is False.

read_input()[source]#

Read/validate input CSV: spatial coords, optional GrainRadius, angles, strain.

rotate()[source]#

Align data to PCA principal axes (auto_rotate) or apply explicit xyz Euler rotation.

compute_principal_axes()[source]#

Compute PCA principal axes (2D/3D, right-handed). Returns (eigenvectors, eigenvalues).

plot_centroids(plot_box=True, save_path='centroid_plot.png')[source]#

Plot centroid data in three orthogonal views (XY, YZ, XZ).

remove_outside_points(bbox=None, tolerance=0.0)[source]#

Remove out-of-bounds points and their associated per-grain data from self.data.

validate_bounding_box()[source]#

Validate or correct the bounding box (remove_points or extend_bounding_box).

build_voronoi(option='voronoi', generate_mesh=False, relative_el_size=None, morphoalgo='praxis', mesh_quality_min=0.9, tesr_size=None, CVT_iter=1000)[source]#

Build a Voronoi (or Laguerre) tessellation using Neper.

Reads the input CSV (if not already loaded), validates/fixes the bounding box, runs NEPER to produce the tessellation, applies the rotation to the cell orientations and strains, evaluates the output, optionally meshes it, and writes the reformatted voxel reconstruction CSV/VTK plus the CPFE strain files.

Parameters:

  • option (str) – Tessellation morphology. “voronoi” seeds a Voronoi tessellation at the input coordinates (and applies the GrainRadius weights when weighted); “centroidal” seeds a CVT relaxation at them. “centroid” instead treats the coordinates as an optimization target – NEPER moves seeds until the cell centroids match them, starting from its own packing rather than from the data – and “centroidsize” targets centroid and size together (requires GrainRadius). Note “centroid” and “centroidal” are distinct NEPER morphologies, not aliases.

  • generate_mesh (bool) – If True, also generate a NEPER/GMSH tet (or tri) .msh mesh; this is a fallback only, the default CPFE mesh is SCULPT hex.

  • relative_el_size (float) – Mesh element size relative to grain size, passed to generate_mesh; defaults to 1.0 when None.

  • morphoalgo (str) – NEPER morphology optimization algorithm, e.g. “praxis”, “subplex”, or “lloyd”.

  • mesh_quality_min (float) – Minimum acceptable mesh element quality, passed to generate_mesh.

  • tesr_size (list) – Voxel raster resolution [nx, ny, nz] for the .tesr output; defaults to [20, 20, 20] when None.

  • CVT_iter (int) – Number of CVT/morphology optimization iterations.

build_graph(device='cpu', option='centroid', CVT_iter=100, morphoalgo='praxis', visualize2D=False, visualize3D=False)[source]#

Build a Voronoi tessellation and convert it to a graph representation.

Runs build_voronoi (no mesh) then parses the resulting .tess into a per-cell graph via NeperTessToGraphNN, registering the loaded dataframe features on it.

Parameters:

  • device (str) – Torch device for the graph tensors, e.g. “cpu” or “cuda”.

  • option (str) – Tessellation seeding mode passed to build_voronoi: “voronoi”, “centroid”, or “centroidsize”.

  • CVT_iter (int) – Number of CVT/morphology optimization iterations passed to build_voronoi.

  • morphoalgo (str) – NEPER morphology optimization algorithm passed to build_voronoi.

  • visualize2D (bool) – If True, save a 2D rendering of the graph under output_dir/figures/gnn.

  • visualize3D (bool) – If True, save a 3D rendering of the graph under output_dir/figures/gnn.

Returns:

The per-cell graph object produced by NeperTessToGraphNN.build_cell_graph.

apply_rotation_to_properties(tess_file)[source]#

Apply the rotation matrix to cell orientations (and strains) in the .tess file.

Parameters:

tess_file (str)

generate_mesh(tess_file, output_name='voronoi', format_type=('msh4',), relative_cl=1.0, mesh_quality_min=0.9, interface_type='continuous', partition=16)[source]#

Generate an FE mesh from a Neper .tess (tri for 2D, tet for 3D, 2nd order).

Parameters:

  • tess_file (str)

  • output_name (str)

  • relative_cl (float)

  • mesh_quality_min (float)

  • interface_type (str)

  • partition (int)

export_cell_properties(tess_file, output_cell='id,vol,w,x,y,z,radeq', output_seed='id,w,x,y,z')[source]#

Compute Neper cell/seed stats, merge them, and export CPFE strain files.

Parameters:

tess_file (str)

evaluate_output_voronoi(tess_file, length_norm=False)[source]#

Evaluate Neper Voronoi output: compare cell vs seed props, save figures.

Parameters:

  • tess_file (str)

  • length_norm (bool)

reformat_tesr_file(tesr_file, orientation_file)[source]#

Output CSV columns: X, Y, Z, CellID, Eul0, Eul1, Eul2

Parameters:

  • tesr_file (str)

  • orientation_file (str)