Link, code and typos fixed in documentation

docs/source/index.rst

@@ -12,8 +12,8 @@ f3dasm
  :hidden:
  :glob:
 
- rst_doc_files/general/gettingstarted
  rst_doc_files/general/overview
+ rst_doc_files/general/gettingstarted
 
 .. toctree::
  :maxdepth: 2
@@ -41,7 +41,7 @@ f3dasm
 
  rst_doc_files/classes/datageneration/datagenerator
  rst_doc_files/classes/datageneration/functions
- rst_doc_files/classes/datageneration/f3dasm-simulate
+ .. rst_doc_files/classes/datageneration/f3dasm-simulate
 
 
 .. toctree::

docs/source/rst_doc_files/classes/design/domain.rst

@@ -19,7 +19,7 @@ The :class:`~f3dasm.design.Domain` is a set of parameter instances that make up
 |
 
 
-To start, we instantiate an empty domain object:
+To start, we create an empty domain object:
 
 .. code-block:: python
 
@@ -28,7 +28,7 @@ To start, we instantiate an empty domain object:
  domain = Domain()
 
 
-Now we can gradually add some parameters!
+Now we can add some parameters!
 
 .. _parameters:
 
@@ -51,31 +51,35 @@ There are four types of parameters that can be created: :ref:`float <continuous-
 Floating point parameters
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-* We can create **continous** parameters with a :code:`low` and :code:`high` boundary with the :meth:`~f3dasm.design.Domain.add_float` method:
+* We can create **continous** parameters with a lower bound (:code:`low`) and upper bound (:code:`high`) with the :meth:`~f3dasm.design.Domain.add_float` method:
 
 .. code-block:: python
 
  domain.add_float(name='x1', low=0.0, high=100.0)
  domain.add_float(name='x2', low=0.0, high=4.0) 
 
+An optional argument :code:`log` can be set to :code:`True` to create a log-scaled parameter:
+
 .. _discrete-parameter:
 
 Discrete parameters
 ^^^^^^^^^^^^^^^^^^^
 
-* We can create **discrete** parameters with a :code:`low` and :code:`high` boundary with the :meth:`~f3dasm.design.Domain.add_int` method:
+* We can create **discrete** parameters with a lower bound (:code:`low`) and upper bound (:code:`high`) with the :meth:`~f3dasm.design.Domain.add_int` method:
 
 .. code-block:: python
 
  domain.add_int(name='x3', low=2, high=4)
  domain.add_int(name='x4', low=74, high=99) 
 
+An optional argument :code:`step` can be set to an integer value to define the step size between the lower and upper bound. By default the step size is 1.
+
 .. _categorical-parameter:
 
 Categorical parameters
 ^^^^^^^^^^^^^^^^^^^^^^
 
-* We can create **categorical** parameters with a list of items (:code:`categories`) with the :meth:`~f3dasm.design.Domain.add_category` method:
+* We can create **categorical** parameters with a list of values (:code:`categories`) with the :meth:`~f3dasm.design.Domain.add_category` method:
 
 .. code-block:: python
 
@@ -139,6 +143,8 @@ We can make easily make a :math:`n`-dimensional continous domain with the helper
 We have to specify the boundaries (``bounds``) for each of the dimensions with a list of lists or numpy :class:`~numpy.ndarray`:
 
 .. code-block:: python
-
+ 
+ from f3dasm.design import make_nd_continuous_domain
+ import numpy as np
  bounds = np.array([[-1.0, 1.0], [-1.0, 1.0]])
- domain = f3dasm.make_nd_continuous_domain(bounds=bounds, dimensionality=2)
+ domain = make_nd_continuous_domain(bounds=bounds, dimensionality=2)

docs/source/rst_doc_files/classes/design/experimentdata.rst

@@ -4,7 +4,7 @@ Experiment Data
 The :class:`~f3dasm.ExperimentData` object is the main object used to store implementations of a design-of-experiments, 
 keep track of results, perform optimization and extract data for machine learning purposes.
 
-All other processses of f3dasm use this object to manipulate and access data about your experiments.
+All other processses of :mod:`f3dasm` use this object to manipulate and access data about your experiments.
 
 The :class:`~f3dasm.ExperimentData` object consists of the following attributes:
 
@@ -42,7 +42,8 @@ You can construct a :class:`~f3dasm.ExperimentData` object by providing it :ref:
 .. code-block:: python
 
  >>> from f3dasm import ExperimentData
- >>> data = ExperimentData(domain, input_data, output_data)
+ >>> data = ExperimentData(
+ domain=domain, input_data=input_data, output_data=output_data)
 
 
 The following sections will explain how to construct a :class:`~f3dasm.ExperimentData` object from your own data.
@@ -62,7 +63,7 @@ Learn more about the :class:`~f3dasm.design.Domain` object in the :ref:`domain <
  >>> domain = Domain()
  >>> domain.add_float('x0', 0., 1.)
  >>> domain.add_float('x1', 0., 1.)
