matcal.sierra.models

Public API for SIERRA models.

This package replaces the legacy monolithic matcal.sierra.models module while preserving the same import paths for public classes.

Examples:

from matcal.sierra.models import RoundUniaxialTensionModel

class matcal.sierra.models.UserDefinedSierraModel(executable, simulation_input_file, simulation_mesh_filename, *other_sources)

Use a user-provided SIERRA input deck + mesh + optional include files/dirs.

read_full_field_data(filename)

Configure model to read full field data compatible with FieldSeriesData importer.

add_constants(**kwargs)

Add additional constant parameters for the model that will be passed to the model before it is evaluated. These key/value pairs will be passed to all states. If these conflict with state variables, these will override the state variables. If these conflict with study parameters, the parameter values from the study will take precedent.

Parameters:

kwargs (dict(str, str) or dict(str, float)) – key/value pair of model constant parameters. For example model.add_simulation_variables(my_var1=5, my_var2=1, etc.)

add_environment_module(module_name)

Adds an environment module to be loaded before running the model. This must be a valid module on the system where the MatCal study is being run. MatCal will run “module load module_name” for the added module before running this model. If multiple modules are added, they will be loaded in the order they were added.

Parameters:

module_name (str) – the name of the module to be loaded when running the model.

add_executable_argument(argument)

Pass an additional argument directly to the SIERRA executable.

add_state_constants(state, **kwargs)

Add additional constant parameters for the model that will be passed to the model before it is evaluated for a given state. If the model is not evaluated for this state in the study, these parameters will not be used. If these conflict with experiment state variables, these will override the state variables. If these conflict with study parameters, the parameter values from the study will take precedent. Finally, adding a specific state model constant will override general model constants added with add_constants() method.

Parameters:

• state (State) – the state for these parameters

• kwargs – key/value pair of model constant parameters. For example model.add_simulation_variables(my_var1=5, my_var2=1, etc.)

continue_when_simulation_fails(**default_field_values)

Call this method on the model if you want the study to continue when its returns with an error or exit code. By default, It will generate a line of values from -1 to 1 for each required field. The objective will be calculated with these values and the study will continue. If desired custom failure values can be based in this method call to set the value for those given fields. Each of these fields must have the same length.

Parameters:

default_field_values (list or ArrayLike) – keyword arguments to set the default values for failed model evaluations. All arguments passed must have the same number of values.

Note

If the simulation errors out before any data can be returned to MatCal, the entire study will still fail due to not being able to formulate an objective.

get_target_dir_name(state, parent_dir=None)

Parameters:

• state (State) – the state for the target directory

• parent_dir (str) – optional parent directory where the model files will be built.

Returns:

Returns the name of the directory where the model will run if launched using run().

Return type:

str

preprocess(state, target_directory=None)

Prepares the model for the given state and places the model and associated files in an optional target directory.

Parameters:

• state (State) – the state to evaluate the model at.

• target_directory (str) – target location to be built to run the models in

reset_constants()

Removes all model constants that were added with the add_constants() and add_state_constants() methods.

run(state, parameter_collection, target_directory=None)

Runs the model for the given state and the current value of each parameter in the parameter collection.

Parameters:

• state (State) – the state to evaluate the model at.

• parameter_collection (ParameterCollection) – the parameter collection that will populate the parameter in the model

• target_directory (str) – target location to be built to run the models in

Returns:

the results from the simulation

Return type:

SimulatorResults

run_check_input(state, parameter_collection, target_directory=None)

Run with SIERRA ‘–check-input’.

run_check_syntax(state, parameter_collection, target_directory=None)

Run with SIERRA ‘–check-syntax’.

run_in_queue(queue_id: str, time_limit_hours: float, is_test: bool = False)

Indicates that this model will be run on a platform requiring queue submission. Will load platform data relevant to the platform the script is launched from.

Parameters:

• passed_id (str) – A valid ID for the user.

• time_limit_hours (float) – the number of hours the simulation will be allowed to run.

set_executable(executable)

Set the executable to a user specified executable. This allows for changing the executable after initialization for non-MatCal generated models, but also allows for changing the executable for MatCal generated models to custom compiled executables.

Parameters:

executable (str) – the name of the executable. It should be in your path or an absolute path.

set_name(new_name)

The name of the model. If the model is run as an external executable, the model will be created and run in a directory with this name. If a name is not provided, a unique identifier is assigned as the mode name.

set_number_of_cores(n_cores)

Sets the number of processors for the model to use.

Parameters:

number_cores (int) – The number of processors needed to run a single state of the model.

set_results_filename(filename, file_type=None)

Sets the name of the model results file.

Parameters:

• filename (str) – the filename of the model results output.

• file_type – the file type of the model results output so the file data importer knows how to read it in. Set to “None” by default, so MatCal will try to infer the type from the file extension.

class matcal.sierra.models.UniaxialLoadingMaterialPointModel(material)

MatCal generated material point model for uniaxial loading.

activate_element_death(death_variable='damage', critical_value=0.15)

Activate element death based on a damage/failure variable.

Parameters:

• death_variable (str) – Element variable used to determine failure.

• critical_value (float or str) – Threshold value at which an element is deleted/deactivated.

activate_exodus_output(output_step_interval=20)

Enable exodus mesh/results output.

Parameters:

output_step_interval (int) – Write exodus output every output_step_interval steps.

activate_thermal_coupling()

Activates adiabatic heating for the model. An initial temperature is added to the model and additional temperature outputs are provided in the heartbeat and exodus output.

add_boundary_condition_data(data)

Add boundary condition data (Data or DataCollection) used to determine loading functions for each state.

add_constants(**kwargs)

Add additional constant parameters for the model that will be passed to the model before it is evaluated. These key/value pairs will be passed to all states. If these conflict with state variables, these will override the state variables. If these conflict with study parameters, the parameter values from the study will take precedent.

Parameters:

kwargs (dict(str, str) or dict(str, float)) – key/value pair of model constant parameters. For example model.add_simulation_variables(my_var1=5, my_var2=1, etc.)

add_element_output_variable(*element_variable_names, volume_average=True)

Add element output variables for the model. The method accepts a comma separated list of strings. These should be valid element variables for the model and material model being used.

Parameters:

• element_variable_names (list(str)) – One or more element variable names to output.

• volume_average (bool) – If True, output a volume-averaged form of each element variable when applicable.

add_environment_module(module_name)

Adds an environment module to be loaded before running the model. This must be a valid module on the system where the MatCal study is being run. MatCal will run “module load module_name” for the added module before running this model. If multiple modules are added, they will be loaded in the order they were added.

Parameters:

module_name (str) – the name of the module to be loaded when running the model.

add_executable_argument(argument)

Pass an additional argument directly to the SIERRA executable.

add_nodal_output_variable(*nodal_variable_names)

Add nodal output variables for the model. The method accepts a comma separated list of strings. These should be valid nodal variables for the model and material model being used.

Parameters:

nodal_variable_names (list(str)) – One or more nodal variable names to output.

add_state_constants(state, **kwargs)

Add additional constant parameters for the model that will be passed to the model before it is evaluated for a given state. If the model is not evaluated for this state in the study, these parameters will not be used. If these conflict with experiment state variables, these will override the state variables. If these conflict with study parameters, the parameter values from the study will take precedent. Finally, adding a specific state model constant will override general model constants added with add_constants() method.

Parameters:

• state (State) – the state for these parameters

• kwargs – key/value pair of model constant parameters. For example model.add_simulation_variables(my_var1=5, my_var2=1, etc.)

continue_when_simulation_fails(**default_field_values)

Call this method on the model if you want the study to continue when its returns with an error or exit code. By default, It will generate a line of values from -1 to 1 for each required field. The objective will be calculated with these values and the study will continue. If desired custom failure values can be based in this method call to set the value for those given fields. Each of these fields must have the same length.

Parameters:

default_field_values (list or ArrayLike) – keyword arguments to set the default values for failed model evaluations. All arguments passed must have the same number of values.

Note

If the simulation errors out before any data can be returned to MatCal, the entire study will still fail due to not being able to formulate an objective.

property coupling

Returns the type of thermomechanical coupling that the model will use in a simulation. Returns None if uncoupled.

property element_type

The element type being used by the model.

property exodus_output

Returns True if exodus output is activated and variables have been added. Otherwise, returns False.

property failure

Returns the type of failure that the model will use in a simulation. Returns None if there is no failure.

get_target_dir_name(state, parent_dir=None)

Parameters:

• state (State) – the state for the target directory

• parent_dir (str) – optional parent directory where the model files will be built.

Returns:

Returns the name of the directory where the model will run if launched using run().

Return type:

str

property input_file

SIERRA input file object associated with this model.

preprocess(state, target_directory=None)

Prepares the model for the given state and places the model and associated files in an optional target directory.

Parameters:

• state (State) – the state to evaluate the model at.

• target_directory (str) – target location to be built to run the models in

read_temperature_from_boundary_condition_data(field_name='temperature')

Read and apply a temperature history from boundary condition data.

reset_boundary_condition_data()

Remove all previously added boundary condition data and clear any request to read temperature from that data.

This resets the model’s boundary-condition data so new boundary condition data can be added before the next run/setup.

reset_constants()

Removes all model constants that were added with the add_constants() and add_state_constants() methods.

run(state, parameter_collection, target_directory=None)

Runs the model for the given state and the current value of each parameter in the parameter collection.

Parameters:

• state (State) – the state to evaluate the model at.

• parameter_collection (ParameterCollection) – the parameter collection that will populate the parameter in the model

• target_directory (str) – target location to be built to run the models in

Returns:

the results from the simulation

Return type:

SimulatorResults

run_check_input(state, parameter_collection, target_directory=None)

Run with SIERRA ‘–check-input’.

run_check_syntax(state, parameter_collection, target_directory=None)

Run with SIERRA ‘–check-syntax’.

run_in_queue(queue_id: str, time_limit_hours: float, is_test: bool = False)

Indicates that this model will be run on a platform requiring queue submission. Will load platform data relevant to the platform the script is launched from.

Parameters:

• passed_id (str) – A valid ID for the user.

• time_limit_hours (float) – the number of hours the simulation will be allowed to run.

set_boundary_condition_scale_factor(value)

Scales the dependent and independent field in the model deformation function by a constant factor. It must be between 1 and 10.

set_convergence_tolerance(target_relative_residual, target_residual=None, acceptable_relative_residual=None, acceptable_residual=None)

Set the convergence tolerance values for the SIERRA/SM conjugate gradient solver. By default the target residual is two orders of magnitude higher than the target relative residual, and the acceptable relative residual is one order of magnitude higher than the target relative residual. Updating the target relative residual will update the target residual and acceptable relative residual according to these defaults. No acceptable residual is specified by default.

Parameters:

• target_relative_residual (float) – the relative residual for convergence of the SIERRA/SM conjugate gradient solver. Must be between zero and one.

• target_residual (float or None) – the target residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive.

• acceptable_relative_residual (float or None) – the acceptable relative residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive and greater than the target relative residual but less than one.

• acceptable_residual (float or None) – the acceptable residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive and should be greater than the target residual.

set_end_time(end_time)

Set the analysis termination time. This will override the final time determined from the supplied boundary condition and state data.

This is most useful when boundary condition data is a complex load history and only a portion of it needs to be simulated. It may also be useful when trying to simulate stress relaxation after the end of loading.

Parameters:

end_time (float) – Final simulation time.

set_executable(executable)

Set the executable to a user specified executable. This allows for changing the executable after initialization for non-MatCal generated models, but also allows for changing the executable for MatCal generated models to custom compiled executables.

Parameters:

executable (str) – the name of the executable. It should be in your path or an absolute path.

set_minimum_timestep(minimum_timestep)

