Options¶

MC_fit reads run-time options from two files generically named perplex_option.dat and MC_fit_option.dat. The perplex_option.dat file contains options common to all Perple_X programs and is documented elsewhere. This page describes the MC_fit option file.

Non-generic names may be specified for both option files. The generic or non-generic name for perplex_option.dat is specified on the 6th line of the problem definition file, which is generically named my_project.dat, whereas the generic or non-generic name for MC_fit_option.dat is specified on the first line of the corresponding my_project.imc file.

Entries in the MC_fit option file take the general form:

keyword value | commentary

where keyword identifies the option and value is the value assigned to the option (e.g., T, F, text, a number, or default).

Comments may be placed anywhere in the file provided they are preceded by the | character.
All keywords accept the value default, in which case the keyword is assigned its default attributes.
Keywords and values are case sensitive.
Keywords that take the value T (true) or F (false) are always binary (Boolean).
Default keyword values are indicated in square brackets in the comment following each keyword.

MC_fit_option.dat lists all available MC_fit options. To change the value of an option in this file from default the word default must be replaced with the desired value. For example, to change the value of the uncertainties option:

uncertainties       default | [all] => all, analytical, or thermodynamic

from all to analytical, the line must be changed to:

uncertainties    analytical | [all] => all, analytical, or thermodynamic

changing the text of the comment does not change the value of the keyword.

Hint

To minimize confusion, create non-generically named option files (e.g., my_MC_fit_option.dat) that list only those options that have non-default values. A copy of MC_fit_option.dat that lists all relevant options is here.

—

Option Keywords Grouped (Roughly) by Functionality¶

—

—

Scoring¶

Bayes
misfit_composition
misfit_mode
no_missing_phases
number_of_tries
prior_probability_PT_only
range_to_sigma
w_composition
w_extra
w_missing
w_mode

—

Uncertainty¶

best_central_model
number_of_perturbations
perturbation_hot_start
relative_error
uncertainties
uncertainty_multiplier

—

Optimization¶

convergence_testing
convergence_threshold
max_misfit_value
max_misfit_evaluations
seed
step_size

—

Debugging¶

seed
model_output
no_missing_phases
print_level

—

Advanced or Irrelevant Options¶

expansion_criterion
GRH
MINIM_algorithm
misfit_filter_value
must_fit_all_data
Nelder-Mead_covariance
number_of_perturbation_tries
quadratic_fitting
uncertainty_plus
thermobarometry

—

Option Details¶

—

Bayes¶

Type: Boolean; Default: F

T: Use Bayes scores to identify the best model. Bayesian scoring applies a penalty to models for which the inversion parameters are far from the midpoint of their specified ranges. The penalty is based on the prior probability of the parameters values that is estimated by assuming a Gaussian distribution of the parameters within their specified ranges.

F: Identify the best model by minimizing the misfit function.

Related options: prior_probability_PT_only, range_to_sigma

Internal variable: bayes

—

best_central_model¶

Type: Boolean; Default: T

T: Use the best central model coordinates as the initial coordinates for the perturbation analysis.

F: Use randomly generated initial coordinates for the perturbation analysis.

Internal variable: newstt

—

convergence_testing¶

Type: Integer; Default: 10

Frequency of testing for convergence in the Nelder-Mead algorithm.

Internal variable: conchk

—

convergence_threshold¶

Type: Float; Default: 1d-4

Threshold used in the convergence criterion of Nelder-Mead algorithm. If the variance of the misfit function around a putative minimum is less than this threshold, the algorithm is considered to have converged.

Internal variable: invtol

—

expansion_criterion¶

Type: Float; Default: 1d-3

Threshold used to decide if the final simplex around a minimum identified by the Nelder-Mead algorithm should be expanded prior to quadratic fitting.

Related options: quadratic_fitting

Internal variable: simplx

—

GRH¶

Type: Boolean; Default: F

T: Use George Helffrich’s normalizations, etc.

F: Use MC_fit defaults.

Internal variable: grh

—

kiso¶

Type: Boolean; Default: F

