Welcome to F_UNCLE’s documentation!

Contents:

Documentation

The FUNCLE module

Functional UNcertainty Constrained by Law and Experiment

User’s Guide

Definitions

Physics Process

“A physics process is a relation between two or more physical quantities, e.g. the rate at which plasma ion and electron temperatures equilibrate as a function of the individual temperatures, particle masses, and number densities. Note that a physics process need not be time dependent, e.g. the shear modulus as a function of temperature and density.”:cite:`VaughanPUBS2014`

Physics Model

“A physics model is an approximate mathematical representation of a physics process. As an example of a physics model, consider the plastic constitutive relation of a metal. This relates the basic quantities governing plastic deformation, e.g. the flow stress, plastic strain, strain rate, temperature, and density. It is an approximate representation of the very complicated mesoscale physics responsible for the flow of a solid, and is therefore a physics model.”:cite:`VaughanPUBS2014`

Degree of Freedom

The mathematical representation of a physics model is dependent on a set of variables whose values can alter the behavior of the model. These variables are referred to as the degrees of freedom or DOF

Experiment

An experiment represents data measured from a real physical experiments. Experiments used in F_UNCLE are chosen so that their results are dominated by a single physics process which can be represented by a physics model Simulation

Simulation

A simulation which represents the physical system from which the experimental data were obtained. The simulation is dependent on one or more physics models and acts as a map between the model degree of freedom space and the experimental result space

F_UNCLE Parent Classes

These concepts are implemented in the following three fundamental F_UNCLE classes

Physics Model

F_UNCLE.Utils.PhysicsModel.PhysicsModel. This class represents a physics model. The degrees of freedom of a PhysicsModel are immutable. Setting the degrees of freedom of a PhysicsModel will return a independent copy of itself with updated DOF.

• F_UNCLE.Utils.PhysicsModel.PhysicsModel.get_dof(): Returns a list of the model degrees of freedom
• F_UNCLE.Utils.PhysicsModel.PhysicsModel.set_dof(): Generates a new Physics Model with the specified degrees of freedom
• F_UNCLE.Utils.PhyscisModel.PhysicsModel.get_sigma(): Returns a square matrix representing the co-variance of the model degrees of freedom
• F_UNCLE.Utils.PhyscisModel.PhysicsModel.shape(): Returns an integer representing the number of model degrees of freedom

Experiment

F_UNCLE.Utils.Experiment.Experiment. This class represents the results for a single experiment performed under a single set of conditions.

• F_UNCLE.Utils.Experiment.Experiment.__call__(): Returns a tuple with the following elements:

  0. The independent variable of the simulation (i.e. time)
  1. List of arrays of dependent variables. Element zero is the element for comparison, the last element is the labels for the previous elements
  2. Dictionary of additional simulation result attributes. Contains at least the key mean_fn which is a functional representation of the relationship between the independent variable and the dependent variable for comparison

• F_UNCLE.Utils.Experiment.Experiment.get_sigma(): Returns an nxn co-variance matrix for the experimental data
• F_UNCLE.Utils.Experiment.Experiment.shape(): Returns an integer representing the number of experimental data points
• F_UNCLE.Utils.Experiment.Experiment.get_fisher_matrix(): This returns the fisher information matrix of the experiment given the simulation’s sensitivity matrix

The Experiment object provides some internal routines to ease comparison of simulations and experiments

• F_UNCLE.Utils.Experiment.Experiment.align(): This takes a set of simulation data and returns a copy of it with the simulation data aligned so it is evaluated at each independent data value of the experiment. This ‘aligned’ tuple of simulation data has a new key tau which is the shift in independent variable (likely time) required to align the simulation to the experiment. In addition, the mean_fn attribute has been modified so it returns values aligned to the experimental data.

• :py:fun:`F_UNCLE.Utils.Experiment.Experiment.compare`: This takes a set of simulation data and returns the error between the experiment and the simulation. The simulation can either be aligned or not. The return value is the experimental value less the aligned simulation value

Simulation

F_UNCLE.Utils.Simulation.Simulation. This class wraps some computer simulation which is dependent on a PhysicsModel

• F_UNCLE.Utils.Simulation.Simulation.compare(): Compares two simulations results and returns the difference

• F_UNCLE.Utils.Simulations.Simulations.__call__(): Returns the results of the simulation as a tuple

  0. The independent variable of the simulation (i.e. time)
  1. List of arrays of dependent variables. Element zero is the element for comparison, the last element is the labels for the previous elements
  2. Dictionary of additional simulation result attributes. Contains at least the key mean_fn which is a functional representation of the relationship between the independent variable and the dependent variable for comparison

• F_UNCLE.Utils.Simulations.Simulations.get_sens(): This returns a sensitivity matrix of the simulation response to changes in the required model degrees of freedom. The response is evaluated at the independent data points of the provided initial_data and the deltas for each finite difference step are evaluated using the compare method.

Optimization Methods