Sets a minimum timestep such that the simulation will exit cleanly if the timestep is cut to below the user specified minimum value. This is done using SIERRA/SM solution termination.

Parameters:

minimum_timestep (float) – Minimum acceptable timestep.

set_name(new_name)

The name of the model. If the model is run as an external executable, the model will be created and run in a directory with this name. If a name is not provided, a unique identifier is assigned as the mode name.

set_number_of_cores(n_cores)

Sets the number of processors for the model to use.

Parameters:

number_cores (int) – The number of processors needed to run a single state of the model.

set_number_of_time_steps(number_of_steps)

Set the number of load/time steps used in the SIERRA procedure. Due to other model options and adaptive time stepping, this number of time steps is not guaranteed.

Parameters:

number_of_steps (int) – Total number of time steps in the analysis.

set_results_filename(filename, file_type=None)

Sets the name of the model results file.

Parameters:

• filename (str) – the filename of the model results output.

• file_type – the file type of the model results output so the file data importer knows how to read it in. Set to “None” by default, so MatCal will try to infer the type from the file extension.

set_start_time(start_time)

Set the analysis start time. This will override the start time determined from the supplied boundary condition and state data.

This is most useful when boundary condition data is a complex load history and only a portion of it needs to be simulated.

Parameters:

start_time (float) – Initial simulation time.

use_total_lagrange_element()

Sets the model to use SIERRA/SM’s total lagrange 8 node hexahedral element with volume average J turned on.

use_under_integrated_element()

Sets the model to use SIERRA/SM’s under integrated element 8 node hexahedral element with hourglass control and the SIERRA/SM default settings for the element.

class matcal.sierra.models.RoundUniaxialTensionModel(material, executable='adagio', **kwargs)

MatCal generated SIERRA/SM uniaxial tension test model with a round cross section.

activate_element_death(death_variable='damage', critical_value=0.15, nonlocal_radius=None)

Activates element death for the model. It will kill elements that have the element variable with name “death_variable” reach the critical value. To use nonlocal damage also specify the “nonlocal_radius” and the “initial_value” for the “death_variable”. Both options are needed for nonlocal damage to work correctly.

Parameters:

• death_variable (str) – the name of the element variable that governs element death.

• critical_value (float, str) – the element “death_variable” value at which the element will die. Elements with a “death_variable” value less than the “critical_value” are kept alive. This can also be a string if it is replaced by a MatCal design or state parameter on run time. For example, it could be set to “{critical_value}” and the critical value could be a MatCal study parameter.

• nonlocal_radius (float) – the radius to be used for nonlocal average in the the geometry units. Specifying this parameter to anything but None activates nonlocal averaging for the “death_variable”. This must be greater than zero.

activate_exodus_output(output_step_interval=20)

Enable exodus mesh/results output.

Parameters:

output_step_interval (int) – Write exodus output every output_step_interval steps.

activate_full_field_data_output(full_field_window_width, full_field_window_height)

Activate full field data output for calibrations requiring full field data. The parameters for this method specify the rectangular window where data will be output. Currently, this is only implemented for the RoundUniaxialTensionModel, RectangularUniaxialTensionModel and the RoundNotchedTensionModel. The rectangular window starts at the axial and radial center of the model and goes outward according to the two arguments passed to this function. Since these models feature 1/8th symmetry, the window only covers one octant of the model. The full field window width and height specify the width and height of the 2D window in the octant where the model is built. Any nodes within that width and height of the window will be included in the output.

Parameters:

• full_field_window_width (float) – width of the 2D window for full field data output. The width is aligned with the X direction of the global coordinate system of the model.

• full_field_window_height (float) – height of the 2D window for full field data output. The height is aligned with the Y direction of the global coordinate system of the model and its axis of loading.

activate_implicit_dynamics()

Turns on implicit dynamics for SIERRA/SM. By default, all models are run quasi-statically.

activate_thermal_coupling(thermal_conductivity=None, density=None, specific_heat=None, plastic_work_variable=None, executable='arpeggio')

Activates thermomechanical coupling for the MatCal generated model. If no options are passed, the model assumes adiabatic heating is being added through the material model. For the adiabatic case, an initial temperature is added to the model and additional temperature outputs are provided in the heartbeat and exodus output.

If the additional input arguments for are provided, then staggered coupling through Arpeggio is used. Staggered coupling is setup to advance the solid mechanics solve, pass the displacements and plastic work to the thermal solver, advance the thermal solve, and pass the temperature to the solid mechanics solver before continuing to the next time step.

To activate iterative coupling, use the use_iterative_coupling() method.

Parameters:

• thermal_conductivity (float or None) – Thermal conductivity for the thermal model.

• density (float or None) – Density for the thermal model.

• specific_heat (float or None) – Specific heat for the thermal model.

• plastic_work_variable (str or None) – Element variable name representing plastic work rate passed to the thermal solver as the element volumetric heat source

• executable (str) – Executable used for the coupled solve. This can be an optional path to an custom compiled executable

add_boundary_condition_data(data)

Add boundary condition data (Data or DataCollection) used to determine loading functions for each state.

add_constants(**kwargs)

Add additional constant parameters for the model that will be passed to the model before it is evaluated. These key/value pairs will be passed to all states. If these conflict with state variables, these will override the state variables. If these conflict with study parameters, the parameter values from the study will take precedent.

Parameters:

kwargs (dict(str, str) or dict(str, float)) – key/value pair of model constant parameters. For example model.add_simulation_variables(my_var1=5, my_var2=1, etc.)

add_element_output_variable(*element_variable_names, volume_average=True)

Add element output variables for the model. The method accepts a comma separated list of strings. These should be valid element variables for the model and material model being used.

Parameters:

• element_variable_names (list(str)) – One or more element variable names to output.

• volume_average (bool) – If True, output a volume-averaged form of each element variable when applicable.

add_environment_module(module_name)

Adds an environment module to be loaded before running the model. This must be a valid module on the system where the MatCal study is being run. MatCal will run “module load module_name” for the added module before running this model. If multiple modules are added, they will be loaded in the order they were added.

Parameters:

module_name (str) – the name of the module to be loaded when running the model.

add_executable_argument(argument)

Pass an additional argument directly to the SIERRA executable.

add_nodal_output_variable(*nodal_variable_names)

Add nodal output variables for the model. The method accepts a comma separated list of strings. These should be valid nodal variables for the model and material model being used.

Parameters:

nodal_variable_names (list(str)) – One or more nodal variable names to output.

add_state_constants(state, **kwargs)

Add additional constant parameters for the model that will be passed to the model before it is evaluated for a given state. If the model is not evaluated for this state in the study, these parameters will not be used. If these conflict with experiment state variables, these will override the state variables. If these conflict with study parameters, the parameter values from the study will take precedent. Finally, adding a specific state model constant will override general model constants added with add_constants() method.

Parameters:

• state (State) – the state for these parameters

• kwargs – key/value pair of model constant parameters. For example model.add_simulation_variables(my_var1=5, my_var2=1, etc.)

continue_when_simulation_fails(**default_field_values)

Call this method on the model if you want the study to continue when its returns with an error or exit code. By default, It will generate a line of values from -1 to 1 for each required field. The objective will be calculated with these values and the study will continue. If desired custom failure values can be based in this method call to set the value for those given fields. Each of these fields must have the same length.

Parameters:

default_field_values (list or ArrayLike) – keyword arguments to set the default values for failed model evaluations. All arguments passed must have the same number of values.

Note

If the simulation errors out before any data can be returned to MatCal, the entire study will still fail due to not being able to formulate an objective.

property coupling

Returns the type of thermomechanical coupling that the model will use in a simulation. Returns None if uncoupled.

property element_type

The element type being used by the model.

property exodus_output

Returns True if exodus output is activated and variables have been added. Otherwise, returns False.

property failure

Returns the type of failure that the model will use in a simulation. Returns None if there is no failure.

get_target_dir_name(state, parent_dir=None)

Parameters:

• state (State) – the state for the target directory

• parent_dir (str) – optional parent directory where the model files will be built.

Returns:

Returns the name of the directory where the model will run if launched using run().

Return type:

str

property input_file

SIERRA input file object associated with this model.

preprocess(state, target_directory=None)

Prepares the model for the given state and places the model and associated files in an optional target directory.

Parameters:

• state (State) – the state to evaluate the model at.

• target_directory (str) – target location to be built to run the models in

read_temperature_from_boundary_condition_data(field_name='temperature')

Read and apply a temperature history from boundary condition data.

reset_boundary_condition_data()

Remove all previously added boundary condition data and clear any request to read temperature from that data.

This resets the model’s boundary-condition data so new boundary condition data can be added before the next run/setup.

reset_constants()

Removes all model constants that were added with the add_constants() and add_state_constants() methods.

run(state, parameter_collection, target_directory=None)

Runs the model for the given state and the current value of each parameter in the parameter collection.

Parameters:

• state (State) – the state to evaluate the model at.

• parameter_collection (ParameterCollection) – the parameter collection that will populate the parameter in the model

• target_directory (str) – target location to be built to run the models in

Returns:

the results from the simulation

Return type:

SimulatorResults

run_check_input(state, parameter_collection, target_directory=None)

Run with SIERRA ‘–check-input’.

run_check_syntax(state, parameter_collection, target_directory=None)

Run with SIERRA ‘–check-syntax’.

run_in_queue(queue_id: str, time_limit_hours: float, is_test: bool = False)

Indicates that this model will be run on a platform requiring queue submission. Will load platform data relevant to the platform the script is launched from.

Parameters:

• passed_id (str) – A valid ID for the user.

• time_limit_hours (float) – the number of hours the simulation will be allowed to run.

set_allowable_load_drop_factor(value)

The allowable drop in the models “load” field before the simulation is terminated. Note that the actual load field name is model dependent. The simulation will terminate when the following is true:

where max_load is the maximum load in the current load history. The load drop factor must be between 0 and 1.

Parameters:

value (float) – the max allowable load drop fraction

set_boundary_condition_scale_factor(value)

Scales the dependent and independent field in the model deformation function by a constant factor. It must be between 1 and 10.

set_convergence_tolerance(target_relative_residual, target_residual=None, acceptable_relative_residual=None, acceptable_residual=None)

Set the convergence tolerance values for the SIERRA/SM conjugate gradient solver. By default the target residual is two orders of magnitude higher than the target relative residual, and the acceptable relative residual is one order of magnitude higher than the target relative residual. Updating the target relative residual will update the target residual and acceptable relative residual according to these defaults. No acceptable residual is specified by default.

Parameters:

• target_relative_residual (float) – the relative residual for convergence of the SIERRA/SM conjugate gradient solver. Must be between zero and one.

• target_residual (float or None) – the target residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive.

• acceptable_relative_residual (float or None) – the acceptable relative residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive and greater than the target relative residual but less than one.

• acceptable_residual (float or None) – the acceptable residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive and should be greater than the target residual.

set_end_time(end_time)

Set the analysis termination time. This will override the final time determined from the supplied boundary condition and state data.

This is most useful when boundary condition data is a complex load history and only a portion of it needs to be simulated. It may also be useful when trying to simulate stress relaxation after the end of loading.

Parameters:

end_time (float) – Final simulation time.

set_executable(executable)

Set the executable to a user specified executable. This allows for changing the executable after initialization for non-MatCal generated models, but also allows for changing the executable for MatCal generated models to custom compiled executables.

Parameters:

executable (str) – the name of the executable. It should be in your path or an absolute path.

set_minimum_timestep(minimum_timestep)

Sets a minimum timestep such that the simulation will exit cleanly if the timestep is cut to below the user specified minimum value. This is done using SIERRA/SM solution termination.

Parameters:

minimum_timestep (float) – Minimum acceptable timestep.

set_name(new_name)

