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 a parametric study from a CSV file. |
|
Return a |
|
Save the parametric study to a file. |
|
Reset the status of any |
|
Clear the error messages for the specified simulations. |
|
Add summaries of executed simulations to the parametric study. |
|
Add single bead permutations to the parametric study. |
|
Add porosity permutations to the parametric study. |
|
Add microstructure permutations to the parametric study. |
|
Update the results of simulations in the parametric study. |
|
Add new simulations to the parametric study. |
|
Remove simulations from the parametric study. |
|
Set the status of simulations in the parametric study. |
|
Set the priority of simulations in the parametric study. |
|
Set the iteration number of simulations in the parametric study. |
|
Remove all permutations from the parametric study. |
|
Get a list of simulation inputs from the parametric study. |
|
Apply filters to the parametric study and return the filtered data frame. |
Version of the parametric study file format. |
|
Name of the file where the parametric study is stored. |
|
Name of material used in the parametric study. |
Load a parametric study from a file. |
|
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.file_name: os.PathLike#
Name of the file where the parametric study is stored.
Method detail#
- ParametricStudy.import_csv_study(file_name: str | os.PathLike) list[str] #
Import a parametric study from a CSV file.
- 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_name
str
,os.PathLike
Name of the file to save the parametric study to.
- file_name
- static ParametricStudy.load(file_name: str | os.PathLike) ParametricStudy #
Load a parametric study from a file.
- Parameters:
- file_name
str
,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 callingload()
.
- file_name
- Returns:
ParametricStudy
Loaded parametric study.
- ParametricStudy.reset_simulation_status()#
Reset the status of any
Pending
orRunning
simulations toNew
.
- ParametricStudy.clear_errors(simulation_ids: list[str] | None = None)#
Clear the error messages for the specified simulations.
- 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 theupdate()
method.A summary that matches an existing simulation will overwrite the results for that simulation.
- Parameters:
- 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_powers
list
[float
] Laser powers (W) to use for single bead simulations. Valid values are from
MIN_LASER_POWER
toMAX_LASER_POWER
.- scan_speeds
list
[float
] Scan speeds (m/s) to use for single bead simulations. Valid values are from
MIN_SCAN_SPEED
toMAX_SCAN_SPEED
.- bead_length
float
, default:DEFAULT_BEAD_LENGTH
Length of the bead (m). Valid values are from
MIN_BEAD_LENGTH
toMAX_BEAD_LENGTH
.- layer_thicknesses
list
[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 fromMIN_LAYER_THICKNESS
toMAX_LAYER_THICKNESS
.- heater_temperatures
list
[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 fromMIN_HEATER_TEMP
toMAX_HEATER_TEMP
.- beam_diameters
list
[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 fromMIN_BEAM_DIAMETER
toMAX_BEAM_DIAMETER
.- min_pv_ratio
float
, 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_ratio
float
, 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.
- iteration
int
, default:DEFAULT_ITERATION
Iteration number for this set of simulations.
- priority
int
, default:DEFAULT_PRIORITY
Priority for this set of simulations.
- laser_powers
- 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_powers
list
[float
] Laser powers (W) to use for porosity simulations. Valid values are from
MIN_LASER_POWER
toMAX_LASER_POWER
.- scan_speeds
list
[float
] Scan speeds (m/s) to use for porosity simulations. Valid values are from
MIN_SCAN_SPEED
toMAX_SCAN_SPEED
.- size_x
float
, default:DEFAULT_SAMPLE_SIZE
Size (m) of the porosity sample in the x direction. Valid values are from
MIN_SAMPLE_SIZE
toMAX_SAMPLE_SIZE
.- size_y
float
,DEFAULT_SAMPLE_SIZE
Size (m) of the porosity sample in the y direction. Valid values are from
MIN_SAMPLE_SIZE
toMAX_SAMPLE_SIZE
.- size_z
float
,DEFAULT_SAMPLE_SIZE
Size (m) of the porosity sample in the z direction. Valid values are from
MIN_SAMPLE_SIZE
toMAX_SAMPLE_SIZE
.- layer_thicknesses
list
[float
], default:None
Layer thicknesses (m) to use for porosity simulations. If this value is
None
,DEFAULT_LAYER_THICKNESS
is used. Valid values are fromMIN_LAYER_THICKNESS
toMAX_LAYER_THICKNESS
.- heater_temperatures
list
[float
], default:None
Heater temperatures (C) to use for porosity simulations. If this value is
None
,DEFAULT_HEATER_TEMP
is used. Valid values are fromMIN_HEATER_TEMP
toMAX_HEATER_TEMP
.- beam_diameters
list
[float
], default:None
Beam diameters (m) to use for porosity simulations. If this value is
None
,DEFAULT_BEAM_DIAMETER
is used. Valid values are fromMIN_BEAM_DIAMETER
toMAX_BEAM_DIAMETER
.- start_angles
list
[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 fromMIN_STARTING_LAYER_ANGLE
toMAX_STARTING_LAYER_ANGLE
.- rotation_angles
list
[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 fromMIN_LAYER_ROTATION_ANGLE
toMAX_LAYER_ROTATION_ANGLE
.- hatch_spacings
list
[float
], default:None
Hatch spacings (m) to use for porosity simulations. If this value is
None
,DEFAULT_HATCH_SPACING
is used. Valid values are fromMIN_HATCH_SPACING
toMAX_HATCH_SPACING
.- stripe_widths
list
[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 fromMIN_SLICING_STRIPE_WIDTH
toMAX_SLICING_STRIPE_WIDTH
.- min_energy_density
float
, 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_density
float
, 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_rate
float
, 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_rate
float
, 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.
- iteration
int
, default:DEFAULT_ITERATION
Iteration number for this set of simulations.
- priority
int
, default:DEFAULT_PRIORITY
Priority for this set of simulations.
- laser_powers
- 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_powers
list
[float
] Laser powers (W) to use for microstructure simulations. Valid values are from
MIN_LASER_POWER
toMAX_LASER_POWER
.- scan_speeds
list
[float
] Scan speeds (m/s) to use for microstructure simulations. Valid values are from
MIN_SCAN_SPEED
toMAX_SCAN_SPEED
.- min_x
float
, default:DEFAULT_POSITION_COORDINATE
Minimum x coordinate (m) of the microstructure sample. Valid values are from
MIN_POSITION_COORDINATE
toMAX_POSITION_COORDINATE
.- min_y
float
, default:DEFAULT_POSITION_COORDINATE
Minimum y coordinate (m) of the microstructure sample. Valid values are from
MIN_POSITION_COORDINATE
toMAX_POSITION_COORDINATE
.- min_z
float
, default:DEFAULT_POSITION_COORDINATE
Minimum z coordinate (m) of the microstructure sample. Valid values are from
MIN_POSITION_COORDINATE
toMAX_POSITION_COORDINATE
.- size_x
float
, default:DEFAULT_SAMPLE_SIZE
Size (m) of the microstructure sample in the x direction. Valid values are from
MIN_SAMPLE_SIZE
toMAX_SAMPLE_SIZE
.- size_y
float
, default:DEFAULT_SAMPLE_SIZE
Size (m) of the microstructure sample in the y direction. Valid values are from
MIN_SAMPLE_SIZE
toMAX_SAMPLE_SIZE
.- size_z
float
, default:DEFAULT_SAMPLE_SIZE
Size (m) of the microstructure sample in the z direction. Valid values are from
MIN_SAMPLE_SIZE
toMAX_SAMPLE_SIZE
.- sensor_dimension
float
, default:DEFAULT_SENSOR_DIMENSION
Sensor dimension (m) to use for microstructure simulations. Valid values are from
MIN_SENSOR_DIMENSION
toMAX_SENSOR_DIMENSION
. The values for thesize_x
andsize_y
parameters must be greater than thesensor_dimension
parameter byMIN_XY_SIZE_CUSHION
meters. The value for thesize_z
parameter must be greater thansensor_dimension
parameter byMIN_Z_SIZE_CUSHION
meters.- layer_thicknesses
list
[float
], default:None
Layer thicknesses (m) to use for microstructure simulations. If this value is
None
,DEFAULT_LAYER_THICKNESS
is used. Valid values are fromMIN_LAYER_THICKNESS
toMAX_LAYER_THICKNESS
.- heater_temperatures
list
[float
], default:None
Heater temperatures (C) to use for microstructure simulations. If this value is
None
,DEFAULT_HEATER_TEMP
is used. Valid values are fromMIN_HEATER_TEMP
toMAX_HEATER_TEMP
.- beam_diameters
list
[float
], default:None
Beam diameters (m) to use for microstructure simulations. If this value is
None
,DEFAULT_BEAM_DIAMETER
is used. Valid values are fromMIN_BEAM_DIAMETER
toMAX_BEAM_DIAMETER
.- start_angles
list
[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 fromMIN_STARTING_LAYER_ANGLE
toMAX_STARTING_LAYER_ANGLE
.- rotation_angles
list
[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 fromMIN_LAYER_ROTATION_ANGLE
toMAX_LAYER_ROTATION_ANGLE
.- hatch_spacings
list
[float
], default:None
Hatch spacings (m) to use for microstructure simulations. If this value is
None
,DEFAULT_HATCH_SPACING
is used. Valid values are fromMIN_HATCH_SPACING
toMAX_HATCH_SPACING
.- stripe_widths
list
[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 fromMIN_SLICING_STRIPE_WIDTH
toMAX_SLICING_STRIPE_WIDTH
.- min_energy_density
float
, 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_density
float
, 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_rate
float
, 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_rate
float
, 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_rate
float
, default:None
The cooling rate (K/s) to use for microstructure simulations. If this value is
None
, andthermal_gradient
,melt_pool_width
, andmelt_pool_depth
areNone
, the cooling rate is calculated. IfNone
and any of the other three parameters are notNone
,DEFAULT_COOLING_RATE
is used. Valid values are fromMIN_COOLING_RATE
toMAX_COOLING_RATE
.- thermal_gradient
float
, default:None
Thermal gradient (K/m) to use for microstructure simulations. If this value is
None
, andcooling_rate
,melt_pool_width
, andmelt_pool_depth
areNone
, the thermal gradient is calculated. If this value isNone
and any of the other three parameters are notNone
,DEFAULT_THERMAL_GRADIENT
is used. Valid values are fromMIN_THERMAL_GRADIENT
toMAX_THERMAL_GRADIENT
.- melt_pool_width
float
, default:None
Melt pool width (m) to use for microstructure simulations. If this value is
None
andcooling_rate
,thermal_gradient
, andmelt_pool_depth
areNone
, the melt pool is calculated. If this value isNone
and any of the other three parameters are notNone
,DEFAULT_MELT_POOL_WIDTH
is used. Valid values are fromMIN_MELT_POOL_WIDTH
toMAX_MELT_POOL_WIDTH
.- melt_pool_depth
float
, default:None
Melt pool depth (m) to use for microstructure simulations. If this value is
None
, andcooling_rate
,thermal_gradient
, andmelt_pool_width
areNone
, the melt pool depth is calculated. If this value isNone
and any of the other three parameters are notNone
,DEFAULT_MELT_POOL_DEPTH
is used. Valid values are fromMIN_MELT_POOL_DEPTH
toMAX_MELT_POOL_DEPTH
.- random_seed
int
, 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 fromMIN_RANDOM_SEED
toMAX_RANDOM_SEED
.- iteration
int
, default:DEFAULT_ITERATION
Iteration number for this set of simulations.
- priority
int
, default:DEFAULT_PRIORITY
Priority for this set of simulations.
- laser_powers
- 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:
- summaries
list
[SingleBeadSummary
,PorositySummary
,MicrostructureSummary
,SimulationError
] List of simulation summaries to use for updating the parametric study.
- summaries
- 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:
- inputs
list
[SingleBeadInput
,PorosityInput
,MicrostructureInput
] List of simulation inputs to add to the parametric study.
- iteration
int
, default:DEFAULT_ITERATION
Iteration number for the simulation inputs.
- priority
int
, default:DEFAULT_PRIORITY
Priority for the simulations.
- status
SimulationStatus
, default:SimulationStatus.NEW
Valid types are
SimulationStatus.NEW
andSimulationStatus.SKIP
.
- inputs
- Returns:
int
The number of simulations added to the parametric study.
- 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.
- ParametricStudy.set_priority(ids: str | list[str], priority: int)#
Set the priority of simulations in the parametric study.
- 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.
- 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:
- study
ParametricStudy
Parametric study to update.
- study
- 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_ids
list
[str
], default:None
List of simulation IDs to run. If this value is
None
, all simulations with a status ofNew
are run.- types
list
[SimulationType
], default:None
Type of simulations to run. If this value is
None
, all simulation types are run.- priority
int
, default:None
Priority of simulations to run. If this value is
None
, all priorities are run.- iteration
int
, 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 ofSimulationStatus.NEW
are selected.- types
list
, default:None
List of simulation types to include. The default is
None
, in which case all simulation types are selected.- priority
int
, default:None
Priority of simulations to include. The default is
None
, in which case all priorities are selected.- iteration
int
, 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