The goal of F_UNCLE is to determine the set of model degrees of freedom which minimizes the error between a set of Experiments and associated Simulations.

F_UNCLE.Opt.Bayesian.Bayesian:

Models

The physics models used in the analyses

Isentrope

class F_UNCLE.Models.Isentrope.Isentrope(name=u'Isentrope', *args, **kwargs)

Abstract class for an isentrope

The equation of state for an isentropic expansion of high explosive is modeled by this class. The experiments for which this model is used occur at such short timescales that the process can be considered adiabatic

Units

Isentropes are assumed to be in CGS units

Diagram

The assumed shape of the equation of state isentrope

Options

Name	Type	Def	Min	Max	Units	Description
spline_N	(int)	50	7	None	‘’	Number of knots in the EOS spline
spline_min	(float)	0.1	0.0	None	‘cm**3/g’	Minimum value of volume modeled by EOS
spline_max	(float)	1.0	0.0	None	‘cm**3/g’	Maximum value of volume modeled by EOS
spline_end	(float)	4	0	None	‘’	Number of zero nodes at end of spline

__init__(name=u'Isentrope', *args, **kwargs)

Parameters:

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

Keyword Arguments:  

name (str) – Name if the isentrope Def ‘Isentrope’

Returns:

None

_get_cj_point(vol_0, pres_0=0.0, debug=False)

Find CJ conditions using two nested line searches.

The CJ point is the location on the EOS where a Rayleigh line originating at the pre-detonation volume and pressure is tangent to the equation of state isentrope.

This method uses two nested line searches implemented by the scipy.optimize.brentq() algorithm to locate the velocity corresponding to this tangent Rayleigh line

Parameters:

vol_0 (float) – The specific volume of the equation of state before the shock arrives

Keyword Arguments:  

• pres_0 (float) – The pressure of the reactants
• debug (bool) – Flag to print debug information

Returns:

Length 3 elements are:

0. (float): The detonation velocity
1. (float): The specific volume at the CJ point
2. (float): The pressure at the CJ point
3. (function): A function defining the Rayleigh line which passes through the CJ point

Return type:

(tuple)

get_constraints(scale=False)

Returns the G and h matrices corresponding to the model

Parameters:model (GaussianModel) – The physics model subject to physical constraints Returns:(): Return type:()

Method

Calculate constraint matrix G and vector h. The constraint enforced by cvxopt.solvers.qp is

\[G*x \leq h\]

Equivalent to \(max(G*x - h) \leq 0\)

Since

\[c_{f_{new}} = c_f+x,\]

\[G(c_f+x) \leq 0\]

is the same as

\[G*x \leq -G*c_f,\]

and \(h = -G*c_f\)

Here are the constraints for \(p(v)\):

p’’ positive for all v p’ negative for v_max p positive for v_max