The name of the model. If the model is run as an external executable, the model will be created and run in a directory with this name. If a name is not provided, a unique identifier is assigned as the mode name.

set_number_of_cores(n_cores)

Sets the number of processors for the model to use.

Parameters:

number_cores (int) – The number of processors needed to run a single state of the model.

set_number_of_time_steps(number_of_steps)

Set the number of load/time steps used in the SIERRA procedure. Due to other model options and adaptive time stepping, this number of time steps is not guaranteed.

Parameters:

number_of_steps (int) – Total number of time steps in the analysis.

set_results_filename(filename, file_type=None)

Sets the name of the model results file.

Parameters:

• filename (str) – the filename of the model results output.

• file_type – the file type of the model results output so the file data importer knows how to read it in. Set to “None” by default, so MatCal will try to infer the type from the file extension.

set_start_time(start_time)

Set the analysis start time. This will override the start time determined from the supplied boundary condition and state data.

This is most useful when boundary condition data is a complex load history and only a portion of it needs to be simulated.

Parameters:

start_time (float) – Initial simulation time.

use_composite_tet_element()

Use the composite tetrahedral total-Lagrange element formulation.

This is a convenience wrapper around use_total_lagrange_element() with use_composite_tet=True.

use_iterative_coupling()

Activates iterative coupling for the model. Iterative coupling can only be used after thermal coupling with staggered coupling has been activated for the model.

use_total_lagrange_element(use_composite_tet=False)

Sets the model to use SIERRA/SM’s total lagrange 8 node hexahedral element with volume average J turned on. Or, optionally, use composite tetrahedral elements for the model.

Parameters:

use_composite_tet (bool) – If True, use the composite tetrahedral version of the formulation; otherwise use the hex formulation.

use_under_integrated_element()

Sets the model to use SIERRA/SM’s under integrated element 8 node hexahedral element with hourglass control and the SIERRA/SM default settings for the element.

class matcal.sierra.models.RectangularUniaxialTensionModel(material, executable='adagio', **kwargs)

MatCal generated SIERRA/SM uniaxial tension test model with a rectangular cross section.

activate_element_death(death_variable='damage', critical_value=0.15, nonlocal_radius=None)

Activates element death for the model. It will kill elements that have the element variable with name “death_variable” reach the critical value. To use nonlocal damage also specify the “nonlocal_radius” and the “initial_value” for the “death_variable”. Both options are needed for nonlocal damage to work correctly.

Parameters:

• death_variable (str) – the name of the element variable that governs element death.

• critical_value (float, str) – the element “death_variable” value at which the element will die. Elements with a “death_variable” value less than the “critical_value” are kept alive. This can also be a string if it is replaced by a MatCal design or state parameter on run time. For example, it could be set to “{critical_value}” and the critical value could be a MatCal study parameter.

• nonlocal_radius (float) – the radius to be used for nonlocal average in the the geometry units. Specifying this parameter to anything but None activates nonlocal averaging for the “death_variable”. This must be greater than zero.

activate_exodus_output(output_step_interval=20)

Enable exodus mesh/results output.

Parameters:

output_step_interval (int) – Write exodus output every output_step_interval steps.

activate_full_field_data_output(full_field_window_width, full_field_window_height)

Activate full field data output for calibrations requiring full field data. The parameters for this method specify the rectangular window where data will be output. Currently, this is only implemented for the RoundUniaxialTensionModel, RectangularUniaxialTensionModel and the RoundNotchedTensionModel. The rectangular window starts at the axial and radial center of the model and goes outward according to the two arguments passed to this function. Since these models feature 1/8th symmetry, the window only covers one octant of the model. The full field window width and height specify the width and height of the 2D window in the octant where the model is built. Any nodes within that width and height of the window will be included in the output.

Parameters:

• full_field_window_width (float) – width of the 2D window for full field data output. The width is aligned with the X direction of the global coordinate system of the model.

• full_field_window_height (float) – height of the 2D window for full field data output. The height is aligned with the Y direction of the global coordinate system of the model and its axis of loading.

activate_implicit_dynamics()

Turns on implicit dynamics for SIERRA/SM. By default, all models are run quasi-statically.

activate_thermal_coupling(thermal_conductivity=None, density=None, specific_heat=None, plastic_work_variable=None, executable='arpeggio')

Activates thermomechanical coupling for the MatCal generated model. If no options are passed, the model assumes adiabatic heating is being added through the material model. For the adiabatic case, an initial temperature is added to the model and additional temperature outputs are provided in the heartbeat and exodus output.

If the additional input arguments for are provided, then staggered coupling through Arpeggio is used. Staggered coupling is setup to advance the solid mechanics solve, pass the displacements and plastic work to the thermal solver, advance the thermal solve, and pass the temperature to the solid mechanics solver before continuing to the next time step.

To activate iterative coupling, use the use_iterative_coupling() method.

Parameters:

• thermal_conductivity (float or None) – Thermal conductivity for the thermal model.

• density (float or None) – Density for the thermal model.

• specific_heat (float or None) – Specific heat for the thermal model.

• plastic_work_variable (str or None) – Element variable name representing plastic work rate passed to the thermal solver as the element volumetric heat source

• executable (str) – Executable used for the coupled solve. This can be an optional path to an custom compiled executable

add_boundary_condition_data(data)

Add boundary condition data (Data or DataCollection) used to determine loading functions for each state.

add_constants(**kwargs)

Add additional constant parameters for the model that will be passed to the model before it is evaluated. These key/value pairs will be passed to all states. If these conflict with state variables, these will override the state variables. If these conflict with study parameters, the parameter values from the study will take precedent.

Parameters:

kwargs (dict(str, str) or dict(str, float)) – key/value pair of model constant parameters. For example model.add_simulation_variables(my_var1=5, my_var2=1, etc.)

add_element_output_variable(*element_variable_names, volume_average=True)

Add element output variables for the model. The method accepts a comma separated list of strings. These should be valid element variables for the model and material model being used.

Parameters:

• element_variable_names (list(str)) – One or more element variable names to output.

• volume_average (bool) – If True, output a volume-averaged form of each element variable when applicable.

add_environment_module(module_name)

Adds an environment module to be loaded before running the model. This must be a valid module on the system where the MatCal study is being run. MatCal will run “module load module_name” for the added module before running this model. If multiple modules are added, they will be loaded in the order they were added.

Parameters:

module_name (str) – the name of the module to be loaded when running the model.

add_executable_argument(argument)

Pass an additional argument directly to the SIERRA executable.

add_nodal_output_variable(*nodal_variable_names)

Add nodal output variables for the model. The method accepts a comma separated list of strings. These should be valid nodal variables for the model and material model being used.

Parameters:

nodal_variable_names (list(str)) – One or more nodal variable names to output.

add_state_constants(state, **kwargs)

Add additional constant parameters for the model that will be passed to the model before it is evaluated for a given state. If the model is not evaluated for this state in the study, these parameters will not be used. If these conflict with experiment state variables, these will override the state variables. If these conflict with study parameters, the parameter values from the study will take precedent. Finally, adding a specific state model constant will override general model constants added with add_constants() method.

Parameters:

• state (State) – the state for these parameters

• kwargs – key/value pair of model constant parameters. For example model.add_simulation_variables(my_var1=5, my_var2=1, etc.)

continue_when_simulation_fails(**default_field_values)

Call this method on the model if you want the study to continue when its returns with an error or exit code. By default, It will generate a line of values from -1 to 1 for each required field. The objective will be calculated with these values and the study will continue. If desired custom failure values can be based in this method call to set the value for those given fields. Each of these fields must have the same length.

Parameters:

default_field_values (list or ArrayLike) – keyword arguments to set the default values for failed model evaluations. All arguments passed must have the same number of values.

Note

If the simulation errors out before any data can be returned to MatCal, the entire study will still fail due to not being able to formulate an objective.

property coupling

Returns the type of thermomechanical coupling that the model will use in a simulation. Returns None if uncoupled.

property element_type

The element type being used by the model.

property exodus_output

Returns True if exodus output is activated and variables have been added. Otherwise, returns False.

property failure

Returns the type of failure that the model will use in a simulation. Returns None if there is no failure.

get_target_dir_name(state, parent_dir=None)

Parameters:

• state (State) – the state for the target directory

• parent_dir (str) – optional parent directory where the model files will be built.

Returns:

Returns the name of the directory where the model will run if launched using run().

Return type:

str

property input_file

SIERRA input file object associated with this model.

preprocess(state, target_directory=None)

Prepares the model for the given state and places the model and associated files in an optional target directory.

Parameters:

• state (State) – the state to evaluate the model at.

• target_directory (str) – target location to be built to run the models in

read_temperature_from_boundary_condition_data(field_name='temperature')

Read and apply a temperature history from boundary condition data.

reset_boundary_condition_data()

Remove all previously added boundary condition data and clear any request to read temperature from that data.

This resets the model’s boundary-condition data so new boundary condition data can be added before the next run/setup.

reset_constants()

Removes all model constants that were added with the add_constants() and add_state_constants() methods.

run(state, parameter_collection, target_directory=None)

Runs the model for the given state and the current value of each parameter in the parameter collection.

Parameters:

• state (State) – the state to evaluate the model at.

• parameter_collection (ParameterCollection) – the parameter collection that will populate the parameter in the model

• target_directory (str) – target location to be built to run the models in

Returns:

the results from the simulation

Return type:

SimulatorResults

run_check_input(state, parameter_collection, target_directory=None)

Run with SIERRA ‘–check-input’.

run_check_syntax(state, parameter_collection, target_directory=None)

Run with SIERRA ‘–check-syntax’.

run_in_queue(queue_id: str, time_limit_hours: float, is_test: bool = False)

Indicates that this model will be run on a platform requiring queue submission. Will load platform data relevant to the platform the script is launched from.

Parameters:

• passed_id (str) – A valid ID for the user.

• time_limit_hours (float) – the number of hours the simulation will be allowed to run.

set_allowable_load_drop_factor(value)

The allowable drop in the models “load” field before the simulation is terminated. Note that the actual load field name is model dependent. The simulation will terminate when the following is true:

where max_load is the maximum load in the current load history. The load drop factor must be between 0 and 1.

Parameters:

value (float) – the max allowable load drop fraction

set_boundary_condition_scale_factor(value)

Scales the dependent and independent field in the model deformation function by a constant factor. It must be between 1 and 10.

set_convergence_tolerance(target_relative_residual, target_residual=None, acceptable_relative_residual=None, acceptable_residual=None)

Set the convergence tolerance values for the SIERRA/SM conjugate gradient solver. By default the target residual is two orders of magnitude higher than the target relative residual, and the acceptable relative residual is one order of magnitude higher than the target relative residual. Updating the target relative residual will update the target residual and acceptable relative residual according to these defaults. No acceptable residual is specified by default.

Parameters:

• target_relative_residual (float) – the relative residual for convergence of the SIERRA/SM conjugate gradient solver. Must be between zero and one.

• target_residual (float or None) – the target residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive.

• acceptable_relative_residual (float or None) – the acceptable relative residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive and greater than the target relative residual but less than one.

• acceptable_residual (float or None) – the acceptable residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive and should be greater than the target residual.

set_end_time(end_time)

Set the analysis termination time. This will override the final time determined from the supplied boundary condition and state data.

This is most useful when boundary condition data is a complex load history and only a portion of it needs to be simulated. It may also be useful when trying to simulate stress relaxation after the end of loading.

Parameters:

end_time (float) – Final simulation time.

set_executable(executable)

Set the executable to a user specified executable. This allows for changing the executable after initialization for non-MatCal generated models, but also allows for changing the executable for MatCal generated models to custom compiled executables.

Parameters:

executable (str) – the name of the executable. It should be in your path or an absolute path.

set_minimum_timestep(minimum_timestep)

