Model:Dakotathon

Dakotathon

Metadata

Also known as	CSDMS Dakota Interface (CDI)
Model type	Tool
Model part of larger framework
Note on status model
Date note status model

Incorporated models or components:

Spatial dimensions	1D, 1.5D, 2D, 3D
Spatial extent	Continental, Global, Grain-Scale, Landscape-Scale, Patch-Scale, Point-Based, Reach-Scale, Regional-Scale, Watershed-Scale
Model domain	Terrestrial, Hydrology, Coastal, Marine, Geodynamic, Climate
One-line model description	A Python API for the Dakota iterative systems analysis toolkit.
Extended model description	Dakota is a software toolkit, developed at Sandia National Laboratories, that provides an interface between models and a library of analysis methods, including support for sensitivity analysis, uncertainty quantification, optimization, and calibration techniques. Dakotathon is a Python package that wraps and extends Dakota’s file-based user interface. It simplifies the process of configuring and running a Dakota experiment, and it allows a Dakota experiment to be scripted. Any model written in Python that exposes a Basic Model Interface (BMI), as well as any model componentized in the CSDMS modeling framework, automatically works with Dakotathon. Currently, six Dakota analysis methods have been implemented from the much larger Dakota library: vector parameter study, centered parameter study, multidim parameter study, sampling, polynomial chaos, and stochastic collocation.

Keywords:	uncertainty, sensitivity, optimization, calibration,

Name	Mark Piper
Type of contact	Technical contact
Institute / Organization	University of Colorado, INSTAAR/CSDMS
Postal address 1	450 UCB
Postal address 2
Town / City	Boulder
Postal code	80309
State	Colorado
Country	United States
Email address	mark.piper@colorado.edu
Phone
Fax

Supported platforms	Linux, Mac OS
Other platform
Programming language	Python
Other program language
Code optimized	Single Processor, Multiple Processors
Multiple processors implemented	Distributed memory
Nr of distributed processors
Nr of shared processors
Start year development	2015
Does model development still take place?	Yes
If above answer is no, provide end year model development
Code development status	Active
When did you indicate the 'code development status'?	2020
Model availability	As code
Source code availability (Or provide future intension)	Through web repository
Source web address	https://github.com/csdms/dakota
Source csdms web address
Program license type	BSD or MIT X11
Program license type other
Memory requirements
Typical run time	Minutes to days -- depends on experiment and model being investigated.

Describe input parameters	[[Describe input parameters model::Dakotathon takes no input parameters, though it does require a configuration file in YAML format. An example is given here.]]
Input format	ASCII
Other input format	Any parameter configuration files required by the model being studied will also be needed by Dakotathon.
Describe output parameters	Dakotathon produces no output parameters; instead, it creates the standard Dakota output files dakota.out and dakota.dat.
Output format	ASCII
Other output format	Any output files created by the model being studied will also be available after running Dakotathon.
Pre-processing software needed?	No
Describe pre-processing software
Post-processing software needed?	No
Describe post-processing software
Visualization software needed?	No
If above answer is yes
Other visualization software

Describe processes represented by the model
Describe key physical parameters and equations
Describe length scale and resolution constraints
Describe time scale and resolution constraints
Describe any numerical limitations and issues	Most Dakota analysis techniques require multiple iterations of a model to explore a requested parameter space, so an experiment created with Dakotathon can take a long time to run and produce a lot of model output.

Describe available calibration data sets
Upload calibration data sets if available:
Describe available test data sets	[[Describe available test data::Sample input files can be found in the Dakotathon repository on GitHub.]]
Upload test data sets if available:
Describe ideal data for testing

Do you have current or future plans for collaborating with other researchers?	[[Current future collaborators::Any CSDMS member is welcome to fork the Dakotathon repository, make changes, and send a pull request back to the CSDMS Integration Facility. We appreciate any contribution!]]

Is there a manual available?	No
Upload manual if available:
Model website if any	http://csdms-dakota.readthedocs.io/
Model forum / discussion board

