Documentation for understanding logic.

.gitignore

@@ -1,2 +1,3 @@
 .vscode/
 _build/
+venv/

conf.py

@@ -30,7 +30,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['breathe', 'sphinx.ext.graphviz', 'sphinxcontrib.plantuml', 'sphinx.ext.extlinks']
+extensions = ['breathe', 'sphinx.ext.graphviz', 'sphinxcontrib.plantuml', 'sphinx.ext.extlinks', 'sphinx.ext.autosummary', 'sphinx.ext.autodoc']
 
 graphviz_output_format='png'
 graphviz_dot_args=[
@@ -75,12 +75,12 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build','_themes','scripts' ]
+exclude_patterns = ['_build','_themes','scripts', 'venv' ]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'

index.rst

@@ -21,6 +21,7 @@ CoreSense Project (CoreSense in short) is a project... TBD
    opensourecommunity/index.rst
    build_instructions/index.rst
    design/index.rst
+   understanding-logic/index.rst
    tutorials/index.rst
    testbeds/index.rst
    demos/index.rst

understanding-logic/concepts/agent.rst

@@ -0,0 +1,13 @@
+Types
+=====
+
+.. _agent:
+
+**agent** ``$tType``
+--------------------
+
+A **CoreSense** agent which may posess `engines <engine.html>`_ and `modelets <modelet.html>`_.
+
+.. warning:: “Unimplemented” To be introduced later, as collective awareness is considered.
+
+Source: ``fundamental-concepts.tff``

understanding-logic/concepts/concept.rst

@@ -0,0 +1,19 @@
+Types
+=====
+
+.. _concept:
+
+**concept** ``$tType``
+----------------------
+
+An instance of a class of `phenomenon <phenomenon.html>`_ in the agent’s world model.
+
+A `concept <#concept>`_ is a `property <property.html>`_ of a `modelet <modelet.html>`_.
+
+.. example::
+   - chair 
+   - dog
+   - the color pink
+   - sunrise
+
+Source: ``fundamental-concepts.tff``

understanding-logic/concepts/datatype.rst

@@ -0,0 +1,216 @@
+Types
+=====
+
+.. _datatype:
+
+**datatype** ``$tType``
+-----------------------
+
+A precise information encoding that is taken as granted. As the name suggests, the fundamental types of data considered.
+
+.. example:: 
+   - real number
+   - uint8
+   - pixel
+
+Source: ``fundamental-concepts.tff``
+
+ROS 2 Interface builtins
+========================
+
+ROS 2 interfaces (messages, services, and actions) are `formalisms <formalism.html>`_ constructed from semantically named builtin `datatypes <#datatype>`_ and arrays of these builtins. See the ROS 2 `documentation <https://docs.ros.org/en/rolling/Concepts/Basic/About-Interfaces.html>`_
+for more details.
+
+.. important:: 
+   These individuals are not associated with a particular semantic label. The intention (WIP) is to match a particular `datatype <#datatype>`_ (the ``fieldtype``) and a `concept <concept.html>`_ (the ``fieldname``) in some `formalism <formalism.html>`_ representing the ROS 2 interface.
+
+.. _ros2-msg-bool:
+
+**‘ROS2.msg.Bool’** `datatype <#datatype>`_
+------------------------------------------------
+
+The builtin ``bool`` field type of a ROS 2 interface.
+
+Source: ``datatypes.tff``
+
+.. _ros2-msg-byte:
+
+**‘ROS2.msg.Byte’** `datatype <#datatype>`_
+------------------------------------------------
+
+The builtin ``byte`` field type of a ROS 2 interface.
+
+Source: ``datatypes.tff``
+
+.. _ros2-msg-char:
+
+**‘ROS2.msg.Char’** `datatype <#datatype>`_
+------------------------------------------------
+
+The builtin ``char`` field type of a ROS 2 interface.
+
+Source: ``datatypes.tff``
+
+.. _ros2-msg-float32:
+
+**‘ROS2.msg.Float32’** `datatype <#datatype>`_
+---------------------------------------------------
+
+The builtin ``float32`` field type of a ROS 2 interface.
+
+Source: ``datatypes.tff``
+
+.. _ros2-msg-float64:
+
+**‘ROS2.msg.Float64’** `datatype <#datatype>`_
+---------------------------------------------------
+
+The builtin ``float64`` field type of a ROS 2 interface.
+
+Source: ``datatypes.tff``
+
+.. _ros2-msg-int8:
+
+**‘ROS2.msg.Int8’** `datatype <#datatype>`_
+------------------------------------------------
+
+The builtin ``int8`` field type of a ROS 2 interface.
+
+Source: ``datatypes.tff``
+
+.. _ros2-msg-uint8:
+
+**‘ROS2.msg.Uint8’** `datatype <#datatype>`_
+-------------------------------------------------
+
+The builtin ``uint8`` field type of a ROS 2 interface.
+
+Source: ``datatypes.tff``
+
+.. _ros2-msg-int16:
+
+**‘ROS2.msg.Int16’** `datatype <#datatype>`_
+-------------------------------------------------
+
+The builtin ``int16`` field type of a ROS 2 interface.
+
+Source: ``datatypes.tff``
+
+.. _ros2-msg-uint16:
+
+**‘ROS2.msg.Uint16’** `datatype <#datatype>`_
+--------------------------------------------------
+
+The builtin ``uin16`` field type of a ROS 2 interface.
+
+Source: ``datatypes.tff``
+
+.. _ros2-msg-int32:
+
+**‘ROS2.msg.Int32’** `datatype <#datatype>`_
+-------------------------------------------------
+
+The builtin ``int32`` field type of a ROS 2 interface.
+
+Source: ``datatypes.tff``
+
+.. _ros2-msg-uint32:
+
+**‘ROS2.msg.Uint32’** `datatype <#datatype>`_
+--------------------------------------------------
+
+The builtin ``uint32`` field type of a ROS 2 interface.
+
+Source: ``datatypes.tff``
+
+.. _ros2-msg-int64:
+
+**‘ROS2.msg.Int64’** `datatype <#datatype>`_
+-------------------------------------------------
+
+The builtin ``int64`` field type of a ROS 2 interface.
+
+Source: ``datatypes.tff``
+
+.. _ros2-msg-uint64:
+
+**‘ROS2.msg.Uint64’** `datatype <#datatype>`_
+--------------------------------------------------
+
+The builtin ``uint64`` field type of a ROS 2 interface.
+
+Source: ``datatypes.tff``
+
+.. _ros2-msg-string:
+
+**‘ROS2.msg.String’** `datatype <#datatype>`_
+--------------------------------------------------
+
+The builtin (unbounded) ``string`` field type of a ROS 2 interface. These strings use 8-bit characters.
+
+Source: ``datatypes.tff``
+
+.. _ros2-msg-wstring:
+
+**‘ROS2.msg.Wstring’** `datatype <#datatype>`_
+---------------------------------------------------
+
+The builtin ``wstring`` field type of a ROS 2 interface. These strings use 16-bit characters.
+
+Source: ``datatypes.tff``
+
+ROS 2 Interface arrays
+======================
+
+ROS 2 interfaces support arrays of builtins, optionally with a fixed or bounded size.
+
+.. warning::
+   Sizes of array datatypes are assumed to be natural numbers. This is **NOT** enforced by the type checker or logic.
+
+.. _ros2-msg-bounded-string:
+
+**‘ROS2.msg.BoundedString’** ( **$int** > `datatype <#datatype>`_ )
+-------------------------------------------------------------------
+
+A bounded ``string<=n`` field type of a ROS 2 interface. ``n`` is a natural number.
+
+Source: ``datatypes.tff``
+
+.. _ros2-msg-unbounded-dynamic-array:
+
+**‘ROS2.msg.UnboundedDynamicArray’** ( `datatype <#datatype>`_ > `datatype <#datatype>`_ )
+------------------------------------------------------------------------------------------
+
+An array of any builtin with an unbouned size field type in a ROS 2 interface. 
+
+.. example:: 
+   - ``char[]``
+   - ``float32[]``
+
+Source: ``datatypes.tff``
+
+.. _ros2-msg-bounded-dynamic-array:
+
+**‘ROS2.msg.BoundedDynamicArray’** (( `datatype <#datatype>`_ * **$int** ) > `datatype <#datatype>`_ )
+------------------------------------------------------------------------------------------------------
+
+A dynamic array of any builtin with a bounded size field type in a ROS 2 interface. The size must be a natural number.
+
+.. example::
+   -``char[<=5]``
+   - ``float32[<=4]``
+
+Source: ``datatypes.tff``
+
+.. _ros2-msg-static-array:
+
+**‘ROS2.msg.StaticArray’** (( `datatype <#datatype>`_ * **$int** ) > `datatype <#datatype>`_ )
+----------------------------------------------------------------------------------------------
+
+A static array of any builtin with a fixed size field type in a ROS 2 interface. The size must be a natural number.
+
+.. example::
+   - ``char[5]``
+   - ``float32[4]``
+
+Source: ``datatypes.tff``

understanding-logic/concepts/engine.rst

@@ -0,0 +1,94 @@
+Types
+=====
+
+
+
+**engine** ``$tType``
+---------------------
+
+Does work within a **CoreSense** `agent <agent.html>`_ to produce `modelets <modelet.html>`_.
+
+-  Takes multiple `modelets <modelet.html>`_ as an input `modelet_set <modelet.rst#modelet_set>`_
+-  Uses semantic information to identify valid input modelet `formalisms <formalism.html>`_
+
+   -  semantics could be external (part of the type definition) or internal (modeled within the `modelet <modelet.html>`_ itself)
+-  Produces one output `modelet <modelet.html>`_
+
+   -  May or may not impart semantic meaning to the output `modelet <modelet.html>`_
+   -  May (re)define the output modelet `origin <origin.html>`_, `concept <concept.html>`_, or characteristics
+-  Has `exertion <exertion.html>`_ characteristics
+
+   -  e.g. time delay, resource usage, power consumption
+
+.. admonition:: Example
+
+   - DroneStateEngine (see tff/tests/test-wind-estimation.tff)
+
+      - Input Model: 
+
+         - Modelet
+
+            - formalism: IMU.msg 
+            - modelled concept: inertia 
+
+         - Modelet:
+
+            - formalism: NavSatFix.msg
+            - modelled concept: geolocation
+
+      - Output Modelet:
+
+         - modelet:
+
+            - formalism: DroneState.msg
+            - modelled concept: drone_state
+
+Source: ``engines-and-modelets.tff``
+
+Relations
+=========
+
+.. _interface_of:
+
+**interface_of** ( `engine <#engine>`_ > `template_set <template.rst#template_set>`_ )
+--------------------------------------------------------------------------------------
+
+An `engine <#engine>`_ requires a set of input `modelets <modelet.html>`_ which matches the `template_set <template.rst#template_set>`_.
+
+Source: ``engines-and-modelets.tff``
+
+.. _output_modelet_formalism:
+
+**output_modelet_formalism** ( `engine <#engine>`_ > `formalism <formalism.html>`_ )
+------------------------------------------------------------------------------------
+
+The `formalism <formalism.html>`_ of an `engine <#engine>`_ output `modelet <modelet.html>`_.
+
+Source: ``engines-and-modelets.tff``
+
+.. _is_output_modelet_concept:
+
+**is_output_modelet_concept** ( `engine <#engine>`_ > `phenomenon <phenomenon.html>`_ )
+---------------------------------------------------------------------------------------
+
+The `concept <concept.html>`_ of an `engine <#engine>`_ output `modelet <modelet.html>`_.
+
+Source: ``engines-and-modelets.tff``
+
+.. _output_property_of_e:
+
+**output_property_of_engine** ( `engine <#engine>`_ > `property <property.html>`_ )
+-----------------------------------------------------------------------------------
+
+The `property <property.html>`_ an `engine <#engine>`_ imparts on its output `modelet <modelet.html>`_.
+
+Source: ``properties.tff``
+
+.. _engine_imparts_representation_class:
+
+**engine_imparts_representation_class** ( `engine <#engine>`_ > `representation_class <representation_class.html>`_ )
+---------------------------------------------------------------------------------------------------------------------
+
+The `representation_class <representation_class.html>`_ an `engine <#engine>`_ imparts on its output `modelet <modelet.html>`_.
+
+Source: ``engines-and-modelets.tff``