Sets a minimum timestep such that the simulation will exit cleanly if the timestep is cut to below the user specified minimum value. This is done using SIERRA/SM solution termination.

Parameters:

minimum_timestep (float) – Minimum acceptable timestep.

set_name(new_name)

The name of the model. If the model is run as an external executable, the model will be created and run in a directory with this name. If a name is not provided, a unique identifier is assigned as the mode name.

set_number_of_cores(n_cores)

Sets the number of processors for the model to use.

Parameters:

number_cores (int) – The number of processors needed to run a single state of the model.

set_number_of_time_steps(number_of_steps)

Set the number of load/time steps used in the SIERRA procedure. Due to other model options and adaptive time stepping, this number of time steps is not guaranteed.

Parameters:

number_of_steps (int) – Total number of time steps in the analysis.

set_results_filename(filename, file_type=None)

Sets the name of the model results file.

Parameters:

• filename (str) – the filename of the model results output.

• file_type – the file type of the model results output so the file data importer knows how to read it in. Set to “None” by default, so MatCal will try to infer the type from the file extension.

set_start_time(start_time)

Set the analysis start time. This will override the start time determined from the supplied boundary condition and state data.

This is most useful when boundary condition data is a complex load history and only a portion of it needs to be simulated.

Parameters:

start_time (float) – Initial simulation time.

use_composite_tet_element()

Use the composite tetrahedral total-Lagrange element formulation.

This is a convenience wrapper around use_total_lagrange_element() with use_composite_tet=True.

use_iterative_coupling()

Activates iterative coupling for the model. Iterative coupling can only be used after thermal coupling with staggered coupling has been activated for the model.

use_total_lagrange_element(use_composite_tet=False)

Sets the model to use SIERRA/SM’s total lagrange 8 node hexahedral element with volume average J turned on. Or, optionally, use composite tetrahedral elements for the model.

Parameters:

use_composite_tet (bool) – If True, use the composite tetrahedral version of the formulation; otherwise use the hex formulation.

use_under_integrated_element()

Sets the model to use SIERRA/SM’s under integrated element 8 node hexahedral element with hourglass control and the SIERRA/SM default settings for the element.

class matcal.sierra.models.RoundNotchedTensionModel(material, executable='adagio', **kwargs)

MatCal generated SIERRA/SM notched tension test model with a round cross section.

activate_element_death(death_variable='damage', critical_value=0.15, nonlocal_radius=None)

Activates element death for the model. It will kill elements that have the element variable with name “death_variable” reach the critical value. To use nonlocal damage also specify the “nonlocal_radius” and the “initial_value” for the “death_variable”. Both options are needed for nonlocal damage to work correctly.

Parameters:

• death_variable (str) – the name of the element variable that governs element death.

• critical_value (float, str) – the element “death_variable” value at which the element will die. Elements with a “death_variable” value less than the “critical_value” are kept alive. This can also be a string if it is replaced by a MatCal design or state parameter on run time. For example, it could be set to “{critical_value}” and the critical value could be a MatCal study parameter.

• nonlocal_radius (float) – the radius to be used for nonlocal average in the the geometry units. Specifying this parameter to anything but None activates nonlocal averaging for the “death_variable”. This must be greater than zero.

activate_exodus_output(output_step_interval=20)

Enable exodus mesh/results output.

Parameters:

output_step_interval (int) – Write exodus output every output_step_interval steps.

activate_full_field_data_output(full_field_window_width, full_field_window_height)

Activate full field data output for calibrations requiring full field data. The parameters for this method specify the rectangular window where data will be output. Currently, this is only implemented for the RoundUniaxialTensionModel, RectangularUniaxialTensionModel and the RoundNotchedTensionModel. The rectangular window starts at the axial and radial center of the model and goes outward according to the two arguments passed to this function. Since these models feature 1/8th symmetry, the window only covers one octant of the model. The full field window width and height specify the width and height of the 2D window in the octant where the model is built. Any nodes within that width and height of the window will be included in the output.

Parameters:

• full_field_window_width (float) – width of the 2D window for full field data output. The width is aligned with the X direction of the global coordinate system of the model.

• full_field_window_height (float) – height of the 2D window for full field data output. The height is aligned with the Y direction of the global coordinate system of the model and its axis of loading.

activate_implicit_dynamics()

Turns on implicit dynamics for SIERRA/SM. By default, all models are run quasi-statically.

activate_thermal_coupling(thermal_conductivity=None, density=None, specific_heat=None, plastic_work_variable=None, executable='arpeggio')

Activates thermomechanical coupling for the MatCal generated model. If no options are passed, the model assumes adiabatic heating is being added through the material model. For the adiabatic case, an initial temperature is added to the model and additional temperature outputs are provided in the heartbeat and exodus output.

If the additional input arguments for are provided, then staggered coupling through Arpeggio is used. Staggered coupling is setup to advance the solid mechanics solve, pass the displacements and plastic work to the thermal solver, advance the thermal solve, and pass the temperature to the solid mechanics solver before continuing to the next time step.

To activate iterative coupling, use the use_iterative_coupling() method.

Parameters:

• thermal_conductivity (float or None) – Thermal conductivity for the thermal model.

• density (float or None) – Density for the thermal model.

• specific_heat (float or None) – Specific heat for the thermal model.

• plastic_work_variable (str or None) – Element variable name representing plastic work rate passed to the thermal solver as the element volumetric heat source

• executable (str) – Executable used for the coupled solve. This can be an optional path to an custom compiled executable

add_boundary_condition_data(data)

Add boundary condition data (Data or DataCollection) used to determine loading functions for each state.

add_constants(**kwargs)

Add additional constant parameters for the model that will be passed to the model before it is evaluated. These key/value pairs will be passed to all states. If these conflict with state variables, these will override the state variables. If these conflict with study parameters, the parameter values from the study will take precedent.

Parameters:

kwargs (dict(str, str) or dict(str, float)) – key/value pair of model constant parameters. For example model.add_simulation_variables(my_var1=5, my_var2=1, etc.)

add_element_output_variable(*element_variable_names, volume_average=True)

Add element output variables for the model. The method accepts a comma separated list of strings. These should be valid element variables for the model and material model being used.

Parameters:

• element_variable_names (list(str)) – One or more element variable names to output.

• volume_average (bool) – If True, output a volume-averaged form of each element variable when applicable.

add_environment_module(module_name)

Adds an environment module to be loaded before running the model. This must be a valid module on the system where the MatCal study is being run. MatCal will run “module load module_name” for the added module before running this model. If multiple modules are added, they will be loaded in the order they were added.

Parameters:

module_name (str) – the name of the module to be loaded when running the model.

add_executable_argument(argument)

Pass an additional argument directly to the SIERRA executable.

add_nodal_output_variable(*nodal_variable_names)

Add nodal output variables for the model. The method accepts a comma separated list of strings. These should be valid nodal variables for the model and material model being used.

Parameters:

nodal_variable_names (list(str)) – One or more nodal variable names to output.

add_state_constants(state, **kwargs)

Add additional constant parameters for the model that will be passed to the model before it is evaluated for a given state. If the model is not evaluated for this state in the study, these parameters will not be used. If these conflict with experiment state variables, these will override the state variables. If these conflict with study parameters, the parameter values from the study will take precedent. Finally, adding a specific state model constant will override general model constants added with add_constants() method.

Parameters:

• state (State) – the state for these parameters

• kwargs – key/value pair of model constant parameters. For example model.add_simulation_variables(my_var1=5, my_var2=1, etc.)

continue_when_simulation_fails(**default_field_values)

Call this method on the model if you want the study to continue when its returns with an error or exit code. By default, It will generate a line of values from -1 to 1 for each required field. The objective will be calculated with these values and the study will continue. If desired custom failure values can be based in this method call to set the value for those given fields. Each of these fields must have the same length.

Parameters:

default_field_values (list or ArrayLike) – keyword arguments to set the default values for failed model evaluations. All arguments passed must have the same number of values.

Note

If the simulation errors out before any data can be returned to MatCal, the entire study will still fail due to not being able to formulate an objective.

property coupling

Returns the type of thermomechanical coupling that the model will use in a simulation. Returns None if uncoupled.

property element_type

The element type being used by the model.

property exodus_output

Returns True if exodus output is activated and variables have been added. Otherwise, returns False.

property failure

Returns the type of failure that the model will use in a simulation. Returns None if there is no failure.

get_target_dir_name(state, parent_dir=None)

Parameters:

• state (State) – the state for the target directory

• parent_dir (str) – optional parent directory where the model files will be built.

Returns:

Returns the name of the directory where the model will run if launched using run().

Return type:

str

property input_file

SIERRA input file object associated with this model.

preprocess(state, target_directory=None)

Prepares the model for the given state and places the model and associated files in an optional target directory.

Parameters:

• state (State) – the state to evaluate the model at.

• target_directory (str) – target location to be built to run the models in

read_temperature_from_boundary_condition_data(field_name='temperature')

Read and apply a temperature history from boundary condition data.

reset_boundary_condition_data()

Remove all previously added boundary condition data and clear any request to read temperature from that data.

This resets the model’s boundary-condition data so new boundary condition data can be added before the next run/setup.

reset_constants()

Removes all model constants that were added with the add_constants() and add_state_constants() methods.

run(state, parameter_collection, target_directory=None)

Runs the model for the given state and the current value of each parameter in the parameter collection.

Parameters:

• state (State) – the state to evaluate the model at.

• parameter_collection (ParameterCollection) – the parameter collection that will populate the parameter in the model

• target_directory (str) – target location to be built to run the models in

Returns:

the results from the simulation

Return type:

SimulatorResults

run_check_input(state, parameter_collection, target_directory=None)

Run with SIERRA ‘–check-input’.

run_check_syntax(state, parameter_collection, target_directory=None)

Run with SIERRA ‘–check-syntax’.

run_in_queue(queue_id: str, time_limit_hours: float, is_test: bool = False)

Indicates that this model will be run on a platform requiring queue submission. Will load platform data relevant to the platform the script is launched from.

Parameters:

• passed_id (str) – A valid ID for the user.

• time_limit_hours (float) – the number of hours the simulation will be allowed to run.

set_allowable_load_drop_factor(value)

The allowable drop in the models “load” field before the simulation is terminated. Note that the actual load field name is model dependent. The simulation will terminate when the following is true:

where max_load is the maximum load in the current load history. The load drop factor must be between 0 and 1.

Parameters:

value (float) – the max allowable load drop fraction

set_boundary_condition_scale_factor(value)

Scales the dependent and independent field in the model deformation function by a constant factor. It must be between 1 and 10.

set_convergence_tolerance(target_relative_residual, target_residual=None, acceptable_relative_residual=None, acceptable_residual=None)

Set the convergence tolerance values for the SIERRA/SM conjugate gradient solver. By default the target residual is two orders of magnitude higher than the target relative residual, and the acceptable relative residual is one order of magnitude higher than the target relative residual. Updating the target relative residual will update the target residual and acceptable relative residual according to these defaults. No acceptable residual is specified by default.

Parameters:

• target_relative_residual (float) – the relative residual for convergence of the SIERRA/SM conjugate gradient solver. Must be between zero and one.

• target_residual (float or None) – the target residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive.

• acceptable_relative_residual (float or None) – the acceptable relative residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive and greater than the target relative residual but less than one.

• acceptable_residual (float or None) – the acceptable residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive and should be greater than the target residual.

set_end_time(end_time)

Set the analysis termination time. This will override the final time determined from the supplied boundary condition and state data.

This is most useful when boundary condition data is a complex load history and only a portion of it needs to be simulated. It may also be useful when trying to simulate stress relaxation after the end of loading.

Parameters:

end_time (float) – Final simulation time.

set_executable(executable)

