Tutorial updated for FDL

Author: christoph-grimm

install/3-SysMLv2Tutorial/Files/element-syntax.png

@@ -27,25 +27,16 @@ After reading the part "KerML," you
  - different kinds of classes in the abstract representation of KerML
 
 --- 
-# KerML and SysML
+# KerML: Basis for SysML and More 
 The SysML v2 ecosystem builds on top of a basic and simple language: 
-KerML (Kernel Modeling language).
-KerML is used as a kind of internal representation and starting point throughout the whole ecosystem. 
-In consequence, we start the tutorial with a description of the KerML.
-
+KerML, the Kernel Modeling language.
 KerML has several purposes: 
 
-* Its classes specify the so-called _Metamodel_. 
-The Metamodel describes the means to specify models, and gives basic semantics.
-* Instances represent concrete models are the basis for persistence and exchange of models; they can be given
- * in an abstract way by elements and relationships between them in arbitrary representation ("abstract representation").
- * in a concrete textual model ("textual representation").
-
-The abstract representation is the foundation, for example, for model exchange in formats like JSON or XML; 
-see part "API." 
-The textual representation allows users to specify models. 
+* First, it serves as the so-called _Metamodel_. 
+The Metamodel describes classes that are the means to specify models, and gives basic semantics and constraints.
+* Second, instances of the metamodel classes are used to represent concrete models.
 
-KerML and SysML are structured in different layers.
+KerML is structured in different layers.
 The layers introduce, step by step and building on top of each other, more and more features.
 The table below gives an overview of the KerML layers, including SysML v2. 
 Note that SysML v2 can be seen as a domain-specific library based on KerML. 
@@ -58,11 +49,15 @@ Note that SysML v2 can be seen as a domain-specific library based on KerML.
 | SysML v2 | Domain-specific library based on KerML | Definition & Usage of Attribute, Part, Port, Connection, Interface, Requirement, ... |
 
 KerML (and SysML) both distinguish two different representations: 
-The _textual representation_ is written text, like a programming language.
-It is translated by a compiler into an _abstract representation_ that consists of elements that are part of the Metamodel description.
-These elements can be serialized, analyzed, etc. 
+
+The **textual representation** is written code, similar a programming language.
 In SysMD, one edits the textual representation in a notebook cell (see figure below, left). 
-After compilation, the abstract representation is shown in the "has-a" tree view (see figure below, right).
+
+The **abstract representation** is generated by compilation, using production rules and related classes from the KerML metamodel. 
+An example of the relationship between textual and abstract representation is shown below.
+It is visualized in the "has-a" tree view of SysMD (see figure below, right).
+The abstract representation is the foundation, for example, for model exchange and persistence.
+Then it is serialized into formats like JSON or XML; see part "API."
 
 ![img.png](Files/textual-versus-abstract-representation.png){width=1000 height=250}
 
@@ -81,13 +76,13 @@ The _Root_ Layer of KerML deals with
 > The Root Layer of SysML introduces no specific semantics; 
 > it just provides infrastructure for modeling. 
 
-In the following, we introduce three main artifacts of the Root Layer
-- Element
-- Relationship
-- Namespace
-- Annotating Elements
+In the following, we introduce main artifacts of the Root Layer
+
+- Element and Relationship as base elements for all KerML and SysML v2 constructs, 
+- Annotating Elements, and 
+- Namespace, Import
 
-## Elements
+## Elements and Relationships 
 
 All artifacts in KerML and SysML are different kind of "Elements". 
 `Element` is the base class for all kinds of Elements in KerML, and all other classes inherit its features. 
@@ -113,12 +108,37 @@ Examples for unrestricted names are:
 - `'This is a valid unrestricted name'`
 - `'1.2'`
 
+The general pattern for elements the textual representation is shown below. 
+
+![img.png](Files/element-syntax.png){width=400 height=130}
+
+Each element generally consists of 
+- suitable prefixes, e.g., private, public, in, out, etc., 
+- a keyword (i.e., doc) from which the element kind in the abstract representation is derived, 
+- a short name and the name as described above.
+
 Each element can own other elements respectively, be owned by an owner.
 This is internally represented by an Element of kind `OwningMembership`, which is a kind of Relationship.
 A fundamental principle of KerML and SysML is that all relationships, including ownership are represented 
 by reified kind of Relationship.
 
