pyemu.mc

pyEMU Monte Carlo module. Supports easy Monte Carlo and GLUE analyses. The MonteCarlo class inherits from pyemu.LinearAnalysis

Module Contents

Classes

MonteCarlo

LinearAnalysis derived type for monte carlo analysis
class pyemu.mc.MonteCarlo(**kwargs)

Bases: pyemu.la.LinearAnalysis

LinearAnalysis derived type for monte carlo analysis

Parameters:

**kwargs (dict) – dictionary of keyword arguments. See pyemu.LinearAnalysis for complete definitions

parensemble

pyemu object derived from a pandas dataframe, the ensemble of parameters from the PEST control file with associated starting value and bounds. Object also exposes methods relevant to the dataframe and parameters– see documentation.

Type:

pyemu.ParameterEnsemble

obsensemble

pyemu object derived from a pandas dataframe, the ensemble of observations from the PEST control file with associated starting weights. Object also exposes methods relevant to the dataframe and observations– see documentation.

Type:

pyemu.ObservationEnsemble

Returns:

pyEMU MonteCarlo object

Return type:

MonteCarlo

Example

>>>import pyemu

>>>mc = pyemu.MonteCarlo(pst="pest.pst")

property num_reals

get the number of realizations in the parameter ensemble

Returns:

num_real

Return type:

int

get_nsing(epsilon=0.0001)

get the number of solution space dimensions given a ratio between the largest and smallest singular values

Parameters:

epsilon (float) – singular value ratio

Returns:

nsing – number of singular components above the epsilon ratio threshold

Return type:

float

Note

If nsing == nadj_par, then None is returned

get_null_proj(nsing=None)

get a null-space projection matrix of XTQX

Parameters:

nsing (int) – optional number of singular components to use If Nonte, then nsing is determined from call to MonteCarlo.get_nsing()

Returns:

v2_proj – the null-space projection matrix (V2V2^T)

Return type:

pyemu.Matrix

draw(num_reals=1, par_file=None, obs=False, enforce_bounds=None, cov=None, how='gaussian')
draw stochastic realizations of parameters and

optionally observations, filling MonteCarlo.parensemble and optionally MonteCarlo.obsensemble.

Parameters:

  • num_reals (int) – number of realization to generate

  • par_file (str) – parameter file to use as mean values. If None, use MonteCarlo.pst.parameter_data.parval1. Default is None

  • obs (bool) – add a realization of measurement noise to observation values, forming MonteCarlo.obsensemble.Default is False

  • enforce_bounds (str) – enforce parameter bounds based on control file information. options are ‘reset’, ‘drop’ or None. Default is None

  • how (str) – type of distribution to draw from. Must be in [“gaussian”,”uniform”] default is “gaussian”.

Example

>>>import pyemu

>>>mc = pyemu.MonteCarlo(pst="pest.pst")

>>>mc.draw(1000)

project_parensemble(par_file=None, nsing=None, inplace=True, enforce_bounds='reset')

perform the null-space projection operations for null-space monte carlo

Parameters:

  • par_file (str) – an optional file of parameter values to use

  • nsing (int) – number of singular values to in forming null subspace matrix

  • inplace (bool) – overwrite the existing parameter ensemble with the projected values

  • enforce_bounds (str) – how to enforce parameter bounds. can be None, ‘reset’, or ‘drop’. Default is None

Returns:

par_en – if inplace is False, otherwise None

Return type:

pyemu.ParameterEnsemble

Note

to use this method, the MonteCarlo instance must have been constructed with the jco argument.

Example

>>>import pyemu

>>>mc = pyemu.MonteCarlo(jco="pest.jcb")

>>>mc.draw(1000)

>>>mc.project_parensemble(par_file="final.par",nsing=100)

write_psts(prefix, existing_jco=None, noptmax=None)
write parameter and optionally observation realizations

to a series of pest control files

Parameters:

  • prefix (str) – pest control file prefix

  • existing_jco (str) – filename of an existing jacobian matrix to add to the pest++ options in the control file. This is useful for NSMC since this jco can be used to get the first set of parameter upgrades for free! Needs to be the path the jco file as seen from the location where pest++ will be run

  • noptmax (int) – value of NOPTMAX to set in new pest control files

Example

>>>import pyemu

>>>mc = pyemu.MonteCarlo(jco="pest.jcb")

>>>mc.draw(1000, obs=True)

>>>mc.write_psts("mc_", existing_jco="pest.jcb", noptmax=1)