Utilities

These are abstract classes which are used in the analysis

Struc

class F_UNCLE.Utils.Struc.Struc(name, def_opts=None, informs=None, warns=None, *args, **kwargs)

Abstract object to contain properties and warnings

Attributes

name

str – The name of the object

def_opts

dict – Default options and bounds

informs

dict – Important user information prompts

warns

dict – Optional warnings

options

dict – The options as set by the user

Methods

__init__(name, def_opts=None, informs=None, warns=None, *args, **kwargs)

Instantiates the structure

Parameters:
  • name (str) – Name of the structure
  • *args – Variable length argument list.
  • **kwargs – Arbitrary keyword arguments.
Keyword Arguments:
 
  • def_opts (dict) –

    Dictionary of the default options for the structure Formatted as follows:

    {option_name(str):
 [type(Type), default(num), lower_bound(num),
  upper_bound(num), unit(str), note(str)]
}
  • informs (dict) – Dictionary of the default informs for the structure
  • warns (dict) – Dictionary of the warnings for the structure
Returns:

None
__str__(inner=False, *args, **kwargs)

Returns a string representation of the object

Parameters:
  • inner (bool) – Flag if the string is being called within another string function
  • *args – Variable length argument list.
  • **kwargs – Arbitrary keyword arguments.
Returns:

A string describing the object
Return type:

(str)
__weakref__

list of weak references to the object (if defined)

_on_str(*args, **kwargs)

Print methods of children

Parameters:
  • *args – Variable length argument list.
  • **kwargs – Arbitrary keyword arguments.
Returns:

A string representing the object
Return type:

(str)
get_inform(err_id)

Returns an inform corresponding to the error code

Parameters:err_id (int) – Error ID number
Returns:String containing the error message
Return type:(str)
get_option(name)

Returns the option corresponding the the given name

Parameters:name (str) – Name of the option
Returns:Value of the option corresponding to ‘name’
get_warn(warn_id)

Returns an inform corresponding to the warning code

Parameters:warn_id (int) – Warning ID number
Returns:String containing the warning message
Return type:(str)
plot(axes=None, fig=None, linestyles=[], labels=[])

Plots the object

Parameters:
  • axes (plt.Axes) – The Axes on which to plot the figure, if None, creates a new figure object on which to plot.
  • fig (plt.Figure) – The Figure on which to plot, cannot specify figure and axes
  • linstyles (list) – Strings for the linestlyes
  • labels (list) – Strings for the plot labels
Returns:

A reference to the figure containing the plot
Return type:

(plt.Figure)
set_option(name, value)

Sets the option corresponding to the given name to a specified value.

Enforces the following checks

  1. name is valid
  2. value is of correct type
  3. value is within bounds
  4. Not Implemented value has correct units
Parameters:
  • name (str) – Name of the option to set
  • value – Value of the option to set
Returns:

None
write_tex_var(name, value, units)

Returns a string which will define a variable in latex

Parameters:
  • name (str) – The variable name, do not include the leading slash
  • value (str) – The string representation of the number
  • units (rstr) – A RAW sting giving the correct latex syntax for the units
write_to_file(filename)

Writes the object to a file

Parameters:filename (string) – A path to a writable location
Returns:None

PhysicsModel

class F_UNCLE.Utils.PhysicsModel.PhysicsModel(prior, name=u'Abstract Physics Model', *args, **kwargs)

Abstract class for a physics model

A physics model is computer code that represents how some physical process responds to changes in the regime.

Definitions

DOF
A physics model has degrees of freedom, dof, which represent how many parameters the model has which can be adjusted to affect its response
Prior
A physics model has a prior, which represents the best estimate of the model’s degrees of freedom. This prior is used by Bayesian methods

Note

all abstract methods must be overloaded for a physics model to work in the F_UNCLE framework

Attributes

prior

PhysicsModel – the prior

Methods

__init__(prior, name=u'Abstract Physics Model', *args, **kwargs)
Parameters:prior – Can be either a PhysicsModel’ object or a function or a vector which defines the prior
Keyword Arguments:
 name (str) – A name for the model
_on_update_dof(model)

An extra method to perform special post-processing tasks when the DOF has been updated

Parameters:model (PhysicsModel) – The new physics model
Returns:The post-processed model
Return type:(PhyscisModel)
_on_update_prior(prior)

Instance specific prior update

Parameters:prior (PhysicsModel) – The prior
Returns:A copy of self with the new prior
Return type:(PhysicsModel)
get_constraints()

Generates the constraints on the physics model

get_dof()

Returns the model degrees of freedom

Note

Abstract Method: Must be overloaded to work with F_UNCLE