-## Annotating Elements
+
+A relationship is a kind of KerML element that models a relationship between elements.
+In addition to an element, a relationship has the properties
+- `source`, and
+- `target`.
+
+Source and target are (ordered) collections of _references_ to elements.
+Relationships are used as reified objects to model all kinds of relationships,
+in particular also the ownership between elements and its owning element.
+Often, but not always, its syntax follows the pattern shown below. 
+
+![img.png](Files/relationship-syntax.png){width=350 height=120}
+
+
+
+
+## Annotating Elements and Annotation 
 
 The most basic and simple elements are annotating elements.
 Don't confuse them with annotations that are relationships as shown later. 
@@ -129,7 +149,8 @@ Specific kind of AnnotatingElement are
 - `Documentation` (starting keyword: `doc`) with a property `body` that holds the comment resp. documenting text.
 - `TextualRepresentation` (starting keyword: `rep`) with a property `body` that holds source code, 
  and a property `language` that holds a string that gives the language of the model, e.g., SysML, or
-- `Metadata`
+- `Metadata`. 
+- `Annotation` is a Relationship that links an annotating element with an annotation (e.g. its owner). 
 
 **Example**
 
@@ -138,33 +159,29 @@ In the example below, we add a Documentation and two comments to the package tut
 doc kermel /* The package tutorial::kerml is the top-level package that owns all artefacts of the tutorial. */ 
 comment /* The owning package is specified in the header of each SysMD cell. */ 
 comment c1 about tutorial /* Comments and Documents can have names! */ 