Set the executable to a user specified executable. This allows for changing the executable after initialization for non-MatCal generated models, but also allows for changing the executable for MatCal generated models to custom compiled executables.

Parameters:

executable (str) – the name of the executable. It should be in your path or an absolute path.

set_minimum_timestep(minimum_timestep)

Sets a minimum timestep such that the simulation will exit cleanly if the timestep is cut to below the user specified minimum value. This is done using SIERRA/SM solution termination.

Parameters:

minimum_timestep (float) – Minimum acceptable timestep.

set_name(new_name)

The name of the model. If the model is run as an external executable, the model will be created and run in a directory with this name. If a name is not provided, a unique identifier is assigned as the mode name.

set_number_of_cores(n_cores)

Sets the number of processors for the model to use.

Parameters:

number_cores (int) – The number of processors needed to run a single state of the model.

set_number_of_time_steps(number_of_steps)

Set the number of load/time steps used in the SIERRA procedure. Due to other model options and adaptive time stepping, this number of time steps is not guaranteed.

Parameters:

number_of_steps (int) – Total number of time steps in the analysis.

set_results_filename(filename, file_type=None)

Sets the name of the model results file.

Parameters:

• filename (str) – the filename of the model results output.

• file_type – the file type of the model results output so the file data importer knows how to read it in. Set to “None” by default, so MatCal will try to infer the type from the file extension.

set_start_time(start_time)

Set the analysis start time. This will override the start time determined from the supplied boundary condition and state data.

This is most useful when boundary condition data is a complex load history and only a portion of it needs to be simulated.

Parameters:

start_time (float) – Initial simulation time.

use_composite_tet_element()

Use the composite tetrahedral total-Lagrange element formulation.

This is a convenience wrapper around use_total_lagrange_element() with use_composite_tet=True.

use_iterative_coupling()

Activates iterative coupling for the model. Iterative coupling can only be used after thermal coupling with staggered coupling has been activated for the model.

use_total_lagrange_element(use_composite_tet=False)

Sets the model to use SIERRA/SM’s total lagrange 8 node hexahedral element with volume average J turned on. Or, optionally, use composite tetrahedral elements for the model.

Parameters:

use_composite_tet (bool) – If True, use the composite tetrahedral version of the formulation; otherwise use the hex formulation.

use_under_integrated_element()

Sets the model to use SIERRA/SM’s under integrated element 8 node hexahedral element with hourglass control and the SIERRA/SM default settings for the element.

class matcal.sierra.models.SolidBarTorsionModel(material, executable='adagio', **kwargs)

MatCal generated SIERRA/SM solid bar torsion test model.

activate_element_death(death_variable='damage', critical_value=0.15, nonlocal_radius=None)

Activates element death for the model. It will kill elements that have the element variable with name “death_variable” reach the critical value. To use nonlocal damage also specify the “nonlocal_radius” and the “initial_value” for the “death_variable”. Both options are needed for nonlocal damage to work correctly.

Parameters:

• death_variable (str) – the name of the element variable that governs element death.

• critical_value (float, str) – the element “death_variable” value at which the element will die. Elements with a “death_variable” value less than the “critical_value” are kept alive. This can also be a string if it is replaced by a MatCal design or state parameter on run time. For example, it could be set to “{critical_value}” and the critical value could be a MatCal study parameter.

• nonlocal_radius (float) – the radius to be used for nonlocal average in the the geometry units. Specifying this parameter to anything but None activates nonlocal averaging for the “death_variable”. This must be greater than zero.

activate_exodus_output(output_step_interval=20)

Enable exodus mesh/results output.

Parameters:

output_step_interval (int) – Write exodus output every output_step_interval steps.

activate_full_field_data_output(full_field_window_width, full_field_window_height)

Activate full field data output for calibrations requiring full field data. The parameters for this method specify the rectangular window where data will be output. Currently, this is only implemented for the RoundUniaxialTensionModel, RectangularUniaxialTensionModel and the RoundNotchedTensionModel. The rectangular window starts at the axial and radial center of the model and goes outward according to the two arguments passed to this function. Since these models feature 1/8th symmetry, the window only covers one octant of the model. The full field window width and height specify the width and height of the 2D window in the octant where the model is built. Any nodes within that width and height of the window will be included in the output.

Parameters:

• full_field_window_width (float) – width of the 2D window for full field data output. The width is aligned with the X direction of the global coordinate system of the model.

• full_field_window_height (float) – height of the 2D window for full field data output. The height is aligned with the Y direction of the global coordinate system of the model and its axis of loading.

activate_implicit_dynamics()

Turns on implicit dynamics for SIERRA/SM. By default, all models are run quasi-statically.

activate_thermal_coupling(thermal_conductivity=None, density=None, specific_heat=None, plastic_work_variable=None, executable='arpeggio')

Activates thermomechanical coupling for the MatCal generated model. If no options are passed, the model assumes adiabatic heating is being added through the material model. For the adiabatic case, an initial temperature is added to the model and additional temperature outputs are provided in the heartbeat and exodus output.

If the additional input arguments for are provided, then staggered coupling through Arpeggio is used. Staggered coupling is setup to advance the solid mechanics solve, pass the displacements and plastic work to the thermal solver, advance the thermal solve, and pass the temperature to the solid mechanics solver before continuing to the next time step.

To activate iterative coupling, use the use_iterative_coupling() method.

Parameters:

• thermal_conductivity (float or None) – Thermal conductivity for the thermal model.

• density (float or None) – Density for the thermal model.

• specific_heat (float or None) – Specific heat for the thermal model.

• plastic_work_variable (str or None) – Element variable name representing plastic work rate passed to the thermal solver as the element volumetric heat source

• executable (str) – Executable used for the coupled solve. This can be an optional path to an custom compiled executable

add_boundary_condition_data(data)

Add boundary condition data (Data or DataCollection) used to determine loading functions for each state.

add_constants(**kwargs)

Add additional constant parameters for the model that will be passed to the model before it is evaluated. These key/value pairs will be passed to all states. If these conflict with state variables, these will override the state variables. If these conflict with study parameters, the parameter values from the study will take precedent.

Parameters:

kwargs (dict(str, str) or dict(str, float)) – key/value pair of model constant parameters. For example model.add_simulation_variables(my_var1=5, my_var2=1, etc.)

add_element_output_variable(*element_variable_names, volume_average=True)

Add element output variables for the model. The method accepts a comma separated list of strings. These should be valid element variables for the model and material model being used.

Parameters:

• element_variable_names (list(str)) – One or more element variable names to output.

• volume_average (bool) – If True, output a volume-averaged form of each element variable when applicable.

add_environment_module(module_name)

Adds an environment module to be loaded before running the model. This must be a valid module on the system where the MatCal study is being run. MatCal will run “module load module_name” for the added module before running this model. If multiple modules are added, they will be loaded in the order they were added.

Parameters:

module_name (str) – the name of the module to be loaded when running the model.

add_executable_argument(argument)

Pass an additional argument directly to the SIERRA executable.

add_nodal_output_variable(*nodal_variable_names)

Add nodal output variables for the model. The method accepts a comma separated list of strings. These should be valid nodal variables for the model and material model being used.

Parameters:

nodal_variable_names (list(str)) – One or more nodal variable names to output.

add_state_constants(state, **kwargs)

Add additional constant parameters for the model that will be passed to the model before it is evaluated for a given state. If the model is not evaluated for this state in the study, these parameters will not be used. If these conflict with experiment state variables, these will override the state variables. If these conflict with study parameters, the parameter values from the study will take precedent. Finally, adding a specific state model constant will override general model constants added with add_constants() method.

Parameters:

• state (State) – the state for these parameters

• kwargs – key/value pair of model constant parameters. For example model.add_simulation_variables(my_var1=5, my_var2=1, etc.)

continue_when_simulation_fails(**default_field_values)

Call this method on the model if you want the study to continue when its returns with an error or exit code. By default, It will generate a line of values from -1 to 1 for each required field. The objective will be calculated with these values and the study will continue. If desired custom failure values can be based in this method call to set the value for those given fields. Each of these fields must have the same length.

Parameters:

default_field_values (list or ArrayLike) – keyword arguments to set the default values for failed model evaluations. All arguments passed must have the same number of values.

Note

If the simulation errors out before any data can be returned to MatCal, the entire study will still fail due to not being able to formulate an objective.

property coupling

Returns the type of thermomechanical coupling that the model will use in a simulation. Returns None if uncoupled.

property element_type

The element type being used by the model.

property exodus_output

Returns True if exodus output is activated and variables have been added. Otherwise, returns False.

property failure

Returns the type of failure that the model will use in a simulation. Returns None if there is no failure.

get_target_dir_name(state, parent_dir=None)

Parameters:

• state (State) – the state for the target directory

• parent_dir (str) – optional parent directory where the model files will be built.

Returns:

Returns the name of the directory where the model will run if launched using run().

Return type:

str

property input_file

SIERRA input file object associated with this model.

preprocess(state, target_directory=None)

Prepares the model for the given state and places the model and associated files in an optional target directory.

Parameters:

• state (State) – the state to evaluate the model at.

• target_directory (str) – target location to be built to run the models in

read_temperature_from_boundary_condition_data(field_name='temperature')

Read and apply a temperature history from boundary condition data.

reset_boundary_condition_data()

Remove all previously added boundary condition data and clear any request to read temperature from that data.

This resets the model’s boundary-condition data so new boundary condition data can be added before the next run/setup.

reset_constants()

Removes all model constants that were added with the add_constants() and add_state_constants() methods.

run(state, parameter_collection, target_directory=None)

Runs the model for the given state and the current value of each parameter in the parameter collection.

Parameters:

• state (State) – the state to evaluate the model at.

• parameter_collection (ParameterCollection) – the parameter collection that will populate the parameter in the model

• target_directory (str) – target location to be built to run the models in

Returns:

the results from the simulation

Return type:

SimulatorResults

run_check_input(state, parameter_collection, target_directory=None)

Run with SIERRA ‘–check-input’.

run_check_syntax(state, parameter_collection, target_directory=None)

Run with SIERRA ‘–check-syntax’.

run_in_queue(queue_id: str, time_limit_hours: float, is_test: bool = False)

Indicates that this model will be run on a platform requiring queue submission. Will load platform data relevant to the platform the script is launched from.

Parameters:

• passed_id (str) – A valid ID for the user.

• time_limit_hours (float) – the number of hours the simulation will be allowed to run.

set_allowable_load_drop_factor(value)

The allowable drop in the models “load” field before the simulation is terminated. Note that the actual load field name is model dependent. The simulation will terminate when the following is true:

where max_load is the maximum load in the current load history. The load drop factor must be between 0 and 1.

Parameters:

value (float) – the max allowable load drop fraction

set_boundary_condition_scale_factor(value)

Scales the dependent and independent field in the model deformation function by a constant factor. It must be between 1 and 10.

set_convergence_tolerance(target_relative_residual, target_residual=None, acceptable_relative_residual=None, acceptable_residual=None)

Set the convergence tolerance values for the SIERRA/SM conjugate gradient solver. By default the target residual is two orders of magnitude higher than the target relative residual, and the acceptable relative residual is one order of magnitude higher than the target relative residual. Updating the target relative residual will update the target residual and acceptable relative residual according to these defaults. No acceptable residual is specified by default.

Parameters:

• target_relative_residual (float) – the relative residual for convergence of the SIERRA/SM conjugate gradient solver. Must be between zero and one.

• target_residual (float or None) – the target residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive.

• acceptable_relative_residual (float or None) – the acceptable relative residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive and greater than the target relative residual but less than one.

• acceptable_residual (float or None) – the acceptable residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive and should be greater than the target residual.

set_end_time(end_time)

Set the analysis termination time. This will override the final time determined from the supplied boundary condition and state data.

