matcal.core.models

The models module includes base classes and helper classes for MatCal models. It also includes the user facing PythonModel.

Classes

AdditionalFileCopyPreprocessor()	Model preprocessor not intended for users.
InputFileCopyPreprocessor()	Model preprocessor not intended for users.
MatCalSurrogateModel(surrogate)	Generates a MatCal model from an instantiated MatCal surrogate model
MeshComposer()	Base class for mesh composers not intended for users.
MeshDecomposer()	Base class for mesh decomposers not intended for users.
PythonModel(python_function[, filename, ...])	Use a python function as a model to be used in an evaluation set for a MatCal study.
UserExecutableModel(executable, *arguments)	Run any executable accessible in the path as a model to be used in an evaluation set for a MatCal study.

class matcal.core.models.MeshDecomposer

Base class for mesh decomposers not intended for users.

class matcal.core.models.MeshComposer

Base class for mesh composers not intended for users.

class matcal.core.models.ModelPreprocessorBase

Base class for model preprocessors not intended for users.

class matcal.core.models.AdditionalFileCopyPreprocessor

Model preprocessor not intended for users.

class matcal.core.models.InputFileCopyPreprocessor

Model preprocessor not intended for users.

class matcal.core.models.ModelBase(executable, **kwargs)

Base class for models not intended for users.

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.

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

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

reset_constants()

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

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

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.

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.

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_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.core.models.PythonModel(python_function, filename=None, field_coordinates=None, pass_evaluation_number=False, pass_params_by_category=False)

Use a python function as a model to be used in an evaluation set for a MatCal study. The model takes two forms of input:

1. Pass in a locally defined function for the parameter python_function.

2. Pass in the name of the python function for the parameter python_function as a string and a string which gives the full path of the file where the python function is defined. Since MatCal will import from this file, it is recommended that nothing is defined or executed in the global names space of that file.

The python function should take in all parameters being calibrated as input parameters. It should return a dictionary with keys being the field names of the responses of interest required by the objectives applied to the model and the values for each key should be 1d arrays of the values corresponding to the responses.

Parameters:

• python_function – locally defined function or name of function defined in another file.

• filename (str) – Name of the file where the function is defined if not in the MatCal python input file.

• filename – Name of the file where the function is defined if not in the MatCal python input file.

• field_coordinates (dict) – Provide the coordinate locations for field data. The coordinates must be in the experimental data coordinate system.

• pass_evaluation_number (bool) – If True, the current evaluation number is passed to the user function as the keyword argument evaluation_number.

• pass_params_by_category (bool) – If True, the parameters are passed in as dictionaries according to parameter category. To read in the parameters the python function should expect the three keyword arguments model_parameters, model_constants and state_parameters. These will be three dictionaries where model_parameters are the study parameters and the other are parameters as described by their keywords. Otherwise each parameter is passed as keyword arguments as follows model_param_1=mpvalue_1, ... , model_const_1=mcvalue_1, ... , state_param_1=svalue_1 and order is not guaranteed.

Warning

When pass_params_by_category=True the MatCal parameter‑type precedence logic (which determines whether a value comes from a study parameter, a state variable, or a model constant) is not applied. Consequently, any user‑provided constants may override study parameters without the usual precedence checks.

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_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_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.core.models.MatCalSurrogateModel(surrogate: MatCalSurrogateBase)

Generates a MatCal model from an instantiated MatCal surrogate model

Parameters:

surrogate (MatCalSurrogateBase) – The MatCal surrogate to use as the base for a model

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_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_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.core.models.UserExecutableModel(executable, *arguments, results_filename=None, results_file_type=None)

Run any executable accessible in the path as a model to be used in an evaluation set for a MatCal study.

If any files are needed in order for the model to run, they can be added using add_necessary_files(). These files will be copied to a templates folder and then linked into the working directory where the model executable is launched for each evaluation.

Parameters:

• executable (str) – The executable to be run. This can be an executable found in path or the full path to an executable should be provided.

• arguments (str) – Arguments to the executable that are required for the executable to run correctly. This can be a comma separated list or unpacked list of strings.

• results_filename (str) – The filename where the model results will be stored.

• results_file_type – The file type for the results file. This should be a valid file type for the FileData() function.

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_necessary_files(*needed_files)

Add files to the working directory of the model that are needed for the model to successfully run.

Parameters:

needed_files (list(str)) – additional files or directories that need to be in the working directory of the model so that it can run. These are include files that the main input file may need or mesh and other data files.

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