For cubic splines between knots, f’’ is constant and f’ is affine. Consequently, \(f''rho + 2f'\) is affine between knots and it is sufficient to check eq:star at the knots.

plot(axes=None, figure=None, linestyles=[u'-k'], labels=[u'Isentrope'], vrange=None, log=False, draw_rayl=False, *args, **kwargs)

Plots the EOS

Overloads the F_UNCLE.Utils.Struc.Struc.plot() method to plot the EOS over the range of volumes.

Parameters:

• axes (plt.Axes) – The axes on which to plot the figure, if None, creates a new figure object on which to plot.
• figure (plt.Figure) – The figure on which to plot ignored
• linstyles (list) – Strings for the linestyles 0. ‘-k’, The Isentrope
• labels (list) – Strings for the plot labels 0. ‘Isentrope’
• vrange (tuple) – Specific volume range to plot
• log (bool) – Flag to plot on semilogy
• draw_rayl (bool) – Flag to draw rayleigh line

Returns:

A reference to the figure containing the plot

Return type:

(plt.Figure)

shape()

Overloaded class to get isentrope DOF’s

Overloads F_UNCLE.Utils.PhysModel.PhysModel.shape()

Returns:(n,1) where n is the number of dofs Return type:(tuple)

BumpEOS

class F_UNCLE.Models.Isentrope.EOSBump(name=u'Bump EOS', *args, **kwargs)

Model of an ideal isentrope with Gaussian bumps

This is treated as the true EOS

Options

Name	Type	Def	Min	Max	Units	Description
const_C	(float)	2.56e9	0.0	None	‘Pa’	‘Constant p = C/v**3’
bumps	(list)	[(0.4 0.1 0.25) (0.5 0.1 -0.3)]	None	None	‘’	‘Gaussian bumps to the EOS’

__call__(vol)

Solve the EOS

Calculates the pressure for a given volume, is called the same way as the EOS model but uses underlying equation rather than the spline

Parameters:vol (np.ndarray) – Specific volume Returns:Pressure Return type:pr(np.ndarray)

__init__(name=u'Bump EOS', *args, **kwargs)

Instantiate the bump EOS

Parameters:

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

Keyword Arguments:  

name (str) – Name if the isentrope Def ‘Bump EOS’

derivative(order=1)

Returns the nth order derivative

Keyword Arguments:  order (int) – The order of the derivative. Def 1 Returns:Function object yielded first derivative of pressure w.r.t volume Return type:d1_fun(function)

EOSModel

class F_UNCLE.Models.Isentrope.EOSModel(p_fun, name=u'Equation of State Spline', *args, **kwargs)

Spline based EOS model

Multiply inherited structure from both Isentrope and Spline

Options

Name	Type	Def	Min	Max	Units	Description
spline_sigma	float	5e-3	0.0	None	‘??’	‘Multiplicative uncertainty of the prior (1/2%)
precondition	bool	False	None	None	‘’	Precondition flag

__init__(p_fun, name=u'Equation of State Spline', *args, **kwargs)

Instantiates the object

Parameters:

• p_fun (function) – A function defining the prior EOS
• *args – Variable length argument list.
• **kwargs – Arbitrary keyword arguments.

Keyword Arguments:  

name (str) – Name of the isentrope Def ‘Equation of State Spline’

_get_knot_spacing()

Returns a list of knot locations based on the spline parameters

If the option spacing is ‘lin’, uses linear spacing

‘log’, uses log spacing

Places ‘spline_N’ knots between ‘spline_min’ and ‘spline_max’

_on_str()

Added information on the EOS

_on_update_dof(model)

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

Parameters:model (EOSModel) – The new physics model Returns:The post-processed model Return type:(EOSModel)

get_dof(*args, **kwargs)

Returns the spline coefficients as the model degrees of freedom

Returns:The degrees of freedom of the model Return type:(np.ndarray)

get_gram()

Creates the gramm matrix

Parameters:None – Returns:(np.ndarray) A nxn gram matrix where n is the numer of knots

get_kernel(alpha, beta)

get_scaling()

Returns a scaling matrix to make the dofs of the same scale

The scaling matrix is a diagonal matrix with off diagonal terms zero the terms along the diagonal are the prior DOFs times the variance in the DOF values.

Returns:A nxn matrix where n is the number of model DOFs. Return type:(np.ndarray)

get_sigma()

Returns the co-variance matrix of the spline

Returns:Co-variance matrix for the EOS shape is (nxn) where n is the dof of the model Return type:(np.ndarray)

plot_basis(axes=None, fig=None, labels=[], linstyles=[])

Plots the basis function and their first and second derivatives

Parameters:

• fig (plt.Figure) – A valid figure object on which to plot
• axes (plt.Axes) – A valid axes, Ignored
• labels (list) – The labels, Ignored
• linestyles (list) – The linestyles, Ignored

Returns:

The figure

Return type:

(plt.Figure)

plot_diff(isentropes, axes=None, figure=None, linestyles=[u'-k', u'--k', u'-.k'], labels=None, vrange=None)

Plots the difference between the current EOS and other Isentropes

Plots the difference vs the prior

Parameters:

• isentropes (list) – A list of isentrope objects to compare
• axes (plt.Axes) – The Axes on which to plot
• figure (plt.Figure) – The figure object Ignored
• linestyles (list) – A list of styles to plot
• labels (list) – A list of labels for the Isentropes
• vrange (tuple) – the specific volume range to plot

Returns:

(plt.Axes)

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)

update_dof(c_in, *args, **kwargs)

Sets the spline coefficients

Parameters:c_in (Iterable) – The knot positions of the spline Returns:A copy of self with the new dofs Return type:(EOSModel)

PTW

class F_UNCLE.Models.Ptw.Ptw(name=u'Ptw flow stress', *args, **kwargs)

PTW Flow stress model

Usage

1. Instantiate a Ptw object with desired options
2. optional set the options as desired
3. Call the Ptw object with a valid temperature, strain rate and material specification
4. Call the object again, material must be specified each time

__call__(temp, strain_rate, material, **overrides)

Solves for the yield stress and flow stress at the given condition

Args:

temp(float): Temperature, in degrees Kelvin

strain_rate(float): Strain rate, in sec**-1 material(str): Key for material type

Keyword Args:

**overrides(dict): Passed as a chain of keyword arguments. These

arguments override any material property

Return:

flow_stress(float): Flow stress in ??Pa?? yield_stress(float): Yield stress in ??Pa??

__init__(name=u'Ptw flow stress', *args, **kwargs)

Instantiates the structure

Parameters:

• name (str) – Name of the structure
• *args – Variable length argument list.
• **kwargs – Arbitrary keyword arguments.

Returns:

None

__pre__(temp, strain_rate, material, **overrides)

Performs data conditioning

Performs the following tasks

1. Ensure the temperature input is in a valid range
2. Ensures the strain rate input is in a valid range
3. Ensure a valid material has been specified
4. Populates the materials database
5. Applies the overrides
6. Returns the normalizing factors

Parameters:

• temp (float) – Temperature, in degrees Kelvin
• strain_rate (float) – Strain rate, in sec**-1
• material (str) – Key for material type

