Merge pull request #233 from bessagroup/pr/1.4.5

Pr/1.4.5

.flake8

@@ -27,10 +27,10 @@ extend-exclude =
 count = True
 
 # Set the maximum length that any line may be
-max-line-length = 119
+max-line-length = 79
 
 # Set the maximum length that a comment or docstring line may be
-max-doc-length = 119
+max-doc-length = 79
 
 # Set the number of spaces used for indentation
 indent-size = 4
@@ -55,4 +55,8 @@ extend-ignore = E226, E3
 # E704 : Multiple statements on one line (def)
 # W504 : Line break after binary operator
 # W505 : Doc line too long (82 > 79 characters) 
-extend-select = E241, E242, E704, W504, W505
+extend-select = E241, E242, E704, W504, W505
+
+# Ignore all errors F401 ('imported but unused') and E402 ('module level import
+# not at top of file') in __init__.py files
+per-file-ignores = __init__.py: F401, E402

README.md

@@ -7,9 +7,10 @@ f3dasm
 [![Python](https://img.shields.io/pypi/pyversions/f3dasm)](https://www.python.org)
 [![pypi](https://img.shields.io/pypi/v/f3dasm.svg)](https://pypi.org/project/f3dasm/)
 [![GitHub license](https://img.shields.io/badge/license-BSD-blue)](https://github.com/bessagroup/f3dasm)
+[![Documentation Status](https://readthedocs.org/projects/f3dasm/badge/?version=latest)](https://f3dasm.readthedocs.io/en/latest/?badge=latest)
 
-[**Docs**](https://bessagroup.github.io/f3dasm/)
-| [**Installation**](https://bessagroup.github.io/f3dasm/general/gettingstarted.html)
+[**Docs**](https://f3dasm.readthedocs.io/)
+| [**Installation**](https://f3dasm.readthedocs.io/en/latest/rst_doc_files/general/gettingstarted.html)
 | [**GitHub**](https://github.com/bessagroup/f3dasm)
 | [**PyPI**](https://pypi.org/project/f3dasm/)
 | [**Practical sessions**](https://github.com/mpvanderschelling/f3dasm_teach)
@@ -27,7 +28,7 @@ The Bessa research group at TU Delft is small... At the moment, we have limited
 
 ## Getting started
 
-The best way to get started is to follow the [installation instructions](https://bessagroup.github.io/f3dasm/general/gettingstarted.html).
+The best way to get started is to follow the [installation instructions](https://f3dasm.readthedocs.io/en/latest/rst_doc_files/general/gettingstarted.html).
 
 ## Referencing
 

VERSION

@@ -1 +1 @@
-1.4.4
+1.4.5

docs/source/_templates/custom-class-template.rst

@@ -33,4 +33,4 @@
  {% endif %}
  {% endblock %}
 
- .. rubric:: {{ _('Methods') }}
+ .. rubric:: {{ _('Public and private methods') }}

docs/source/conf.py

@@ -14,7 +14,8 @@
 
 sys.path.insert(0, os.path.abspath('../..'))
 sys.path.insert(0, os.path.abspath('../../src'))
-src_dir = [f.path for f in os.scandir(os.path.abspath('../../src/')) if f.is_dir()]
+src_dir = [f.path for f in os.scandir(
+ os.path.abspath('../../src/')) if f.is_dir()]
 for path in src_dir:
  sys.path.insert(0, path)
 
@@ -24,8 +25,8 @@
 project = 'f3dasm'
 author = 'Martin van der Schelling'
 copyright = '2022, Martin van der Schelling'
-version = '1.4.4'
-release = '1.4.4'
+version = '1.4.5'
+release = '1.4.5'
 
 
 # -- General configuration ----------------------------------------------------
@@ -82,7 +83,7 @@
 # napoleon: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
 napoleon_numpy_docstring = True
 napoleon_include_init_with_doc = True
-napoleon_include_private_with_doc = False
+napoleon_include_private_with_doc = True
 
 # autosummary: https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html#module-sphinx.ext.autosummary
 autosummary_generate = True

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

@@ -1,7 +1,34 @@
 Domain and parameters
 =====================
 
-This section will give you information on how to set up your search space with the :ref:`domain <domain>` class and the :ref:`parameter classes <parameters>`
+This section will give you information on how to set up your search space with the :ref:`domain <domain>` class and the :ref:`parameters <parameters>`
+
+
+Domain
+------
+
+.. _domain:
+
+The :class:`~f3dasm.design.Domain` is a set of :class:`f3dasm.design.Parameter` instances that make up the feasible search space.
+
+.. image:: ../../../img/f3dasm-domain.png
+ :width: 100%
+ :align: center
+ :alt: Domain
+
+|
+
+
+To start, we instantiate an empty domain object:
+
+.. code-block:: python
+
+ from f3dasm import Domain
+
+ domain = Domain()
+
+
+Now we can gradually add some parameters!
 
 .. _parameters:
 
@@ -17,107 +44,85 @@ Parameters are singular features of the input search space. They are used to def
 
 |
 
-There are four types of parameters that can be created: :class:`~f3dasm.design.ContinuousParameter`, :class:`~f3dasm.design.DiscreteParameter`, :class:`~f3dasm.design.CategoricalParameter` and :class:`~f3dasm.design.ConstantParameter`:
-
-Continuous Parameter
-^^^^^^^^^^^^^^^^^^^^
-
-* We can create **continous** parameters with a :attr:`~f3dasm.design.ContinuousParameter.lower_bound` and :attr:`~f3dasm.design.ContinuousParameter.upper_bound` with the :class:`~f3dasm.design.ContinuousParameter` class
+There are four types of parameters that can be created: :ref:`float <continuous-parameter>`, :ref:`int <discrete-parameter>`, :ref:`categorical <categorical-parameter>` and :ref:`constant <constant-parameter>` parameters.
 
-.. code-block:: python
-
- x1 = f3dasm.ContinuousParameter(lower_bound=0.0, upper_bound=100.0)
- x2 = f3dasm.ContinuousParameter(lower_bound=0.0, upper_bound=4.0)
+.. _continuous-parameter:
 
-Discrete Parameter
-^^^^^^^^^^^^^^^^^^
+Floating point parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
-* We can create **discrete** parameters with a :attr:`~f3dasm.design.DiscreteParameter.lower_bound` and :attr:`~f3dasm.design.DiscreteParameter.upper_bound` with the :class:`~f3dasm.design.DiscreteParameter` class
+* We can create **continous** parameters with a :code:`low` and :code:`high` boundary with the :meth:`~f3dasm.design.Domain.add_float` method:
 
 .. code-block:: python
 
- x3 = f3dasm.DiscreteParameter(lower_bound=2, upper_bound=4)
- x4 = f3dasm.DiscreteParameter(lower_bound=74, upper_bound=99)
+ domain.add_float(name='x1', low=0.0, high=100.0)
+ domain.add_float(name='x2', low=0.0, high=4.0) 
 
-Categorical Parameter
-^^^^^^^^^^^^^^^^^^^^^
+.. _discrete-parameter:
 
-* We can create **categorical** parameters with a list of items (:attr:`~f3dasm.design.CategoricalParameter.categories`) with the :class:`~f3dasm.design.CategoricalParameter` class
+Discrete parameters
+^^^^^^^^^^^^^^^^^^^
 
-.. code-block:: python
-
- x5 = f3dasm.CategoricalParameter(categories=['test1','test2','test3','test4'])
- x6 = f3dasm.CategoricalParameter(categories=[0.9, 0.2, 0.1, -2])
-
-Constant Parameter
-^^^^^^^^^^^^^^^^^^
-
-* We can create **constant** parameters with any value (:attr:`~f3dasm.design.ConstantParameter.value`) with the :class:`~f3dasm.design.ConstantParameter` class
+* We can create **discrete** parameters with a :code:`low` and :code:`high` boundary with the :meth:`~f3dasm.design.Domain.add_int` method:
 
 .. code-block:: python
 
- x7 = f3dasm.ConstantParameter(value=0.9)
+ domain.add_int(name='x3', low=2, high=4)
+ domain.add_int(name='x4', low=74, high=99) 
 
+.. _categorical-parameter:
 
-Domain
-------
+Categorical parameters
+^^^^^^^^^^^^^^^^^^^^^^
 
-.. _domain:
+* We can create **categorical** parameters with a list of items (:code:`categories`) with the :meth:`~f3dasm.design.Domain.add_category` method:
 
-The :class:`~f3dasm.design.Domain` is a set of :class:`f3dasm.design.Parameter` instances that make up the feasible search space.
+.. code-block:: python
 
-.. image:: ../../../img/f3dasm-domain.png
- :width: 100%
- :align: center
- :alt: Domain
+ domain.add_category(name='x5', categories=['test1','test2','test3','test4'])
+ domain.add_category(name='x6', categories=[0.9, 0.2, 0.1, -2])
 
-|
+.. _constant-parameter:
 
-Domain from a dictionary
-^^^^^^^^^^^^^^^^^^^^^^^^
+Constant parameters
+^^^^^^^^^^^^^^^^^^^
 
-The domain can be constructed by initializing the :class:`~f3dasm.design.Domain` class and 
-providing an attribute (:attr:`~f3dasm.design.Domain.input_space`) containing string names as keys and parameters as values.
+* We can create **constant** parameters with any value (:code:`value`) with the :meth:`~f3dasm.design.Domain.add_constant` method:
 
 .. code-block:: python
 
- from f3dasm import Domain, ContinuousParameter, DiscreteParameter, CategoricalParameter, ConstantParameter
-
- param_1 = f3dasm.ContinuousParameter(lower_bound=-1.0, upper_bound=1.0)
- param_2 = f3dasm.DiscreteParameter(lower_bound=1, upper_bound=10)
- param_3 = f3dasm.CategoricalParameter(categories=['red', 'blue', 'green', 'yellow', 'purple'])
- param_4 = f3dasm.ConstantParameter(value='some_value')
-
- domain = f3dasm.Domain(input_space={'param_1': param_1, 'param_2': param_2, 'param_3': param_3, 'param_4': param_4})
+ domain.add_constant(name='x7', value=0.9)
 
 .. _domain-from-yaml:
 
 Domain from a `hydra <https://hydra.cc/>`_ configuration file
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-------------------------------------------------------------
 
-If you are using `hydra <https://hydra.cc/>`_ to manage your configuration files, you can create a domain from a configuration file. Your config needs to have the following key:
+If you are using `hydra <https://hydra.cc/>`_ to manage your configuration files, you can create a domain from a configuration file. 
+Your config needs to have a key (e.g. :code:`domain`) that has a dictionary with the parameter names (e.g. :code:`param_1`) as keys 
+and a dictionary with the parameter type (:code:`type`) and the corresponding arguments as values:
 
 .. code-block:: yaml
  :caption: config.yaml
 
  domain:
  param_1:
- _target_: f3dasm.ContinuousParameter
+ type: float
  lower_bound: -1.0
  upper_bound: 1.0
  param_2:
- _target_: f3dasm.DiscreteParameter
+ type: int
  lower_bound: 1
  upper_bound: 10
  param_3:
- _target_: f3dasm.CategoricalParameter
+ type: category
  categories: ['red', 'blue', 'green', 'yellow', 'purple']
  param_4:
- _target_: f3dasm.ConstantParameter
+ type: constant
  value: some_value
 
  
-The same domain can now be created by calling the :func:`~f3dasm.design.Domain.from_yaml` method:
+The domain can now be created by calling the :func:`~f3dasm.design.Domain.from_yaml` method:
 
 .. code-block:: python