`ParametricStudy`#

class ansys.additive.core.parametric_study.parametric_study.ParametricStudy(file_name: str | os.PathLike, material_name: str)#: Provides data storage and utility methods for a parametric study.

Overview#

Methods

`import_csv_study`	Import a parametric study from a CSV file.
`data_frame`	Return a `DataFrame` containing the study simulations.
`save`	Save the parametric study to a file.
`reset_simulation_status`	Reset the status of any `Pending` or `Running` simulations to `New`.
`clear_errors`	Clear the error messages for the specified simulations.
`add_summaries`	Add summaries of executed simulations to the parametric study.
`generate_single_bead_permutations`	Add single bead permutations to the parametric study.
`generate_porosity_permutations`	Add porosity permutations to the parametric study.
`generate_microstructure_permutations`	Add microstructure permutations to the parametric study.
`update`	Update the results of simulations in the parametric study.
`add_inputs`	Add new simulations to the parametric study.
`remove`	Remove simulations from the parametric study.
`set_simulation_status`	Set the status of simulations in the parametric study.
`set_priority`	Set the priority of simulations in the parametric study.
`set_iteration`	Set the iteration number of simulations in the parametric study.
`clear`	Remove all permutations from the parametric study.
`simulation_inputs`	Get a list of simulation inputs from the parametric study.
`filter_data_frame`	Apply filters to the parametric study and return the filtered data frame.

Properties

`format_version`	Version of the parametric study file format.
`file_name`	Name of the file where the parametric study is stored.
`material_name`	Name of material used in the parametric study.

Static methods

`load`	Load a parametric study from a file.
`update_format`	Update a parametric study to the latest format version.

Import detail#

from ansys.additive.core.parametric_study.parametric_study import ParametricStudy

Property detail#

property ParametricStudy.format_version: int#: Version of the parametric study file format.

property ParametricStudy.file_name: os.PathLike#: Name of the file where the parametric study is stored.

property ParametricStudy.material_name: str | None#: Name of material used in the parametric study.

Method detail#

ParametricStudy.import_csv_study(file_name: str | os.PathLike) → list[str]#

Import a parametric study from a CSV file.

Parameters:

file_name: str, os.PathLike: Name of the csv file containing the simulation parameters.
For the column names used in the returned data frame, see
the :class:`ColumnNames ` class.

Returns:

list[str]: List of error messages of any simulations that have invalid input parameters.

ParametricStudy.data_frame() → pandas.DataFrame#

Return a DataFrame containing the study simulations.

For the column names used in the returned data frame, see the ColumnNames class.

Note

Updating the returned data frame does not update this parametric study.

ParametricStudy.save(file_name: str | os.PathLike)#

Save the parametric study to a file.

Parameters:

file_namestr, os.PathLike: Name of the file to save the parametric study to.

static ParametricStudy.load(file_name: str | os.PathLike) → ParametricStudy#

Load a parametric study from a file.

Parameters:

file_namestr, os.PathLike: Name of the parametric study file to load. This file is overwritten when the parametric study is updated. To prevent this behavior, update the file_name attribute of the returned parametric study after calling load().

Returns:

ParametricStudy: Loaded parametric study.

ParametricStudy.reset_simulation_status()#: Reset the status of any Pending or Running simulations to New.

ParametricStudy.clear_errors(simulation_ids: list[str] | None = None)#

Clear the error messages for the specified simulations.

Parameters:

simulation_idslist[str], default: None: List of simulation IDs to clear the error messages for. If this value is None, all error messages are cleared.

ParametricStudy.add_summaries(summaries: list[ansys.additive.core.single_bead.SingleBeadSummary | ansys.additive.core.porosity.PorositySummary | ansys.additive.core.microstructure.MicrostructureSummary], iteration: int = DEFAULT_ITERATION) → int#

Add summaries of executed simulations to the parametric study.

Simulation summaries are created using the Additive.simulate() method. This method adds new simulations to the parametric study. To update existing simulations, use the update() method.

A summary that matches an existing simulation will overwrite the results for that simulation.

Parameters:

summarieslist[SingleBeadSummary, PorositySummary, MicrostructureSummary]: List of simulation result summaries to add to the parametric study.
iterationint, default: DEFAULT_ITERATION: Iteration number for the new simulations.