Keyword Arguments:  

**overrides (dict) – Passed as a chain of keyword arguments. These arguments override any material property

Returns

(float): The shear modulus (float): The characteristic temperature. Temp normalized by melt temp (float): The characteristic timescale. Time for a vibration to pass through one atom

get_mat_data(material)

Gets the material data corresponding to the given material

Parameters:material (str) – Key for material type

get_melt_temperature(temp, strain_rate)

Gets the melt temperature for the operating conditions

Parameters:

• temp (float) – Temperature, in degrees Kelvin
• strain_rate (float) – Strain rate, in sec**-1

Returns:

The melt temperature in Kelvin

Return type:

(float)

get_shear_modulus(temp, strain_rate, t_melt)

Gets the shear modulus for the operating conditions

Parameters:

• temp (float) – Temperature, in degrees Kelvin
• strain_rate (float) – Strain rate, in sec**-1
• t_melt (float) – Melt temperature of the material in Kelvin

get_stress(strain, strain_rate, temp, material, **overrides)

Returns the stress in the material material

Parameters:

• strain (float or np.array) – The strain in the material
• strain_rate (float) – The train rate in the material
• temp (float) – The temperature of the material
• mat (str) – A valid material specifier

Keyword Arguments:  

• materials properties can be passed as kwargs to (valid) –
• default values (override) –

Returns:

The stress in the material

Return type:

(float or np.array)

get_stress_strain(temp, strain_rate, material, min_strain=0.05, max_strain=0.7, **overrides)

Returns the stress strain relationship for the material

Random Varialbe

class F_UNCLE.Models.RandomVariable.RandomVariable(prior_mean, name='Random Variable', *args, **kwargs)

A model of a normally distributed random variable of known variance

__call__(*args, **kwargs)

Returns the mean of the distribution

Parameters:None – Returns:The mean Return type:(float)

__init__(prior_mean, name='Random Variable', *args, **kwargs)

_on_str()

get_dof()

get_sigma(*args, **kwargs)

plot(axes=None, labels=['Coeff'], linestyles=['ok'], *args, **kwargs)

shape()

update_dof(dof_in)

Random Process

class F_UNCLE.Models.RandomProcess.RandomProcess(prior_mean, prior_var, name='Random Process', *args, **kwargs)

A model of a normally distributed random process of known variance

__call__(*args, **kwargs)

Returns the mean of the distribution

Parameters:None – Returns:The mean Return type:(float)

__init__(prior_mean, prior_var, name='Random Process', *args, **kwargs)

_on_str()

get_dof()

get_sigma(*args, **kwargs)

plot(axes=None, labels=['Coeff'], linestyles=['ok'], *args, **kwargs)

shape()

update_dof(dof_in, var_in=None)

Experiments

The F_UNCLE project currently does not use any true experimental data

Gun

class F_UNCLE.Experiments.GunModel.Gun(name=u'Gun Toy Computational Experiment', *args, **kwargs)

A toy physics model representing a gun type experiment

The problem integrates the differential equation for a mass being accelerated down the barrel of a gun by an the expanding products- of-detonation of a high explosive. The gun has finite dimensions and the integration lasts beyond when the projectile exits the gun.

Units

This model is based on the CGS units system

Diagram

variables defining the gun experiment

Options

Name	Type	Def	Min	Max	Units	Description
X_i	(float)	0.4	0.0	None	cm	Initial position of projectile
x_f	(float)	3.0	0.0	None	cm	Final/muzzle position of projectile
m	(float)	500.0	0.0	None	g	Mass of projectile
mass_he	(float)	4	0.0	None	g	The initial mass of high explosives used to drive the projectile
area	(float)	1.0	0.0	None	cm**2	Projectile cross section
sigma	(float)	1.0e0	0.0	None	??	Variance attributed to v measurements
t_min	(float)	1.0e-6	0.0	None	sec	Range of times for t2v spline
t_max	(float)	1.0e-2	0.0	None	sec	Range of times for t2v spline
n_t	(int)	250	0	None	‘’	Number of times for t2v spline

Attributes

Inherited from ::pyclass::pyStruc

Methods

__init__(name=u'Gun Toy Computational Experiment', *args, **kwargs)

Instantiate the Experiment object

Parameters:None – Keyword Arguments:  name (str) – A name. (Default = ‘Gun Toy Computational Experiment’)

_fit_t2v(vel, time)

Fits a cubic spline to the velocity-time history

This allows simulations and experiments to be compared at the experimental time-stamps

Parameters:

• vel (np.ndarray) – Velocity history
• time (np.ndarray) – Time history

Returns:

Spline of vel = f(time)

Return type:

(Spline)

_get_force(eos, posn)

Calculates the force on the projectile

The force is the pressure of the HE gas acting on the projectile. The pressure is given by the EOS model

Parameters:

• eos (Isentrope) – The equation of state model
• posn (float) – The scalar position

Returns:

The force in dyes

Return type:

(float)

_on_call(eos, **kwargs)

Performs the simulation / experiment using the internal EOS

Parameters:

• eos (Isentrope) – The equation of state model
• **kwargs – Arbitrary keyword arguments.

Returns:

Length 3, elements are:

0. (np.ndarray): Time, the independent variable

1. (tuple): length 2 for the two dependent variables

   0. (np.ndarray): Velocity history of the simulation
   1. (np.ndarray): Position history of the simulation

2. (Spline): A spline representing the velocity-time history

Return type:

(tuple)

_on_check_models(models)

Checks that the model is valid

Parameters:model (Isentrope) – A new EOS model Returns:A copy of self with the new eos model Return type:(GunModel)

_on_str(*args, **kwargs)

Print method of the gun model

Parameters:

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

Returns:

A string representing the object

Return type:

(str)

_shoot(eos)

Run a simulation and return the results: t, [x,v]

Solves the ODE

\[F(x,v,t) = \frac{d}{dt} (x, v)\]

Parameters:eos (Isentrope) – The equation of state model Returns:Length 2 elements are:

0. (np.ndarray): time vector
1. (list): elements are:

   0. (np.ndarray): position
   1. (np.ndarray): velocity

Return type:(tuple)

compare(simdata1, simdata2)

Compares a set of experimental data to the model

Error is dep less the model_data

See F_UNCLE.Utils.Experiment.Experiment.compare()

get_sigma(models)

Returns the co-variance matrix

see F_UNCLE.Utils.Experiment.Experiment.get_sigma()

plot(axes=None, fig=None, level=0, data=None, linestyles=[u'-k', u'-r'], labels=[u'Model', u'Error'], *args, **kwargs)

Plots the gun experiment

Overloads F_UNCLE.Utils.Struc.Struc.plot()

Plot Levels

0. The velocity-time history
1. The position-time history
2. The velocity-position history
3. A 4 subplot figure with levels 1-3 as well as the EOS plotted

Parameters:

• axes (plt.Axes) – Axes object on which to plot, if None, creates new figure
• fig (str) – A Figure object on which to plot, used for level3 plot
• linestyles (list) – A list of strings for linestyles 0. Data ‘-k’ 1. Error ‘-r’
• labels (list) – A list of strings for labels 0. ‘Model’ 1. ‘Error’
• level (int) – A tag for which kind of plot should be generated
• data (dict) – A list of other data to be plotted for comparison

Returns:

A figure

Return type:

(plt.figure)

shape()

Returns the degrees of freedom of the model

see F_UNCLE.Utils.Experiment.Experiment.shape()

Stick

class F_UNCLE.Experiments.Stick.Stick(name=u'Rate Stick Computational Experiment', *args, **kwargs)

A toy physics model representing a rate stick TO DO

• Update the __call__ method to not use hardcoded sensor positions

Units

Units are based on CGS system

Diagram

The assumed geometry of the rate stick

Attributes

eos

Isentrope – The products-of-detonation equation of state

Methods

__init__(name=u'Rate Stick Computational Experiment', *args, **kwargs)

Instantiate the Experiment object

Keyword Arguments:  name (str) – A name. (Default = “Rate Stick Computational Experiment”)

_on_call(eos)

Performs the rate stick experiment

Parameters:eos (Isentrope) – A valid EOS model Returns:Length 3. Elements are

0. (np.ndarray): The independent variable, the n sensor positions
1. (list): The dependent variables, elements are:
   0. (np.ndarray): The arrival n times at each sensor
   1. (list): The lables
2. (dict): The other solution data - ‘mean_fn’(Function): A function returning shock arrival

   time as a function of position

   • ‘vel_CJ’(float): The detonation velocity
   • ‘vol_CJ’(float): The specific volume at the_CJ point
   • ‘pres_CJ’(float): The pressure at the_CJ point
   • ‘Rayl_fn’(Function): A Rayleigh line function, see below

Return type:(tuple)

Rayleigh Line Function

p = ray(v, vel, vol0, eos)

Args:

• v(np.ndarray): The specific volume
• vel(float): Detonation velocity
• vol_0(float): Specific volume ahead of the shock
• eos(Isentrope): An equation of state model

Return:

• p(float): The pressure along the Rayleigh line at v

_on_check_models(models)

Checks that the model is valid

Parameters:model (dict) – A dictionary of models Returns:A copy of self with the new eos model Return type:(GunModel)

_on_str(*args, **kwargs)

Print method of the gun model. Called by Struct.__str__

Parameters:

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

Returns:

A string representing the object

Return type:

(str)

compare(simdata1, simdata2)

Compares the model instance to other data

The error is the difference in arrival times, dep less data.

see F_UNCLE.Utils.Experiment.Experiment.compare()

get_sigma(models)

Returns the variance matrix

variance is

\[\Sigma_i = \sigma_t^2 + \frac{\sigma_x^2}{V_{CJ}}\]

Where

