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#

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.

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.

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.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