Feat/designs

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/user_guide/design_evaluation.rst

@@ -0,0 +1,110 @@
+.. _ref_design_evaluation:
+
+==================
+Design evaluation
+==================
+Instance of the :class:`RootSystem() <ansys.optislang.core.nodes.RootSystem>` allows user to
+create new designs and evaluate them. This feature is currently supported only 
+on the project level and parameters have to be already defined in the project. Instance of the 
+:class:`RootSystem() <ansys.optislang.core.nodes.RootSystem>` is accessible from instance of the 
+:class:`Optislang() <ansys.optislang.core.optislang.Optislang>`.
+
+.. 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
+
+    parametric_project = examples.get_files('calculator_with_params')[1][0]
+    osl = Optislang(project_path=parametric_project)
+    osl.save_as(Path.cwd() / 'parametric_project.opf')
+    root_system = osl.project.root_system
+
+
+Get 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 value of parameter using either ``parameter`` and ``value``
+    reference_design.set_parameter_by_name(parameter = '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)
+
+
+Create new design
+-----------------
+Design can be also created from scratch and there are 2 ways of doing it, either by method 
+:func:`create_design() <ansys.optislang.core.nodes.RootSystem.create_design>` of the
+:class:`RootSystem() <ansys.optislang.core.nodes.RootSystem>` instance or 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(parameter = 'a', value = 3)
+    empty_design.set_parameter_by_name(parameter = 'q', value = 4)
+    # parameters may also be removed
+    empty_design.remove_parameter(name = 'c')
+    # or remove all parameters
+    empty_design.clear_parameters()
+
+
+Check design structure
+----------------------
+In order to check whether design contains all parameters defined in project, methods
+:func:`get_missing_parameters_names() <ansys.optislang.core.nodes.RootSystem.get_missing_parameters_names>` and
+: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 when 
+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 optiSLang retains only last evaluated design at RootSystem level. 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()
+
+
+
+
+
+
+

doc/source/user_guide/functions.rst

@@ -9,8 +9,7 @@ In order to start project, use :func:`start <ansys.optislang.core.optislang.Opti
 .. code:: python
 
     from pathlib import Path
-    from ansys.optislang.core import Optislang
-    from ansys.optislang.core import examples
+    from ansys.optislang.core import Optislang, examples
     osl = Optislang()
     path_to_file = examples.get_files('simple_calculator')[0]
     osl.run_python_file(file_path=path_to_file)
@@ -54,10 +53,7 @@ Or via running specific requests:
 .. code:: python
 
     print(f'Version: {osl.get_osl_version_string()}')
-    print(f'Description: {osl.get_project_description()}')
-    print(f'Location: {osl.get_project_location()}')
-    print(f'Name: {osl.get_project_name()}')
-    print(f'Status: {osl.get_project_status()}')
+    print(f'Working directory: {osl.get_working_dir()}')
 
 When the :class:`Optislang() <ansys.optislang.core.optislang.Optislang>` instance is no longer 
 needed, terminate connection with optiSLang server by running:

doc/source/user_guide/index.rst

@@ -12,6 +12,8 @@ PyOptiSLang library.
 
    launch
    functions
+   project_content
+   design_evaluation
    run_python
    troubleshooting
 
@@ -31,10 +33,11 @@ by the ``project_path`` parameter of the
 
     import os
     from ansys.optislang.core import Optislang
+    from pathlib import Path
 
-    path = os.getcwd()
+    path = Path.cwd()
     file_name = 'test_optislang.opf'
-    with Optislang(project_path = os.path.join(path, file_name)) as osl:
+    with Optislang(project_path = path / file_name) as osl:
         print(osl)