T: Convert mass compositions to molar units and terminate. This option is provided as a convenience for users who wish to convert compositions from mass to molar units.

F: Do not convert.

Related options: molar_composition_input

Internal variable: kiso

—

max_misfit_value¶

Type: Float; Default: 1d5

Maximum acceptable value of the misfit function; larger values trigger an error.

Related options: misfit_filter_value

Internal variable: oktol

—

max_misfit_evaluations¶

Type: Integer; Default: 1000

Maximum number of misfit function evaluations permitted for a try. Generally, the recommended value for this limit is 1000 times the number of inversion parameters.

Note

The number of misfit evaluations may become excessive when an inversion parameter lies near the limits of its specified range. In such cases, increasing the maximum number of evaluations may be futile; and the best remedy is to expand the range of the inversion parameter.

Internal variable: kcount

—

MINIM_algorithm¶

Type: Boolean; Default: T

T: Use MINIM (Nelder-Mead) algorithm ([ONeill1971], [MINIM]) to find the best-fit model.

F: Use grid search.

Note

George Helffrich’s grid search algorithm was disabled in version 7.1.6. Support for this mode will be restored in a future release.

Internal variable: ~mcgrid

—

misfit_composition¶

Values: Chi, LSQ, or wChi; Default: Chi

Controls the form of the component of the misfit function used to evaluate the fit of a model to observed compositions.

LSQ: Least-squares, Eq 11

Chi: Pearson’s chi-squared, Eq 12

wChi: Weighted chi-squared, Eq 13

Internal variable: lsqchi

—

misfit_mode¶

Values: Chi, LSQ, or wChi; Default: Chi

Controls the form of the component of the misfit function used to evaluate the fit of a model to observed modal proportions.

LSQ: Least-squares, Eq 11

Chi: Pearson’s chi-squared, Eq 12

wChi: Weighted chi-squared, Eq 13

Internal variable: lsqchm

—

misfit_filter_value¶

Type: Float; Default: 1d99

Maximum value of the misfit function at which a successful model will be output. This option can be used to eliminate outliers.

Related options: max_misfit_value

Internal variable: mxobjf

—

model_output¶

Values: all, improved, or best; Default: all

Controls which successful models are output.

all: all successful models.

improved: only models that improve on a previous successful model.

best: only the best-fit model.

Related options: Bayes, no_missing_phases, misfit_filter_value

Internal variable: bstout

—

molar_composition_input¶

Type: Boolean; Default: T

T: Input compositions are in molar units.

F: Input compositions are in mass units.

Output from MC_fit is always in molar units. Molar output from MC_fit can be converted to mass and standard molar formula units by cutting and pasting the MC_fit my_project.bst file output into the my_project.dat file and running MEEMUM at the relevant physicochemical conditions.

Related options: kiso

Internal variable: ~lmass

—

must_fit_all_data¶

Type: Boolean; Default: F

T: Do not accept models that do not fit all observational data within its uncertainty.

F: Accept models even if some observational data is not fit.

Related options: uncertainty_multiplier, no_missing_phases, misfit_filter_value

Internal variable: mustft

—

Nelder-Mead_covariance¶

Type: Boolean; Default: T

T: Include Nelder-Mead information matrix in model output.

F: Do not include covariance matrix.

The Nelder-Mead information matrix is strictly equivalent to the covariance matrix only when the dominant components of the misfit function are weighted Chi-squared (misfit_composition and/or misfit_mode are set to wChi). If the misfit function is LSQ or Chi, the reported covariance matrix is obtained by scaling the Nelder-Mead information matrix by half the residual variance. This scaling is rigorous if the misfit function is LSQ; but has no theoretical basis for Chi. In all cases, the extraneous and missing phase components of the misfit function are ignored when the information matrix is computed. This policy is justified by the assumption that these components are negligible for useful solutions.

