NeurAM: Nonlinear dimensionality reduction through neural active manifolds

Introduction

Installation

To install the dependencies in a conda enviroment, run the following:

conda env create -f environment.yml

Activate the environment as follows:

conda activate neuram

Usage

python src/main.py <path_to_input_file.json>

Modes of operation

The construction of the active manifold for a given set of low- and high-fidelity models can be performed in two ways:

1. By providing the low- and high-fidelity models as numerical functions implemented in Python.
   • The functions (most easily implemented as lambda functions) will be evaluated to map the input parameters to the output quantities of interest.
   • This mode is recommended for simple, inexpensive functions.
   • An example of this mode using the Hartmann problem.
2. By providing the inputs and outputs of the low- and high-fidelity models in files that are read by NeurAM package.
   • The input and output data can be generated by any other program.
   • This mode is recommended for most applications, especially those involving data from computationally expensive simulations that are performed outside this package.
   • An example of this mode using patient-specific CFD simulations of coronary artery blood flow.

Input file format

This package uses a .json input file with the following format to specify the parameters for the construction of the reduced dimension and surrogate models:

{
    "model_type" : "data",
    "number_of_iterations" : 1,
    "epochs" : 10000,
    "random_seed" : 2025,
    "save" : true,
    "hyperparameter_tuning" : "hyperparameters.txt",
    "model" : { 
        "Details provided below" 
    }
}

All the parameters in the .json file except the "model" block are common between the two modes of operation described above. Below is a description of the parameters that are common to the two modes.

Parameter	Options	Description	Default value
"model_type"	"function"/"data"	If the low- and high-fidelity models are provided as Python functions, this should be "function". The Python function should be in a named get_model(name), where the argument specifies the name of the QoI, in a script called model.py. If the low- and high-fidelity models are provided as data (from simulations/measurements performed separately), this should be "data". See the examples for details.	-
"number_of_iterations"	Integer >= 1	Number of independent trials to perform in constructing the shared space and surrogate models.	1
"epochs"	Integer >= 1	Number of epochs to train the autencoders and surrogate models	10000
"random_seed"	Integer	Seed for the random number generators. Providing a seed makes the code more repeatable.	False
"save"	true/false	Toggles whether to save data files.	True
"hyperparameter_tuning"	true/false/"file_name"	Specifies whether to tune hyperparameters using Optuna (when set to true), use default hyperparameters (when set to false) or read hyperparameters from a file (when provided a "file_name")	False

The model block for models of type "function"

A sample "model" block is provided below:

{   
    "model" : {
        "HF_QoI_name" : "HF_QoI",
        "LF_QoI_name" : "LF_QoI",
        "cost_ratio" : 0.01,
        "model_path" : "./",
        "number_of_training_samples" : 1000,
        "number_of_testing_samples" : 1000
    }
}

Parameter	Format	Description
"HF_QoI_name"	String	Name of the high-fidelity QoI. This should be a valid argument for name in get_model(name).
"LF_QoI_name"	String	Name of the low-fidelity QoI. This should be a valid argument for name in get_model(name).
"cost_ratio"	Float	Ratio of computational cost between low- and high-fidelity model evaluations.
"model_path"	String	Path to the directory containing model.py
"number_of_training_samples"	Integer	Number of samples to draw for training the autoencoders and surrogate models.
"number_of_testing_samples"	Integer	Number of samples to draw for testing the autoencoders and surrogate models.

The model block for models of type "data"

{   
    "model" : {
        "HF_QoI_name" : "max_osi_sten_lad",
        "LF_QoI_name" : "mean_flow:lca1:BC_lca1",
        "cost_ratio" : 4.1275E-6,
        "data_files" : {
            "HF_inputs" : "./simulations/all_param_values.json",
            "HF_outputs" : "./simulations/all_3d_data.json",
            "LF_inputs_pilot" : "./simulations/all_param_values.json",
            "LF_outputs_pilot" : "./simulations/all_0d_data.json",
            "LF_inputs_propagation" : "./simulations/all_param_values_propagation.json",
            "LF_outputs_propagation" : "./simulations/all_0d_data_propagation.json",
            "LF_outputs_pilot_AE" : "./simulations/all_0d_data_AE.json",
            "LF_outputs_propagation_AE" : "./simulations/all_0d_data_AE_propagation.json",
            "LF_inputs_limits" : "./simulations/param_limits.json",
            "HF_inputs_limits" : "./simulations/param_limits.json"
        },
        "num_pilot_samples" : -1,
        "load_NN_models": "./"
    }
}

Parameter	Format	Description
"HF_QoI_name"	String	Name of the high-fidelity QoI. This should be a valid argument for name in get_model(name).
"LF_QoI_name"	String	Name of the low-fidelity QoI. This should be a valid argument for name in get_model(name).
"cost_ratio"	Float	Ratio of computational cost between low- and high-fidelity model evaluations.
"HF_inputs"	String	Path to the .json file containing the input parameters for the high-fidelity model.
"HF_outputs"	String	Path to the .json file containing the output QoIs for the high-fidelity model.
"LF_inputs_pilot"	String	Path to the .json file containing the pilot samples' input parameters for the low-fidelity model. These samples are used to construct the low-dimensional manifold and surrogate models.
"LF_outputs_pilot"	String	Path to the .json file containing the pilot samples' output QoIs for the low-fidelity model. These samples are used to construct the low-dimensional manifold and sur rogate models.
"LF_inputs_propagation"	String	Path to the .json file containing the pilot samples' input parameters for the low-fidelity model. These samples are used to perform multi-fidelity uncertainty quantification.
"LF_outputs_propagation"	String	Path to the .json file containing the pilot samples' output QoIs for the low-fidelity model. These samples are used to perform multi-fidelity uncertainty quant ification.
"LF_outputs_pilot_AE"	String	Path to the .json file containing the output QoIs for the low-fidelity model after resampling the original pilot samples' inputs (which were in "LF_inputs_pilot") via the active manifold. These samples are used to perform the improved multi-fidelity uncertainty quantification with improved correlation between low- and high-fidelity models.
"LF_outputs_propagation_AE"	String	Path to the .json file containing the output QoIs for the low-fidelity model after resampling the original propagation samples' inputs (which were in "LF_inputs_propagation") via the active manifold. These samples are used to perform the improved multi-fidelity uncertainty quantification with improved correlation between low- and high-fidelity models.
"LF_inputs_limits"	String	Path to the .json file containing the upper and lower bounds for each input parameter for the low-fidelity model. This is required to scale the inputs in the range [-1,1].
"HF_inputs_limits"	String	Path to the .json file containing the upper and lower bounds for each input parameter for the high-fidelity model. This is required to scale the inputs in the range [-1,1].
"num_pilot_samples"	Integer	Number of pilot samples to use from the provided data file in "LF_inputs_pilot". If -1, all samples are used. Otherwise specified number of samples are read randomly. Default is to use all samples.
"load_NN_models"	String	Optional parameter specifying the path to previously trained (and saved) autoencoders and surrogate models. If specified, new models are not trained.

Note: For the format of the .json files storing the inputs and outputs, please look at the simulations directory in the CoronaryArtery example.