graintrace.generate_random_crystal

Generate synthetic crystal tessellations with NEPER and simulate HEDM z-scans.

class graintrace.generate_random_crystal.CrystalGenerator(output_dir, bounding_box, dim=3, seed=None, env=None, neper_path=None, auto_install=False)

Bases: object

Build NEPER Voronoi tessellations and derive HEDM-like scan CSVs from them.

generate_tessellation(morpho_args, iterations=10, extra_neper_args=None)

Run neper -T. extra_neper_args are appended verbatim (e.g. [‘-reg’,’1’]).

Parameters:

• morpho_args (Dict[str, Any])

• iterations (int)

• extra_neper_args (List[str] | None)

Return type:

None

hedm_zscan(tess_file, nstep, overlap_percentage, output_hedm='hedm_scan', verbose=False, position_noise_std=0.0, orientation_noise_std=0.0, radius_noise=0.0, noise_seed=None, remove_minimum_volume=False, min_vol=0.0)

Generate overlapping z-direction tessellation cuts to simulate HEDM scans.

nstep slices span the domain z-extent; overlap_percentage (0-100) sets the overlap between adjacent scans; output_hedm is the output subfolder name.

Per-scan measurement error is forwarded to write_to_csv: position_noise_std (absolute length units), orientation_noise_std (degrees, proper misorientation), radius_noise (relative fraction); noise_seed for reproducibility.

Parameters:

• tess_file (str)

• nstep (int)

• overlap_percentage (float)

• output_hedm (str)

• verbose (bool)

• position_noise_std (float)

• orientation_noise_std (float)

• radius_noise (float)

• noise_seed (int | None)

• remove_minimum_volume (bool)

• min_vol (float)

check_dependencies(neper_path=None, auto_install=False)

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

Returns (neper_bin, env). Raises RuntimeError with install guidance when NEPER cannot be found and auto_install is False.

static write_to_csv(stat_file, ori_file, output_csv, verbose=True, position_noise_std=0.0, orientation_noise_std=0.0, radius_noise=0.0, noise_seed=None, remove_minimum_volume=False, min_vol=0.0)

Combine Neper .stcell (geometry) and .ori (orientation) into one CSV mimicking HEDM APS output (columns X, Y, Z, GrainRadius, Eul0, Eul1, Eul2).

Measurement error is injected per property, each applied only when its value is > 0 (all-zero gives a noiseless result):

• position_noise_std: additive absolute Gaussian on X, Y, Z, in the data’s physical length units (micrometers), isotropic and origin-independent.

• orientation_noise_std: proper random misorientation of this angular std (degrees), applied via orientation_helper.perturb_orientation.

• radius_noise: relative (fractional) Gaussian std on GrainRadius.

noise_seed makes the noise reproducible (None uses global np.random); remove_minimum_volume drops grains below min_vol.

Parameters:

• stat_file (str)

• ori_file (str)

• output_csv (str)

• verbose (bool)

• position_noise_std (float)

• orientation_noise_std (float)

• radius_noise (float)

• noise_seed (int | None)

• remove_minimum_volume (bool)

• min_vol (float)

static crop_tessellation(tess_name, bounding_box=None, seed=12345, zlo=0.0, zhi=1.0, dim=3, output_dir='.', out_name='tess_cropped', env=None, neper_bin='neper', verbose=True)

Crop an existing .tess file along z between zmin and zmax.

Parameters:

• tess_name (str)

• seed (int)

• zlo (float)

• zhi (float)

• dim (int)

• output_dir (str)

• out_name (str)

• env (dict | None)

• neper_bin (str)

• verbose (bool)

static show_morpho_options(exit_after=False)

Display available morphology configurations and supported distributions.

Parameters:

exit_after (bool)

Return type:

None

static validate_morpho(morpho)

Validate morphology dictionary against schema.

Parameters:

morpho (Dict[str, Any])

Return type:

None

static validate_distribution(dist_name, params)

Validate distribution name and its parameter count.

Parameters:

• dist_name (str)

• params (Any)

Return type:

None