The covariance matrix of the misfit function is sometimes used to estimate inversion parameter uncertainties ([Duesterhoeft2020], [Khan2021]). The fallacy of this practice is that without a measure of the precision of the misfit function, the covariance matrix cannot be quantitatively related to parameter uncertainties. For this reason, use of the Nelder-Mead_covariance option is discouraged in favor of MC_fit Strategy, which provides a rigorous framework for evaluating parameter uncertainties. The utility of the option is that it provides information about the shape of the misfit function in the vicinity of a solution without requiring multiple tries.

Because shape is better described as parameter correlation than covariance, when the Nelder-Mead covariance matrix is requested and available, both the covariance and correlation matrices are output. As both matrices are symmetric, and the diagonal elements of the correlation matrix are all unity, they are combined in a single matrix in my_project.out file output, e.g.:
Misfit covariance and correlation matrices* and standard deviations:

              P_bar         T_K           C_O2          Cpx           Gt
P_bar      16116.7      -.972547      0.936720      0.969177      -.894136
T_K       -968.009       61.4696      -.850881      -.971190      0.885776
C_O2      0.102848      -.576959E-02  0.747981E-06  0.844735      -.888468
Cpx        2.24574      -.138980      0.133347E-04  0.333146E-03  -.782102
Gt        -2.91068      0.178076      -.197033E-04  -.366044E-03  0.657514E-03

std_dev    126.952       7.84026      0.864859E-03  0.182523E-01  0.256420E-01
where the off-diagonal elements of the correlation matrix are above the diagonal. Strong parameter correlations, as in the above example, indicate the parameter estimates are not independent, but do not quantify their uncertainties.

The Nelder-Mead covariance estimated by MC_fit is based on a quadratic fit to the misfit function at the minimum found by the Nelder-Mead algorithm ([MINIM]).

Related options: quadratic_fitting, number_of_tries, uncertainties

Internal variable: nmcov

—

no_missing_phases¶

Type: Boolean; Default: T

T: Do not accept models that fail to predict all observed phases.

F: Accept models even if some phases are missing.

If no, or few, successful models are obtained, set this option to F to discover which phases are problematic.

Related options: must_fit_all_data, misfit_filter_value

Internal variable: nomiss

—

number_of_tries¶

Type: Integer; Default: 100

Number of tries during search for the best-fit central model.

Internal variable: mtry

—

number_of_perturbations¶

Type: Integer; Default: 100

Number of perturbations for the uncertainty analysis.

Related options: uncertainties

Internal variable: nunc(1)

—

number_of_perturbation_tries¶

Type: Integer; Default: 100

Number of tries for each perturbation during uncertainty analysis. If best_central_model is T, number_of_perturbation_tries is automatically set to 1.

Related options: uncertainties, best_central_model

Internal variable: ptry

—

perturbation_hot_start¶

Type: Boolean; Default: F

T: Allows the user to provide coordinates for perturbation analysis. Typically, these coordinates have been obtained by a previous central model analysis.

F: Perturbation analysis is performed around the best-fit central model coordinates.

This option is useful, particularly if the central model analysis is costly, when:

MC_fit has been interrupted during central model analysis, but generated a useful best-fit model.

The number of perturbations specified in a previous MC_fit run did not adequately sample the uncertainty space.

It is desired to explore the uncertainty space around a model other than the best-fit model.

If this option is T, MC_fit prompts for the coordinates of the starting model. These coordinates can be obtained from the my_project.bst or my_project_central.pts files generated by a previous run of MC_fit.

Internal variable: mchot

—

print_level¶

Type: Integer; Default: 0

Controls the verbosity of console output by the Nelder-Mead algorithm.

<0: Only errors and warnings are printed.

0: Basic information is printed.

>0: Detailed information about each step is printed.

Internal variable: jprint

—

prior_probability_PT_only¶

Type: Boolean; Default: T

Controls which inversion parameters are assigned prior probabilities for Bayes scoring.

T: Only pressure and temperature.

F: All inversion parameters.

Internal variable: bayes

—

quadratic_fitting¶

Type: Boolean; Default: F (may be overridden by Nelder-Mead_covariance)

T: A quadratic fit to the misfit function at the minimum found by the Nelder-Mead algorithm is used to refine the location of the minimum and estimate covariance/correlation matrices.

