Merge pull request #31 from csdms/mdpiper/update-documentation

Update documentation

.gitmodules

@@ -1,6 +1,3 @@
-[submodule "docs/scipy-sphinx-theme"]
-	path = docs/scipy-sphinx-theme
-	url = https://github.com/scipy/scipy-sphinx-theme
 [submodule "docs/numpydoc"]
 	path = docs/numpydoc
 	url = https://github.com/numpy/numpydoc

README.md

@@ -7,7 +7,7 @@
 
 The CSDMS Dakota interface provides
 a [Basic Model Interface](http://dx.doi.org/10.1016/j.cageo.2012.04.002)
-and API for the [Dakota](https://dakota.sandia.gov/)
+and a Python API for the [Dakota](https://dakota.sandia.gov/)
 iterative systems analysis toolkit.
 This is currently alpha-level software
 supported on Linux and Mac OSX.
@@ -56,16 +56,17 @@ specifying a Dakota analysis method:
 	>>> d = Dakota(method='vector_parameter_study')
 
 Currently,
-three Dakota methods
+four Dakota methods
 
 * [vector parameter study](https://dakota.sandia.gov/sites/default/files/docs/6.1/html-ref/method-vector_parameter_study.html)
 * [centered parameter study](https://dakota.sandia.gov/sites/default/files/docs/6.1/html-ref/method-centered_parameter_study.html)
 * [multidim parameter study](https://dakota.sandia.gov/sites/default/files/docs/6.1/html-ref/method-multidim_parameter_study.html)
+* [sampling](https://dakota.sandia.gov/sites/default/files/docs/6.1/html-ref/method-sampling.html)
 
 are supported.
 
 To run a sample case,
-create an input file
+create a Dakota input file
 from the default vector parameter study
 and call Dakota:
 

csdms/dakota/dakota.py

@@ -11,7 +11,7 @@
 
 class Dakota(Experiment):
 
-    """Configure and run a Dakota experiment."""
+    """Controller for configuring and running a Dakota experiment."""
 
     def __init__(self,
                  run_directory=os.getcwd(),
@@ -21,18 +21,34 @@ def __init__(self,
                  template_file=None,
                  auxiliary_files=(),
                  **kwargs):
-        """Create a new `Dakota` instance.
+        """Initialize a Dakota experiment.
 
-        Called with no parameters, a Dakota experiment with basic
-        defaults (a vector parameter study with the built-in
-        `rosenbrock` example) is created. Use ``method`` to set the
-        Dakota analysis method in a new experiment.
+        Called with no parameters, a Dakota experiment with basic defaults
+        (a vector parameter study with the built-in `rosenbrock` example)
+        is created. Use ``method`` to set the Dakota analysis method in a
+        new experiment.
 
         Parameters
         ----------
-        method : str, optional
-          The desired Dakota method (e.g., `vector_parameter_study`,
-          `polynomial_chaos`, etc.) to use in an experiment.
+        run_directory : str, optional
+            The working directory in which Dakota is run, and output
+            is placed (default is the current directory).
+        configuration_file : str, optional
+            A Dakota instance serialized to a YAML file (default is
+            **config.yaml**).
+        input_file : str, optional
+            Name of Dakota input file (default is **dakota.in**)
+        output_file : str, optional
+            Name of Dakota output file (default is **dakota.out**)
+        template_file : str, optional
+            The Dakota template file, formed from the input file of
+            the model to study, but with study variables replaced by
+            descriptors in braces; e.g., ``{total_annual_precipitation}``
+            (default is None).
+        auxiliary_files : str or tuple or list of str, optional
+            Additional input files used by the model being studied.
+        **kwargs
+            Arbitrary keyword arguments.
 
         Examples
         --------
@@ -65,7 +81,7 @@ def run_directory(self, value):
         Parameters
         ----------
         value : str
-          The new run directory path.
+          The new run directory path (default is current directory).
 
         """
         self._run_directory = os.path.abspath(value)
@@ -82,7 +98,7 @@ def configuration_file(self, value):
         Parameters
         ----------
         value : str
-          The new file path.
+          The new file path (default is 'config.yaml').
 
         """
         if not os.path.isabs(value):
@@ -159,11 +175,11 @@ def from_file_like(cls, file_like):
         return cls(**config)
 
     def serialize(self, config_file=None):
-        """Dump settings to a YAML configuration file.
+        """Dump settings for experiment to a YAML configuration file.
 
         Parameters
         ----------
-        config_file: str, optional
+        config_file : str, optional
           A path/name for a new configuration file.
 
         Examples
@@ -189,11 +205,14 @@ def serialize(self, config_file=None):
             yaml.safe_dump(props, fp, default_flow_style=False)
 
     def write_input_file(self, input_file=None):
-        """Create a Dakota input file on the file system.
+        """Create the Dakota input file for the experiment.
+
+        The input file is written to the directory specified by the
+        `run_directory` attribute.
 
         Parameters
         ----------
-        input_file: str, optional
+        input_file : str, optional
           A path/name for a new Dakota input file.
 
         Examples

csdms/dakota/environment/base.py

@@ -14,6 +14,6 @@ def __init__(self, **kwargs):
         pass
 
     def __str__(self):
-        """Define the environment block of a Dakota input file."""
+        """The header for the environment block of a Dakota input file."""
         s = 'environment\n'
         return(s)

csdms/dakota/environment/environment.py

@@ -11,7 +11,16 @@ class Environment(EnvironmentBase):
     """Describe Dakota environment."""
 
     def __init__(self, data_file='dakota.dat', **kwargs):
-        """Create a set of default experiment parameters."""
+        """Define parameters for the Dakota environment.
+
+        Parameters
+        ----------
+        data_file : str, optional
+            The Dakota tabular data file (default is 'dakota.dat').
+        **kwargs
+            Optional keyword arguments.
+
+        """
         EnvironmentBase.__init__(self, **kwargs)
         self.data_file = data_file
 

csdms/dakota/experiment.py

@@ -1,5 +1,3 @@
-"""A template for describing a Dakota experiment."""
-
 import os
 import importlib
 
@@ -9,6 +7,7 @@ class Experiment(object):
     """An aggregate of control blocks that define a Dakota input file."""
 
     blocks = ('environment', 'method', 'variables', 'interface', 'responses')
+    """The named control blocks of a Dakota input file."""
 
     def __init__(self,
                  component=None,
@@ -18,7 +17,46 @@ def __init__(self,
                  interface='direct',
                  responses='response_functions',
                  **kwargs):
-        """Create a set of default experiment parameters."""
+        """Create the set of control blocks for a Dakota experiment.
+
+        Called with no parameters, a Dakota experiment with basic defaults
+        (a vector parameter study with the built-in `rosenbrock` example)
+        is created.
+
+        Parameters
+        ----------
+        component : str, optional
+            Name of CSDMS component which Dakota is analyzing (default
+            is None).
+        environment : str, optional
+            Type of environment used in Dakota experiment (default is
+            'environment').
+        method : str, optional
+            Type of method used in Dakota experiment (default is
+            'vector_parameter_study').
+        variables : str, optional
+            Type of variables used in Dakota experiment (default is
+            'continuous_design').
+        interface : str, optional
+            Type of interface used in Dakota experiment (default is
+            'direct').
+        responses : str, optional
+            Type of responses used in Dakota experiment (default is
+            'response_functions').
+        **kwargs
+            Arbitrary keyword arguments.
+
+        Examples
+        --------
+        Create a generic Dakota experiment:
+
+        >>> x = Experiment()
+
+        Create a vector parameter study experiment:
+
+        >>> x = Experiment(method='vector_parameter_study')
+
+        """
         self.component = component
         if self.component is not None:
             interface = 'fork'
@@ -29,54 +67,104 @@ def __init__(self,
 
     @property
     def environment(self):
+        """The environment control block."""
         return self._environment
 
     @environment.setter
     def environment(self, value):
+        """Set the environment control block.
+
+        Parameters
+        ----------
+        value : obj
+            An environment control block object, an instance of a
+            subclass of csdms.dakota.environment.base.EnvironmentBase.
+
+        """
         supr = self._environment.__class__.__bases__[0]
         if not isinstance(value, supr):
             raise TypeError("Must be a subclass of " + str(supr))
         self._environment = value
 
     @property
     def method(self):
+        """The method control block."""
         return self._method
 
     @method.setter
     def method(self, value):
+        """Set the method control block.
+
+        Parameters
+        ----------
+        value : obj
+            A method control block object, an instance of a
+            subclass of csdms.dakota.method.base.MethodBase.
+
+        """
         supr = self._method.__class__.__bases__[0]
         if not isinstance(value, supr):
             raise TypeError("Must be a subclass of " + str(supr))
         self._method = value
 
     @property
     def variables(self):
+        """The variables control block."""
         return self._variables
 
     @variables.setter
     def variables(self, value):
+        """Set the variables control block.
+
+        Parameters
+        ----------
+        value : obj
+            A variables control block object, an instance of a
+            subclass of csdms.dakota.variables.base.VariablesBase.
+
+        """
         supr = self._variables.__class__.__bases__[0]
         if not isinstance(value, supr):
             raise TypeError("Must be a subclass of " + str(supr))
         self._variables = value
 
     @property
     def interface(self):
+        """The interface control block."""
         return self._interface
 
     @interface.setter
     def interface(self, value):
+        """Set the interface control block.
+
+        Parameters
+        ----------
+        value : obj
+            An interface control block object, an instance of a
+            subclass of csdms.dakota.interface.base.InterfaceBase.
+
+        """
         supr = self._interface.__class__.__bases__[0]
         if not isinstance(value, supr):
             raise TypeError("Must be a subclass of " + str(supr))
         self._interface = value
 
     @property
     def responses(self):
+        """The responses control block."""
         return self._responses
 
     @responses.setter
     def responses(self, value):
+        """Set the responses control block.
+
+        Parameters
+        ----------
+        value : obj
+            A responses control block object, an instance of a
+            subclass of csdms.dakota.responses.base.ResponsesBase.
+
+        """
         supr = self._responses.__class__.__bases__[0]
         if not isinstance(value, supr):
             raise TypeError("Must be a subclass of " + str(supr))
@@ -92,6 +180,41 @@ def _import(self, subpackage, module, **kwargs):
         return cls(**kwargs)
 
     def __str__(self):
+        """The contents of the Dakota input file represented as a string.
+
+        Examples
+        --------
+        Print the Dakota input file to the console.
+
+        >>> x = Experiment()
+        >>> print x
+        # Dakota input file
+        environment
+          tabular_data
+            tabular_data_file = 'dakota.dat'
+        <BLANKLINE>
+        method
+          vector_parameter_study
+            final_point = 1.1 1.3
+            num_steps = 10
+        <BLANKLINE>
+        variables
+          continuous_design = 2
+            descriptors = 'x1' 'x2'
+            initial_point = -0.3 0.2
+        <BLANKLINE>
+        interface
+          id_interface = 'CSDMS'
+          direct
+          analysis_driver = 'rosenbrock'
+        <BLANKLINE>
+        responses
+          response_functions = 1
+            response_descriptors = 'y1'
+          no_gradients
+          no_hessians
+        <BLANKLINE>
+        """
         s = '# Dakota input file\n'
         for section in Experiment.blocks:
             s += str(getattr(self, section))

csdms/dakota/interface/base.py

@@ -17,7 +17,25 @@ def __init__(self,
                  asynchronous=False,
                  evaluation_concurrency=2,
                  **kwargs):
-        """Create a set of default experiment parameters."""
+        """Create a default interface.
+
+        Parameters
+        ----------
+        interface : str, optional
+            The Dakota interface type (default is 'direct').
+        id_interface : str, optional
+            Interface identifier.
+        analysis_driver : str, optional
+            Name of analysis driver for Dakota experiment (default is
+            'rosenbrock').
+        asynchronous : bool, optional
+            Set to perform asynchronous evaluations (default is False).
+        evaluation_concurrency : int, optional
+            Number of concurrent evaluations (default is 2).
+        **kwargs
+            Optional keyword arguments.
+
+        """
         self.interface = interface
         self.id_interface = id_interface
         self.analysis_driver = analysis_driver