- >>> data = ExperimentData(domain)
+ >>> data = ExperimentData(domain=domain)
 
 .. warning ::
 
@@ -89,9 +90,9 @@ Several datatypes are supported for the ``input_data`` argument:
 
  >>> from f3dasm import ExperimentData
  >>> from f3dasm.design import Domain
- >>> df = pd.DataFrame(...) # your data in a pandas DataFrame
- >>> domain = Domain({'x0': ContinuousParameter(0., 1.)}, 'x1': ContinuousParameter(0., 1.)}) 
- >>> data = ExperimentData.from_dataframe(df, domain)
+ >>> domain.add_float('x0', 0., 1.)
+ >>> domain.add_float('x1', 0., 1.)
+ >>> data = ExperimentData(domain=domain, input_data=df)
 
 * A two-dimensional :class:`~numpy.ndarray` object with shape (<number of experiments>, <number of input dimensions>)
 
@@ -100,9 +101,10 @@ Several datatypes are supported for the ``input_data`` argument:
  >>> from f3dasm import ExperimentData
  >>> from f3dasm.design import Domain
  >>> import numpy as np
- >>> input_data = np.array([[0.1, 0.2], [0.3, 0.4]])
- >>> domain = Domain({'x0': ContinuousParameter(0., 1.)}, 'x1': ContinuousParameter(0., 1.)}) 
- >>> data = ExperimentData.from_array(input_data, domain)
+ >>> input_array = np.array([[0.1, 0.2], [0.3, 0.4]])
+ >>> domain.add_float('x0', 0., 1.)
+ >>> domain.add_float('x1', 0., 1.)
+ >>> data = ExperimentData(domain=domain, input_data=input_array)
 
 .. note::
 
@@ -116,8 +118,9 @@ Several datatypes are supported for the ``input_data`` argument:
 
  >>> from f3dasm import ExperimentData
  >>> from f3dasm.design import Domain
- >>> domain = Domain({'x0': ContinuousParameter(0., 1.)}, 'x1': ContinuousParameter(0., 1.)}) 
- >>> data = ExperimentData.from_csv("my_experiment_data.csv", domain)
+ >>> domain.add_float('x0', 0., 1.)
+ >>> domain.add_float('x1', 0., 1.) 
+ >>> data = ExperimentData(domain=doman, input_data="my_experiment_data.csv")
 
 .. _output-data-format:
 
@@ -135,24 +138,27 @@ Several datatypes are supported for the ``output_data`` argument:
  >>> from f3dasm import ExperimentData
  >>> from f3dasm.design import Domain
  >>> df = pd.DataFrame(...) # your data in a pandas DataFrame
- >>> domain = Domain({'x0': ContinuousParameter(0., 1.)}, 'x1': ContinuousParameter(0., 1.)}) 
- >>> data = ExperimentData(input_data=df, domain=domain)
+ >>> domain.add_output('x0')
+ >>> domain.add_output('x1')
+ >>> data = ExperimentData(domain=domain, output_data=df)
 
 * A two-dimensional :class:`~numpy.ndarray` object with shape (<number of experiments>, <number of output dimensions>)
 
  >>> from f3dasm import ExperimentData
  >>> from f3dasm.design import Domain
  >>> import numpy as np