F: Quadratic fitting is not used.

Internal variable: iquad

—

range_to_sigma¶

Type: Float; Default: 4.0

Sets the scaling factor \(c\) in Eq 16 used to convert the range specified for each inversion parameter to a confidence interval for Bayesian scoring.

Large values of \(c\) increase the influence of the prior probability on the Bayes score, favoring models near the midpoint of the parameter ranges.

Internal variable: ra2zs

—

relative_error¶

Type: Boolean; Default: T

Controls how uncertainties are interpreted on input.

T: Uncertainties are relative (fraction of measured value).

F: Uncertainties are absolute (fixed values).

This option applies to all observational data read from the my_project.imc file. Uncertainties read from the thermodynamic data file are always treated as absolute uncertainties. The absolute error \(\epsilon\) on a measured value \(x\) with relative uncertainty \(\delta\) is computed as \(\epsilon = x \delta\). This relation unrealistically implies that the absolute uncertainty on a measured value of zero is also zero.

Internal variable: relerr

—

seed¶

Type: Boolean; Default: F

Controls whether the random number generator is seeded for the Nelder-Mead algorithm.

T: Each run produces different results (useful for exploring parameter space).

F: Results are reproducible (useful for debugging/testing).

Internal variable: seed

—

step_size¶

Type: Float; Default: 1e-1

Sets the fractional [0, 1] spacing of inversion parameter coordinates for constructing the initial simplex in the Nelder-Mead algorithm. A larger value means a wider search; a smaller value means a more localized search.

Internal variable: frac

—

thermobarometry¶

Type: Boolean; Default: T

Specifies the type of inversion problem.

T: Thermobarometric inversion (estimates pressure, temperature, and unmeasured components).

F: Thermodynamic parameter inversion (estimates thermodynamic parameters directly).

Note

Thermodynamic parameter inversion was disabled as of version 7.1.6. Support for this mode will be restored in a future release. See: [Khan2021], [Pitsch2025].

Internal variable: invxpt

—

uncertainties¶

Values: all, analytical, or thermodynamic; Default: all

Controls whether analytical and/or thermodynamic uncertainties are propagated in the uncertainty analysis.

all: Both thermodynamic and compositional uncertainties are propagated.

analytical: Only observational uncertainties from my_project.imc are propagated.

thermodynamic: Only thermodynamic parameter uncertainties from the thermodynamic data file are propagated.

Note

Thermodynamic uncertainties require both the uncertainty_enabled tag in the thermodynamic data file header and numerical values for the uncertainties for the entries of interest. Currently MC_fit is only programmed to propagate enthalpic uncertainties. Support of other sources of thermodynamic uncertainty will be added if these become available.

Related options: number_of_perturbations, Nelder-Mead_covariance.

Internal variable: invunc (all = 1, analytical = 2, thermodynamic = 3)

—

uncertainty_multiplier¶

Type: Float; Default: 2.0

Sets the scaling factor for observational uncertainties used to assess model fit. A model prediction must fall within the uncertainty multiplied by this factor to be considered a fit. When uncertainties are the standard deviation, a value of 2.0 corresponds to a 95% confidence interval.

Internal variable: un2ft

—

uncertainty_plus¶

Note

This keyword is a stub.

—

vital_sign¶

Type: Boolean; Default: T

Controls whether the misfit function counter and value are output to the console. See also: print_level.

Internal variable: vital

—

w_composition¶

Type: Float; Default: 1e0

Sets the weighting factor for the composition component of the misfit function.

Internal variable: wcomp

—

w_extra¶

Type: Float; Default: 1e4

Sets the weighting factor for the extraneous phase component of the misfit function.

Internal variable: wextra

—

w_missing¶

Type: Float; Default: 1e3

Sets the weighting factor for the missing phase component of the misfit function.

Internal variable: wmiss

—

w_mode¶

Type: Float; Default: 1e0

Sets the weighting factor for the phase mode component of the misfit function.

Internal variable: wmode