+rep code language C /* println("Hello"); */ 
 ```
 
-## Namespace
+Note that the comment about the tutorial includes an annotation that refers from the comment (source) to the package `tutorial` (target).
+Also note that the syntax is "about" instead of "from .. to". 
 
-A namespace provides the means to retrieve elements by its name or short name.
-In this context, a **qualified name** describes a path from an element to another element in a 
-hierarchy of elements.
-In a qualified name, different names are called segments, and they are separated by "::". 
+## Namespace, Import 
 
-Namespaces can **import** single or all elements of other namespaces via "imports."
-In KerML, an import is a relationship between an importing namespace and 
-- an imported namespace (all elements are imported), or 
-- a single element.
-It makes imported elements visible directly in the importing namespace. 
+A namespace provides the means to retrieve elements by its name, its short name, 
+or by qualified names that give a kind of path (see below).
 
 >The process of searching an element by its name is called _name resolution_.
 
-**Example**
+Name resolution searches locally, in supertypes, and in imported members. 
+
+**Example: Namespace**
 
 Below, an example with two nested namespaces is given.
 Note that the syntax schema throughout KerML and SysML is to start all elements by
 - A keyword that gives its kind, that is the respective KerML, SysML class by convention in small letters.
 - Optionally, a name and short name (in < .. >) and/or name 
 - Optionally, a body in curly braces where owned elements are modeled
 
-In the example, the qualified name `namespaceExample::Bike` refers to the Bike of the 
-namespace owning the namespaceExample. 
 ```KerML::tutorial::kerml
 namespace NamespaceExample { 
  namespace Car {
@@ -184,36 +201,46 @@ The figure below shows the abstract representation generated by the example:
 ![ownership.png](Files/ownership.png){width=550 height=330}
 
 
+To refer to elements in other namespaces, one can use qualified names. 
+A qualified name gives a path from the namespace where it is used to another element.
+IIn a qualified name, different names are called segments, and they are separated by "::".
+For example, the namespace Car has, starting with `tutorial::kerml`, the qualified name `NamespaceExample::Car`.
+However, the use of qualified names can lead to overly verbose models. 
+Hence, namespaces can **import** single or all elements of other namespaces via "import."
+In KerML, an import is a relationship between an importing namespace and
+
+- an imported namespace (all elements are imported), or
+- a single element.
+
+An import makes imported elements available as member in the importing namespace.
+
 >**Warning**: 
 > SysMD permits executing code in cells in a given namespace (selected in the line above the cell). 
 > The whole tutorial is part of the namespace `tutorial`. 
 > The concrete example is executed in an isolated namespace `tutorial::kerml`, where `NamespaceExample' is added.
 > This is not (yet?) part of the standard, where every cell would have to be in the root namespace.
 
-## Relationship
-
-A relationship is a kind of KerML element that models a relationship between elements. 
-In addition to an element, a relationship has the properties
-- `source`, and
-- `target`. 
-
-Source and target are (ordered) collections of _references_ to elements.
-Relationships are used as reified objects to model all kinds of relationships,
-in particular also the ownership between elements and its owning element. 
-
-From the user's perspective, `Annotation` is an important kind of elements in the Root layer of KerML.
-An Annotation is a relationship between Annotating Element and an annotated element. 
-
-> We come back to relationships later in the Kernel Layer.
 
-## Annotating Elements 
+**Example: Import**
+The name resoluti
+```KerML::tutorial::kerml 
+namespace Car {
+ class Engine; 
+}
+ 
+package importExample {
+ class Car { 
+ private import carParts::*; feature engine: Engine; 
+ }
+}
+```
 
-# Core Layer
+# Core Layer: Classifiers and Features
 
 The core layer introduces _types_ to describe and classify things that exist 
 in an imaginary or the existing universe.
-For this purpose, a type introduces a relationship `Specialization` or a more specific kinds thereof. 
-This relationship relates each type to a more general type.
+For this purpose, a type uses a relationship `Specialization`; 
+more specific types use also more specific kinds of the relationship. 
 
 The most general and predefined type is `Base::Anything`.
 All types are subtypes of this type. 
@@ -223,18 +250,20 @@ All types are subtypes of this type.
 > (OMG, KerML)
 
 For example, we can introduce a type `Vehicle` with the extent of all vehicles.
-An individual vehicle would then be an instance of this type.
+A feature `vehicle` typed by the type `Vehicle` is then an instance of this type.
+Note that SysML v2 further adds _individuals_ that occur individually in the physical world. 
 
-KerML introduces two different kind of types, each with different purpose: 
+## Classifiers and Features 
 
-- Classifier, and
-- Feature.
-## Classifiers
 
-SysML v2 has an ontological foundation. 
-Classifiers are types that classify single things in an imaginary or the real universe. 
+## Subtyping and 
 
+## 
 
+## Classifiers
+
+SysML v2 has an ontological foundation. 
+Classifiers are types that classify single things in an imaginary or the real universe.
 
 The Kernel layer (see below) further refines the ontological semantics of classifiers into: 
 
@@ -273,7 +302,8 @@ The Kernel layer introduces specific classes with more complex semantics, includ
 - Behavior
 - Functions and Expressions
 - Associations and Connectors 
-## DataType, Class 
+
+## DataType
 
 The Kernel layer differentiates Classifiers into
 - data types (keyword `datatype`, KerML class DataType), where occurrences are non-distinguishable individuals.
@@ -284,12 +314,11 @@ The Kernel layer differentiates Classifiers into
 
 The standard library `ScalarValues` introduces some basic data types, including
 - Boolean; it can be referred by its qualified name: `ScalarValues::Boolean`.
- Alternatively, you can import the namespace `ScalarValues` in the current namespace (`private import ScalarValues::*`).
+ Alternatively, one can import the namespace `ScalarValues` into the current namespace (`private import ScalarValues::*`).
  Then, you can directly refer the type by `Boolean` 
 - Integer (`ScalarValues::Integer`)
 - Real (`ScalarValues::Real`)
 
-
 Note that Reals have no accurate representation on computers; 
 they are, for example, represented by symbolic representations.
 For execution or computations, approximations like floating point representations must be used. 

install/3-SysMLv2Tutorial/Files/relationship-syntax.png

@@ -7,5 +7,5 @@
  "website" : null,
  "topic" : null,
  "usage" : [ ],
- "id" : "ca8e16b9-da19-4037-b1ff-82783f6c8d05"
+ "id" : "b6a394f1-99e7-42b9-8172-f3631fd3986c"
 }