- >>> input_array = np.array([[0.1, 0.2], [0.3, 0.4]])
- >>> domain = Domain({'x0': ContinuousParameter(0., 1.)}, 'x1': ContinuousParameter(0., 1.)}) 
- >>> data = ExperimentData(input_data=input_array, domain=domain)
+ >>> output_array = np.array([[0.1, 0.2], [0.3, 0.4]])
+ >>> domain.add_output('x0')
+ >>> domain.add_output('x1') 
+ >>> data = ExperimentData(domain=domain, output_array=output_array)
 
 * A string or path to a ``.csv`` file containing the output data. The ``.csv`` file should contain a header row with the names of the output variables and the first column should be indices for the experiments.
 
  >>> from f3dasm import ExperimentData
  >>> from f3dasm.design import Domain
- >>> domain = Domain({'x0': ContinuousParameter(0., 1.)}, 'x1': ContinuousParameter(0., 1.)}) 
- >>> data = ExperimentData(input_data="my_experiment_data.csv", domain=domain)
+ >>> domain.add_output('x0')
+ >>> domain.add_output('x1') 
+ >>> data = ExperimentData(domain=domain, output_data="my_experiment_data.csv")
 
 If you don't have output data yet, you can also construct an :class:`~f3dasm.ExperimentData` object without providing output data.
 
@@ -163,7 +169,8 @@ project directory
 ^^^^^^^^^^^^^^^^^
 
 The ``project_dir`` argument is used to :ref:`store the ExperimentData to disk <experimentdata-store>`
-You can provide a string or a path to a directory. If the directory does not exist, it will be created.
+You can provide a string or a path to a directory. This can either be a relative or absolute path.
+If the directory does not exist, it will be created.
 
 .. code-block:: python
 
@@ -177,7 +184,6 @@ You can also set the project directoy manually after creation with the :meth:`~f
 .. code-block:: python
 
  >>> from f3dasm import ExperimentData
- >>> from f3dasm.design import Domain
  >>> data = ExperimentData()
  >>> data.set_project_dir("folder/to/my_project_directory")
 
@@ -197,39 +203,32 @@ classmethod with the path of project directory:
 
 .. _experimentdata-sampling:
 
-ExperimentData from a sampling
-------------------------------
+ExperimentData from sampling
+----------------------------
 
 You can directly construct an :class:`~f3dasm.ExperimentData` object from a sampling strategy by using the :meth:`~f3dasm.ExperimentData.from_sampling` method.
 You have to provide the following arguments:
 
-* A sampling function. To learn more about integrating your sampling function, please refer to :ref:`this <integrating-sampling>` section.
+* A sampling function. To learn more about integrating your sampling function, please refer to the :ref:`this <integrating-samplers>` section.
 * A :class:`~f3dasm.design.Domain` object describing the input variables of the sampling function.
 * The number of samples to generate.
 * An optional seed for the random number generator.
 
 .. code-block:: python
 
- from f3dasm import ExperimentData, Domain, ContinuousParameter
+ from f3dasm import ExperimentData, Domain
 
  def your_sampling_function(domain, n_samples, seed):
  # your sampling function
  # ...
  return samples
 
- domain = Domain({'x0': ContinuousParameter(0., 1.)}, 'x1': ContinuousParameter(0., 1.)}
- sampler = RandomUniform(domain, 10)
+ domain = Domain()
+ domain.add_float('x0', 0., 1.)
+ domain.add_float('x1', 0., 1.) 
  data = ExperimentData.from_sampling(sampler=your_sampling_function, domain=domain, n_samples=10, seed=42)
 
-You can use the built-in samplers from the sampling module by providing one of the following strings as the ``sampler`` argument:
-
-======================== ====================================================================== ===========================================================================================================
-Name Method Reference
-======================== ====================================================================== ===========================================================================================================
-``"random"`` Random Uniform sampling `numpy.random.uniform <https://numpy.org/doc/stable/reference/random/generated/numpy.random.uniform.html>`_
-``"latin"`` Latin Hypercube sampling `SALib.latin <https://salib.readthedocs.io/en/latest/api/SALib.sample.html?highlight=latin%20hypercube#SALib.sample.latin.sample>`_
-``"sobol"`` Sobol Sequence sampling `SALib.sobol_sequence <https://salib.readthedocs.io/en/latest/api/SALib.sample.html?highlight=sobol%20sequence#SALib.sample.sobol_sequence.sample>`_
-======================== ====================================================================== ===========================================================================================================
+You can use :ref:`built-in samplers <implemented samplers>` by providing one of the following strings as the ``sampler`` argument:
 
 .. code-block:: python
 