Parameters:None –
Returns:The model degrees of freedom
Return type:(np.ndarray)
get_log_like()

Returns the log likelihood of the model

get_pq(scale=False)

Returns the p and q matrices for the model

get_scaling()

Returns a matrix to scale the model degrees of freedom

Note

Abstract Method: Must be overloaded to work with F_UNCLE

Scaling the model dofs may be necessary where there are large changes in the magnitude of the dofs

Returns:a n x n matrix of scaling factors to make all dofs of the same order of magnitude.
Return type:(np.ndarray)
get_sigma(*args, **kwargs)

Gets the co-variance matrix of the model

Note

Abstract Method: Must be overloaded to work with F_UNCLE

Parameters:
  • *args – Variable length argument list.
  • **kwargs – Arbitrary keyword arguments.
Returns:

A n x n diagonal matrix of the uncertainty in each dof. where n is the model degrees of freedom
Return type:

(np.ndarray)
static plot_sens_matrix(sens_matrix, simid, models, mkey, fig=None)

Prints the sensitivity matrix

Parameters:
  • sens_matrix (dict) – Dictionary of sensitivity matrices
  • simid (str) – Key for simulation
  • models (OrderedDict) – Ordered dictionary of models
  • mkey (str) – Key in models corresponding to the EOSModel
Keyword Args
fig(plt.Figure): A valid matplotlib figure on which to plot.
If None, creates a new figure
Returns:The figure
Return type:(plt.Figure)
shape()

Returns the shape of the model dof space

Note

Abstract Method: Must be overloaded to work with F_UNCLE

Returns:Dimensions
Return type:(tuple)
update_dof(dof_in)

Sets the model degrees of freedom

Note

Abstract Method: Must be overloaded to work with F_UNCLE

Parameters:dof_in (Iterable) – The new values for all model degrees of freedom
Returns:A copy of self with the new DOF values
Return type:(PhysicsModel)
update_prior(prior)

Creates a new PhyscisModel with a new prior

Parameters:prior (PhysicsModel) – The prior
Returns:A copy of self with the new prior
Return type:(PhysicsModel)

Experiment

class F_UNCLE.Utils.Experiment.Experiment(name='Data Experiment', *args, **kwargs)

Abstract class to represent true experimental data DataExperiments are immutable and load data on instantiation

The following pre-processing activities occur on the data

  1. The data is loaded from file
  2. The data is checked for missing values and Nan’s
  3. A smoothing spline is passed through the data along regularly spaced knots
  4. Other pre-processing activities are carried out by _on_init
data

list – A list of the data

[0]. The independent variable, typically time [1]. The dependent variable [2]. The variance of the dependent variable

mean_fn

scipy.interpolate.LSQSpline – A smoothing spline passing through the data

var_fn

scipy.interpolate.IUSpline – An interpolated spline for the difference between the data and mean_fn

trigger

None – An object to align experiments to the data. Is None for basic case

__call__()

Returns the experimental data

Parameters:None –
Returns:Values are
[0]. (np.ndarray): The independent data from the experiment [1]. (list): Dependent data
[0]. (np.ndarray): The raw data form the experiment [1]. (np.ndarray): The mean_fn evaluated at the independent
data points

[2]. (np.ndarray): The raw variance from the experiment [3]. (list): labels

[2]. (dict): Auxiliary information

  • mean_fn (function): The smoothed function representing
    the dependent variable
  • var_fn (function): The interpolated function
    representing the difference between mean_fn and the measured data
  • trigger (Trigger): An object to align
    simulations to the data
Return type:(tuple)
__init__(name='Data Experiment', *args, **kwargs)

Loads the data and performs pre-processing activities

_check_finite(data)

Removes Nan from data

_get_data(*args, **kwargs)

Abstract class for parsing data-files or generating synthetic data

Parameters:
  • *args (list) – Variable length list of arguments passed from __init__
  • *kwargs (list) – Variable length list of keyword args passed from __init__
Returns:

The data, elements are

  1. (np.ndarray): The independent variable
  2. (np.ndarray): The single dependent variable
  3. (np.ndarray or None): The variance of the dependent variable if available
Return type:

(tuple)
_on_init(*args, **kwargs)

Experiment specific instantiation tasks

Creates the trigger object, In the base case it is a function which always returns zero

align(sim_data, plot=False, fig=None)

Updates the simulation data so it is aligned with the experiments

  1. Obtains the time-steps of the experiment
  2. Calculates the time shift to align the simulation with the experiment
  3. Evaluates the function representing the simulation output at the experimental time steps
  4. Updates the simulation trigger and tau values with the experimental Trigger object and the calculated tau
  5. Returns the simulation data aligned with the experiments
