Model:Dakotathon

From CSDMS


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
Nr. of publications: --
Total citations: 0
h-index: --"--" is not a number.
m-quotient: 0

Link to this page


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.