Returns:

int: Number of new simulations added to the parametric study.

ParametricStudy.generate_single_bead_permutations(laser_powers: list[float], scan_speeds: list[float], bead_length: float = SingleBeadInput.DEFAULT_BEAD_LENGTH, layer_thicknesses: list[float] | None = None, heater_temperatures: list[float] | None = None, beam_diameters: list[float] | None = None, min_pv_ratio: float | None = None, max_pv_ratio: float | None = None, iteration: int = DEFAULT_ITERATION, priority: int = DEFAULT_PRIORITY) → int#

Add single bead permutations to the parametric study.

Parameters:

laser_powerslist[float]: Laser powers (W) to use for single bead simulations. Valid values are from MIN_LASER_POWER to MAX_LASER_POWER.
scan_speedslist[float]: Scan speeds (m/s) to use for single bead simulations. Valid values are from MIN_SCAN_SPEED to MAX_SCAN_SPEED.
bead_lengthfloat, default: DEFAULT_BEAD_LENGTH: Length of the bead (m). Valid values are from MIN_BEAD_LENGTH to MAX_BEAD_LENGTH.
layer_thicknesseslist[float], default: None: Layer thicknesses (m) to use for single bead simulations. If this value is None, DEFAULT_LAYER_THICKNESS is used. Valid values are from MIN_LAYER_THICKNESS to MAX_LAYER_THICKNESS.
heater_temperatureslist[float], default: None: Heater temperatures (C) to use for single bead simulations. If this value is None, DEFAULT_HEATER_TEMP is used. Valid values are from MIN_HEATER_TEMP to MAX_HEATER_TEMP.
beam_diameterslist[float], default: None: Beam diameters (m) to use for single bead simulations. If this value is None, DEFAULT_BEAM_DIAMETER is used. Valid values are from MIN_BEAM_DIAMETER to MAX_BEAM_DIAMETER.
min_pv_ratiofloat, default: None: The P/V ratio is defined as the ratio of laser power (w) to the velocity of the laser beam, which is the scan speed (m/s). Parameter combinations with ratios less than this value are not included.
max_pv_ratiofloat, default: None: The P/V ratio is defined as the ratio of laser power (w) to the velocity of the laser beam, which is the scan speed (m/s). Parameter combinations with ratios greater than this value are not included.
iterationint, default: DEFAULT_ITERATION: Iteration number for this set of simulations.
priorityint, default: DEFAULT_PRIORITY: Priority for this set of simulations.

Returns:

int: Number of single bead permutations added to the parametric study.

ParametricStudy.generate_porosity_permutations(laser_powers: list[float], scan_speeds: list[float], size_x: float = PorosityInput.DEFAULT_SAMPLE_SIZE, size_y: float = PorosityInput.DEFAULT_SAMPLE_SIZE, size_z: float = PorosityInput.DEFAULT_SAMPLE_SIZE, layer_thicknesses: list[float] | None = None, heater_temperatures: list[float] | None = None, beam_diameters: list[float] | None = None, start_angles: list[float] | None = None, rotation_angles: list[float] | None = None, hatch_spacings: list[float] | None = None, stripe_widths: list[float] | None = None, min_energy_density: float | None = None, max_energy_density: float | None = None, min_build_rate: float | None = None, max_build_rate: float | None = None, iteration: int = DEFAULT_ITERATION, priority: int = DEFAULT_PRIORITY) → int#

Add porosity permutations to the parametric study.

Parameters:

laser_powerslist[float]: Laser powers (W) to use for porosity simulations. Valid values are from MIN_LASER_POWER to MAX_LASER_POWER.
scan_speedslist[float]: Scan speeds (m/s) to use for porosity simulations. Valid values are from MIN_SCAN_SPEED to MAX_SCAN_SPEED.
size_xfloat, default: DEFAULT_SAMPLE_SIZE: Size (m) of the porosity sample in the x direction. Valid values are from MIN_SAMPLE_SIZE to MAX_SAMPLE_SIZE.
size_yfloat, DEFAULT_SAMPLE_SIZE: Size (m) of the porosity sample in the y direction. Valid values are from MIN_SAMPLE_SIZE to MAX_SAMPLE_SIZE.
size_zfloat, DEFAULT_SAMPLE_SIZE: Size (m) of the porosity sample in the z direction. Valid values are from MIN_SAMPLE_SIZE to MAX_SAMPLE_SIZE.
layer_thicknesseslist[float], default: None: Layer thicknesses (m) to use for porosity simulations. If this value is None, DEFAULT_LAYER_THICKNESS is used. Valid values are from MIN_LAYER_THICKNESS to MAX_LAYER_THICKNESS.
heater_temperatureslist[float], default: None: Heater temperatures (C) to use for porosity simulations. If this value is None, DEFAULT_HEATER_TEMP is used. Valid values are from MIN_HEATER_TEMP to MAX_HEATER_TEMP.
beam_diameterslist[float], default: None: Beam diameters (m) to use for porosity simulations. If this value is None, DEFAULT_BEAM_DIAMETER is used. Valid values are from MIN_BEAM_DIAMETER to MAX_BEAM_DIAMETER.
start_angleslist[float], default: None: Scan angles (deg) for the first layer to use for porosity simulations. If this value is None, DEFAULT_STARTING_LAYER_ANGLE is used. Valid values are from MIN_STARTING_LAYER_ANGLE to MAX_STARTING_LAYER_ANGLE.
rotation_angleslist[float], default: None: Angles (deg) by which the scan direction is rotated with each layer to use for porosity simulations. If this value is None, DEFAULT_LAYER_ROTATION_ANGLE is used. Valid values are from MIN_LAYER_ROTATION_ANGLE to MAX_LAYER_ROTATION_ANGLE.
hatch_spacingslist[float], default: None: Hatch spacings (m) to use for porosity simulations. If this value is None, DEFAULT_HATCH_SPACING is used. Valid values are from MIN_HATCH_SPACING to MAX_HATCH_SPACING.
stripe_widthslist[float], default: None: Stripe widths (m) to use for porosity simulations. If this value is None, DEFAULT_SLICING_STRIPE_WIDTH is used. Valid values are from MIN_SLICING_STRIPE_WIDTH to MAX_SLICING_STRIPE_WIDTH.
min_energy_densityfloat, default: None: Minimum energy density (J/m^3) to use for porosity simulations. Energy density is defined as laser power / (layer thickness * scan speed * hatch spacing). Parameter combinations with an energy density below this value are not included.
max_energy_densityfloat, default: None: Maximum energy density (J/m^3) to use for porosity simulations. Energy density is defined as laser power / (layer thickness * scan speed * hatch spacing). Parameter combinations with an energy density above this value are not included.
min_build_ratefloat, default: None: Minimum build rate (m^3/s) to use for porosity simulations. Parameter combinations with a build rate below this value are not included. Build rate is defined as layer thickness * scan speed * hatch spacing.
max_build_ratefloat, default: None: Maximum build rate (m^3/s) to use for porosity simulations. Parameter combinations with a build rate above this value are not included. Build rate is defined as layer thickness * scan speed * hatch spacing.
iterationint, default: DEFAULT_ITERATION: Iteration number for this set of simulations.
priorityint, default: DEFAULT_PRIORITY: Priority for this set of simulations.

Returns:

int: Number of porosity permutations added to the parametric study.

ParametricStudy.generate_microstructure_permutations(laser_powers: list[float], scan_speeds: list[float], min_x: float = MicrostructureInput.DEFAULT_POSITION_COORDINATE, min_y: float = MicrostructureInput.DEFAULT_POSITION_COORDINATE, min_z: float = MicrostructureInput.DEFAULT_POSITION_COORDINATE, size_x: float = MicrostructureInput.DEFAULT_SAMPLE_SIZE, size_y: float = MicrostructureInput.DEFAULT_SAMPLE_SIZE, size_z: float = MicrostructureInput.DEFAULT_SAMPLE_SIZE, sensor_dimension: float = MicrostructureInput.DEFAULT_SENSOR_DIMENSION, layer_thicknesses: list[float] | None = None, heater_temperatures: list[float] | None = None, beam_diameters: list[float] | None = None, start_angles: list[float] | None = None, rotation_angles: list[float] | None = None, hatch_spacings: list[float] | None = None, stripe_widths: list[float] | None = None, min_energy_density: float | None = None, max_energy_density: float | None = None, min_build_rate: float | None = None, max_build_rate: float | None = None, cooling_rate: float | None = None, thermal_gradient: float | None = None, melt_pool_width: float | None = None, melt_pool_depth: float | None = None, random_seed: int | None = None, iteration: int = DEFAULT_ITERATION, priority: int = DEFAULT_PRIORITY) → int#

