Feat/designs (#75)

doc/source/_templates/class.rst

@@ -0,0 +1,34 @@
+{{ name | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block methods %}
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in methods %}
+      {% if item != "__init__" %}
+      {{ name }}.{{ item }}
+      {% endif %}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {% if item.0 != item.upper().0 %}
+      {{ name }}.{{ item }}
+      {% endif %}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

doc/source/api/index.rst

@@ -7,9 +7,12 @@ This section gives an overview of the API of several public PyOptiSLang
 classes, functions, and attributes. Use the search feature or click links to view API documentation.
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    optislang
+   project
+   nodes
+   project_parametric
    logging
    utils
 

doc/source/api/logging.rst

@@ -29,9 +29,12 @@ of the tools provided in this module to extend or modify these loggers.
 
 Logging API
 -----------
+These classes are specific to the :mod:`ansys.optislang.core.logging <ansys.optislang.core.logging>` module:
+
 .. currentmodule:: ansys.optislang.core.logging
 
 .. autosummary::
-   :toctree: _autosummary
-
-   OslLogger
+    :toctree: _autosummary
+    :template: class.rst
+
+    OslLogger

doc/source/api/nodes.rst

@@ -0,0 +1,14 @@
+Nodes
+=====
+These classes are specific to the :mod:`ansys.optislang.core.nodes <ansys.optislang.core.nodes>` module:
+
+.. currentmodule:: ansys.optislang.core.nodes
+
+.. autosummary::
+   :toctree: _autosummary
+   :template: class.rst
+
+   Node
+   System
+   ParametricSystem
+   RootSystem

doc/source/api/optislang.rst

@@ -1,10 +1,11 @@
 Optislang
 =========
-These classes are specific to the ``optislang`` module:
+These classes are specific to the :mod:`ansys.optislang.core.optislang <ansys.optislang.core.optislang>` module:
 
 .. currentmodule:: ansys.optislang.core.optislang
 
 .. autosummary::
    :toctree: _autosummary
+   :template: class.rst
 
    Optislang

doc/source/api/project.rst

@@ -0,0 +1,11 @@
+Project
+=======
+These classes are specific to the :mod:`ansys.optislang.core.project <ansys.optislang.core.project>` module:
+
+.. currentmodule:: ansys.optislang.core.project
+
+.. autosummary::
+   :toctree: _autosummary
+   :template: class.rst
+
+   Project

doc/source/api/project_parametric.rst

@@ -0,0 +1,17 @@
+Project parametric
+==================
+These classes are specific to the :mod:`ansys.optislang.core.project_parametric <ansys.optislang.core.project_parametric>` module:
+
+.. currentmodule:: ansys.optislang.core.project_parametric
+
+.. autosummary::
+   :toctree: _autosummary
+   :template: class.rst
+
+   ParameterManager
+   Design
+   DesignVariable
+   DependentParameter
+   MixedParameter
+   OptimizationParameter
+   StochasticParameter

doc/source/api/utils.rst

@@ -1,6 +1,6 @@
 Helper functions
 ================
-These classes are specific to the ``utils`` module:
+These methods are specific to the :mod:`ansys.optislang.core.utils <ansys.optislang.core.utils>` module:
 
 .. currentmodule:: ansys.optislang.core.utils
 

doc/source/conf.py

@@ -1,37 +1,23 @@
 """Sphinx documentation configuration file."""
 from datetime import datetime
+import os
 
-from ansys_sphinx_theme import pyansys_logo_black
+from ansys_sphinx_theme import ansys_favicon, get_version_match, pyansys_logo_black
 from sphinx_gallery.sorting import FileNameSortKey
 
 import ansys.optislang.core as pyoptislang
 from ansys.optislang.core import __version__
 
 # Project information
-project = "ansys-optislang-core"
+project = "ansys.optislang.core"
 copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
 author = "ANSYS, Inc."
 release = version = __version__
-
-# use the default pyansys logo
-html_logo = pyansys_logo_black
-html_theme = "ansys_sphinx_theme"
-
-html_short_title = html_title = "ansys-optislang-core"
+cname = os.getenv("DOCUMENTATION_CNAME", "nocname.com")
 
 # necessary when building the sphinx gallery
 pyoptislang.BUILDING_GALLERY = True
 
-# specify the location of your github repo
-html_theme_options = {
-    "github_url": "https://github.com/pyansys/pyoptislang",
-    "show_prev_next": False,
-    "show_breadcrumbs": True,
-    "additional_breadcrumbs": [
-        ("PyAnsys", "https://docs.pyansys.com/"),
-    ],
-}
-
 # Sphinx extensions
 extensions = [
     "sphinx.ext.autodoc",
@@ -77,6 +63,9 @@
     # type, unless multiple values are being returned"
 }
 
+# Favicon
+html_favicon = ansys_favicon
+
 # static path
 html_static_path = ["_static"]
 
@@ -89,6 +78,18 @@
 # The master toctree document.
 master_doc = "index"
 
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = "en"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build"]
+
 # -- Sphinx Gallery Options ---------------------------------------------------
 sphinx_gallery_conf = {
     # convert rst to md for ipynb
@@ -112,3 +113,32 @@
     # Execute scripts?
     "plot_gallery": False,
 }
+
+# -- Options for HTML output -------------------------------------------------
+html_short_title = html_title = "PyOptiSLang"
+html_theme = "ansys_sphinx_theme"
+html_logo = pyansys_logo_black
+html_theme_options = {
+    "github_url": "https://github.com/pyansys/pyoptislang",
+    "show_prev_next": False,
+    "show_breadcrumbs": True,
+    "collapse_navigation": True,
+    "use_edit_page_button": True,
+    "additional_breadcrumbs": [
+        ("PyAnsys", "https://docs.pyansys.com/"),
+    ],
+    "switcher": {
+        "json_url": f"{cname}/release/versions.json",
+        "version_match": get_version_match(__version__),
+    },
+    "navbar_end": ["version-switcher", "theme-switcher", "navbar-icon-links"],
+    "navigation_depth": 1,
+}
+
+html_context = {
+    "display_github": True,  # Integrate GitHub
+    "github_user": "pyansys",
+    "github_repo": "pyoptislang",
+    "github_version": "main",
+    "doc_path": "doc/source",
+}

doc/source/getting_started/index.rst

@@ -68,10 +68,10 @@ Verify installation
 
 .. code:: python
 
-    >>> from ansys.optislang.core import Optislang
-    >>> osl = Optislang()
-    >>> print(osl)
-    >>> osl.dispose()
+   from ansys.optislang.core import Optislang
+   osl = Optislang()
+   print(osl)
+   osl.dispose()
 
 If you see a response from the server, congratulations, you're ready
 to get started using OptiSLang as a service. For details regarding the

doc/source/user_guide/design_evaluation.rst

@@ -0,0 +1,141 @@
+.. _ref_design_evaluation:
+
+==================
+Design evaluation
+==================
+Instance of the :class:`RootSystem() <ansys.optislang.core.nodes.RootSystem>` allows user to
+create new designs and evaluate them. Instance of the 
+:class:`RootSystem() <ansys.optislang.core.nodes.RootSystem>` is accessible from instance of the 
+:class:`Optislang() <ansys.optislang.core.optislang.Optislang>` via its 
+:func:`project <ansys.optislang.core.project.Project>` property.
+
+.. code:: python
+    
+    from ansys.optislang.core import Optislang
+    from ansys.optislang.core.project_parametric import Design
+    from ansys.optislang.core import examples
+    from pathlib.Path import Path
+
+    # open project with defined parameters
+    parametric_project = examples.get_files('calculator_with_params')[1][0]
+    osl = Optislang(project_path=parametric_project)
+
+    # do not modify original file
+    osl.save_as(Path.cwd() / 'parametric_project.opf')
+
+    # get root system
+    root_system = osl.project.root_system
+
+.. note::
+
+    Creation and evaluation of designs is currently supported only on the 
+    :class:`RootSystem() <ansys.optislang.core.nodes.RootSystem>`. Therefore, project has to have 
+    parameters already defined at the project root system and workflow has to be 
+    prepared for this (``Receive designs`` and ``Send back designs`` must be set in design flow).
+    Please, see example :ref:`ref_ten_bar_truss_evaluate_design`.
+
+
+Create new design
+-----------------
+New :class:`Design() <ansys.optislang.core.project_parametric.Design>` can be created by obtaining 
+design with reference values from :class:`RootSystem() <ansys.optislang.core.nodes.RootSystem>` 
+and modifying its parameters or design parameters can be specified from scratch.
+
+
+From reference design
+~~~~~~~~~~~~~~~~~~~~~
+Design with all parameters specified in the project with their reference values can be obtained by 
+:func:`get_reference_design() <ansys.optislang.core.nodes.RootSystem.create_design>` method. 
+Parameters values may be modified by methods of the instance of
+:class:`Design() <ansys.optislang.core.project_parametric.Design>` class.
+
+.. code:: python
+    
+    # ...
+    
+    from ansys.optislang.core.project_parametric import DesignVariable
+
+    reference_design = root_system.get_reference_design()
+
+    # modify parameter value using either ``name`` and ``value``
+    reference_design.set_parameter_by_name(name = 'a', value = 12)
+
+    # instance of ``DesignVariable`` or ``Parameter`` may be used as well
+    a = DesignVariable(name='a', value=12)
+    reference_design.set_parameter(parameter=a)
+
+
+From empty design
+~~~~~~~~~~~~~~~~~~~
+Design can be also created from scratch directly creating instance of the 
+:class:`Design() <ansys.optislang.core.project_parametric.Design>` class.
+Parameters don't have to be provided when initializing new design.
+
+.. code:: python
+    
+    # design created using directly Design() class
+    direct_design = Design(parameters = {'a': 3, 'b': 4})
+
+    # create empty design and add parameters afterward
+    empty_design = Design()
+    empty_design.set_parameter_by_name(name = 'a', value = 3)
+    empty_design.set_parameter_by_name(name = 'q', value = 4)
+
+    # parameters may also be removed
+    empty_design.remove_parameter(name = 'c')
+
+    # or remove all parameters
+    empty_design.clear_parameters()
+
+
+Check design parameters
+~~~~~~~~~~~~~~~~~~~~~~~
+In order to check whether design contains all parameters defined in the project, 
+:func:`get_missing_parameters_names() <ansys.optislang.core.nodes.RootSystem.get_missing_parameters_names>` 
+method can be used. To check, whether design contains parameters which are not defined in the project, method
+:func:`get_undefined_parameters_names() <ansys.optislang.core.nodes.RootSystem.get_undefined_parameters_names>` 
+may be used. This step is not necessary though, because this is always done internally while evaluating design.
+
+.. code:: python
+
+    # ...
+
+    missing_parameters = root_system.get_missing_parameters(empty_design)
+    undefined_parameters = root_system.get_undefined_parameters(direct_design)
+
+
+Evaluate design
+---------------
+Designs can be evaluated using method
+:func:`evaluate_design() <ansys.optislang.core.nodes.RootSystem.evaluate_design>`. This method 
+returns the same instance of :class:`Design() <ansys.optislang.core.project_parametric.Design>` 
+class with updated results.
+
+.. code:: python
+
+    # ...
+
+    # single design
+    result_design = root_system.evaluate_design(design = reference_design)
+
+.. note:: 
+
+    Please, note that the optiSLang retains only last evaluated design at the project root system. 
+    Therefore, results of previous designs have to be stored locally if they are required for 
+    further usage, for example as an instance of 
+    :class:`Design() <ansys.optislang.core.project_parametric.Design>` class.
+
+Finally, when everything is done and 
+:class:`Optislang() <ansys.optislang.core.optislang.Optislang>` instance is not needed any more,
+terminate it.
+
+.. code:: python
+
+    osl.dispose()
+
+
+
+
+
+
+