updates to documentation

alex-quin-gabriel · alex-quin-gabriel · commit 2751b00d5cfe · 2025-05-01T17:31:13.000+02:00
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@ variable with the absolute path:
 ```bash
 mkdir src && cd src
 export TPTP=$(pwd)
-git clone git@github.com:alex-quin-gabriel/understanding-logic.git
+git clone git@github.com:CoreSenseEU/understanding-logic.git
 ```
 This results in `include()` paths being read relative to the `src` directory.
 Other TPTP files can be placed in the same `src` directory matching this tree
diff --git a/docs/concepts/concept.md b/docs/concepts/concept.md
@@ -0,0 +1,12 @@
+## Types
+### **concept** `$tType` { #concept data-toc-label='concept' }
+The class of a [phenomenon](phenomenon.md) in the agent's world model. 
+
+A [concept](#concept) is a [property](property.md) of a [modelet](modelet.md).
+
+!!! example
+    - chair
+    - dog
+    - the color pink
+    - sunrise
+###### Source: `fundamental-concepts.tff`
diff --git a/docs/concepts/datatype.md b/docs/concepts/datatype.md
@@ -19,7 +19,7 @@ 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 [topic](topic.md) (the `fieldname`) in some
+    `fieldtype`) and a [concept](concept.md) (the `fieldname`) in some
     [formalism](formalism.md) representing the ROS 2 interface.
 
 ### **'ROS2.msg.Bool'** [**`datatype`**](#datatype) { #ros2-msg-bool data-toc-label="'ROS2.msg.Bool'" }
diff --git a/docs/concepts/engine.md b/docs/concepts/engine.md
@@ -1,22 +1,31 @@
 ## Types
 ### **engine** `$tType` { #engine data-toc-label='engine' }