Add microstructure permutations to the parametric study.

Parameters:

laser_powerslist[float]: Laser powers (W) to use for microstructure simulations. Valid values are from MIN_LASER_POWER to MAX_LASER_POWER.
scan_speedslist[float]: Scan speeds (m/s) to use for microstructure simulations. Valid values are from MIN_SCAN_SPEED to MAX_SCAN_SPEED.
min_xfloat, default: DEFAULT_POSITION_COORDINATE: Minimum x coordinate (m) of the microstructure sample. Valid values are from MIN_POSITION_COORDINATE to MAX_POSITION_COORDINATE.
min_yfloat, default: DEFAULT_POSITION_COORDINATE: Minimum y coordinate (m) of the microstructure sample. Valid values are from MIN_POSITION_COORDINATE to MAX_POSITION_COORDINATE.
min_zfloat, default: DEFAULT_POSITION_COORDINATE: Minimum z coordinate (m) of the microstructure sample. Valid values are from MIN_POSITION_COORDINATE to MAX_POSITION_COORDINATE.
size_xfloat, default: DEFAULT_SAMPLE_SIZE: Size (m) of the microstructure sample in the x direction. Valid values are from MIN_SAMPLE_SIZE to MAX_SAMPLE_SIZE.
size_yfloat, default: DEFAULT_SAMPLE_SIZE: Size (m) of the microstructure sample in the y direction. Valid values are from MIN_SAMPLE_SIZE to MAX_SAMPLE_SIZE.
size_zfloat, default: DEFAULT_SAMPLE_SIZE: Size (m) of the microstructure sample in the z direction. Valid values are from MIN_SAMPLE_SIZE to MAX_SAMPLE_SIZE.
sensor_dimensionfloat, default: DEFAULT_SENSOR_DIMENSION: Sensor dimension (m) to use for microstructure simulations. Valid values are from MIN_SENSOR_DIMENSION to MAX_SENSOR_DIMENSION. The values for the size_x and size_y parameters must be greater than the sensor_dimension parameter by MIN_XY_SIZE_CUSHION meters. The value for the size_z parameter must be greater than sensor_dimension parameter by MIN_Z_SIZE_CUSHION meters.
layer_thicknesseslist[float], default: None: Layer thicknesses (m) to use for microstructure simulations. If this value is None, DEFAULT_LAYER_THICKNESS is used. Valid values are from MIN_LAYER_THICKNESS to MAX_LAYER_THICKNESS.
heater_temperatureslist[float], default: None: Heater temperatures (C) to use for microstructure simulations. If this value is None, DEFAULT_HEATER_TEMP is used. Valid values are from MIN_HEATER_TEMP to MAX_HEATER_TEMP.
beam_diameterslist[float], default: None: Beam diameters (m) to use for microstructure simulations. If this value is None, DEFAULT_BEAM_DIAMETER is used. Valid values are from MIN_BEAM_DIAMETER to MAX_BEAM_DIAMETER.
start_angleslist[float], default: None: Scan angles (deg) for the first layer to use for microstructure simulations. If this value is None, DEFAULT_STARTING_LAYER_ANGLE is used. Valid values are from MIN_STARTING_LAYER_ANGLE to MAX_STARTING_LAYER_ANGLE.
rotation_angleslist[float], default: None: Angles (deg) by which the scan direction is rotated with each layer to use for microstructure simulations. If this value is None, DEFAULT_LAYER_ROTATION_ANGLE is used. Valid values are from MIN_LAYER_ROTATION_ANGLE to MAX_LAYER_ROTATION_ANGLE.
hatch_spacingslist[float], default: None: Hatch spacings (m) to use for microstructure simulations. If this value is None, DEFAULT_HATCH_SPACING is used. Valid values are from MIN_HATCH_SPACING to MAX_HATCH_SPACING.
stripe_widthslist[float], default: None: Stripe widths (m) to use for microstructure simulations. If this value is None, DEFAULT_SLICING_STRIPE_WIDTH is used. Valid values are from MIN_SLICING_STRIPE_WIDTH to MAX_SLICING_STRIPE_WIDTH.
min_energy_densityfloat, default: None: Minimum energy density (J/m^3) to use for microstructure simulations. Energy density is defined as laser power / (layer thickness * scan speed * hatch spacing). Parameter combinations with an energy density below this value are not included.
max_energy_densityfloat, default: None: Maximum energy density (J/m^3) to use for microstructure simulations. Energy density is defined as laser power / (layer thickness * scan speed * hatch spacing). Parameter combinations with an energy density above this value are not included.
min_build_ratefloat, default: None: The minimum build rate (m^3/s) to use for microstructure simulations. Parameter combinations with a build rate below this value will not be included. Build rate is defined as layer thickness * scan speed * hatch spacing.
max_build_ratefloat, default: None: The maximum build rate (m^3/s) to use for microstructure simulations. Parameter combinations with a build rate above this value will not be included. Build rate is defined as layer thickness * scan speed * hatch spacing.
cooling_ratefloat, default: None: The cooling rate (K/s) to use for microstructure simulations. If this value is None, and thermal_gradient, melt_pool_width, and melt_pool_depth are None, the cooling rate is calculated. If None and any of the other three parameters are not None, DEFAULT_COOLING_RATE is used. Valid values are from MIN_COOLING_RATE to MAX_COOLING_RATE.
thermal_gradientfloat, default: None: Thermal gradient (K/m) to use for microstructure simulations. If this value is None, and cooling_rate, melt_pool_width, and melt_pool_depth are None, the thermal gradient is calculated. If this value is None and any of the other three parameters are not None, DEFAULT_THERMAL_GRADIENT is used. Valid values are from MIN_THERMAL_GRADIENT to MAX_THERMAL_GRADIENT.
melt_pool_widthfloat, default: None: Melt pool width (m) to use for microstructure simulations. If this value is None and cooling_rate, thermal_gradient, and melt_pool_depth are None, the melt pool is calculated. If this value is None and any of the other three parameters are not None, DEFAULT_MELT_POOL_WIDTH is used. Valid values are from MIN_MELT_POOL_WIDTH to MAX_MELT_POOL_WIDTH.
melt_pool_depthfloat, default: None: Melt pool depth (m) to use for microstructure simulations. If this value is None, and cooling_rate, thermal_gradient, and melt_pool_width are None, the melt pool depth is calculated. If this value is None and any of the other three parameters are not None, DEFAULT_MELT_POOL_DEPTH is used. Valid values are from MIN_MELT_POOL_DEPTH to MAX_MELT_POOL_DEPTH.
random_seedint, default: None: The random seed to use for microstructure simulations. If this value is None, an automatically generated random seed is used. Valid values are from MIN_RANDOM_SEED to MAX_RANDOM_SEED.
iterationint, default: DEFAULT_ITERATION: Iteration number for this set of simulations.
priorityint, default: DEFAULT_PRIORITY: Priority for this set of simulations.