@@ -269,7 +268,7 @@ You can create an experimentdata :class:`~f3dasm.ExperimentData` object in the s
  experimentdata:
  input_data: path/to/input_data.csv
  output_data:
- domain:  ${domain}
+ domain: ${domain}
 
 .. note:: 
 
@@ -285,11 +284,8 @@ Inside your python script, you can then create the :class:`~f3dasm.ExperimentDat
 
  >>> @hydra.main(config_path="conf", config_name="config")
  >>> def my_app(config):
- >>> data = ExperimentData.from_yaml(config)
-
-.. note:: 
+ >>> data = ExperimentData.from_yaml(config.experimentdata)
 
- Make sure to pass the full :code:`config` to the :meth:`~f3dasm.ExperimentData.from_yaml` constructor!
 
 To create the :class:`~f3dasm.ExperimentData` object with the :meth:`~f3dasm.ExperimentData.from_sampling` method, you can use the following configuration:
 
@@ -316,7 +312,7 @@ To create the :class:`~f3dasm.ExperimentData` object with the :meth:`~f3dasm.Exp
 
 .. note:: 
 
- The :class:`~f3dasm.sampling.Sampler` object will be constructed using the :class:`~f3dasm.design.Domain` object from the config file. Make sure you have the :code:`domain` key in your :code:`config.yaml`!
+ Make sure you have the :code:`domain` key in your :code:`config.yaml`!
  To see how to configure the :class:`~f3dasm.design.Domain` object with hydra, see :ref:`this <domain-from-yaml>` section.
 
 
@@ -357,12 +353,13 @@ Storing the ExperimentData object
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The :class:`~f3dasm.ExperimentData` object can be exported to a collection of files using the :meth:`~f3dasm.ExperimentData.store` method.
+You can provide a path to a directory where the files will be stored, or if not provided, the files will be stored in the directory provided in the :attr:`~f3dasm.design.ExperimentData.project_dir` attribute:
 
 .. code-block:: python
 
  >>> data.store("path/to/project_dir")
 
-Inside the project directory, a subfolder `experiment_data` will be created containing the following files:
+Inside the project directory, a subfolder `experiment_data` will be created with the following files:
 
 - :code:`domain.pkl`: The :class:`~f3dasm.design.Domain` object
 - :code:`input.csv`: The :attr:`~f3dasm.design.ExperimentData.input_data` table

docs/source/rst_doc_files/classes/design/experimentsample.rst

@@ -13,20 +13,20 @@ A :class:`~f3dasm.ExperimentSample` object contains a single realization of the
 .. warning:: 
  A :class:`~f3dasm.ExperimentSample` is not constructed manually, but created inside the :class:`~f3dasm.ExperimentData` when it is required by internal processes. 
  The main use of the :class:`~f3dasm.ExperimentSample` is in the context of the :class:`~f3dasm.datageneration.DataGenerator` in order to extract design variables and store output variables. 
- Learn more about the :class:~`f3dasm.datageneration.DataGenerator` in the :ref:`Data Generation <data-generation>` section.
+ Learn more about the :class:`~f3dasm.datageneration.DataGenerator` in the :ref:`Data Generation <data-generation>` section.
 
 
 For each of the experiments in the :class:`~f3dasm.ExperimentData`, an :class:`~f3dasm.ExperimentSample` object can be created.
-This object contains:
+This object contains the following attributes:
 
-* the input parameters of the sample: :attr:`~f3dasm.design.ExperimentSample.input_data`
+* the input parameters of the experiment, :attr:`~f3dasm.design.ExperimentSample.input_data`, as a dictionary
 
 .. code-block:: python
 
  >>> experiment_sample.input_data
  {'param_1': 0.0249, 'param_2': 0.034, 'param_3': 0.1}
 