• \(\sigma_t\) is the error in time measurements
• \(\sigma_x\) is the error in sensor position
• \(V_{CJ}\) is the detonation velocity

see F_UNCLE.Utils.Experiment.Experiment.get_sigma()

plot(models, axes=None, fig=None, data=None, level=1, linestyles=[u'-k', u':k', u'ok', u'+k'], labels=[u'Fit EOS', u'Rayleigh Line', u'($v_o$, $p_o$)', u'Inital point'], vrange=None)

Plots the EOS and Rayleigh line

Plots the critical Rayleigh line corresponding to the detonation velocity tangent to the EOS.

Parameters:

models (dict) – Dict of models

Keyword Arguments:  

• axes (plt.Axes) – The Axes on which to plot
• fig (plt.Figure) – The figure on which to plot ignored
• data (list) – The output from a call to Stick
• level (int) – Specifies what to plot

1. Plots the EOS with the Raylight line intersecting the CJ point

2. Plots the output from a simulation

   linestyles(list): Format strings for the trends, entries as follow

0. Stlye for the best fit EOS OR The data trend

   1. Style for the Rayleigh line
   2. Style for the CJ point
   3. Style for the initial condiations

   labels(list): Strings for the legend

0. ‘Fit EOS’ (Change to Data for level 2 plot)

   1. ‘Rayleigh line’
   2. ‘v_o, p_o’
   3. ‘Initial point’

   vrange(tuple): Range of volumes to plot

see F_UNCLE.Utils.Struc.Struc.plot()

shape()

Returns the shape of the object

see F_UNCLE.Utils.Experiment.Experiment.shape()

Sphere

class F_UNCLE.Experiments.Sphere.Sphere(name=u'Sphere compuational experiment', *args, **kwargs)

A toy physics model representing an expanding plastic sphere driven by HE

const

dict – A dictionary of conversion factors

__init__(name=u'Sphere compuational experiment', *args, **kwargs)

Instantiate the Experiment object

Keyword Arguments:  name (str) – A name. (Default = ‘Sphere computational experiment’)

_on_call(eos, strength)

Solves the sphere problem

Parameters:

• eos (Isentrope) – The Equation of strength model
• strength (Ptw) – The material strength model

Returns:

[0] - times [1](list): Data at each timestep

[0] - velocity of the case [1] - radius of the case [2] - case thickness [3] - specific volume of gasses within case [4] - pressure of gasses within case [5] - stress in the case [6] - strain in the case

Return type:

(tuple)

_on_check_models(models)

Checks that the model is valid

Parameters:model (Isentrope) – A new EOS model Returns:A copy of self with the new eos model Return type:(GunModel)

_on_str(*args, **kwargs)

Print method of the gun model

Parameters:

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

Returns:

A string representing the object

Return type:

(str)

compare(data1, data2)

Compares a set of experimental data to the model

Error is data2 less the data1

See F_UNCLE.Utils.Experiment.Experiment.compare()

plot(data, axes=None, fig=None, linestyles=[u'-k'], labels=[])

Plots the object

Parameters:

data (tuple) – The output from a call to a Sphere object

Keyword Arguments:  

• axes (plt.Axes) – The axes on which to plot Ignored
• fig (plt.Figure) – The figure on which to plot
• linestyles (list) – Strings for the linestyles
• labels (list) – Strings for the labels

Returns:

A reference to the figure containing the plot

Return type:

(plt.Figure)

shape(*args, **kwargs)

Gives the length of the independent variable vector

see F_UNCLE.Utils.Experiment.Experiment.shape()

update(model=None, strength=None)

Update the analysis with a new EOS model

Parameters:model (Isentrope) – A new EOS model Returns:A copy of self with the new eos model Return type:(GunModel)

Cylinder

Note

Cylinder has not been implemented yet

Optimization

The methods used for the actual optimization

Bayesian

class F_UNCLE.Opt.Bayesian.Bayesian(simulations, models, opt_keys=None, name=u'Bayesian', *args, **kwargs)

A class for performing Bayesian inference on a model given data

Attributes

Attributes:

simulations(list): Each element is a tuple with the following elements

0. A simulation
1. Experimental results

model(PhysicsModel): The model under consideration sens_matrix(nump.ndarray): The (nxm) sensitivity matrix

• n model degrees of freedom
• m total experiment DOF
• [i,j] sensitivity of model response i to experiment DOF j

Options These can be set as keyword arguments in a call to self.__init__

Name	Type	Def	Min	Max	Units	Description
outer_atol	(float)	1E-6	0.0	1.0		Absolute tolerance on change in likelihood for outer loop convergence
outer_rtol	(float)	1E-4	0.0	1.0		Relative tolerance on change in likelihood for outer loop convergence
maxiter	(int)	6	1	100		Maximum iterations for convergence of the likelihood
constrain	(bool)	True	None	None		Flag to constrain the optimization
precondition	(bool)	True	None	None		Flag to scale the problem
debug	(bool)	False	None	None		Flag to print debug information
verb	(bool)	True	None	None		Flag to print stats during optimization

