Webel: Mathematica: CONVENTION: A 'type$' indicator for an '$opt$' or '$arg$' is for documentation only. It may use a "pattern helper", a human-friendly String, or a SysML-similar short-hand type representation. It need not correspond to a valid Pattern.
Webel: SysML4Mathematica: A custom stereotype «M:Paclet» applied to a SysML Package denotes a Wolfram Package Paclet. An «M:Package» is a specialisation of SysMLv1 Block and denotes a Wolfram Language Package.
Webel: SysML4Mathematica: A SysML/UML Usage (keyword «uses») is used to indicate a Wolfram Package Needs import, where an «M:Package» is a specialisation of Block (not a SysML/UML Package) and denotes a Wolfram Language Package.
Webel: Mathematica: CONVENTION: A '$Q$' in a function variant name indicates that it is a variant where every argument is strictly either a Quantity or dimensionless Real. Compare with '$SI$' functions.
Webel: Mathematica: CONVENTION: An '$E$' or '$EQ$' in a function name indicates that it is symbolic (takes Blank expression arguments), but the absence of '$E$' or '$EQ$' does not necessarily imply that it does not take Blank arguments.
Webel: Mathematica: The Method syntax for the user contributed MTools does not seem to support Method-specific ::usage. The Webel libraries offer method documentation support (including arguments and options) via the HelpO` class/method registry.
Webel: Mathematica: The Method syntax for the user contributed MTools does not seem to support Wolfram Language Options[]. The Webel MTools extensions offer options support via a Webel Options Association in combination with the HelpO` method registry.
Mathematica: Webel ADT pseudo classes: «adt:ref» applied to a property indicates that it is resolved by ID through the ADT store using adt$fetch[id]. Use adt$store[adt] for very large ADTs and for cleaner ADT views and easier Notebook development.
Mathematica: Webel OpenXML: The XL$Cell value accessor XL$Cell⊙valReal has no units-awareness; prefer the US$Cell value accessor US$Cell⊙val, which can return a Quantity.
Mathematica: Webel ADT pseudo classes: POLICY: Where an ADT-Method uses UUID-driven Once[] caching the trigger argument is a String '$uuid' which MUST have a default None and MUST be the first argument that has a default.
Webel IT Australia prefers to use examples from real client projects but usually heavily obfuscates, masks, or randomises client-specific data. Educational examples do not expose client data without permission.
Mathematica: Webel ADT pseudo classes: The ADT⊙get method may be used to access the '$$' wrapped primary. This is intended for development and testing purposes only (not for regular use by clients) since it BREAKS ENCAPSULATION!
Webel: SysML4Mathematica: An '@*~' prefix in a @pseudo function (OpaqueBehavior or Activity) represents a cast from any expression to a Type. Example: '@*~OpenerView' casts from any expression to an OpenerView. '@Type~' casts from a specific Type.
Webel: Mathematica: The Webel MAll universal base class does not itself use Webel method options (but does offer some support for method options for extending classes)
Webel: Mathematica: CONVENTION: An '$SI$' in a function variant name indicates that all arguments are SI Real convention (no Quantity arguments with units). An '$SI$' function can also be used to generate '$C$' compiled function variants.
Webel: Mathematica: CONVENTION: A '$C$' in a function name indicates that it is a compiled variant. Typically it is compiled from an '$E$' symbolic function or an '$SI$' Real convention function.
Webel: Mathematica: CONVENTION: An '$E$' in a function name indicates that it is symbolic (takes Blank expression arguments). An '$E$' function can also be used with Quantity inputs and can be used to generate '$C$' compiled function variants.
Webel: Mathematica: CONVENTION: A '$EQ$' in a function name indicates that it is a symbolic equation (with LHS == RHS). An '$EQ$ function can be used in combination with 'sym$' markup to create human-friendly formatted equations.
Webel: Mathematica: CONVENTION: Entity "field definers" are prefixed with '$e$[pac]' (where '[pac]' is a nickname for a package or logical grouping) and carry String field names. EntityStore functions are prefixed with 'e$[pac]'.
Webel: Mathematica: Packages that import the Webel HelpF` package (but not MTools and the Webel HelpM` package) should use the 'usageF' function for ::usage String generation (rather than the 'docF' and 'docV' functions) and an AOR Map.
Webel: Mathematica: CONVENTION: A '$sig$f$' prefix indicates a String signature helper for a function (or for a "method" of an MTools class or a Webel Abstract Data Type (ADT) pseudo class).
Webel: Mathematica: CONVENTION: A '$doc$' prefix indicates a formatted documentation String helper. A '$doc$arg$' is for an argument, a '$doc$opt$' is for an option. A '$doc$ String may be used to create ::usage documentation via docF.
Webel: Mathematica: CONVENTION: A ‘$pac$’ String helper variable is used to capture the fully qualified String name of every package. Useful for quick '$pac' argument provision for search functions and for DEVEL package load echoes.
Webel: Mathematica: CONVENTION: A 'z$' prefix may be used to indicate a Private` function or expression within a package or a "private" method of an MTools class or Webel Abstract Data Type (ADT) stateless pseudo class.
Webel: Mathematica: CONVENTION: The Stereotype keyword «functional» indicates a "pseudo functional" representation of functional in SysML. There are limits to representation of functional programming in SysML, but it can be informative and is worth doing.
Webel: Mathematica: CONVENTION: A '$t$' prefix indicates a String help holder with a "pseudo type" indicator (for human friendly documentation only). Used by the Doc`, HelpF`, and HelpO` packages.
Webel: Mathematica: CONVENTION: A function's description (but not its signature, arguments, or options) may be captured as an '$info$f$' Stringhelp holder for use by the Doc` package for ::usage generation and the HelpF`& HelpO` help registry packages.
Webel: Mathematica: A help Rule 'rule$opt$' for an '$opt$' (option) accepts keys: '$k$help' (required), '$k$def' (required), and optional '$k$warn', '$k$tip', '$k$lab' (a label), '$k$type' (indicator only), '$k$mult' (SysML multiplicity), and '$k$pat'.
Webel: Mathematica: A help Rule 'rule$arg' for an '$arg$' (argument) accepts keys: '$k$help' (required), '$k$def' (required if $k$req = True not given), '$k$req' (True if $k$def not given), '$k$warn', '$k$tip', '$k$lab', '$k$type', '$k$mult' and '$k$pat'
Webel: Mathematica: CONVENTION: An '$opt$' (option) or '$arg$ (argument) help holder may be have an associated (typically short) '$lab$opt$' or '$lab$arg$' label help holder for use in GUIs and views.
Webel: Mathematica: CONVENTION: Where keys of Associations are Strings they are encapsulated as variables prefixed with '$k$' (promotes DRY and has many advantages, such as IDE prompting). Direct use of "Strings" as keys is WET and strongly discouraged!
Webel: Mathematica: CONVENTION: "pattern helpers" (which are not themselves Patterns) use the prefix '$pat$. Encapsulated Patterns use a 'pat$' prefix, and may use a '$pat$' pattern helper (such as an Alternatives).
Webel: Mathematica: CONVENTION: Argument help holders use a String variable with the prefix '$arg$', a related '$info$arg$' String, a 'def$arg$' default value expression and/or 'req$arg$', and optional '$warn$arg$', '$tip$arg$, '$lab$arg$', 'type$arg$'..
TIP/GOTCHA: SysMLv1/fUML: Cameo Simulation Toolkit: If you have a ControlFlow loop with a DecisionNode test you MUST have a MergeNode for the continuation path ControlFlow (typically entered also from an InitialNode or other loop starting point).
TIP/GOTCHA: SysMLv1/UML: Cameo Simulation Toolkit: If you use a «decisionInputFlow» to a DecisionNode you MUST also have a ControlFlow to the DecisionNode; if you don't use an explicit «decisionInputFlow» you don't need the "extra" ControlFlow
Webel: SysMLv1: Recommend using Block Definition Diagrams as associative, graphical engineering "scratchpads" FOR YOU; Use Internal Block Diagrams as the main presentation diagrams for your engineering colleagues and other stakeholders!
Webel: SysMLv1: Overview of annotated Diagram Slides and Note pages related to general high level SysML modelling principles (some specific to MagicDraw/Cameo). Recommended reading for all Webel SysML/MBSE course attendees.
Mathematica: Webel ADT pseudo classes: POLICY: The ADT-Methods of an ADT-Class are created as TagSetDelayed UpValues using the 'signature' of the ADT-Class and its defining 'pattern' as 1st argument
Mathematica: Webel ADT pseudo classes: CONVENTION: PROVISIONAL: The infix operator for calling ADT-Methods on ADT "objects" is the CircleDot (⊙ in Notebooks). ISSUE: \[CircleDot] is NOT GOOD FOR USE IN IDEs!
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 '$$' via $ContextAliases! The recommended alias is "A`" (which stands of course for ADT).
Mathematica: Webel ADT pseudo classes: POLICY: 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: Webel ADT pseudo classes: ADTs 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: Webel ADT pseudo classes: There is an 'ADT' universal base that has no supers. It "blesses" every other sub-class ADT by populating it with some common ADT-Method UpValues against a signature pattern via the 'adt$def$All[]' definer function.
Mathematica: Webel ADT pseudo classes: DEFINITION/CONVENTION: Functions that populate ADTs with reusable ADT-method UpValues are called 'definers' and include '$def' in the name after a Package scope indicator: Example: adt$def$ADT, my$def$MY$CleverList
Mathematica: Webel ADT pseudo classes: POLICY: Every named concrete Abstract Data Type (ADT) has a ONE unique "signature" (which is the pattern passed to the "definer" functions). To vary a signature, define another unique ADT 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: 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: Psy/MPsy: Psychrometrics for Mathematica: Convention: Option variable names are prefixed with '$opt$psy'
Webel: Mathematica: CONVENTION: Option help holders use a String variable with the prefix '$opt$', a related '$info$opt$' String, a 'def$opt$' default value expression, and optional '$warn$opt$', '$tip$opt$', '$lab$opt$', and 'type$opt$' indicator ...
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).
Mathematica: TIP: Protecting against computations breaking verbosely because of Null, None, Undefined. And about using Undefined as a return policy.
MagicDraw/Cameo: Rule: Internal Block Diagram and Block structure compartment: only one symbol for a given Property may be shown.
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: Where too many dashed line "anchors" from Snippets to elicited members lead to clutter they may be selectively omitted from a Parsing Analysis Diagram (PAD) once each member has been collected.
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: An anonymous Element may be collected as a /member of a Snippet (it is not important whether collected elements list with a clear name under /member, only that they are traceably elicited).
Webel Parsing Analysis: A "focus" Parsing Analysis Diagram (PAD) for one or more Snippets SHOULD always show the /member tagged value of every Snippet.
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: In some SysML trails ValueType names with Unit indicator suffixes have been used for dimensional analysis and illustrative purposes. This practice is NOT otherwise recommended here. Instead just use consistent custom ValueTypes across your system!
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.
Webel Twin Pattern: The information and data in AssetSpecification leveraged for creation of a new ActualPhysicalAsset need not necessarily only be «digital».
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: Once a PotentialPhysicalAsset has been integrated with a real, existing (has mass) ActualPhysicalAsset under twinning control, its job is done forever (although it may be kept as an historical tracking record).
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: 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!
In the Webel Parsing Analysis recipe you are not obliged to map every single part of a Snippet's text extract to a UML or SysML model, just traceably elicit model elements of immediate or anticipated interest to your task or goal.
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.
A "staging" BDD for defining the flows, ports, and item properties on blocks to be used in an IBD does not have to be a "work of art" if it is not intended as a final presentation diagram.
Webel: SysMLv1.x: AVOID (where possible) SysML Unit names that are the same as unit symbols. Unit names SHOULD start with a lower case Latin alpha letter. Custom Unit names should be a single lower case word or lowerCamelCase.
Webel: A plain Dependency that is not stereotyped is always strictly timed-ordered; the supplier (target) must exist before the client (source).
Webel: SysML: Always consider including an abstract (sometimes intermediate) base Block in your domain modelling Generalization hierarchy.
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.
The name of a «testCase» Behavior may be verbose and may use natural language, but should always start with a Capital letter.
"Trust the Port or Pin Type!" - Often the name of the Type of an anonymous Port or Pin is completely sufficient to indicate its role, unless a clear indication of its direction or unique role is required.
Avoid mixing flow properties on the Type of a Port with directed features (operations and values); One distinguishes between "ports with flows" and "contract ports".
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.
Use of 'this-that' with a hyphen in Connector names is admissable (where 'this' and 'that' indicate Connector ends or their types)
DO NOT use Property names that are identical to the names of the Classifier (Class, DataType, Block, ValueType) that type them!
Webel: SysMLv1.x: AVOID (where possible) ValueType names that are the same as the name of units or unit symbols
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')!
For Blocks and Interface blocks with one or more FlowProperty items, choose a direction convention and use it across one project.
DO NOT name ports with first letter capital (like 'Port'), DO NOT name ports 'port' (except for educational illustration), and DO NOT use port names that do not indicate a role.
Webel suggests using a verbose 'name' for leaf (child) Requirements but NO 'text' to prevent Single Source of Truth issues and for improved callout vs relationships (but this might not always work when syncing with external requirements management tools)
SysML: Webel: "Trust the Type!" - Often the name of the Type of an anonymous Property or instance-level element is completely sufficient to indicate its role - unless multiple Properties of the same Type have different roles within the same owner context!
"Trust the Namespace" - DO NOT repeat information in names of owned elements that can be gleaned from the owner or ancestor (and is usually easily shown using display options). It is WET, it breaks the DRY principle!
The Webel versions of the SysML HSUV sample problems and specification sample figures use "standard" Ports EXCEPT where ProxyPorts or FullPorts are explicitly indicated in the specification
Since SysML-1.6 use of direct UML conjugation of Ports is NOT supported; If you are using InterfaceBlocks use instead a conjugated ~InterfaceBlock type!
The Webel modelling style, naming conventions, and Best Practices for SysML are more consistent than most SysML spec diagrams. When following Webel courses please DO NOT use the spec sample diagrams (which serve a different purpose) as visual references!
SysML: MagicDraw/Cameo: Diagram Style: Recommend DO NOT use shadows or gradient fill adornments on diagrams! [TIP OFTEN IGNORED]
Webel: SysML symbol colour styles: Recommend use black symbol borders and no symbol fill (or white symbol fill) EXCEPT for special highlighting. Recommend DO NOT use the default VENDOR-SPECIFIC line and fill colours for symbols! [TIP IS MOSTLY IGNORED]
Webel: For SysML Blocks and InterfaceBlocks used to type Ports with physical flows use 'F_UpperCamelCase' [may be combined with acronymn conventions]. The trailing part (after the underscore '_') may indicate the type that flows.
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.
Use 'UpperCamelCase' (a.k.a. PascalCase) names for Classifiers such as UML Classes and SysML Blocks) to avoid confusion with 'lowerCase' Property names [see however special naming conventions for acronyms and SysML contract and flow Blocks]
Prefer anonymous Actions, or if they must be named, prefer code-like 'lowerCamelCase' or completely 'lower case' (if you do absolutely insist on having spaces in action names, but please no other punctuation).
Prefer 'UpperCamelCase' (a.k.a. PascalCase) names for Behaviors such as Activities intended for use in CallBehaviorActions, or at least use a 'Capital first letter'; avoid 'all lower case' (as it leads to confusion with lower case Action names)
