Calibration Command

The musica calibration run command can be used to perform micromechanical model calibrations. The command requires a configuration file to specify the calibration settings. By default, the following configuration files are searched if it is not specified in the command line:

1. micromechanical-calibrations.(toml|yaml|yml|json),
2. [calibrations] in micromechanical.(toml|yaml|yml|json),
3. [calibrations] in micromechanical/config.(toml|yaml|yml|json),
4. [tool.micromechanical.calibrations] in pyproject.toml.

The following is an example of a configuration file:

micromechanical-calibrations.toml

# Command line options
[cli]
overwrite = true
# ...

# Base calculation options
[calculation]
disp_steps = -1
# ...

# Base calibration options
[calibration]
phase_steps = {}
# ...

# Base figure options
[figures.macroscopic]
method = "plotComparisons"
# ...

# Experiment calibrations
[experiment_calibrations.Gu2014]
model_type = "CH-OSIMSAND"
experiment.files = []
experiment.filters = {}

calculation = {}
calibration = {}
figures = {}
matrix = {}
# ...

The configuration file is divided into several sections, each of which specifies a different aspect of the calibration process. The cli section specifies command line options (see CLIOptions), the calculation section specifies the base calculation options (see Calculation Options), the calibration section specifies the base calibration options (see Calibration Options), and the figures section specifies the base figure options (see [FigureOptions][micromechanical.cli.calibration.FigureOptions]). The experiment_calibrations section specifies the experiment calibrations to be performed (see ExperimentCalibrationOptions). The based calculation, calibration, and figures options can be overridden by the experiment_calibrations section.

The following mermaid diagram shows the relationship between the different sections of the configuration file:

flowchart LR
    CLI[CLI Options]

    CALC[Calculation Options]
    CALI[Calibration Options]
    FIG[Figures]
    EXP[Experiment Calibrations]

    OVER_CALC[Overridden Calculation Options]
    OVER_CALI[Overridden Calibration Options]
    OVER_FIG[Overridden Figures]

    CALC -->|overridden| EXP --> OVER_CALC
    CALI -->|overridden| EXP --> OVER_CALI
    FIG -->|overridden| EXP --> OVER_FIG

Note

Dictionaries are deeply merged using the deepmerge package when overriding options, and lists are directly replaced.

Note

The phase, step, idx, and col options in the calibration.data_get_kwargs, experiment_calibrations.<calibration-name>.figures.<figure-name>, and experiment_calibrations.<calibration-name>.figures.<figure-name>.simulation_kwargs sections will be evaluated by the eval function to allow for dynamic values. For example, the option step = "slice(10, None)" will set the option step to the slice slice(10, None) before being used.

The matrix attribute in the experiment_calibrations and figures sections can be used to expand the current configuration into multiple configurations. Options under the matrix section override the corresponding options in the parent section. The following is an example of a configuration file with a matrix:

micromechanical-calibrations.yaml

experiment_calibrations:
  Gu2014:
    matrix:
      drainage: # in the Gu2014 base configurations, placeholders like {drainage} can be used
        - drained: {} # configurations for drained experiments
        - undrained:
            if:
              anisotropy: "isotropic" # conditions
              options: {} # extra conditional options
            specs: {} # extra formatting specifications
      anisotropy:
        - isotropic: {} # configurations for isotropic models, will be deeply merged with drainage configurations
        - anisotropic: {}

      # includes and excludes
      includes:
        # drainage and anisotropy must be both specified if you include a new configuration
        # if you want to modify existing configurations, drainage, anisotropy or both can be omitted
        - drainage: "undrained"
          anisotropy: "cross-anisotropic"
          if: # only include this configuration if the condition is met, all `micromechanical.config` options can be used here
            any: true # any condition is true, by default false
            case_sensitive: false # case-sensitive for comparison of environment variables, by default false
            language: "zh" # can be a list ["zh", "en"], assumed true if language is in the list
            env: # compare with environment variables
              CROSS_ANISOTROPY: "true" # can also be a list
          # other configurations can be added here
        - drainage: "drained"
          anisotropy: "isotropic"
          # You can also update configurations here for `drained-isotropic`
      excludes: # drainage and anisotropy may not be both specified
        - drainage: "undrained"
          anisotropy: "anisotropic"

    # optionally set the name of the configuration, by default it is "{base}-{drainage}-{anisotropy}", where {base} is the
    # name of the base configuration which is "Gu2014" in this case
    name: "{base}-{drainage}-{anisotropy}"

The above example expands the Gu2014 calibration configuration into 4 configurations: Gu2014-drained-isotropic, Gu2014-drained-anisotropic, Gu2014-undrained-isotropic and Gu2014-undrained-cross-anisotropic (Gu2014-undrained-anisotropic is excluded).