Parameters:

sim_data (list) – A list returned by a F_UNCLE experiment
Keyword Arguments:
 
  • plot (bool) – Flag to plot the comparison
  • fig (plt.Figure) – If not none, the figure object on which to plot
Returns:

The updated simulation data

  1. (np.ndarray): The experimental time steps

  2. (list): The simulation dependent results

    1. (np.ndarray): The simulation mean_fn shifted and evaluated at the experimental times
    2. The remaining elements are unchanged

  3. (dict): The simulation summary data

    • ‘tau’: Updated to show the time shift, in seconds, required to bring the simulations and experiments inline
    • ‘t_0’: The experimental time step when the experiment starts
    • ‘trigger’: The Trigger object used by the DataExperiment
Return type:

(list)
compare(sim_data, plot=False, fig=None)

Compares the results of a simulation to this these data

Performs the following actions

  1. Calculates the time shift required to align the simulation data with the experiment
  2. Evaluates the simulation data at the experimental time-stamps
  3. Calculates the difference between the simulation and the experiment for every experimental time step. Experiment less simulation
Parameters:

sim_data (list) – The output from a call to a F_UNCLE Experiment
Keyword Arguments:
 
  • plot (bool) – Flag to plot the comparison
  • fig (plt.Figure) – If not none, the figure object on which to plot
Returns:

The difference between sim_data and this experiment

at each experimental time-stamp
Return type:

(np.ndarray)
get_fisher_matrix(sens_matrix)

Returns the fisher information matrix of the simulation

Parameters:sens_matrix (np.ndarray) – the sensitivity matrix
Keyword Arguments:
 use_hessian (bool) – Flag to toggle whether or not to use the hessian
Returns:The fisher information matrix, a nxn matrix where n is the degrees of freedom of the model.
Return type:(np.ndarray)
get_log_like(sim_data)

Gets the log likelihood of the current simulation

Parameters:
  • sim_data (list) – Length three list corresponding to the __call__ from an Experiment object
  • experiment (Experiment) – A valid Experiment object
Returns:

The log of the likelihood of the simulation
Return type:

(float)
get_pq(models, opt_key, sim_data, sens_matrix, scale=False)

Generates the P and q matrix for the Bayesian analysis

Parameters:
  • models (dict) – The dictionary of models
  • opt_key (str) – The key for the model being optimized
  • sim_data (list) – Length three list corresponding to the __call__ from an Experiment object
  • sens_matrix (np.ndarray) – The sensitivity matrix
Keyword Arguments:
 

scale (bool) – Flag to use the model scaling
Returns:

Elements are:
  1. (np.ndarray): P, a nxn matrix where n is the model DOF
  2. (np.ndarray): q, a nx1 matrix where n is the model DOF
Return type:

(tuple)
get_sigma()

Returns the variance matrix.

Variance is given as:

self.data[1] * exp_var
Parameters:tmp (dict) – The physics models - not used
Returns:nxn variance matrix where n is the number of data
Return type:(np.ndarray)

Warning

This is a work in progress. The true variance should be calculated from the data.

get_splines(x_data, y_data, var_data=0.0)

Returns a spline representing the mean and variance of the data

Parameters:None –
Returns:Elements
  1. (scipy.interpolate.LSQSpline): A smoothing spline representing the data
  2. (scipy.interpolate.IUSpline): An interpolated spline for the difference between the data and mean_fn
Return type:(tuple)
get_window()

Creates a ‘window’ to consider only a selection of the data slice

Default window goes between tau + bounds[0] and tau + bounds[1]

Parameters:None –
Returns:Boolean array, True where data is to be used
Return type:(np.ndarray)
parse_datafile(folder, filename, root_dir, header_lines, delimiter, indepcol, depcols, varcols)

Parser to read experimental datafiles

Parameters:
  • folder (str) – The folder within fit_9501/Data where the experimental data are located
  • filename (str) – The name of the data-file
  • root_dir (str) – The path of the file calling this method
  • header_lines (int) – The number of header lines to skip
  • delimiter (str) – The delimiter for the file
  • indepcol (int) – The index of the independent variable column
  • depcols (list) – The indices of the dependent variables
  • varcols (list) – The indices of the variance of the dep var
shape()

Returns the number of independent data for the experiment

Parameters:None –
Returns:The number of data
Return type:(int)
simple_trigger(x, y)

This is the most basic trigger object for data which does not need to be aligned. Returns a shift if zero for all values of trial data

Simulation

class F_UNCLE.Utils.Simulation.Simulation(req_models, name=u'Simulation', *args, **kwargs)