Note

The options outer_atol and prior_weight are deprecated and should be used for debugging purposes only

Methods

__call__(comm=None)

Determines the best candidate EOS function for the models

Parameters:comm (MPI.intracom) – An MPI communicator for sensitities Returns:length 3, elements are:

0. (Bayesian): A copy of self with the optimal models
1. (list): is of solution history elements are:

   0. (np.ndarray) Log likelihood, (nx1) where n is number of iterations
   1. (np.ndarray) model dof history (nxm) where n is iterations and m is the model dofs

2. (dict) sensitivity matrix of all experiments to

   the model, keys are simulation keys

3. (dict) fisher information matrix for all experiments

   keys are simulation keys

Return type:(tuple)

__init__(simulations, models, opt_keys=None, name=u'Bayesian', *args, **kwargs)

Instantiates the Bayesian analysis

Parameters:

• simulations (dict) – A dictionary of simulation, experiment pairs
• models (dict) – A dictionary of models
• opt_keys (list) – The list of models to be optimized

Keyword Arguments:  

name (str) – Name for the analysis.(‘Bayesian’)

Returns:

None

_check_inputs(models, simulations)

Checks that the values for model and simulation are valid

_get_constraints()

Get the constraints on the model

_get_model_pq()

Gets the quadratic optimization matrix contributions from the prior

Parameters:None – Returns:elements are

0. (np.ndarray): p, a nxn matrix where n is the model DOF
1. (np.ndarray): q, a nx1 matrix where n is the model DOF

Return type:(tuple)

_get_sens(initial_data=None, comm=None)

Gets the sensitivity of the simulated experiment to the EOS

The sensitivity matrix is the attribute self.sens_matrix which is set by this method

Note

This method is specific to the model type under consideration. This implementation is only for spline models of EOS

Parameters:None – Keyword Arguments:  initial_data – The results of each simulation with the current best model. Each element in the list corresponds tho the output from a __call__ to each element in the self.simulations list Returns:None

_get_sim_pq(initial_data, sens_matrix)

Gets the QP contributions from the model

Note

This method is specific to the model type under consideration. This implementation is only for spline models of EOS

Parameters:

• initial_data (list) – A list of the initial results from the simulations in the same order as in the sim list
• sens_matrix (np.ndarray) – The sensitivity matrix

Returns:

Elements are:

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

Return type:

(tuple)

_local_opt(initial_data, sens_matrix)

Solves the quadratic problem for maximization of the log likelihood

Parameters:

• initial_data (list) – The initial data corresponding to simulations from sims
• sens_matrix (np.array) – The sensitivity matrix about the model

Returns:

The step direction for greatest improvement in log likelihood

Return type:

(np.ndarray)

_on_str()

Print method for Bayesian model called by Struct.__str__

Parameters:None – Returns:String describing the Bayesian object Return type:(str)

static fisher_decomposition(fisher_dct, simid, models, mkey, tol=0.001)

Calculate a spectral decomposition of the fisher information matrix

Parameters:

• fisher_dct (dict) – A dictionary nxn array where n is sum of all model dof
• simid (str) – Key for the simulation you want the Fisher info for
• models (dict) – A dictionary of all models
• mkey (str) – The key for the model on which the analysis is being performed

Keyword Arguments:  

tol (float) – Eigenvalues less than tol are ignored

Returns:

Elements are:

0. (list): Eigenvalues greater than tol

1. (np.ndarray): nxm array.

   • n is number of eigenvalues greater than tol
   • m is model dof

2. (np.ndarray): nxm array

   • n is the number of eigenvalues greater than tol
   • m is an arbitrary dimension of independent variable

3. (np.ndarray): vector of independent variable

Return type:

(tuple)

get_data()

Generates a set of data at each experimental data-point

For each pair of simulations and experiments, generates the the simulation response, aligning it with the experimental data

Parameters:None – Returns:List of lists for experiment comparison data

0. independent value
1. dependent value of interest
2. the summary data (3rd element) of sim

Return type:(list)

get_hessian(initial_data=None, simid=None)

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

\[\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}\\ \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}\\ \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{split}\]

\[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}\]

get_opt_dof()

Returns a vector of the model DOF for the optimization

model_log_like()

Gets the log likelihood of the self.model given that model’s prior

Returns:Log likelihood of the model Return type:(float)

\[\log(p(f|y))_{model} = -\frac{1}{2}(f - \mu_f)\Sigma_f^{-1}(f-\mu_f)\]

plot_convergence(hist, axes=None, linestyles=[u'-k'], labels=[])

Parameters:

hist (tuple) – Convergence history, elements 0. (list): MAP history 1. (list): DOF history

Keyword Arguments:  

• axes (plt.Axes) – The axes on which to plot the figure, if None, creates a new figure object on which to plot.
• linestyles (list) – Strings for the linestyles
• labels (list) – Strings for the labels

