Merge pull request #129 from aimclub/docs/update_171023

Update readthedocs

.readthedocs.yaml

@@ -1,7 +1,7 @@
 version: 2
 
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
     python: "mambaforge-4.10"
 

docs/README.md

@@ -0,0 +1,7 @@
+# Rostok
+
+Rostok is an open source Python framework for generative design of linkage mechanisms for robotic purposes. It provides a framework to describe mechanisms as a graph, set an environment, perform simulation of generated mechanisms, get a reward as a quantitative value of the generated design, and search for the best possible design.
+
+A user can utilize the entire framework as a pipeline to generate a set of suboptimal designs, or utilize the modules and submodules as independent parts. The framework allows to implement custom generative rules, modify search and optimization algorithms.
+
+Currently the framework allows to perform co-design of open chain linkage mechanisms. Co-design consists in simultaneously searching for the mechanical structure and the trajectories of the robot to get the best possible performance.

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

@@ -0,0 +1,31 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :inherited-members:
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

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

@@ -0,0 +1,66 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module Attributes
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree: 
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: custom-class-template.rst
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/source/advanced_usage/algorithm.rst

@@ -9,18 +9,21 @@ Search for grasping mechanism with open kinematic chain
 
 The framework generates planar mechanisms for industrial grippers to grasp objects defined by a user. A graph is generated by a set of rules which can be modified by a user. The graphs constructed by the set of rules form the space of possible solutions and the algorithm searches that space to obtain the best design. Currently, the rules are set to generate the open kinematic chain mechanisms.  
 
-The ability of the generated mechanism/graph to grasp the object is simulated with the physical engine Pychrono. The simulation of the physical properties of the grasping process results in the scalar reward that is calculated using the four criterions:  
-    1. Criterion of isotropy of contact forces
-        Description: list cont contains mean values of contact force for each body element. If sum of cont is equal zero (no body is in contact), then criterion f1 = 0.  
-        Otherwise, delta_u (standard deviation of contact forces) is calculated. We want to minimize deviation.  
-    2. Criterion of number of contact surfaces
-        Description: f2 is equal the ratio of mean value of contact surfaces (during simulation) to the overall potential number of contact surfaces.  
-    3. Criterion of mean values of distance between each of fingers
-        Description: algorithm has to minimize mean values of the distance for each finger.  
-    4. Criterion of simulation time
-        Description: algorithm has to maximize simulation time
-
-In addition to the design of the parts, the second essential part of the mechanism is the optimal trajectories of the actuators. For each design we optimize these  trajectories. The optimization is based on the same reward. Final reward for a design is calculated with the optimized trajectories and is used to search for the most effective design.
+The ability of the generated mechanism/graph to grasp the object is simulated with the physical engine Pychrono. The simulation of the physical properties of the grasping process results in the scalar reward that is calculated using the six criterions:  
+    1. Time period for the grasp
+        Description: We abort the simulation prematurely if the mechanism cannot touch an object or the contact is lost. This criterion is used to separate unsuccessful designs based on the idea that longer contact with the object is better. All the mechanisms that successfully secure an object in place receive a score of 1. 
+    2. The fraction of phalanxes contacting with the object
+        Description: The idea is to reward the design for effective use of the phalanxes and prevent the growth of unnecessary components. Equals 1 if the body is in contact with the object.
+    3. Dispersion of the contact forces
+        Description: The effective gripper should apply similar forces to the object. The grasp that rely on applying much force on specific point could damage an object or a corresponding element of the gripper, while the weak contact cannot withstand the external force
+    4. Distance between object center and the geometric center of the contact points
+        Description: The small distance reduce inertia effects during the gripping process and helps to achieve a stable grip
+    5. Grasp time
+        Description: The time required to fix an object in place. The faster designs get higher rewards
+    6. The ability to withstand external forces
+        Description: In simulation, in a few time steps after the grasp event we apply gradually increasing force to the object for several seconds. If the object lose the contact with the mechanism the hold is considered as failed and the design get the 0 reward. The designs that managed to hold an object get a reward that is calculated based on the object shift from the grasp position
+
+In addition to the design of the parts, the second essential part of the mechanism is the optimal trajectories of the actuators. For each design we optimize these trajectories. The optimization is based on the same reward. Final reward for a design is calculated with the optimized trajectories and is used to search for the most effective design.
 The graph generating rules are fed to the searching algorithm to get the list of available actions at each step of the generation. Currently we use Monte Carlo Tree Search algorithm to explore the space of the possible designs. Therefore, at any step the algorithm gradually grow several designs and calculate their rewards in order to make a step in generation.
 
 The input data should include two different parts:
@@ -34,4 +37,4 @@ The input data should include two different parts:
 
 The output is the designed mechanism, in the graph form, the information about actuator trajectories and the obtained reward
 The output can be used to start and visualize the simulation of the final design
-The history of the exploration of the design space is saved within log file
+The history of the exploration of the design space is saved within log file

docs/source/api.rst

@@ -0,0 +1,9 @@
+===
+API
+===
+
+.. autosummary::
+   :toctree: generated
+   :recursive:
+
+   rostok

docs/source/conf.py

@@ -9,10 +9,12 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 import sys
+import os
 from pathlib import Path
 
-sys.path.insert(0, str(Path(__file__).parent / '../../'))
-sys.path.insert(0, str(Path(__file__).parent / '../../rostok'))
+sys.path.insert(0, os.path.abspath('../'))
+sys.path.insert(0, os.path.abspath('../../'))
+sys.path.insert(0, os.path.abspath('../../rostok'))
 
 #The master toctree document
 master_doc = 'index'
@@ -23,13 +25,24 @@
 project = 'rostok'
 copyright = '2022, BE2R Lab, ITMO'
 author = 'Ivan Borisov, Kirill Zharkov, Yefim Osipov, Dmitriy Ivolga, Kirill Nasonov, Sergey Kolyubin'