Abstract class for experiments

A child of the Struc class. This abstract class contains methods common to all Simulations.

Definitions

Simulation
A analysis based on one or more physics models which attempts to predict experimental data

In order for an Experiment to work with the F_UNCLE framework, it must implement all the inherited methods from Experiment.

Attributes

None

Methods

__call__(models=None, *args, **kwargs)

Runs the simulation.

Note

Abstract Method: Must be overloaded to work with F_UNCLE

The simulation instance should be structured so that the necessary attributes, options and initial conditions are instantiated before calling the object.

Parameters:
  • *args – Variable length list of models.
  • **kwargs – Arbitrary keyword arguments.
Returns:

length 3 tuple with components

  1. (np.ndarray): The single vector of the simulation independent variable
  2. (list): A list of np.ndarray objects representing the various dependent variables for the problem. Element zero is the most important quantity. By default, comparisons to other data-sets are made to element zero. The length of each element of this list must be equal to the length of the independent variable vector. The last element of this list is the labels for the previous elements
  3. (dict): A dictionary of other attributes of the simulation
    result. The composition of this dictionary is problem dependent
Return type:

(tuple)
__init__(req_models, name=u'Simulation', *args, **kwargs)

Instantiates the object.

Parameters:req_models (dict) – A dictionary in the form {key: type} of the names and types of the mandatory physics models this Experiment uses

Options can be set by passing them as keyword arguments

_get_hessian(models, model_key, initial_data=None)

Gets the Hessian (matrix of second derivatives) of the simulated experiments to the EOS

\[ \begin{align}\begin{aligned}\begin{split}H(f_i) = \begin{smallmatrix} \frac{\partial^2 f_i}{\partial \mu_1^2} & \frac{\partial^2 f_i}{\partial \mu_1 \partial \mu_2}& \ldots & \frac{\partial^2 f_i}{\partial \mu_1 \partial \mu_n}\\\end{split}\\\begin{split}\frac{\partial^2 f_i}{\partial \mu_2 \partial \mu_1}& \frac{\partial^2 f_i}{\partial \mu_2^2}& \ldots & \frac{\partial^2 f_i}{\partial \mu_2 \partial \mu_n}\\\end{split}\\\frac{\partial^2 f_i}{\partial \mu_n \partial \mu_1}& \frac{\partial^2 f_i}{\partial \mu_n \partial \mu_2}& \ldots & \frac{\partial^2 f_i}{\partial \mu_n^2}\\\end{smallmatrix}\end{aligned}\end{align} \]
\[H(f) = (H(f_1), H(f_2), \ldots , H(f_n))\]

where

\[\begin{split}f \in \mathcal{R}^m \\ \mu \in \mathcal{R}^m\end{split}\]
_on_call(*models)

The overloaded method where the Experiment does its work

check_models(models)

Checks that the models passed to the Experiment are valid

compare(simdata1, simdata2)

Compares a the results of two Experiments

The comparison is made by comparing the results of simdata1 and simdata2 at each independent variable in simdata2.

The difference is evaluated as simdata2 less simdata1

Note

Abstract Method: Must be overloaded to work with F_UNCLE

Parameters:
  • simdata1 (tuple) – Complete output of a __call__ to an Experiment object.
  • simdata2 (tuple) – Complete output of a __call__ to an Experiment object.
Returns:

The error between the dependent variables and the model for each value of independent variable
Return type:

(np.ndarray)
get_log_like(model, sim_data, experiment)

Gets the log likelihood of the current simulation

Parameters:
  • model (PhysicsModel) – The model under investigation
  • sim_data (list) – Length three list corresponding to the __call__ from an Experiment object
  • experiment (Experiment) – A valid Experiment object
Returns:

The log of the likelihood of the simulation
Return type:

(float)
get_pq(model, sim_data, experiment, sens_matrix, scale=False)

Generates the P and q matrix for the Bayesian analysis

Parameters:
  • model (PhysicsModel) – The model being analyzed
  • sim_data (list) – Length three list corresponding to the __call__ from an Experiment object
  • experiment (Experiment) – A valid Experiment object
  • sens_matrix (np.ndarray) – The sensitivity matrix
Returns:

  1. (np.ndarray): P, a nxn matrix where n is the model DOF
  2. (np.ndarray): q, a nx1 matrix where n is the model DOF
Return type:

(tuple)
get_sens(models, model_keys, initial_data=None, verb=False)

Gets the sensitivity of the experiment response to the model DOF

Parameters:
  • models (dict) – The dictionary of models
  • model_keys (list) – The list of model keys for which the sensitivity is desired
Keyword Arguments:
 

