Webel Parsing Analysis for SysML: "Snippet trumps Requirement": A SysML Requirement element is just another model element that is elicited IN PARALLEL WITH other elements that a text description mentions in any way as being involved with or related to it.
Mathematica: TIP/GOTCHA: When using a Table loop variable within a Module always declare a module variable for it or you can get very hard to track side-effects elsewhere in your project due to exposed scope. Yes, it's obvious (yet easy to miss).
Mathematica: Webel: ADT pseudo classes: POLICY/DEFINITION: Every "hard coded" definer or defining client of a definer has a corresponding ADT ArchetypeClass. Example ("hard coded"): The definer 'my$def$MY$SmartList' has ArchetypeClass 'MY$SmartList'.
Mathematica: Webel ADT pseudo classes: A tricky POLICY & CONVENTION: Client packages MUST access the special "wrapped" primary named ADT-parameter '$$' via $ContextAliases! The recommended alias is "A`" (which stands of course for ADT).
Mathematica: POLICY: Webel: ADT pseudo classes: Multiple inheritance is supported via ONE (only) ADT-Class and one or more ADT-MemberInterfaces (which have no ADT-Method UpValues)
Mathematica: Webel: ADT pseudo classes: POLICY: Definer functions MUST return the self-declared or injected 'pattern' that determines the unique "ADT-signature" of the defined ADT class.
Mathematica: POLICY: Webel: ADT pseudo classes that define membership of ADT-classes in a domain package have ADT-signature MemberInterface[$$:None] and MUST NOT populate ADT-method UpValues in their definers.
Mathematica: NAMING CONVENTION: Webel: ADT pseudo classes: An UpValue that can be invoked on an ADT accepting its unique 'signature' pattern as (at least) 1st argument is called an "ADT-method"'. They are NOT methods in the general object-oriented sense!
Mathematica: Webel: ADT pseudo classes: There is an 'ADT' universal base class that has no supers. It "blesses" every other sub-class ADT by populating it with some common ADT-method UpValues against its signature pattern via the 'adt$def$All[]' definer.
Mathematica: Webel: ADT pseudo classes: POLICY: Every named concrete Abstract Data Type (ADT) class has a ONE unique "signature" (which is the pattern passed to the "definer" functions). To vary a signature, define another unique ADT class name.
Mathematica: Webel: ADT pseudo classes: POLICY: The Abstract Data Types (ADTs) are stateless functional (although inheritance and overrides are supported), with no caching by default (although there is nice optional caching using CreateUUID[] and Once[]).
Mathematica: Webel: ADT pseudo classes: POLICY: The expression '$$' is reserved as the primary named parameter for the defining pattern of all ADT classes that extend the universal base 'ADT' class.
Webel: SysML4Mathematica: Convention: A prefix '$doc' indicates a documentation String for each primary variable/quantity (argument or output)
Webel: SysML4Mathematica: Convention: A prefix 'sym$' indicates a markup variable "symbol" for a documented variable. It need not be a String, but each referenced part MUST be a String, not a raw Mathematica Symbol, to avoid namespace clashes!
Webel: Psy/MPsy: Psychrometrics for Mathematica: A suffix '$wat$i' indicates water (liquid or vapour) flow TO (into) the humid air mixture. A suffix '$wat$o' indicates water (liquid or vapour) flow FROM (out of) the humid air mixture.
Webel: Psy/MPsy: Psychrometrics for Mathematica: A suffix '$sat' indicates a humid air mixture quantity at saturation (relative humidity = 1 or degree of saturation = 1).
Webel: Psy/MPsy: Psychrometrics for Mathematica: A suffix '$ha' indicates a HUMID air mixture variable, quantity, or function or a PER humid air mass quantity.
Webel: Psy/MPsy: Psychrometrics for Mathematica: A suffix '$a' indicates a DRY air component variable, quantity, or function. A suffix '$da' indicates a HUMID air mixture quantity PER dry air.
Webel: Psy/MPsy: Psychrometrics for Mathematica: A suffix '$wat' indicates a water-related variable, quantity, or function (note that 'w' is reserved for the humidity ratio).
Webel: Psy/MPsy: Psychrometrics for Mathematica: The term 'steam' (indicated in variable names with a suffix '$s') is reserved for water vapour created through boiling.
Psychrometrics: Calculations of the mass flow rate of the dry air component (assumed constant under steady state) from the ENTRY volumetric flow rate of the humid air mixture MUST use the INITIAL state variables!
Webel: SysML4Mathematica: POLICY: Handle flow sign changes via a single negative (not duplicated and "adjusted" algebra). This strategy may come at a very slight performance cost (for benefit of more robustness).
Webel: SysML4Mathematica: Convention: A custom SysML ValueType 'Quantity' extends a custom ValueType '_' (representing a Mathematica '_' Blank). It DOES NOT also extend the SysML Real!
Webel: SysML4Mathematica: Convention: A Mathematica Blank '_' (which pattern-matches any Expression) is represented by a custom SysML ValueType '_'
Webel: Psy/MPsy: Psychrometrics for Mathematica: Convention: Option variable names are prefixed with '$opt$psy'
Webel Best Practice: Mathematica: Options are encapsulated as a String variable with the prefix '$opt', and have a related '$info$opt$' String (help), '$lab$opt' String (label), a 'def$opt' default value expression, and an optional '$warn$opt' String.
Webel: SysML4Mathematica: An Association used as the Type of an argument or return is represented by a Block '<||>'. A List used as as the Type of an argument or return is represented by a Block '{}'.
Webel: Psy/MPsy: Psychrometrics for Mathematica: The default newPsy[tdb] builder accepts the pressure 'p' as an option, which defaults to sea level atmospheric pressure.
Webel: Psy/MPsy: Psychrometrics for Mathematica: The default newPsy[tdb] builder requires the dry bulb temperature 'tdb', and one (only) of the relative humidity 'r', the humidity ratio 'w', or the wet bulb temperature 'twb' (as options).
Webel: Psy/MPsy: Psychrometrics for Mathematica: Due to Mathematica's units-aware Quantity algebra system it is irrelevant what units are used for the input Quantities for creation of the MPsy objects, as long as they are dimensionally consistent!
Webel: Psy/MPsy: Psychrometrics for Mathematica: Transferred heat (energy "Q") has field names with lower case 'qTot', 'qSen', 'qLat'. Heat rates (energy per time) have field names 'qDotTot', 'qDotSen', 'qDotLat' (to avoid clashes with Mathematica core)
Webel: Psy/MPsy: Psychrometrics for Mathematica: Relative humidity is indicated by a lower case 'r' and measured as a Real fraction (rather than as a Percentage). [Some tables and plots do SHOW the relative humidity as a Percentage.]
Webel: Psy/MPsy: Psychrometrics for Mathematica: For Imperial Units (IP), International British Thermal Units (Btu) are assumed
Webel: Psy/MPsy: Psychrometrics for Mathematica: Convention: 'Q' indicates the energy GAINED BY the system as heat energy transfer; 'W' indicates the work DONE BY the system on its external surroundings.
Webel: Psy/MPsy: Psychrometrics for Mathematica: Humidity ratio (absolute humidity) is indicated by a lower case 'w' and measured in mass (water) / mass (dry air) units, so the SI and IP representations are equal Real (without an explicit unit system)
Webel: SysMLv1.x: TIP: The name and documentation of a ValueType can indicate and specify more than just the unit and quantity kind. Example: A ClockFrequency may document how the frequency is measured. Example: WeightOnEarth.
"Everything now uses functional, nobody uses object-oriented anymore ... " WRONG: Grow up! Dr Darren (Webel IT)
Webel Parsing Analysis: SysML: Pseudo Semantic Triple: A «pa:triple» may be applied to a uni-directional Association between SysML Blocks and/or Actors.
Webel Parsing Analysis: SysML: Pseudo Semantic Triple: A «pa:triple» may be applied to a Dependency between SysML Blocks and/or Actors or Properties typed by them.
Webel Parsing Analysis: Pseudo Semantic Triple: When «pa:triple» is applied to a named uni-directional Association the name and a consistent direction arrow should be displayed on the Association symbol in diagrams.
Webel Parsing Analysis: Pseudo Semantic Triple: For «pa:triple» applied to a named one-to-one Dependency, the source is the subject, the name of the Dependency is the predicate, the target is the object.
Webel Parsing Analysis: Pseudo Semantic Triple: For «pa:triple» applied to a named one-to-one or one-to-many uni-directional Association, the non-navigable end Property is the subject, the name is the predicate, the navigable end Property is the object.
Webel Parsing Analysis: A 'source' Document must have one (only) of a URL or a URN (includes ISBN or other unique identifier) for use as a URI
Webel Parsing Analysis: The name of a Parsing Analysis Diagram (PAD) may be drawn from a focus Snippet OR may simply indicate a topic of interest to the analysis
Webel Parsing Analysis: While Associations may be collected as elicited members of a Snippet this can quickly lead to clutter in the /member list display. Often just collecting an end Property as member is sufficient.
Webel Parsing Analysis: While Generalizations may be collected as elicited members of a Snippet this can quickly lead to clutter in the /member list display.
Webel Parsing Analysis: Acronym: PAD = Parsing Analysis Diagram (may be nearly any diagram type, except those types that must be owned by an elicited model element)
Webel Parsing Analysis: As StateMachine Diagrams are always owned by an element that is not eventually under the Source Input Zone they should not be used as «pa» diagrams. Elicit States instead via the /member section of the specification dialog.
Webel Parsing Analysis: A Parsing Analysis Container MAY collect any other Element type as a member EXCEPT for another Parsing Analysis Container
Webel Parsing Analysis: The symbol for a Parsing Analysis Container MUST be able to indicate the unique domain source document from which its analysed text extract was quoted.
Webel Parsing Analysis: The symbol for a Parsing Analysis Container MUST be able to OPTIONALLY display a list of names of elicited model elements (a.k.a. members)
Webel Parsing Analysis: It SHOULD be possible to relate one Parsing Analysis Container to another and stereotype that relationship as an RDF/OWL-like semantic triple
Webel Parsing Analysis: It MUST be possible to collect elicited members of a Parsing Analysis Container graphically in diagrams using relationship-like path drawing (not just via a specification dialog or other indirect modelling means)
Webel Parsing Analysis: The symbol for the relationship between a Parsing Analysis Container and elicited model elements SHOULD be a dashed line (like the anchor/handle line used with a UML Comment)
Webel Parsing Analysis: The symbol for a Parsing Analysis Container MUST be text-friendly and evocative of quoting a domain source text extract
Webel Parsing Analysis: The symbol of a Parsing Analysis Container MUST be usable on every possible diagram type
SysML+SysPhS: Flows: If you intend to use a Classifier to type the itemProperty of an ItemFlow on a Connector for a physical interaction you MUST use a Block (not a ValueType or Signal) so your can extend ConservedQuantityKind.
Webel vs SysPhS-1.1: Annex A.5: Humidifier: Where ValueTypes involving litre are defined, the Unit symbol "L" is used rather than the Modelica-preferred "l" (in combination with an explicit additional unit converter).
Webel vs SysPhS-1.1: Annex A.5: Humidifier: The water temperature from TemperatureIncreaseConstraint and HeatingCalculationConstraint starts at 0 °C (should probably be the environment temperature 20 °C). Needs an additional parameter and initial value.
Webel vs SysPhS-1.1: Annex A.5: Humidifier: Where custom ValueTypes are defined, Modelica-friendly Unit symbols are used. Examples: "m3" not "m^3"; "degC" not "°C"; "J/(K.L)" (full stop as multiplier) not "J/(K⋅L)"; (EXCEPT "L" for litre not "l").
Webel: SysML: DO NOT sacrifice modelling naming conventions for the mere sake of carrying organisation-specific names! Instead use tagged values of custom stereotypes as metadata to carry alternative names in parallel with systematic model element names.
GOTCHA: MD SysML/Cameo 19SP3 vs SysPhS-1.1: Export to Modelica does not see a 'doActivity' on a State (does not write it to a Modelica algorithm), you MUST use an 'entry'!
Webel Twin Pattern: DigitalTwin: The multiplicity of 'digitalEntity:@Entity' and 'physicalEntity:PhysicalEntity' MUST be [1] when the DigitalTwin is in the state Attached, the @Entity is in the state Bound, and the PhysicalEntity is in the state Exists.
UML/SysML: If you have a Boolean "state flag" attribute corresponding to a State you MUST set it on an 'entry' of the State, not on the 'effect' of a Transition into the State (otherwise with multiple incoming Transitions it could be WET and breaks SSoT).
Webel Twin Pattern: A DigitalTwin and PhysicalEntity must both be 'attached' to Sensors and/or Actuators under management of the DigitalTwin before the twinning control loop is fully entered.
Webel Twin Pattern: The sensor/actuator twinning control loop can involve automated devices (SensorDevice and/or ActuatorDevice) and or humans (SensorHuman and/or ActuatorHuman).
Webel Twin Pattern: A DigitalTwin (even a "process twin" or "finance twin"), always, without exception, BY DEFINITION HERE either directly or indirectly involves at least one existing or anticipated PhysicalEntity (even if only via another DigitalTwin)!
Webel Twin Pattern: A DigitalEntity (a.k.a. «digital» @Entity) used as a digital variant must not be directly bound to a «physical» PhysicalEntity (may not directly actuate/sense/affect)
Webel Twin Pattern: Communication between the ControlSystem of a DigitalTwin and its digitalEntity:@Entity is via a dedicated protocol (ReadTwin, WriteTwin) distinct from the sensor reading or actuator driving signals.
Webel Twin Pattern: A DigitalTwin may use one or more variantEntity:@Entity[0..*] to explore the impact of changes (optimisation studies, trade off studies) and then use them to drive the PhysicalEntity into a desired state (via its ControlSystem).
Webel Twin Pattern: The primary aim of the digitalEntity:@Entity of a DigitalTwin is to replicate its physical:PhysicalEntity as closely as possible (not to explore variants).
Webel Twin Pattern: A «digital» DigitalEntity (a.k.a. @Entity) is NOT a representation! It is a digital encapsulation (it can only be perceived at the level of "bits and bytes"). It HAS many representations (such as views)!
Webel Twin Pattern: A PotentialPhysicalAsset is «digital», not «physical». It is used to acquire (an existing) or create (build, manifest, make) an «physical» ActualPhysicalAsset, which is a special case of «physical» PhysicalEntity.
Webel Twin Pattern: A DigitalTwin manages a control loop including a PhysicalEntity and a DigitalEntity (a.k.a. @Entity) that «replicates» it. It typically includes at least one Sensor and at least one Actuator.
Webel Twin Pattern: It is a DigitalEntity (a.k.a. @Entity) - not the DigitalTwin that owns it - that directly «replicates» geometrical, spatial, and material aspects (only) of a single PhysicalEntity.
Webel Twin Pattern: A «digital» DigitalEntity (a.k.a. @Entity) encapsulates strictly geometrical, spatial, and material aspects of a «physical» PhysicalEntity only. BY DEFINITION of this pattern it DOES NOT encapsulate processes!
Webel: SysML-1.7/SysMLv2: WISHLIST: Constraint: A BindingConnector used for pure proxying MUST NOT be typed by an AssociationBlock by definition, because the associated information can be mis-appropriated to undermine the proxy equality!
Webel Parsing Analysis diagrams do their job once - namely traceable elicitation of model elements - and are then only kept as a reference! The elicited model elements are then used elsewhere in the final model.
In Webel Parsing Analysis elicited model elements MUST eventually be moved out of the 'source' (or '0-source') Package/Model zone and under a main project Package/Model area. (Use the owner display option to check.)
ALL Model-Based Engineering: Just because you can't see a Feature or some other aspect of a SysML (or UML) Element in a tool on a symbol does NOT mean it does not exist in the underlying model (repository)! The model is not just what is DISPLAYED!
Rule #1: A UML or SysML Element in a tool is NOT just an Element symbol in a diagram! A Note is not an Element (compare with a Comment).
GOTCHA: Just because an InitialNode MAY have more than one outgoing ControlFlow and offers tokens on every outgoing ControlFlow does NOT mean that every outgoing edge takes a control token; InitialNode does NOT act like an implicit fork!
Webel: A plain Dependency that is not stereotyped is always strictly timed-ordered; the supplier (target) must exist before the client (source).
Visual nesting of InstanceSpecification symbols has no meaning in the underlying model, only assignment to a Slot does!
When dealing with required Interfaces you must use Usage (not Dependency) and it has dedicated "socket" notation.
MagicDraw/Cameo: If you make a copy of the SYMBOL of an Element in a Diagram you have only copied the SYMBOL, it represents the same Element! If you make a copy of an Element in the model browser you have indeed made a unique new (distinct) Element!
Webel Parsing Analysis: A Snippet (keyword «snippet») MUST always have exactly one domain 'source' Document (keyword «document»).
Webel Parsing Analysis: A custom Document stereotype (keyword «document») extends the UML standard profile Document that extends Artifact (which is NOT in the UML4SysML intersection). Such a Document may act as the 'source' of a «snippet».
Webel Parsing Analysis: Create a top-level 'source' or '0-source' Package/Model SEPARATE from your project model. All source «document» elements and «snippet» extracts and «pa» diagrams MUST be ultimately owned by that top-level Package/Model as ancestor!
Webel «pa» Parsing Analysis Diagrams (PADs) are "scratchpads" used to elicit model elements traceably from text Snippets (extracts from source Documents). While BDDs are a good initial choice, most types of SysML diagram can be used as a «pa» diagram.
Webel Parsing Analysis: If you wish to show a «snippet» comment symbol (with its body text) in a presentation diagram (that is NOT a «pa» diagram) remove the '/member' tagged value from display so the only visible tagged value is 'source'.
Webel Parsing Analysis «pa» diagrams are NOT intended as final presentation diagrams! They serve merely to traceably elicit model elements, which may then be shown in other (typically much tidier) presentation diagrams elsewhere.
AVOID "mixed" functional (behavioral) allocation levels! DO NOT Allocate from Usage level (Action) to Definition level (Block) or from Definition level (Activity) to usage level (part Property) - even if formally permitted in SysML.
DO NOT use Property names that are identical to the names of the Classifier (Class, DataType, Block, ValueType) that type them!
Webel: DO NOT name the Type (Block or InterfaceBlock) of a Port with a flow the same as the name of the 'Stuff' that flows through it; use the Webel 'F_Stuff' convention!
DO NOT use spaces in Property names or Class/Block names! If you want to communicate familiar names of elements within an organisation use a custom stereotype and tagged values (such as 'aka')!
SysML: MagicDraw/Cameo: Diagram Style: Recommend DO NOT use shadows or gradient fill adornments on diagrams! [TIP OFTEN IGNORED]
Webel: For SysML Blocks and InterfaceBlocks used to type Ports with physical flows use 'F_UpperCamelCase' [may be combined with acronymn conventions
For SysML Blocks and InterfaceBlocks used to type Ports with contracts use the naming convention 'I_UpperCamelCase' [may be combined with acronymn conventions]
SysML: Naming: Always use either anonymous or first letter lower case for Property, ObjectNode and InstanceSpecification names; no exceptions (unless using names to "quote text")! Valid: 'lowerCamelCase' OR 'tla' vs TLA acronym OR 'uCC' vs UpperCamelCase
When using acronyms in names of Classifiers either treat them as a word 'TlaLikeThis' or suffix with an underscore 'TLA_LikeThis', except at the end of the name 'LikeThisTLA' is admissable.