Returns:

int: Number of microstructure permutations added to the parametric study.

ParametricStudy.update(summaries: list[ansys.additive.core.single_bead.SingleBeadSummary | ansys.additive.core.porosity.PorositySummary | ansys.additive.core.microstructure.MicrostructureSummary | ansys.additive.core.simulation_error.SimulationError])#

Update the results of simulations in the parametric study.

This method updates values for existing simulations in the parametric study. To add completed simulations, use the add_summaries() method instead.

Parameters:

summarieslist[SingleBeadSummary, PorositySummary, MicrostructureSummary, SimulationError]: List of simulation summaries to use for updating the parametric study.

ParametricStudy.add_inputs(inputs: list[ansys.additive.core.single_bead.SingleBeadInput | ansys.additive.core.porosity.PorosityInput | ansys.additive.core.microstructure.MicrostructureInput], iteration: int = DEFAULT_ITERATION, priority: int = DEFAULT_PRIORITY, status: ansys.additive.core.simulation.SimulationStatus = SimulationStatus.NEW) → int#

Add new simulations to the parametric study.

If the input matches an existing simulation, the input will be ignored.

Parameters:

inputslist[SingleBeadInput, PorosityInput, MicrostructureInput]: List of simulation inputs to add to the parametric study.
iterationint, default: DEFAULT_ITERATION: Iteration number for the simulation inputs.
priorityint, default: DEFAULT_PRIORITY: Priority for the simulations.
statusSimulationStatus, default: SimulationStatus.NEW: Valid types are SimulationStatus.NEW and SimulationStatus.SKIP.

