Dakotathon

Dakotathon provides a Basic Model Interface and a Python API for a subset of the methods included in the Dakota iterative systems analysis toolkit, including:

• vector_parameter_study,
• centered_parameter_study,
• multidim_parameter_study,
• psuade_moat,
• sampling,
• polynomial_chaos, and
• stoch_collocation.

Dakotathon is currently beta-level software supported on Linux and macOS. API documentation is available at http://csdms-dakota.readthedocs.io.

Installation

Install Dakotathon into an Anaconda Python distribution with

$ conda install -c csdms-stack dakotathon

or install from source with

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

Dakotathon requires Dakota 6.1 or greater. Install Dakota through conda with

$ conda install -c csdms-stack -c conda-forge dakota

or, follow the instructions on the Dakota website for downloading and installing a precompiled Dakota binary for your system.

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 Dakotathon as a standalone Python package, see the Jupyter Notebooks in the examples directory of this repository.

Note

If you're using Anaconda IPython on macOS, 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 #17 for more information.

Execution: in PyMT

Dakotathon can also be called as a component in PyMT. 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:

experiment = {
  'component': type(c).__name__,
  'run_duration': 10,                # years
  '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 for Hydrotrend:

cparameters, hparameters = configure_parameters(experiment)

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'  # get from pymt eventually
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 this repository.

Contributing

Dakotathon is open source software, released under an MIT license. Contributions are welcome. Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.