-release = '0.0.1'
+release = '1.0.0'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon','sphinx.ext.githubpages']
+extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.napoleon',
+              'sphinx.ext.githubpages',
+              'sphinx.ext.autosummary']
 
+autosummary_generate = True
+
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.txt': 'markdown',
+    '.md': 'markdown',
+}
+autodoc_member_order = 'groupwise'
 
 napoleon_google_docstring = False
 napoleon_use_param = False
@@ -40,6 +53,6 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 html_static_path = ['_static']
 html_logo = '../images/logo_rostok.jpg'

docs/source/index.rst

@@ -25,6 +25,7 @@ Content
    introduction/tutorials
    advanced_usage/algorithm
    modules/index
+   api
    contact_us
 
 Indices and tables

docs/source/introduction/tutorials.rst

@@ -5,8 +5,8 @@ Tutorials
 In order to use the full potential of the `Rostok` library a user needs to get accustomed with features of the framework.  
 We prepared tutorials that show what one can do with the library.
 
-1. `Create node and rule vocabularies <../_static/tutorial_rules_and_nodes_vocabulary.html>`_
-2. `Create graphs using nodes and rules <../_static/tutorial_graph.html>`_
-3. `Set the object to grasp and use the built graphs to start simulation of the grasping mechanism <../_static/tutorial_sym_step.html>`_
-4. `Use optimizer to get optimal joint trajectories and best reward for the mechanism <../_static/tutorial_control_optimization.html>`_
-5. `Use node and rule vocabularies to search the design of grasping robot for a simple body <../_static/tutorial_search.html>`_
+1. `Create node and rule vocabularies <_static/tutorial_rules_and_nodes_vocabulary.html>`_
+2. `Create graphs using nodes and rules <_static/tutorial_graph.html>`_
+3. `Set the object to grasp and use the built graphs to start simulation of the grasping mechanism <_static/tutorial_sym_step.html>`_
+4. `Use optimizer to get optimal joint trajectories and best reward for the mechanism <_static/tutorial_control_optimization.html>`_
+5. `Use node and rule vocabularies to search the design of grasping robot for a simple body <_static/tutorial_search.html>`_

docs/source/modules/block_builder.rst

@@ -2,22 +2,23 @@
 Block builder
 =============
 
-Block render
-============
+Block blueprints
+================
 
-.. automodule:: rostok.block_builder.node_render
+.. automodule:: rostok.block_builder_api.block_blueprints
     :members:
+    :undoc-members:
 
-Control
-=======
+Block parameters
+================
 
-.. automodule:: rostok.block_builder.control
+.. automodule:: rostok.block_builder_api.block_parameters
     :members:
     :undoc-members:
 
 Shapes
 ======
 
-.. automodule:: rostok.block_builder.envbody_shapes
+.. automodule:: rostok.block_builder_api.easy_body_shapes
     :members:
     :undoc-members:

docs/source/modules/criterion.rst

@@ -5,11 +5,11 @@ Criterion
 Criterion calculation
 =====================
 
-.. automodule:: rostok.criterion.criterion_calc
+.. automodule:: rostok.criterion.criterion_calculation
     :members:
 
 Flag stop simulation
 ====================
 
-.. automodule:: rostok.criterion.flags_simualtions
+.. automodule:: rostok.criterion.simulation_flags
     :members:

docs/source/modules/graph_generators.rst

@@ -2,9 +2,25 @@
 Graph generation
 ================
 
-Graph environments
+Design environment
 ==================
 
-.. automodule:: rostok.graph_generators.graph_environment
+.. automodule:: rostok.graph_generators.environments.design_environment
     :members:
-    :undoc-members:
+    :undoc-members:
+
+MCTS
+==================
+
+.. automodule:: rostok.graph_generators.search_algorithms.mcts
+    :members:
+    :undoc-members:
+
+
+MCTS Manager
+============
+
+.. automodule:: rostok.graph_generators.mcts_manager
+    :members:
+    :undoc-members:
+

docs/source/modules/graph_grammar.rst

@@ -8,10 +8,10 @@ Node
 .. automodule:: rostok.graph_grammar.node
     :members:
 
-Nodes division
-==============
+Graph-grammar explorer
+======================
 
-.. automodule:: rostok.graph_grammar.nodes_division
+.. automodule:: rostok.graph_grammar.graphgrammar_explorer
     :members:
 
 Node Vocabulary
@@ -26,11 +26,6 @@ Rule Vocabulary
 .. automodule:: rostok.graph_grammar.rule_vocabulary
     :members:
 
-Graph grammar explorer
-======================
-
-.. automodule:: rostok.graph_grammar.graphgrammar_explorer
-    :members:
 
 Random graph
 ============

docs/source/modules/index.rst

@@ -12,6 +12,7 @@ That is about modules into rostok
    graph_generators
    criterion
    trajectory_optimizer
+   simulation_chrono
    virtual_experiment
    utils
 

docs/source/modules/simulation_chrono.rst

@@ -0,0 +1,21 @@
+===========================
+Simulation in ProjectChrono
+===========================
+
+Simulation scenario
+===================
+
+.. automodule:: rostok.simulation_chrono.simulation_scenario
+    :members:
+
+Simulation
+==========
+
+.. automodule:: rostok.simulation_chrono.simulation
+    :members:
+
+Simulation utils
+================
+
+.. automodule:: rostok.simulation_chrono.simulation_utils
+    :members:

docs/source/modules/utils.rst

@@ -3,7 +3,7 @@ Utils
 =====
 
 Pickle save
-=================
+===========
 
 .. automodule:: rostok.utils.pickle_save
     :members: