SimulationParameters.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: Copyright (c) Stanford University, The Regents of the
// University of California, and others. SPDX-License-Identifier: BSD-3-Clause
/**
 * @file SimulationParameters.h
 * @brief Source file to read simulation configuration
 */
#ifndef SVZERODSOLVER_SIMULATIONPARAMETERS_HPP_
#define SVZERODSOLVER_SIMULATIONPARAMETERS_HPP_
 
#include <list>
#include <nlohmann/json.hpp>
#include <stdexcept>
#include <string>
 
#include "ActivationFunction.h"
#include "ActiveStress.h"
#include "Model.h"
#include "SphereMaterial.h"
#include "State.h"
#include "debug.h"
 
/**
 * @brief Simulation parameters
 *
 * Each of these can be set from the .json configuration file as part of the
 * dict which is keyed by "simulation_parameters".
 *
 * For example:
 *
 *      "simulation_parameters": {
 *         "number_of_cardiac_cycles": 30,
 *         "number_of_time_pts_per_cardiac_cycle": 201,
 *         "output_all_cycles": true
 *      }
 *
 * each parameter in the documentation may be specified using the attribute name
 * and a value which takes the type of the attribute.
 *
 */
struct SimulationParameters {
  // Negative value indicates this has not
  // been read from config file yet.
  double sim_time_step_size{0.0};   ///< Simulation time step size
  double sim_abs_tol{0.0};          ///< Absolute tolerance for simulation
  double sim_cardiac_period{-1.0};  ///< Cardiac period
  int sim_num_cycles{0};            ///< Number of cardiac cycles to simulate
  int sim_pts_per_cycle{0};         ///< Number of time steps per cardiac cycle
  bool use_cycle_to_cycle_error{
      false};  ///< If model does not have RCR boundary conditions, simulate
               ///< model to convergence (based on cycle-to-cycle error of last
               ///< two cardiac cycles); if it does, update number of cardiac
               ///< cycles to simulate to be value estimated from equation 21 of
               ///< Pfaller 2021
  double sim_cycle_to_cycle_error{0};  ///< Cycle-to-cycle error
  int sim_num_time_steps{0};           ///< Total number of time steps
  int sim_nliter{0};  ///< Maximum number of non-linear iterations in time
                      ///< integration
  double sim_rho_infty{0.0};  ///< Spectral radius of generalized-alpha
  int output_interval{0};     ///< Interval of writing output
 
  bool sim_steady_initial{0};  ///< Start from steady solution
  bool output_variable_based{
      false};  ///< Output variable based instead of vessel based
  bool output_mean_only{false};   ///< Output only the mean value
  bool output_derivative{false};  ///< Output derivatives
  bool output_all_cycles{false};  ///< Output all cardiac cycles
 
  bool sim_coupled{
      false};  ///< Running 0D simulation coupled with external solver
  double sim_external_step_size{0.0};  ///< Step size of external solver if
                                       ///< running coupled
  bool sim_max_iter_error_to_warning{
      false};  ///< If true, warn instead of throwing when max nonlinear
               ///< iterations is reached
};
 
/// @brief Wrapper class for nlohmann:json with error checking
class JsonWrapper : public nlohmann::json {
 public:
  /**
   * @brief Wrap around JSON configuration with detailed error message in case
   * key is not found in configuration
   *
   * @param json JSON configuration
   * @param component Name of the JSON sub-list to be extracted
   * @param name_str Name string of the JSON sub-list to be extracted
   * @param id Index of JSON sub-list to be extracted
   */
  JsonWrapper(const nlohmann::json& json, const std::string& component,
              const std::string& name_str, const int& id)
      : nlohmann::json(json[component][id]),
        component(component),
        name_str(name_str),
        block_id(id) {}
 
  /**
   * @brief Wrap error check around key retrieval (throws detailed error if key
   * doesn't exist)
   *
   * @param key Key to retrieve from JSON object
   * @return JSON entry of key
   */
  const nlohmann::json& operator[](const char* key) const {
    if (!this->contains(key)) {
      if (this->contains(name_str)) {
        const std::string name = this->at(name_str);
        throw std::runtime_error("Key " + std::string(key) +
                                 " not found in element " + name +
                                 " of component " + component);
      } else {
        throw std::runtime_error(
            "Key " + std::string(key) + " not found in element number " +
            std::to_string(block_id) + " of component " + component);
      }
    }
    return this->at(key);
  }
 
  // Inherit functions
  using nlohmann::json::contains;
  using nlohmann::json::value;
  using nlohmann::json::operator[];
 
 private:
  std::string component;
  std::string name_str;
  int block_id;
};
 
/**
 * @brief Generate a new block and add its parameters to the model
 *
 * @param model The model that the block is added to
 * @param block_params_json The JSON configuration containing the block
 * parameter values
 * @param block_type The type of block
 * @param name The name of the block
 * @param internal Is this an internal block? This is relevant for the
 * calibrator
 * @param periodic Is this block periodic with the cardiac cycle? This is
 * relevant for coupling with external solvers
 * @return int The block count
 */
int generate_block(Model& model, const nlohmann::json& block_params_json,
                   const std::string& block_type, const std::string_view& name,
                   bool internal = false, bool periodic = true);
 
/**
 * @brief Create an activation function from JSON (analogous to generate_block)
 *
 * Validates keys against the activation type's params, reads scalar
 * parameters, and returns a created ActivationFunction. Caller associates
 * it with a chamber block via set_activation_function().
 *
 * @param model Model (for cardiac_cycle_period)
 * @param j JSON object (e.g. chamber_config["activation_function"])
 * @param chamber_name Chamber name for error messages
 * @return Unique pointer to the created activation function
 */
std::unique_ptr<ActivationFunction> generate_activation_function(
    Model& model, const nlohmann::json& j, const std::string& chamber_name);
 
/**
 * @brief Create a SphereMaterial from JSON (analogous to
 * generate_activation_function)
 *
 * Validates keys against the material type's params, reads scalar parameters,
 * and returns a created SphereMaterial. Caller associates it with a
 * ChamberSphere block via set_material().
 *
 * @param j            JSON object (e.g. chamber_config["material"])
 * @param chamber_name Chamber name for error messages
 * @return Unique pointer to the created material
 */
std::unique_ptr<SphereMaterial> generate_material(
    const nlohmann::json& j, const std::string& chamber_name);
 
/**
 * @brief Create an ActiveStress model from JSON (analogous to
 * generate_material)
 *
 * Validates keys against the active stress type's params, reads scalar
 * parameters, and returns a created ActiveStress. Caller associates it with
 * a ChamberSphere block via set_active_stress().
 *
 * @param j            JSON object (e.g. chamber_config["active_stress"])
 * @param chamber_name Chamber name for error messages
 * @return Unique pointer to the created active stress model
 */
std::unique_ptr<ActiveStress> generate_active_stress(
    const nlohmann::json& j, const std::string& chamber_name);
 
/**
 * @brief Load initial conditions from a JSON configuration
 *
 * @param config The JSON configuration
 * @param model The model
 * @return State Initial configuration for the model
 */
State load_initial_condition(const nlohmann::json& config, Model& model);
 
/**
 * @brief Load the simulation parameters from a JSON configuration
 *
 * @param config The JSON configuration
 * @return SimulationParameters Simulation parameters read from configuration
 */
SimulationParameters load_simulation_params(const nlohmann::json& config);
 
/**
 * @brief Reconcile the cardiac cycle period between the model and parameters
 *
 * The period may be defined by a model block (e.g. a closed-loop block or a
 * chamber) or by `simulation_parameters.cardiac_period`. This resolves
 * `model.cardiac_cycle_period` from both sources, throws if the two disagree,
 * and falls back to a default of 1.0 if neither defines it. Must be called by
 * every entry point (solver and coupled interface) before blocks that depend
 * on the period are used.
 *
 * @param model The 0D model
 * @param params Simulation parameters read from the configuration
 */
void resolve_cardiac_cycle_period(Model& model,
                                  const SimulationParameters& params);
 
/**
 * @brief Load the 0D block in the model from a configuration
 *
 * @param config The json configuration
 * @param model The 0D model
 * @
 */
void load_simulation_model(const nlohmann::json& config, Model& model);
 
/**
 * @brief Check that the JSON configuration has the required inputs
 *
 * @param config The JSON configuration
 */
void validate_input(const nlohmann::json& config);
 
/**
 * @brief Handle the creation of vessel blocks and connections with boundary
 * conditions
 *
 * @param model The model the block is associated with
 * @param connections Vector storing the connections between blocks
 * @param config The JSON configuration
 * @param component Name of the component to retrieve from config
 * @param vessel_id_map Map between vessel names and IDs
 */
void create_vessels(
    Model& model,
    std::vector<std::tuple<std::string, std::string>>& connections,
    const nlohmann::json& config, const std::string& component,
    std::map<int, std::string>& vessel_id_map);
 
/**
 * @brief Handle the creation of external coupling blocks and connections with
 * other blocks
 *
 * @param model The model the block is associated with
 * @param connections Vector storing the connections between blocks
 * @param config The JSON configuration
 * @param component Name of the component to retrieve from config
 * @param vessel_id_map Map between vessel names and IDs
 * @param bc_type_map Map between boundary condition names and their types
 */
void create_external_coupling(
    Model& model,
    std::vector<std::tuple<std::string, std::string>>& connections,
    const nlohmann::json& config, const std::string& component,
    std::map<int, std::string>& vessel_id_map,
    std::map<std::string, std::string>& bc_type_map);
 
/**
 * @brief Handle the creation of boundary condition blocks
 *
 * @param model The model the block is associated with
 * @param config The JSON configuration
 * @param component Name of the component to retrieve from config
 * @param bc_type_map Map between boundary condition names and their types
 * @param closed_loop_bcs List of boundary conditions that should be connected
 * to a closed loop heart block
 */
void create_boundary_conditions(Model& model, const nlohmann::json& config,
                                const std::string& component,
                                std::map<std::string, std::string>& bc_type_map,
                                std::vector<std::string>& closed_loop_bcs);
 
/**
 * @brief Handle the creation of junctions and their connections
 *
 * @param model The model the block is associated with
 * @param connections Vector storing the connections between blocks
 * @param config The JSON configuration
 * @param component Name of the component to retrieve from config
 * @param vessel_id_map Map between vessel names and IDs
 */
void create_junctions(
    Model& model,
    std::vector<std::tuple<std::string, std::string>>& connections,
    const nlohmann::json& config, const std::string& component,
    std::map<int, std::string>& vessel_id_map);
 
/**
 * @brief Handle the creation of closed-loop blocks and associated connections
 *
 * @param model The model the block is associated with
 * @param connections Vector storing the connections between blocks
 * @param config The JSON configuration
 * @param component Name of the component to retrieve from config
 * @param closed_loop_bcs List of boundary conditions that should be connected
 * to a closed loop heart block
 */
void create_closed_loop(
    Model& model,
    std::vector<std::tuple<std::string, std::string>>& connections,
    const nlohmann::json& config, const std::string& component,
    std::vector<std::string>& closed_loop_bcs);
 
/**
 * @brief Handle the creation of valves and their associated connections
 *
 * @param model The model the block is associated with
 * @param connections Vector storing the connections between blocks
 * @param config The JSON configuration
 * @param component Name of the component to retrieve from config
 */
void create_valves(
    Model& model,
    std::vector<std::tuple<std::string, std::string>>& connections,
    const nlohmann::json& config, const std::string& component);
 
/**
 * @brief Handle the creation of chambers
 *
 * @param model The model the block is associated with
 * @param connections Vector storing the connections between blocks
 * @param config The JSON configuration containing all the closed loop blocks
 * @param component Name of the component to retrieve from config
 */
void create_chambers(
    Model& model,
    std::vector<std::tuple<std::string, std::string>>& connections,
    const nlohmann::json& config, const std::string& component);
 
#endif