plot_fisher_data(fisher_data, axes=None, fig=None, linestyles=[], labels=[])

Parameters:

fisher_dat (tuple) – Data from the fisher_decomposition function see docscring for definition

Keyword Arguments:  

• axes (plt.Axes) – Ignored
• fig (plt.Figure) – A valid figure to plot on
• linestyles (list) – A list of valid linestyles Ignored
• labels (list) – A list of labels Ignored

shape()

Gets the dimensions of the problem

Returns:The (n, m) dimensions of the problem

• n is the total degrees of freedom of all the model responses
• m is the degrees of freedom of the model

Return type:(tuple)

sim_log_like(initial_data)

Gets the log likelihood of the simulations given the data

Parameters:

• model (PhysicsModel) – The model under investigation
• initial_data (list) – A list of the initial data for the simulations Each element in the list is the output from a __call__ to the corresponding element in the self.simulations list

Returns:

Log likelihood of the simulation given the data

Return type:

(float)

\[\log(p(f|y))_{model} = -\frac{1}{2} (y_k - \mu_k(f))\Sigma_k^{-1}(y_k-\mu_k(f))\]

update(simulations=None, models=None)

Updates the properties of the Bayesian analysis

Keyword Arguments:  

• simulations (dict) – Dictionary of simulation experiment pairs (Default None)
• models (dict) – Dictionary of models (Default None)

Returns:

None

CostOpt

class F_UNCLE.Opt.cost_opt.CostOpt(simulations, models, opt_keys=None, name=u'Bayesian', *args, **kwargs)

Code for experimenting with alternative optimization algorithms

This class is experimental. It Requires importing pyOpt.

__call__()

Overloaded call function to optimize cost directly

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

0. (np.ndarray): The independent variable
1. (np.ndarray): The single dependent variable
2. (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

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

1. (list): The simulation dependent results

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

2. (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:

0. (np.ndarray): P, a nxn matrix where n is the model DOF
1. (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

0. (scipy.interpolate.LSQSpline): A smoothing spline representing the data
1. (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

0. (np.ndarray): The single vector of the simulation independent variable
1. (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

2. (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:

0. (np.ndarray): P, a nxn matrix where n is the model DOF
1. (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:

0. list-n of value basis functions for the nth dof evaluated at all knots
1. list-n of 1st derivative basis functions for the nth dof evaluated at all knots
2. list-n of 2nd derivative basis functions for the nth dof evaluated at all knots
3. 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)

examples

/README.rst

The following is in the file README.rst which is in the root directory of the project:

Functional Uncertainty Constrained by Law and Experiment

Prerequisites

To run the tests, certain software must be installed.

The minimum required python packages to run F_UNCLE are shown in the file /pip_req.txt. These packages can either be installed manually or the conda package manager can be used to create an environment containing all the required packages. In the root F_UNCLE folder run the following commands:

conda create -n funcle python=3.5 --file pip_req.txt
source activate funcle

The conda environment will now be active and provide all the packages needed to run F_UNCLE

To run the tests, several other packages are needed, they are given in pip_test_req.txt. These packages can either be installed manually or added to the conda environment with the following commands from the root F_UNCLE directory:

source activate funcle
conda install --file pip_test_req.txt

To build the documentation, further packages are needed, they are given in pip_doc_req.txt and can be installed as above

Testing

From the root directory of F_UNCLE run:

pytest F_UNCLE

This will discover, run and report on all test in the F_UNCLE module

Documentation

Documentation is available on readthedocs

Los Alamos National Laboratory (LANL) Release Information

The initial version of this code was written at LANL. It was released in 2016 with Los Alamos Computer Code index LA-CC-16-034 and the following description:

The F_UNCLE project is for quantitatively characterizing uncertainty about functions and how physical laws and experiments constrain that uncertainty. The project is an evolving platform consisting of program and text files that numerically demonstrate and explore quantitative characterizations of uncertainty about functions and how either historical or proposed experiments have or could constrain that uncertainty. No actual physical measurements are distributed as part of the software.

Authors

• Stephen Andrews
• Andrew Fraser

License

F_UNCLE: Tools for understanding functional uncertainty Copyright (C) 2016 Andrew M. Fraser and Stephen A. Andrews

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

Files and Directories

The root project directory has the following files and sub-directories:

docs

Files for making the documentation

F_UNCLE

Code described in this documentation

reports

Latex source for papers and presentations based on F_UNCLE

The F_UNCLE directory has the following sub-directories:

examples

Scripts that make figures for documents in root/reports

Experiments

Code to simulate toy experiments such as: Cylinder, Gun, Sphere and Stick with classes that are sub-classes of classes defined in the Models and Utils directories

Models

Scripts that define particular “Physics Models” that inherit from Utils/PhysicsModel.py

Opt

Code for optimizing a posteriori probability and reporting Fisher information

Utils

Scripts with base classes for Experiments and Models

__init__.py

File that enables importing directory as module and contains text for documentation

Indices and tables

• Index
• Module Index
• Search Page