This is most useful when boundary condition data is a complex load history and only a portion of it needs to be simulated. It may also be useful when trying to simulate stress relaxation after the end of loading.

Parameters:

end_time (float) – Final simulation time.

set_executable(executable)

Set the executable to a user specified executable. This allows for changing the executable after initialization for non-MatCal generated models, but also allows for changing the executable for MatCal generated models to custom compiled executables.

Parameters:

executable (str) – the name of the executable. It should be in your path or an absolute path.

set_minimum_timestep(minimum_timestep)

Sets a minimum timestep such that the simulation will exit cleanly if the timestep is cut to below the user specified minimum value. This is done using SIERRA/SM solution termination.

Parameters:

minimum_timestep (float) – Minimum acceptable timestep.

set_name(new_name)

The name of the model. If the model is run as an external executable, the model will be created and run in a directory with this name. If a name is not provided, a unique identifier is assigned as the mode name.

set_number_of_cores(n_cores)

Sets the number of processors for the model to use.

Parameters:

number_cores (int) – The number of processors needed to run a single state of the model.

set_number_of_time_steps(number_of_steps)

Set the number of load/time steps used in the SIERRA procedure. Due to other model options and adaptive time stepping, this number of time steps is not guaranteed.

Parameters:

number_of_steps (int) – Total number of time steps in the analysis.

set_results_filename(filename, file_type=None)

Sets the name of the model results file.

Parameters:

• filename (str) – the filename of the model results output.

• file_type – the file type of the model results output so the file data importer knows how to read it in. Set to “None” by default, so MatCal will try to infer the type from the file extension.

set_start_time(start_time)

Set the analysis start time. This will override the start time determined from the supplied boundary condition and state data.

This is most useful when boundary condition data is a complex load history and only a portion of it needs to be simulated.

Parameters:

start_time (float) – Initial simulation time.

use_composite_tet_element()

Use the composite tetrahedral total-Lagrange element formulation.

This is a convenience wrapper around use_total_lagrange_element() with use_composite_tet=True.

use_iterative_coupling()

Activates iterative coupling for the model. Iterative coupling can only be used after thermal coupling with staggered coupling has been activated for the model.

use_total_lagrange_element(use_composite_tet=False)

Sets the model to use SIERRA/SM’s total lagrange 8 node hexahedral element with volume average J turned on. Or, optionally, use composite tetrahedral elements for the model.

Parameters:

use_composite_tet (bool) – If True, use the composite tetrahedral version of the formulation; otherwise use the hex formulation.

use_under_integrated_element()

Sets the model to use SIERRA/SM’s under integrated element 8 node hexahedral element with hourglass control and the SIERRA/SM default settings for the element.

class matcal.sierra.models.TopHatShearModel(material, executable='adagio', **geo_params)

MatCal generated SIERRA/SM top hat shear test model.

property self_contact

Returns True if self contact is on for the model. Otherwise, returns False.

activate_full_field_data_output()

Not implemented for this model.

activate_element_death(death_variable='damage', critical_value=0.15, nonlocal_radius=None)

Activates element death for the model. It will kill elements that have the element variable with name “death_variable” reach the critical value. To use nonlocal damage also specify the “nonlocal_radius” and the “initial_value” for the “death_variable”. Both options are needed for nonlocal damage to work correctly.

Parameters:

• death_variable (str) – the name of the element variable that governs element death.

• critical_value (float, str) – the element “death_variable” value at which the element will die. Elements with a “death_variable” value less than the “critical_value” are kept alive. This can also be a string if it is replaced by a MatCal design or state parameter on run time. For example, it could be set to “{critical_value}” and the critical value could be a MatCal study parameter.

• nonlocal_radius (float) – the radius to be used for nonlocal average in the the geometry units. Specifying this parameter to anything but None activates nonlocal averaging for the “death_variable”. This must be greater than zero.

activate_exodus_output(output_step_interval=20)

Enable exodus mesh/results output.

Parameters:

output_step_interval (int) – Write exodus output every output_step_interval steps.

activate_implicit_dynamics()

Turns on implicit dynamics for SIERRA/SM. By default, all models are run quasi-statically.

activate_self_contact(friction_coefficient=0.3)

Activates self-contact for the model.

Parameters:

friction_coefficient (float) – the desired friction coefficient for self-contact

activate_thermal_coupling(thermal_conductivity=None, density=None, specific_heat=None, plastic_work_variable=None, executable='arpeggio')

Activates thermomechanical coupling for the MatCal generated model. If no options are passed, the model assumes adiabatic heating is being added through the material model. For the adiabatic case, an initial temperature is added to the model and additional temperature outputs are provided in the heartbeat and exodus output.

If the additional input arguments for are provided, then staggered coupling through Arpeggio is used. Staggered coupling is setup to advance the solid mechanics solve, pass the displacements and plastic work to the thermal solver, advance the thermal solve, and pass the temperature to the solid mechanics solver before continuing to the next time step.

To activate iterative coupling, use the use_iterative_coupling() method.

Parameters:

• thermal_conductivity (float or None) – Thermal conductivity for the thermal model.

• density (float or None) – Density for the thermal model.

• specific_heat (float or None) – Specific heat for the thermal model.

• plastic_work_variable (str or None) – Element variable name representing plastic work rate passed to the thermal solver as the element volumetric heat source

• executable (str) – Executable used for the coupled solve. This can be an optional path to an custom compiled executable

add_boundary_condition_data(data)

Add boundary condition data (Data or DataCollection) used to determine loading functions for each state.

add_constants(**kwargs)

Add additional constant parameters for the model that will be passed to the model before it is evaluated. These key/value pairs will be passed to all states. If these conflict with state variables, these will override the state variables. If these conflict with study parameters, the parameter values from the study will take precedent.

Parameters:

kwargs (dict(str, str) or dict(str, float)) – key/value pair of model constant parameters. For example model.add_simulation_variables(my_var1=5, my_var2=1, etc.)

add_element_output_variable(*element_variable_names, volume_average=True)

Add element output variables for the model. The method accepts a comma separated list of strings. These should be valid element variables for the model and material model being used.

Parameters:

• element_variable_names (list(str)) – One or more element variable names to output.

• volume_average (bool) – If True, output a volume-averaged form of each element variable when applicable.

add_environment_module(module_name)

Adds an environment module to be loaded before running the model. This must be a valid module on the system where the MatCal study is being run. MatCal will run “module load module_name” for the added module before running this model. If multiple modules are added, they will be loaded in the order they were added.

Parameters:

module_name (str) – the name of the module to be loaded when running the model.

add_executable_argument(argument)

Pass an additional argument directly to the SIERRA executable.

add_nodal_output_variable(*nodal_variable_names)

Add nodal output variables for the model. The method accepts a comma separated list of strings. These should be valid nodal variables for the model and material model being used.

Parameters:

nodal_variable_names (list(str)) – One or more nodal variable names to output.

add_state_constants(state, **kwargs)

Add additional constant parameters for the model that will be passed to the model before it is evaluated for a given state. If the model is not evaluated for this state in the study, these parameters will not be used. If these conflict with experiment state variables, these will override the state variables. If these conflict with study parameters, the parameter values from the study will take precedent. Finally, adding a specific state model constant will override general model constants added with add_constants() method.

Parameters:

• state (State) – the state for these parameters

• kwargs – key/value pair of model constant parameters. For example model.add_simulation_variables(my_var1=5, my_var2=1, etc.)

continue_when_simulation_fails(**default_field_values)

Call this method on the model if you want the study to continue when its returns with an error or exit code. By default, It will generate a line of values from -1 to 1 for each required field. The objective will be calculated with these values and the study will continue. If desired custom failure values can be based in this method call to set the value for those given fields. Each of these fields must have the same length.

Parameters:

default_field_values (list or ArrayLike) – keyword arguments to set the default values for failed model evaluations. All arguments passed must have the same number of values.

Note

If the simulation errors out before any data can be returned to MatCal, the entire study will still fail due to not being able to formulate an objective.

property coupling

Returns the type of thermomechanical coupling that the model will use in a simulation. Returns None if uncoupled.

property element_type

The element type being used by the model.

property exodus_output

Returns True if exodus output is activated and variables have been added. Otherwise, returns False.

property failure

Returns the type of failure that the model will use in a simulation. Returns None if there is no failure.

get_target_dir_name(state, parent_dir=None)

Parameters:

• state (State) – the state for the target directory

• parent_dir (str) – optional parent directory where the model files will be built.

Returns:

Returns the name of the directory where the model will run if launched using run().

Return type:

str

property input_file

SIERRA input file object associated with this model.

preprocess(state, target_directory=None)

Prepares the model for the given state and places the model and associated files in an optional target directory.

Parameters:

• state (State) – the state to evaluate the model at.

• target_directory (str) – target location to be built to run the models in

read_temperature_from_boundary_condition_data(field_name='temperature')

Read and apply a temperature history from boundary condition data.

reset_boundary_condition_data()

Remove all previously added boundary condition data and clear any request to read temperature from that data.

This resets the model’s boundary-condition data so new boundary condition data can be added before the next run/setup.

reset_constants()

Removes all model constants that were added with the add_constants() and add_state_constants() methods.

run(state, parameter_collection, target_directory=None)

Runs the model for the given state and the current value of each parameter in the parameter collection.

Parameters:

• state (State) – the state to evaluate the model at.

• parameter_collection (ParameterCollection) – the parameter collection that will populate the parameter in the model

• target_directory (str) – target location to be built to run the models in

Returns:

the results from the simulation

Return type:

SimulatorResults

run_check_input(state, parameter_collection, target_directory=None)

Run with SIERRA ‘–check-input’.

run_check_syntax(state, parameter_collection, target_directory=None)

Run with SIERRA ‘–check-syntax’.

run_in_queue(queue_id: str, time_limit_hours: float, is_test: bool = False)

Indicates that this model will be run on a platform requiring queue submission. Will load platform data relevant to the platform the script is launched from.

Parameters:

• passed_id (str) – A valid ID for the user.

• time_limit_hours (float) – the number of hours the simulation will be allowed to run.

set_allowable_load_drop_factor(value)

The allowable drop in the models “load” field before the simulation is terminated. Note that the actual load field name is model dependent. The simulation will terminate when the following is true:

where max_load is the maximum load in the current load history. The load drop factor must be between 0 and 1.

Parameters:

value (float) – the max allowable load drop fraction

set_boundary_condition_scale_factor(value)

Scales the dependent and independent field in the model deformation function by a constant factor. It must be between 1 and 10.

set_contact_convergence_tolerance(target_relative_residual, target_residual=None, acceptable_relative_residual=None, acceptable_residual=None)

Set the convergence tolerance values for the control contact block. By default the target residual and acceptable relative residual are set to one order of magnitude higher than the target relative residual. Updating the target relative residual will update the target residual and acceptable relative residual according to these defaults.

The conjugate gradient solver settings will also be updated such that its target relative residual is one order of magnitude less than the contact target relative residual, its target residual is one order of magnitude higher than the contact target relative and its acceptable relative residual is set to 10. To specify custom CG solver convergence tolerances with contact, call set_convergence_tolerance() after calling this method.

No acceptable residual is specified for either solver.

Parameters:

• target_relative_residual (float) – the relative residual for convergence of SIERRA/SM control contact. Must be between zero and one.

• target_residual (float) – the target residual for convergence of SIERRA/SM control contact. Must be positive.

• acceptable_relative_residual (float) – the acceptable relative residual for convergence of SIERRA/SM control contact. Must be positive and greater than the target relative residual.

• acceptable_residual (float) – the acceptable residual for convergence of SIERRA/SM control contact. Must be positive and should be greater than the target residual.

set_convergence_tolerance(target_relative_residual, target_residual=None, acceptable_relative_residual=None, acceptable_residual=None)