-* the output parameters of the sample: :attr:`~f3dasm.design.ExperimentSample.output_data`
+* the output parameters of the experiment, :attr:`~f3dasm.design.ExperimentSample.output_data`, as a dictionary
 
 .. code-block:: python
 
@@ -36,18 +36,18 @@ This object contains:
 
 .. note::
 
- If you have `stored your output to disk <store-to-disk>`, the :attr:`~f3dasm.design.ExperimentSample.output_data` will contain a reference to the stored output instead of the actual output.
+ If you have :ref:`stored your output to disk <store-to-disk>`, the :attr:`~f3dasm.design.ExperimentSample.output_data` will contain a reference to the stored output instead of the actual output.
  If you want to load the objects from disk, use the :attr:`~f3dasm.design.ExperimentSample.output_data_loaded` attribute.
 
-* the index number of the experiment: :attr:`~f3dasm.design.ExperimentSample.job_number`
+* the index number of the experiment: :attr:`~f3dasm.design.ExperimentSample.job_number`, as an integer
 
 .. code-block:: python
 
  >>> experiment_sample.job_number
  0
 
-Input parameters of an experiment sample can be accessed using the :attr:`~f3dasm.design.ExperimentSample.get` attribute, with the name of the parameter as the key.
-An KeyError will be raised if the key is not found.
+Input and output parameters of an experiment sample can be accessed using the :attr:`~f3dasm.design.ExperimentSample.get` attribute, with the name of the parameter as the key.
+An error will be raised if the key is not found.
 
 .. code-block:: python
 
@@ -70,7 +70,7 @@ The :class:`~f3dasm.ExperimentData` object can be manually iterated over to get
 Storing output parameters to the experiment sample
 --------------------------------------------------
 
-After running your simulation, you can store the result back into the :class:`~f3dasm.ExperimentSample` with the :meth:`f3dasm.design.ExperimentSample.store` method.
+After running your simulation, you can store the result back into the :class:`~f3dasm.ExperimentSample` with the :meth:`~f3dasm.design.ExperimentSample.store` method.
 There are two ways of storing your output:
 
 * Singular values can be stored directly to the :attr:`~f3dasm.design.ExperimentData.output_data`
@@ -129,7 +129,7 @@ A reference (:code:`Path`) will be saved to the :attr:`~f3dasm.design.Experiment
 In the output data of the :class:`~f3dasm.ExperimentData` object, a reference path (e.g. :code:`/output_numpy/0.npy`) to the stored object will be saved.
 
 
-:mod:`f3dasm` has built-in storing functions for numpy :class:`~numpy.ndarray`, pandas :class:`~pandas.DataFrame` and xarray :class:`~xarray.DataArray` and :class:`~xarray.Dataset`. 
+:mod:`f3dasm` has built-in storing functions for numpy :class:`~numpy.ndarray`, pandas :class:`~pandas.DataFrame` and xarray :class:`~xarray.DataArray` and :class:`~xarray.Dataset` objects. 
 For any other type of object, the object will be stored in the `pickle <https://docs.python.org/3/library/pickle.html>`_ format
 
 

docs/source/rst_doc_files/classes/optimization/f3dasm-optimize.rst

@@ -4,10 +4,8 @@
 =======================
 
 
-The :mod:`f3dasm.datageneration` module is designed to be easily extended by third-party libraries.
-In order to not bloat the main :mod:`f3dasm` package, these extensions are provided as separate package: `f3dasm_optimize <https://github.com/bessagroup/f3dasm_optimize>`_.
-
-More ports to optimization algorithms are available in the `f3dasm_optimize <https://github.com/bessagroup/f3dasm_optimize>`_ package, which can be installed via pip:
+The :mod:`f3dasm.optimization` module is designed to be easily extended by third-party libraries.
+These extensions are provided as separate package: `f3dasm_optimize <https://github.com/bessagroup/f3dasm_optimize>`_, which can be installed via pip:
 
 .. code-block:: bash