Returns:

int: The number of simulations added to the parametric study.

ParametricStudy.remove(ids: str | list[str])#

Remove simulations from the parametric study.

Parameters:

idsstr, list[str]: One or more ID values for the simulations to remove.

ParametricStudy.set_simulation_status(ids: str | list[str], status: ansys.additive.core.simulation.SimulationStatus, err_msg: str = '')#

Set the status of simulations in the parametric study.

Parameters:

idsstr, list[str]: One or more IDs of the simulations to update.
statusSimulationStatus: Status for the simulations.
err_msgstr, default: “”: Error message for the simulations. Only used if status is SimulationStatus.ERROR.

ParametricStudy.set_priority(ids: str | list[str], priority: int)#

Set the priority of simulations in the parametric study.

Parameters:

idsstr, list[str]: One or more IDs of the simulations to update.
priorityint: Priority for the simulations.

ParametricStudy.set_iteration(ids: str | list[str], iteration: int)#

Set the iteration number of simulations in the parametric study.

The iteration number is used to track the evolution of a design of experiments. Its use is optional.

Parameters:

idsstr, list[str]: One or more IDs of the simulations to update.
iterationint: Iteration for the simulations.

ParametricStudy.clear()#: Remove all permutations from the parametric study.

static ParametricStudy.update_format(study: ParametricStudy) → ParametricStudy#

Update a parametric study to the latest format version.

Parameters:

studyParametricStudy: Parametric study to update.

Returns:

ParametricStudy: Updated parametric study.

ParametricStudy.simulation_inputs(get_material_func: Callable[[str], ansys.additive.core.material.AdditiveMaterial], simulation_ids: list[str] = None, types: list[ansys.additive.core.simulation.SimulationType] = None, priority: int = None, iteration: int = None) → list[ansys.additive.core.single_bead.SingleBeadInput | ansys.additive.core.porosity.PorosityInput | ansys.additive.core.microstructure.MicrostructureInput]#

Get a list of simulation inputs from the parametric study.

Parameters:

get_material_func: Callable[[str], AdditiveMaterial]: Function to get the material object from the material name. This can be a call to the Additive server or another source.
simulation_idslist[str], default: None: List of simulation IDs to run. If this value is None, all simulations with a status of New are run.
typeslist[SimulationType], default: None: Type of simulations to run. If this value is None, all simulation types are run.
priorityint, default: None: Priority of simulations to run. If this value is None, all priorities are run.
iterationint, default: None: Iteration number of simulations to run. The default is None, all iterations are run.

Returns:

list[SingleBeadInput, PorosityInput, MicrostructureInput]: List of simulation inputs.

ParametricStudy.filter_data_frame(simulation_ids: list[str] = None, types: list[ansys.additive.core.simulation.SimulationType] = None, priority: int = None, iteration: int = None) → pandas.DataFrame#

Apply filters to the parametric study and return the filtered data frame.

Parameters:

simulation_ids: list[str], default: None: List of simulation IDs to include. The default is None, in which case all simulations with status of SimulationStatus.NEW are selected.
typeslist, default: None: List of simulation types to include. The default is None, in which case all simulation types are selected.
priorityint, default: None: Priority of simulations to include. The default is None, in which case all priorities are selected.
iterationint, default: None: Iteration number of simulations to include. The default is None, in which case all iterations are selected.

Returns:

pd.DataFrame: Filtered view of the parametric study data frame