Comments	Please send any questions or comments to mark.piper@colorado.edu or csdmssupport@colorado.edu.

This part will be filled out by CSDMS staff

OpenMI compliant	No but possible
BMI compliant	Yes
WMT component	Yes
PyMT component
Is this a data component

Can be coupled with:

Model info

Authors

Mark Piper

Source code

Go to external source code site

Model citations

Nr. of publications:	--
Total citations:	0
h-index:	--"--" is not a number.
m-quotient:	0

QR-code

Link to this page

Other models by author

Dakotathon provides a Basic Model Interface and a Python API for a subset of the methods included in the Dakota iterative systems analysis toolkit. Installation instructions and usage examples are provided below. Developer documentation is available at http://csdms-dakota.readthedocs.io.

This is currently alpha-level software supported on Linux and Mac OSX.

Installation

Install Dakotathon into an Anaconda Python distribution with

$ conda install -c csdms dakotathon

or install from source with

$ git clone https://github.com/csdms/dakota.git
$ cd dakota
$ python setup.py install

Dakotathon requires Dakota. Follow the instructions on the Dakota website for downloading and installing a precompiled Dakota binary for your system. Dakota version 6.1 is currently supported.

Execution: standalone

Import Dakotathon into a Python session with:

from dakotathon import Dakota

Create a `Dakota` instance, specifying a Dakota analysis method:

d = Dakota(method='vector_parameter_study')

To run a sample case, create a Dakota input file from the default vector parameter study and call Dakota:

d.write_input_file()
d.run()

Dakota output is written to two files, dakota.out (run information) and dakota.dat (tabular output), in the current directory.

For more in-depth examples of using the CSDMS Dakota interface, see the Jupyter Notebooks in the examples directory of the Dakotathon repository.

Note

If you're using Anaconda IPython on Mac OS X, include the DYLD_LIBRARY_PATH environment variable in your session before calling the `run` method with:

from dakotathon.utils import add_dyld_library_path
add_dyld_library_path()

See https://github.com/csdms/dakota/issues/17 for more information.

Execution: in PyMT

Dakotathon can also be called as a component in a WMT execution server where PyMT has been installed. For example, to perform a centered parameter study on the Hydrotrend component, start with imports:

import os
from pymt.components import CenteredParameterStudy, Hydrotrend
from dakotathon.utils import configure_parameters

then create instances of the Hydrotrend and Dakota components:

h, c = Hydrotrend(), CenteredParameterStudy()

Next, set up a dict of parameters for the experiment:

parameters = {
  'component': type(c).__name__,
  'run_duration': 365,               # days
  'auxiliary_files': 'HYDRO0.HYPS',  # the default Waipaoa hypsometry
  'descriptors': ['starting_mean_annual_temperature',
                  'total_annual_precipitation'],
  'initial_point': [15.0, 2.0],
  'steps_per_variable': [2, 5],
  'step_vector': [2.5, 0.2],
  'response_descriptors': ['channel_exit_water_sediment~suspended__mass_flow_rate',
                           'channel_exit_water__volume_flow_rate'],
  'response_statistics': ['median', 'mean']
}

and use a helper function to format the parameters for Dakota and Hydrotrend:

cparameters, hparameters = configure_parameters(parameters)

Set up the Hydrotrend component:

cparameters['run_directory'] = h.setup(os.getcwd(), **hparameters)

Create the Dakota template file from the Hydrotrend input file:

cfg_file = 'HYDRO.IN'
dtmpl_file = cfg_file + '.dtmpl'
os.rename(cfg_file, dtmpl_file)
cparameters['template_file'] = dtmpl_file

Set up the Dakota component:

c.setup(dparameters['run_directory'], **cparameters)

then initialize, run, and finalize the Dakota component:

c.initialize('dakota.yaml')
c.update()
c.finalize()

Dakota output is written to two files, dakota.out (run information) and dakota.dat (tabular output), in the current directory.

For more in-depth examples of using Dakotathon with PyMT, see the Python scripts in the examples directory of the Dakotathon repository.