initial_data (np.ndarray) – The response for the nominal model DOF, if it is None, it is calculated when this method is called
get_sens_mpi(models, model_keys, initial_data=None, comm=None)

MPI evaluation of the model gradients

Parameters:
  • models (dict) – The dictionary of model dof to run
  • model_key (str) – The list of models for which the sensitivity is desired
Keyword Arguments:
 
  • initial_data (np.ndarray) – The response for the nominal model DOF, if it is None, it is calculated when this method is called
  • comm() – A MPI communicator
get_sens_runjob(models, model_key, initial_data=None)

Uses runjob for evaluation of the model gradients

Note

runjob is an internal LANL code

Parameters:
  • models (dict) – The dictionary of models
  • model_key (str) – The key of the model for which the sensitivity is desired
Keyword Arguments:
 
  • initial_data (np.ndarray) – The response for the nominal model DOF, if it is None, it is calculated when this method is called
  • comm() – A MPI communicator
get_sigma(models, *args, **kwargs)

Gets the co-variance matrix of the experiment

Note

Abstract Method: Must be overloaded to work with F_UNCLE

Parameters:
  • *args – Variable length argument list.
  • **kwargs – Arbitrary keyword arguments.
Returns:

A nxn array of the co-variance matrix of the simulation. Where n is the length of the independent variable vector, given by PhysicsModel.shape()
Return type:

(np.ndarray)
multi_solve(models, opt_keys, dof_list)

Returns the results from calling the Experiment object for each element of dof_list

Parameters:
  • models (dict) – Dictionary of models
  • model_key (list) – A list of the model keys used
  • dof_list (list) – A list of numpy array’s defining the model DOFs
Returns:

A list of outputs to __call___ for the experiment

corresponding to the elements of dof_list
Return type:

(list)
multi_solve_mpi(models, model_keys, dof_list, comm=None, verb=False)

Returns the results from calling the Experiment object for each element of dof_list using mpi

Parameters:
  • models (dict) – Dictionary of models
  • model_keys (str) – The list of key for the models in the dof list
  • dof_list (list) – A list of numpy array’s defining the model DOFs
Returns:

A list of outputs to __call___ for the experiment

corresponding to the elements of dof_list
Return type:

(list)
multi_solve_runjob(models, model_key, dof_list)

Returns the results from calling the Experiment object for each element of dof_list using the runjob script

Note

runjob is an internal LANL code

Parameters:
  • models (dict) – Dictionary of models
  • model_key (str) – The key for the model in the models to be used
  • dof_list (list) – A list of numpy array’s defining the model DOFs
Returns:

A list of outputs to __call___ for the experiment

corresponding to the elements of dof_list
Return type:

(list)
shape(*args, **kwargs)

Gives the length of the independent variable vector

Note

Abstract Method: Must be overloaded to work with F_UNCLE

Returns:The number of independent variables in the experiment
Return type:(int)

Spline

class F_UNCLE.Models.Isentrope.Spline(x, y, w=None, bbox=[None, None], k=3, ext=0, check_finite=False)

Overloaded scipy spline to work as a PhysicsModel

Child of the scipy.interpolate.InterpolatedUnivariateSpline class which provides access to details to the knots which are treated as degrees of freedom

get_basis()

Extracts the basis functions for the value and 1st and 2nd der

Parameters:None –
Returns:
  1. list-n of value basis functions for the nth dof evaluated at all knots
  2. list-n of 1st derivative basis functions for the nth dof evaluated at all knots
  3. list-n of 2nd derivative basis functions for the nth dof evaluated at all knots
  4. list-(n-4) of unique knot locations
Return type:(tuple)
get_c(spline_end=None)

Return the coefficients for the basis functions

Keyword Arguments:
 spline_end (int) – The number of fixed nodes at the end of the spline
Returns:basis function spline coefficients
Return type:(np.ndarray)
get_t()

Gives the knot locations

Returns:knot locations
Return type:(np.ndarray)
set_c(c_in, spline_end=None)

Updates the new spline with updated coefficients

Sets the spline coefficients of this instance to the given values

Parameters:c_in (np.ndarray) – The new set of spline coefficients
Keyword Arguments:
 spline_end (int) – The number of fixed nodes at the end of the spline
Returns:A copy of self with the new coefficients
Return type:(Spline)

Noise Model

class F_UNCLE.Utils.NoiseModel.NoiseModel

Model for biased, correlated white noise

__call__(times, values, white_frac=0.1, cor_time=1e-07, rstate=None)

Returns a random vector based

Parameters:shape (tuple) – A tuple of the shape you want out
Returns:The random noise, has the specified shape
Return type:(np.ndarray)