-Does work within a **CoreSense** [agent](agent.md) to consume and/or produce [modelets](modelet.md).
+Does work within a **CoreSense** [agent](agent.md) to produce [modelets](modelet.md).
 
 - Takes multiple [modelets](modelet.md) as an input [modelet_set](modelet.md#modelet_set)
 - Uses semantic information to identify valid input modelet [formalisms](formalism.md)
     - semantics could be external (part of the type definition) or internal
       (modeled within the [modelet](modelet.md) itself)
 - Produces one output [modelet](modelet.md)
 	- May or may not impart semantic meaning to the output [modelet](modelet.md)
-    - May (re)define the output modelet [origin](origin.md), [topic](topic.md),
+    - May (re)define the output modelet [origin](origin.md), [concept](concept.md),
       or characteristics
 - Has [exertion](exertion.md) characteristics
 	- e.g. time delay, resource usage, power consumption
 
 !!! example
-    - PersonLocatorNode
-    - Planner
-    - Min function
+    - 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
@@ -29,17 +38,15 @@ matches the [template_set](template.md#template_set).
 The [formalism](formalism.md) of an [engine](#engine) output [modelet](modelet.md).
 ###### Source: `engines-and-modelets.tff`
 
-### **output_modelet_topic** `(`[**`engine`**](#engine)` > `[**`phenomenon`**](phenomenon.md)`)` { #output_modelet_topic data-toc-label='output_modelet_topic' }
-The [topic](topic.md) of an [engine](#engine) output [modelet](modelet.md).
-!!! question "TODO"
-    `topic` will soon be renamed. Right now this outputs a `phenomenon_class`.
+### **is_output_modelet_concept** `(`[**`engine`**](#engine)` > `[**`phenomenon`**](phenomenon.md)`)` { #is_output_modelet_concept data-toc-label='is_output_modelet_concept' }
+The [concept](concept.md) of an [engine](#engine) output [modelet](modelet.md).
 ###### Source: `engines-and-modelets.tff`
 
 ### **output_property_of_engine** `(`[**`engine`**](#engine)` > `[**`property`**](property.md)`)` { #output_property_of_e data-toc-label='output_property_of_e' }
 The [property](property.md) an [engine](#engine) imparts on its output [modelet](modelet.md).
 ###### Source: `properties.tff`
 
 
-### **engine_imparts_role** `(`[**`engine`**](#engine)` > `[**`role`**](role.md)`)` { #engine_imparts_role data-toc-label='engine_imparts_role' }
-The [role](role.md) an [engine](#engine) imparts on its output [modelet](modelet.md).
+### **engine_imparts_representation_class** `(`[**`engine`**](#engine)` > `[**`representation_class`**](representation_class.md)`)` { #engine_imparts_representation_class data-toc-label='engine_imparts_representation_class' }
+The [representation_class](representation_class.md) an [engine](#engine) imparts on its output [modelet](modelet.md).
 ###### Source: `engines-and-modelets.tff`
diff --git a/docs/concepts/exertion.md b/docs/concepts/exertion.md
@@ -8,7 +8,7 @@ Check if a [modelet](modelet.md) matches a [template](template.md).
 ###### Source: `engines-and-modelets.tff`, `properties.tff`
 
 ### **formally_equivalent** `((`[**`template`**](template.md)` * `[**`modelet`**](modelet.md)`) > `**`$o`**`)` { #formally_equivalent data-toc-label='formally_equivalent' }
-A [template](template.md) and a [modelet](modelet.md) share the same *referent* and [formalism](formalism.md).
+A [template](template.md) and a [modelet](modelet.md) share the same *phenomenon* and [formalism](formalism.md).
 ###### Source: `properties.tff`
 
 ### **interfaces_match** `((`[**`modelet_set`**](modelet.md#modelet_set)` * `[**`template_set`**](template.md#template_set)`) > `**`$o`**`)` { #interfaces_match data-toc-label='interfaces_match' }
@@ -19,7 +19,7 @@ Check if all of the [templates](template.md) in the [template_set](template.md#t
 ###### Source: `engines-and-modelets.tff`, `properties.tff`
 
 ### **exert** `((`[**`engine`**](engine.md)` * `[**`modelet_set`**](modelet.md#modelet_set)` * `[**`modelet`**](modelet.md)`) > `**`$o`**`)` { #exert data-toc-label='exert' }
-Exert an [engine](engine.md) on a [modelet_set](modelet.md#modelet_set) to produce and output [modelet](modelet.md).
+Exert an [engine](engine.md) on a [modelet_set](modelet.md#modelet_set) to produce an output [modelet](modelet.md).
 ###### Source: `engines-and-modelets.tff`
 
 ### **exertable** `((`[**`modelet_set`**](modelet.md#modelet_set)` * `[**`engine`**](engine.md)`) > `**`$o`**`)` { #exertable data-toc-label='exertable' }
diff --git a/docs/concepts/formalism.md b/docs/concepts/formalism.md
@@ -3,8 +3,8 @@
 The language and structure in which a [phenomenon](phenomenon.md) could be described.
 Methods used to express [modelets](modelet.md); class in the *Data Model*.
 
-- The information structure used to capture the [topic](topic.md) and [origin](origin.md)
-- Highlights some aspects of the *referent* while hiding others
+- The information structure used to capture the [concept](concept.md) and [origin](origin.md)
+- Highlights some aspects of the *phenomenon* while hiding others
 - Defines [engine](engine.md) I/O compatibility and usability with other models
 
 New [formalism](#formalism) could be defined or old ones modified.
diff --git a/docs/concepts/index.md b/docs/concepts/index.md
@@ -10,7 +10,7 @@ The main idea is to:
     Find *strategies* of **Engine** *exertions* to **create** required **Modelets**.
 
 !!! question "TODO"
-    Add a map of the conepts or something more elegant here...
+    Add a map of the concepts or something more elegant here...
     We should also include the triangle of meaning.
 
 ## Types
@@ -50,8 +50,8 @@ The main idea is to:
 ### [**requirement**](requirement.md)
 --8<-- "docs/concepts/requirement.md:3:3"
 
-### [**role**](role.md)
---8<-- "docs/concepts/role.md:3:3"
+### [**representation_class**](representation_class.md)
+--8<-- "docs/concepts/representation_class.md:3:3"
 
 ### [**spacetime_point**](spacetime_point.md)
 --8<-- "docs/concepts/spacetime_point.md:3:3"
@@ -65,6 +65,6 @@ The main idea is to:
 ### [**template_set**](template.md#template_set)
 --8<-- "docs/concepts/template.md:11:11"
 
-### [**topic**](topic.md)
---8<-- "docs/concepts/topic.md:3:3"
+### [**concept**](concept.md)
+--8<-- "docs/concepts/concept.md:3:3"
 
diff --git a/docs/concepts/modelet.md b/docs/concepts/modelet.md
@@ -1,12 +1,12 @@
 ## Types
 ### **modelet** `$tType` { #modelet data-toc-label='modelet' }
 Models a [phenomenon](phenomenon.md) as the *thought* in the triangle of meaning.
-All modelets describe a [topic](topic.md), have an [origin](origin.md), and are
+All modelets describe an instance of a [concept](concept.md), have an [origin](origin.md), and are
 modeled in a specific [formalism](formalism.md).
 
-- [**Topic**](topic.md): the *referent* of the [modelet](#modelet)
-- [**Origin**](origin.md): the agent's perspective on the *referent*
-- [**Formalism**](formalism.md): the representation of the *referent*
+- [**Concept**](concept.md): the *phenomenon* of the [modelet](#modelet), an instance of a class in the world model.
+- [**Origin**](origin.md): the agent's perspective on the *phenomenon*
+- [**Formalism**](formalism.md): the representation of the *phenomenon*
 ###### Source: `engines-and-modelets.tff`
 
 ### **modelet_set** `$tType` { #modelet_set data-toc-label='modelet_set' }
@@ -20,16 +20,16 @@ Used to collect the inputs to an [engine](engine.md).
 
 
 ## Relations
-### **topic_of_modelet** `(`[**`modelet`**](#modelet)` > `[**`phenomenon`**](phenomenon.md)`)` { #topic_of_modelet data-toc-label='topic_of_modelet' }
-The [phenomenon](phenomenon.md) symbolizing the *referent* of a [modelet](modelet.md).
+### **modelet_models_concept** `(`[**`modelet`**](#modelet)` > `[**`phenomenon`**](phenomenon.md)`)` { #modelet_models_concept data-toc-label='modelet_models_concept' }
+The [phenomenon](phenomenon.md) symbolizing the *phenomenon* of a [modelet](modelet.md).
 !!! question "TODO"
-    rename from 'topic' to something else.
+    rename from 'concept' to something else.
 !!! question "TODO"
     Should we call this the intrinsic purpose? (as opposed to the [`role`](role.md)).
 ###### Source: `engines-and-modelets.tff`
 
 ### **formalism_of_modelet** `(`[**`modelet`**](#modelet)` > `[**`formalism`**](formalism.md)`)` { #formalism_of_modelet data-toc-label='formalism_of_modelet' }
-The [formalism](formalism.md) used by a [modelet](#modelet) to describe the *referent*.
+The [formalism](formalism.md) used by a [modelet](#modelet) to describe the *phenomenon*.
 ###### Source: `engines-and-modelets.tff`
 
 ### **modelet_creation_date** `(`[**`modelet`**](#modelet)` > `**`$real`**`)` { #modelet_creation_date data-toc-label='modelet_creation_date' }
diff --git a/docs/concepts/origin.md b/docs/concepts/origin.md
@@ -1,6 +1,6 @@
 ## Types
 ### **origin** `$tType` { #origin data-toc-label='origin' }
-An agent's perspective on the *referent* captured in a particular [modelet](modelet.md).
+An agent's perspective on the *phenomenon* captured in a particular [modelet](modelet.md).
 
 - Observation is *situated* in time and space
 - Measured with sensors that have certain characteristics and limitations
diff --git a/docs/concepts/phenomenon.md b/docs/concepts/phenomenon.md
@@ -1,13 +1,15 @@
 ## Types
 ### **phenomenon** `$tType` { #phenomenon data-toc-label='phenomenon' }
-A *symbol* of some structure or object in the real world that the system
+Some space or object or being or process in the real world that the system
 represents using [modelets](modelet.md).
-A class in the *world model*.
-!!! question "TODO"
-    this has been renamed to "phenomenon_class" but maybe we pick something else?
+
+- *Situated* in time and space
+- May change over time
+- Associated with a mission-dependent *meaning*
 
 !!! example
-    - chair1
-    - dog7
-    - cloud5
+    - you
+    - your office
+    - your tea
+    - your tea approaching room temperature
 ###### Source: `fundamental-concepts.tff`
diff --git a/docs/concepts/representation_class.md b/docs/concepts/representation_class.md
@@ -0,0 +1,5 @@
+## Types
+### **representation_class** `$tType` { #representation_class data-toc-label='representation_class' }
+The purpose of a [modelet](modelet.md) (extrinsic to itself) when used by an [engine](engine.md). 
+Class in the *Processing/Modelling Model*.
+###### Source: `fundamental-concepts.tff`
diff --git a/docs/concepts/role.md b/docs/concepts/role.md
diff --git a/docs/concepts/strategy.md b/docs/concepts/strategy.md
@@ -4,7 +4,7 @@ A succession of [exertions](exertion.md) of [engines](engine.md) connects [model
 [Strategies](#strategy) are transitive.
 
 - Must respect engine [requirements](requirement.md)
-- Matches [modelet](modelet.md) *referent* semantics to physical reality
+- Matches [modelet](modelet.md) *phenomenon* semantics to physical reality
 	- e.g. "on the living room table" to coordinates
 
 ###### Source: `transitive-strategies.tff`
diff --git a/docs/concepts/template.md b/docs/concepts/template.md
@@ -17,35 +17,28 @@ Some particular set of [templates](#template) which describe the inputs to an [e
 
 
 ## Relations
-### **topic_of_template** `(`[**`template`**](#template)` > `[**`phenomenon`**](phenomenon.md)`)` { #topic_of_template data-toc-label='topic_of_template' }
-The [phenomenon](phenomenon.md) symbolizing the *referent* of a [template](template.md).
-!!! question "TODO"
-    rename from 'topic' to something else.
-!!! question "TODO"
-    Should we call this the intrinsic purpose? (as opposed to the [`role`](role.md)).
+### **template_has_concept_requirement** `(`[**`template`**](#template)` > `[**`concept`**](concept.md)`)` { #template_has_concept_requirement data-toc-label='template_has_concept_requirement' }
+The [concept](concept.md) symbolizing the *phenomenon class* of a [template](template.md).
 ###### Source: `engines-and-modelets.tff`
 
-### **formalism_of_template** `(`[**`template`**](#template)` > `[**`formalism`**](formalism.md)`)` { #formalism_of_template data-toc-label='formalism_of_template' }
-The [formalism](formalism.md) this [template](#template) expects the *referent*
+### **template_formalism_requirement** `(`[**`template`**](#template)` > `[**`formalism`**](formalism.md)`)` { #template_formalism_requirement data-toc-label='template_formalism_requirement' }
+The [formalism](formalism.md) this [template](#template) expects the *phenomenon*
 to be described by.
 ###### Source: `engines-and-templates.tff`
 
-### **template_location** `(`[**`template`**](#template)` > `[**`spacetime_point`**](spacetime_point.md)`)` { #template_location data-toc-label='template_location' }
+### **template_has_location_requirement** `(`[**`template`**](#template)` > `[**`spacetime_point`**](spacetime_point.md)`)` { #template_has_location_requirement data-toc-label='template_has_location_requirement' }
 The time and spatial location a [template](#template) refers to.
 A [template](template.md) may have a specific temporal scope or expect an observation
 at a specific [`spacetime_point`](spacetime_point.md).
 ###### Source: `engines-and-modelets.tff`
 
-### **template_extent** `(`[**`template`**](#template)` > `[**`extent`**](extent.md)`)` { #template_extent data-toc-label='template_extent' }
+### **template_has_extent_requirement** `(`[**`template`**](#template)` > `[**`extent`**](extent.md)`)` { #template_has_extent_requirement data-toc-label='template_has_extent_requirement' }
 The time and spatial [extent](extent.md) a [template](#template) covers.
 A [template](#template) may expect an area/volume/duration of reference.
 ###### Source: `engines-and-modelets.tff`
 
-### **role_of_template** `(`[**`template`**](#template)` > `[**`role`**](role.md)`)` { #role_of_template data-toc-label='role_of_template' }
-The [role](role.md) a [template](#template) requires a [modelet](modelet.md) to
-play when used by an [engine](engine.md).
-!!! question "TODO"
-    This looks like it will turn out to be HOL.
+### **template_has_creator_requirement** `(`[**`template`**](#template)` > `[**`engine`**](engine.md)`)` { #template_has_creator_requirement data-toc-label='template_has_creator_requirement' }
+The [engine](engine.md) a [template](#template) requires a [modelet](modelet.md) to have been created by.
 ###### Source: `engines-and-modelets.tff`
 
 ### **is_in_template_set** `((`[**`template`**](#template)` * `[**`template_set`**](#template_set)`) > `**`$o`**`)` { #is_in_template_set data-toc-label='is_in_template_set' }
diff --git a/docs/concepts/topic.md b/docs/concepts/topic.md
diff --git a/tff/tests/test-wind-scenario.tff b/tff/tests/test-wind-scenario.tff
@@ -583,8 +583,6 @@ tff(drone_state_estimation_template_set_parts, axiom,
       T = wind_template
       |
       T = trajectory_template
-      |
-      T = wind_template
     )
   )
 ).
@@ -655,7 +653,7 @@ tff(template_sets_are_distinct, axiom,
 %    E = dsee_engine
 %  )
 %).
-
+/*
 tff(question_decl, question,
   ?[MS : modelet_set, M: modelet, US1: modelet_set]:
   (
@@ -668,15 +666,16 @@ tff(question_decl, question,
     is_in_modelet_set(M, exertion(we_engine, MS, M, US1))
   )
 ).
+*/
 
-%tff(question_decl, question,
-%  ?[M : modelet]:
-%  (
-%    ~(M = wind0_modelet)
-%    &
-%    modelet_models_concept(M, wind) 
-%  )
-%).
+tff(question_decl, question,
+  ?[M : modelet]:
+  (
+    ~(M = wind0_modelet)
+    &
+    modelet_models_concept(M, wind) 
+  )
+).
 
 
 %tff(question_decl, question,