Set the convergence tolerance values for the SIERRA/SM conjugate gradient solver. By default the target residual is two orders of magnitude higher than the target relative residual, and the acceptable relative residual is one order of magnitude higher than the target relative residual. Updating the target relative residual will update the target residual and acceptable relative residual according to these defaults. No acceptable residual is specified by default.

Parameters:

• target_relative_residual (float) – the relative residual for convergence of the SIERRA/SM conjugate gradient solver. Must be between zero and one.

• target_residual (float or None) – the target residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive.

• acceptable_relative_residual (float or None) – the acceptable relative residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive and greater than the target relative residual but less than one.

• acceptable_residual (float or None) – the acceptable residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive and should be greater than the target residual.

set_end_time(end_time)

Set the analysis termination time. This will override the final time determined from the supplied boundary condition and state data.

This is most useful when boundary condition data is a complex load history and only a portion of it needs to be simulated. It may also be useful when trying to simulate stress relaxation after the end of loading.

Parameters:

end_time (float) – Final simulation time.

set_executable(executable)

Set the executable to a user specified executable. This allows for changing the executable after initialization for non-MatCal generated models, but also allows for changing the executable for MatCal generated models to custom compiled executables.

Parameters:

executable (str) – the name of the executable. It should be in your path or an absolute path.

set_minimum_timestep(minimum_timestep)

Sets a minimum timestep such that the simulation will exit cleanly if the timestep is cut to below the user specified minimum value. This is done using SIERRA/SM solution termination.

Parameters:

minimum_timestep (float) – Minimum acceptable timestep.

set_name(new_name)

The name of the model. If the model is run as an external executable, the model will be created and run in a directory with this name. If a name is not provided, a unique identifier is assigned as the mode name.

set_number_of_cores(n_cores)

Sets the number of processors for the model to use.

Parameters:

number_cores (int) – The number of processors needed to run a single state of the model.

set_number_of_time_steps(number_of_steps)

Set the number of load/time steps used in the SIERRA procedure. Due to other model options and adaptive time stepping, this number of time steps is not guaranteed.

Parameters:

number_of_steps (int) – Total number of time steps in the analysis.

set_results_filename(filename, file_type=None)

Sets the name of the model results file.

Parameters:

• filename (str) – the filename of the model results output.

• file_type – the file type of the model results output so the file data importer knows how to read it in. Set to “None” by default, so MatCal will try to infer the type from the file extension.

set_start_time(start_time)

Set the analysis start time. This will override the start time determined from the supplied boundary condition and state data.

This is most useful when boundary condition data is a complex load history and only a portion of it needs to be simulated.

Parameters:

start_time (float) – Initial simulation time.

use_composite_tet_element()

Use the composite tetrahedral total-Lagrange element formulation.

This is a convenience wrapper around use_total_lagrange_element() with use_composite_tet=True.

use_iterative_coupling()

Activates iterative coupling for the model. Iterative coupling can only be used after thermal coupling with staggered coupling has been activated for the model.

use_total_lagrange_element(use_composite_tet=False)

Sets the model to use SIERRA/SM’s total lagrange 8 node hexahedral element with volume average J turned on. Or, optionally, use composite tetrahedral elements for the model.

Parameters:

use_composite_tet (bool) – If True, use the composite tetrahedral version of the formulation; otherwise use the hex formulation.

use_under_integrated_element()

Sets the model to use SIERRA/SM’s under integrated element 8 node hexahedral element with hourglass control and the SIERRA/SM default settings for the element.

class matcal.sierra.models.VFMUniaxialTensionHexModel(material, surface_mesh_filename, thickness, **kwargs)

VFM model using a disconnected (exploded) hex mesh.

Parameters:

• material (matcal.sierra.material.Material) – Material model for the solid mechanics region.

• mesh (str or FieldGridBase) – surface mesh filename (or FieldGridBase) used for VFM meshing.

• thickness (float) – specimen thickness.

activate_thermal_coupling(*args, **kwargs)

Disconnected elements support only adiabatic heating (no conduction).

use_iterative_coupling(*args, **kwargs)

Activates iterative coupling for the model. Iterative coupling can only be used after thermal coupling with staggered coupling has been activated for the model.

activate_element_death(*args, **kwargs)

Element death is allowed but not recommended due to loss of material.

activate_exodus_output()

By default, output is activated and output at every step. Output step interval cannot be adjusted.

add_boundary_condition_data(data)

Add boundary condition data (Data or DataCollection) used to determine loading functions for each state.

add_constants(**kwargs)

Add additional constant parameters for the model that will be passed to the model before it is evaluated. These key/value pairs will be passed to all states. If these conflict with state variables, these will override the state variables. If these conflict with study parameters, the parameter values from the study will take precedent.

Parameters:

kwargs (dict(str, str) or dict(str, float)) – key/value pair of model constant parameters. For example model.add_simulation_variables(my_var1=5, my_var2=1, etc.)

add_element_output_variable(*element_variable_names, volume_average=True)

Add element output variables for the model. The method accepts a comma separated list of strings. These should be valid element variables for the model and material model being used.

Parameters:

• element_variable_names (list(str)) – One or more element variable names to output.

• volume_average (bool) – If True, output a volume-averaged form of each element variable when applicable.

add_environment_module(module_name)

Adds an environment module to be loaded before running the model. This must be a valid module on the system where the MatCal study is being run. MatCal will run “module load module_name” for the added module before running this model. If multiple modules are added, they will be loaded in the order they were added.

Parameters:

module_name (str) – the name of the module to be loaded when running the model.

add_executable_argument(argument)

Pass an additional argument directly to the SIERRA executable.

add_nodal_output_variable(*nodal_variable_names)

Add nodal output variables for the model. The method accepts a comma separated list of strings. These should be valid nodal variables for the model and material model being used.

Parameters:

nodal_variable_names (list(str)) – One or more nodal variable names to output.

add_state_constants(state, **kwargs)

Add additional constant parameters for the model that will be passed to the model before it is evaluated for a given state. If the model is not evaluated for this state in the study, these parameters will not be used. If these conflict with experiment state variables, these will override the state variables. If these conflict with study parameters, the parameter values from the study will take precedent. Finally, adding a specific state model constant will override general model constants added with add_constants() method.

Parameters:

• state (State) – the state for these parameters

• kwargs – key/value pair of model constant parameters. For example model.add_simulation_variables(my_var1=5, my_var2=1, etc.)

continue_when_simulation_fails(**default_field_values)

Call this method on the model if you want the study to continue when its returns with an error or exit code. By default, It will generate a line of values from -1 to 1 for each required field. The objective will be calculated with these values and the study will continue. If desired custom failure values can be based in this method call to set the value for those given fields. Each of these fields must have the same length.

Parameters:

default_field_values (list or ArrayLike) – keyword arguments to set the default values for failed model evaluations. All arguments passed must have the same number of values.

Note

If the simulation errors out before any data can be returned to MatCal, the entire study will still fail due to not being able to formulate an objective.

property coupling

Returns the type of thermomechanical coupling that the model will use in a simulation. Returns None if uncoupled.

property element_type

The element type being used by the model.

property exodus_output

Returns True if exodus output is activated and variables have been added. Otherwise, returns False.

property failure

Returns the type of failure that the model will use in a simulation. Returns None if there is no failure.

get_target_dir_name(state, parent_dir=None)

Parameters:

• state (State) – the state for the target directory

• parent_dir (str) – optional parent directory where the model files will be built.

Returns:

Returns the name of the directory where the model will run if launched using run().

Return type:

str

get_thickness()

Returns thickness as provided on instantiation.

property input_file

SIERRA input file object associated with this model.

preprocess(state, target_directory=None)

Prepares the model for the given state and places the model and associated files in an optional target directory.

Parameters:

• state (State) – the state to evaluate the model at.

• target_directory (str) – target location to be built to run the models in

read_temperature_from_boundary_condition_data(field_name='temperature')

Read and apply a temperature history from boundary condition data.

reset_boundary_condition_data()

Remove all previously added boundary condition data and clear any request to read temperature from that data.

This resets the model’s boundary-condition data so new boundary condition data can be added before the next run/setup.

reset_constants()

Removes all model constants that were added with the add_constants() and add_state_constants() methods.

run(state, parameter_collection, target_directory=None)

Runs the model for the given state and the current value of each parameter in the parameter collection.

Parameters:

• state (State) – the state to evaluate the model at.

• parameter_collection (ParameterCollection) – the parameter collection that will populate the parameter in the model

• target_directory (str) – target location to be built to run the models in

Returns:

the results from the simulation

Return type:

SimulatorResults

run_check_input(state, parameter_collection, target_directory=None)

Run with SIERRA ‘–check-input’.

run_check_syntax(state, parameter_collection, target_directory=None)

Run with SIERRA ‘–check-syntax’.

run_in_queue(queue_id: str, time_limit_hours: float, is_test: bool = False)

Indicates that this model will be run on a platform requiring queue submission. Will load platform data relevant to the platform the script is launched from.

Parameters:

• passed_id (str) – A valid ID for the user.

• time_limit_hours (float) – the number of hours the simulation will be allowed to run.

set_boundary_condition_scale_factor(*args, **kwargs)

Scales the dependent and independent field in the model deformation function by a constant factor. It must be between 1 and 10.

set_convergence_tolerance(target_relative_residual, target_residual=None, acceptable_relative_residual=None, acceptable_residual=None)

Set the convergence tolerance values for the SIERRA/SM conjugate gradient solver. By default the target residual is two orders of magnitude higher than the target relative residual, and the acceptable relative residual is one order of magnitude higher than the target relative residual. Updating the target relative residual will update the target residual and acceptable relative residual according to these defaults. No acceptable residual is specified by default.

Parameters:

• target_relative_residual (float) – the relative residual for convergence of the SIERRA/SM conjugate gradient solver. Must be between zero and one.

• target_residual (float or None) – the target residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive.

• acceptable_relative_residual (float or None) – the acceptable relative residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive and greater than the target relative residual but less than one.

• acceptable_residual (float or None) – the acceptable residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive and should be greater than the target residual.

set_displacement_field_names(x_displacement, y_displacement)

Set the field names in the boundary FieldData used for x/y displacements.

set_end_time(end_time)

Set the analysis termination time. This will override the final time determined from the supplied boundary condition and state data.

This is most useful when boundary condition data is a complex load history and only a portion of it needs to be simulated. It may also be useful when trying to simulate stress relaxation after the end of loading.

Parameters:

end_time (float) – Final simulation time.

set_executable(executable)

Set the executable to a user specified executable. This allows for changing the executable after initialization for non-MatCal generated models, but also allows for changing the executable for MatCal generated models to custom compiled executables.

Parameters:

executable (str) – the name of the executable. It should be in your path or an absolute path.

set_mapping_parameters(polynomial_order: int = 1, search_radius_multiplier: float = 2.75)

Set the mapping parameters for Compadre GMLS.

set_minimum_timestep(minimum_timestep)

Sets a minimum timestep such that the simulation will exit cleanly if the timestep is cut to below the user specified minimum value. This is done using SIERRA/SM solution termination.

Parameters:

minimum_timestep (float) – Minimum acceptable timestep.

set_name(new_name)

The name of the model. If the model is run as an external executable, the model will be created and run in a directory with this name. If a name is not provided, a unique identifier is assigned as the mode name.

set_number_of_cores(n_cores)

Sets the number of processors for the model to use.

Parameters:

number_cores (int) – The number of processors needed to run a single state of the model.

set_number_of_time_steps(number_of_steps)

Set the number of load/time steps used in the SIERRA procedure. Due to other model options and adaptive time stepping, this number of time steps is not guaranteed.

Parameters:

number_of_steps (int) – Total number of time steps in the analysis.

set_results_filename(filename, file_type=None)

Sets the name of the model results file.

Parameters:

• filename (str) – the filename of the model results output.

• file_type – the file type of the model results output so the file data importer knows how to read it in. Set to “None” by default, so MatCal will try to infer the type from the file extension.

set_start_time(start_time)

Set the analysis start time. This will override the start time determined from the supplied boundary condition and state data.

This is most useful when boundary condition data is a complex load history and only a portion of it needs to be simulated.

Parameters:

start_time (float) – Initial simulation time.

use_composite_tet_element()

Use the composite tetrahedral total-Lagrange element formulation.

This is a convenience wrapper around use_total_lagrange_element() with use_composite_tet=True.

use_total_lagrange_element(use_composite_tet=False)

Sets the model to use SIERRA/SM’s total lagrange 8 node hexahedral element with volume average J turned on. Or, optionally, use composite tetrahedral elements for the model.

Parameters:

use_composite_tet (bool) – If True, use the composite tetrahedral version of the formulation; otherwise use the hex formulation.

use_under_integrated_element()

Sets the model to use SIERRA/SM’s under integrated element 8 node hexahedral element with hourglass control and the SIERRA/SM default settings for the element.

class matcal.sierra.models.VFMUniaxialTensionConnectedHexModel(material, surface_mesh_filename, thickness, **kwargs)

VFM model using a connected hex mesh and half-thickness symmetry, enabling conduction coupling.

Parameters:

• material (matcal.sierra.material.Material) – Material model for the solid mechanics region.

• mesh (str or FieldGridBase) – surface mesh filename (or FieldGridBase) used for VFM meshing.

• thickness (float) – specimen thickness.

get_thickness()

Return full thickness (undo symmetry halving).

activate_element_death(*args, **kwargs)

Element death is allowed but not recommended due to loss of material.

activate_exodus_output()

By default, output is activated and output at every step. Output step interval cannot be adjusted.

activate_thermal_coupling(thermal_conductivity=None, density=None, specific_heat=None, plastic_work_variable=None, executable='arpeggio')

Activates thermomechanical coupling for the MatCal generated model. If no options are passed, the model assumes adiabatic heating is being added through the material model. For the adiabatic case, an initial temperature is added to the model and additional temperature outputs are provided in the heartbeat and exodus output.

If the additional input arguments for are provided, then staggered coupling through Arpeggio is used. Staggered coupling is setup to advance the solid mechanics solve, pass the displacements and plastic work to the thermal solver, advance the thermal solve, and pass the temperature to the solid mechanics solver before continuing to the next time step.

To activate iterative coupling, use the use_iterative_coupling() method.

Parameters:

• thermal_conductivity (float or None) – Thermal conductivity for the thermal model.

• density (float or None) – Density for the thermal model.

• specific_heat (float or None) – Specific heat for the thermal model.

• plastic_work_variable (str or None) – Element variable name representing plastic work rate passed to the thermal solver as the element volumetric heat source

• executable (str) – Executable used for the coupled solve. This can be an optional path to an custom compiled executable

add_boundary_condition_data(data)

Add boundary condition data (Data or DataCollection) used to determine loading functions for each state.

add_constants(**kwargs)

Add additional constant parameters for the model that will be passed to the model before it is evaluated. These key/value pairs will be passed to all states. If these conflict with state variables, these will override the state variables. If these conflict with study parameters, the parameter values from the study will take precedent.

Parameters:

kwargs (dict(str, str) or dict(str, float)) – key/value pair of model constant parameters. For example model.add_simulation_variables(my_var1=5, my_var2=1, etc.)

add_element_output_variable(*element_variable_names, volume_average=True)

Add element output variables for the model. The method accepts a comma separated list of strings. These should be valid element variables for the model and material model being used.

Parameters:

• element_variable_names (list(str)) – One or more element variable names to output.

• volume_average (bool) – If True, output a volume-averaged form of each element variable when applicable.

add_environment_module(module_name)

Adds an environment module to be loaded before running the model. This must be a valid module on the system where the MatCal study is being run. MatCal will run “module load module_name” for the added module before running this model. If multiple modules are added, they will be loaded in the order they were added.

Parameters:

module_name (str) – the name of the module to be loaded when running the model.

add_executable_argument(argument)

Pass an additional argument directly to the SIERRA executable.

add_nodal_output_variable(*nodal_variable_names)

Add nodal output variables for the model. The method accepts a comma separated list of strings. These should be valid nodal variables for the model and material model being used.

Parameters:

nodal_variable_names (list(str)) – One or more nodal variable names to output.

add_state_constants(state, **kwargs)

Add additional constant parameters for the model that will be passed to the model before it is evaluated for a given state. If the model is not evaluated for this state in the study, these parameters will not be used. If these conflict with experiment state variables, these will override the state variables. If these conflict with study parameters, the parameter values from the study will take precedent. Finally, adding a specific state model constant will override general model constants added with add_constants() method.

Parameters:

• state (State) – the state for these parameters

• kwargs – key/value pair of model constant parameters. For example model.add_simulation_variables(my_var1=5, my_var2=1, etc.)

continue_when_simulation_fails(**default_field_values)

Call this method on the model if you want the study to continue when its returns with an error or exit code. By default, It will generate a line of values from -1 to 1 for each required field. The objective will be calculated with these values and the study will continue. If desired custom failure values can be based in this method call to set the value for those given fields. Each of these fields must have the same length.

Parameters:

default_field_values (list or ArrayLike) – keyword arguments to set the default values for failed model evaluations. All arguments passed must have the same number of values.

Note

If the simulation errors out before any data can be returned to MatCal, the entire study will still fail due to not being able to formulate an objective.

property coupling

Returns the type of thermomechanical coupling that the model will use in a simulation. Returns None if uncoupled.

property element_type

The element type being used by the model.

property exodus_output

Returns True if exodus output is activated and variables have been added. Otherwise, returns False.

property failure

Returns the type of failure that the model will use in a simulation. Returns None if there is no failure.

get_target_dir_name(state, parent_dir=None)

Parameters:

• state (State) – the state for the target directory

• parent_dir (str) – optional parent directory where the model files will be built.

Returns:

Returns the name of the directory where the model will run if launched using run().

Return type:

str

property input_file

SIERRA input file object associated with this model.

preprocess(state, target_directory=None)

Prepares the model for the given state and places the model and associated files in an optional target directory.

Parameters:

• state (State) – the state to evaluate the model at.

• target_directory (str) – target location to be built to run the models in

read_temperature_from_boundary_condition_data(field_name='temperature')

Read and apply a temperature history from boundary condition data.

reset_boundary_condition_data()

Remove all previously added boundary condition data and clear any request to read temperature from that data.

This resets the model’s boundary-condition data so new boundary condition data can be added before the next run/setup.

reset_constants()

Removes all model constants that were added with the add_constants() and add_state_constants() methods.

run(state, parameter_collection, target_directory=None)

Runs the model for the given state and the current value of each parameter in the parameter collection.

Parameters:

• state (State) – the state to evaluate the model at.

• parameter_collection (ParameterCollection) – the parameter collection that will populate the parameter in the model

• target_directory (str) – target location to be built to run the models in

Returns:

the results from the simulation

Return type:

SimulatorResults

run_check_input(state, parameter_collection, target_directory=None)

Run with SIERRA ‘–check-input’.

run_check_syntax(state, parameter_collection, target_directory=None)

Run with SIERRA ‘–check-syntax’.

run_in_queue(queue_id: str, time_limit_hours: float, is_test: bool = False)

Indicates that this model will be run on a platform requiring queue submission. Will load platform data relevant to the platform the script is launched from.

Parameters:

• passed_id (str) – A valid ID for the user.

• time_limit_hours (float) – the number of hours the simulation will be allowed to run.

set_boundary_condition_scale_factor(*args, **kwargs)

Scales the dependent and independent field in the model deformation function by a constant factor. It must be between 1 and 10.

set_convergence_tolerance(target_relative_residual, target_residual=None, acceptable_relative_residual=None, acceptable_residual=None)

Set the convergence tolerance values for the SIERRA/SM conjugate gradient solver. By default the target residual is two orders of magnitude higher than the target relative residual, and the acceptable relative residual is one order of magnitude higher than the target relative residual. Updating the target relative residual will update the target residual and acceptable relative residual according to these defaults. No acceptable residual is specified by default.

Parameters:

• target_relative_residual (float) – the relative residual for convergence of the SIERRA/SM conjugate gradient solver. Must be between zero and one.

• target_residual (float or None) – the target residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive.

• acceptable_relative_residual (float or None) – the acceptable relative residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive and greater than the target relative residual but less than one.

• acceptable_residual (float or None) – the acceptable residual for convergence of the SIERRA/SM conjugate gradient solver. Must be positive and should be greater than the target residual.

set_displacement_field_names(x_displacement, y_displacement)

Set the field names in the boundary FieldData used for x/y displacements.

set_end_time(end_time)

Set the analysis termination time. This will override the final time determined from the supplied boundary condition and state data.

This is most useful when boundary condition data is a complex load history and only a portion of it needs to be simulated. It may also be useful when trying to simulate stress relaxation after the end of loading.

Parameters:

end_time (float) – Final simulation time.

set_executable(executable)

Set the executable to a user specified executable. This allows for changing the executable after initialization for non-MatCal generated models, but also allows for changing the executable for MatCal generated models to custom compiled executables.

Parameters:

executable (str) – the name of the executable. It should be in your path or an absolute path.

set_mapping_parameters(polynomial_order: int = 1, search_radius_multiplier: float = 2.75)

Set the mapping parameters for Compadre GMLS.

set_minimum_timestep(minimum_timestep)

Sets a minimum timestep such that the simulation will exit cleanly if the timestep is cut to below the user specified minimum value. This is done using SIERRA/SM solution termination.

Parameters:

minimum_timestep (float) – Minimum acceptable timestep.

set_name(new_name)

The name of the model. If the model is run as an external executable, the model will be created and run in a directory with this name. If a name is not provided, a unique identifier is assigned as the mode name.

set_number_of_cores(n_cores)

Sets the number of processors for the model to use.

Parameters:

number_cores (int) – The number of processors needed to run a single state of the model.

set_number_of_time_steps(number_of_steps)

Set the number of load/time steps used in the SIERRA procedure. Due to other model options and adaptive time stepping, this number of time steps is not guaranteed.

Parameters:

number_of_steps (int) – Total number of time steps in the analysis.

set_results_filename(filename, file_type=None)

Sets the name of the model results file.

Parameters:

• filename (str) – the filename of the model results output.

• file_type – the file type of the model results output so the file data importer knows how to read it in. Set to “None” by default, so MatCal will try to infer the type from the file extension.

set_start_time(start_time)

Set the analysis start time. This will override the start time determined from the supplied boundary condition and state data.

This is most useful when boundary condition data is a complex load history and only a portion of it needs to be simulated.

Parameters:

start_time (float) – Initial simulation time.

use_composite_tet_element()

Use the composite tetrahedral total-Lagrange element formulation.

This is a convenience wrapper around use_total_lagrange_element() with use_composite_tet=True.

use_iterative_coupling()

Activates iterative coupling for the model. Iterative coupling can only be used after thermal coupling with staggered coupling has been activated for the model.

use_total_lagrange_element(use_composite_tet=False)

Sets the model to use SIERRA/SM’s total lagrange 8 node hexahedral element with volume average J turned on. Or, optionally, use composite tetrahedral elements for the model.

Parameters:

use_composite_tet (bool) – If True, use the composite tetrahedral version of the formulation; otherwise use the hex formulation.

use_under_integrated_element()

Sets the model to use SIERRA/SM’s under integrated element 8 node hexahedral element with hourglass control and the SIERRA/SM default settings for the element.