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: SysML4Mathematica: Activity Diagrams used purely for analysis and as development aids are not required to show every ControlFlow, may omit InitialNode and ActivityFinalNode, and are not required to fully validate in SysML tools or execute.
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.
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.
Webel: SysML4Mathematica: An OptionsPattern[] may be represented by an «M:OptionsPattern» SysMLv1 Block with «M:Opt» properties. An «M:Opt» property represents an Options[] Rule IMPLICITLY (an «M:Opt» does not use the Rule block modelling recipe).
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.
Mathematica: Webel ADT pseudo classes: The SysMLv1 models are supported by custom stereotypes with icons. Some of these indicate OO-similar use of ADT-Methods and departures from formal Abstract Data Type (ADT) definitions.
Webel: Mathematica: CONVENTION: MTools classes: A 'z' prefix indicates a "private" method; A 'my' prefix indicates a "protected" method (typically a protected hook). There is no actual visibility enforcement other than by name convention.
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: 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.
Mathematica: CONVENTION: A prefix 'eq$' indicates a symbolic equation (typically using 'sym$' human-friendly markup "symbols")
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: 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: SysML: SE: A functional analysis «whitebox» Activity may have swimlanes that Allocate to logical subsystems (logical handlers) within the 'problem' zone or to design/implementation level blocks.
Webel: SysML: SE: The custom Stereotype keyword «whitebox» applied to an Activity indicates that it is part of the functional analysis breakdown serving a «whitebox» «scenario» Activity (directly or indirectly) for a UseCase.
Webel: SysML: SE: «blackbox»: The custom Stereotype keyword «scenario» indicates a Behavior (Interaction as Sequence Diagram or Activity) that Refines a top-level UseCase within the 'problem' zone.
The Webel recipe for pragramatic SE with SysML omits many of the concerns addressed by fully-fledged systems engineering frameworks. Many of these can be partially addressed by using custom Stereotypes for extraction using query view tables.
Webel: SysML: SE: The custom stereotype keyword «design» covers elements involved with BOTH design and/or implementation aspects in the 'solution' zone. (In more comprehensive SE methodologies design and implementation are often treated separately.)
Webel: SysML: SE: Stereotype keyword convention: BY DEFINITION HERE «blackbox» and «whitebox» refer specifically to the 'problem' zone and NEVER the 'solution' zone (as opposed to more general uses of the terms 'black-box' and 'white-box').
Webel: SysML: SE: Naming convention: «whitebox»: A '$' prefix indicates a «logical» system, «logical» subsystem (aka conceptual subsystem) or «logical» handler Block (which is a more specific form of «logical» subsystems Block).
Webel: SysML: SE: Naming convention: '0' used for a Package/Model name indicates a zone dedicated to a formal systems engineering breakdown (functional analysis, blackbox, whitebox, logical vs design or implementation etc.)
Webel: SysML: Use concise Package and Model naming to provide "context aware" owner paths that reflect a systems engineering strategy. Extremely so-called "human friendly" verbose Package/Model names with spaces DO NOT make the model easier to understand!
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: Functional analysis (isolation of white-box Activities identified via «blackbox» scenario Activities of UseCases). Recommend custom stereotype them. Candidate: «whitebox» (or a recommended SE methodology stereotype).
SysMLv1: MagicDraw/Cameo: Having a SystemContext as the 'subject' of each main UseCase plays nicely with the feature for automated creation of usage-level allocation swimlanes in SysML Activity Diagrams for part properties. But it's not the only way.
SysMLv1: UseCase scenario representations: On use of Activity Diagrams with swimlanes and/or Sequence Diagrams (Interactions): Actor or block-based custom «actor» on 1st (typically left) Lifeline/Swimlane, System/Subsystem on 2nd Lifeline/Swimlane
Webel: MBSE: SysMLv1: Prefer a custom «actor» extension of a Block (such as the non-normative External) over UML-style Actor for use as parts in IBDs and on allocation swimlanes. You can also have a Trace from a block-based «actor» to a UML-style Actor.
Webel: SysML for MBSE: The frequent recommendation that each UseCase have at least one "primary" scenario is a very useful and highly recommended CONVENTION (only). But it is not actually enforced by the SysML1.7 or UML2.5.1 metamodels or specifications.
Webel: SysML/UML: Dr Darren explains HOWTO use concise 'i'/'o' (input/output) Pin and Parameter naming conventions to promote a signal processing mindset in Activity Diagrams. And HOWTO get them compact.
Mathematica: Webel: A concise i:/o: notation is often used for indicating input/output cells in Mathematica notebooks in Webel's online help pages and tutorials, instead of 'In[n]:=' and 'Out[n]='. (Also learn how to hide them completely in notebooks.)
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: NAMING CONVENTION: 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: 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[]).
Webel: Psy/MPsy: Psychrometrics for Mathematica: '$HC' in a function name indicates pure sensible heating or cooling (with no change in water vapour content). Such functions may also be used in the pure sensible portion of a 2-step treatment.
Webel: Mathematica: CONVENTION: A prefix '$doc' indicates a documentation String for each primary variable/quantity (argument or output)
Webel: Mathematica: 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 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: Variable/quantity registry and naming conventions, with symbol markup.
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.
Webel: Psy/MPsy: Psychrometrics for Mathematica: A suffix '$g' in a water-related variable name refers to water vapour (a special case of gas) or steam. A suffix '$f' refers to liquid (fluid) water. [Although a gas is a fluid.]
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: 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 '{}'. (Extending types may adapt the notation.)
Webel: Psy/MPsy: Psychrometrics for Mathematica: The CoolProp "wrappers" of the Psy library in fact wrap lower-level wrappers (bindings) for CoolProp for Mathematica
SysML/UML: MagicDraw/Cameo: GOTCHA: Connecting a typed OutputPin to an untyped (UNSPECIFIED) InputPin with an ObjectFlow changes the type of the InputPin
Webel: SysML4Mathematica: Convention: A '$E' in a function name indicates that all parameters (arguments and return) are Mathematica '_' expressions. However, when representing such functions as Activities they may end up getting strongly typed in tools!
Webel: SysML4Mathematica: When modelling the main logic flow of Mathematica code with Activity Diagrams it isn't necessary to model every Mathematica construct. Placeholder Actions, OpaqueActions , and OpaqueBehaviors (as CallBehaviorActions) may be used.
Webel: SysML4Mathematica: An '@' prefix in the name of a Block indicates a data structure (such as an Association or List) that does not have a corresponding MTools class or a Webel Abstract Data Type (ADT) "pseudo class" in the Wolfram Language code.
Webel: SysML4Mathematica: An '@' prefix in the name of a ConstraintBlock, Activity, or OpaqueBehavior indicates that it is a "@pseudo" function not represented directly in the Wolfram Language or Webel code libraries (typically for minor maths or logic)
Webel: Psy/MPsy: Psychrometrics for Mathematica: Most CoolProp wrappers can be invoked with the dry bulb temperature 'tdb', the pressure 'p', and one (only) of the relative humidity 'r', the humidity ratio 'w', or the wet bulb temperature 'twb'
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' as a quantity symbol in equations 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: SysML: TIP: CONVENTION (default policy suggestion): Use reverse time ordering for Dependency, reserve Usage, PackageImport, ElementImport for software dependencies
Mathematica: TIP: Protecting against computations breaking verbosely because of Null, None, Undefined. And about using Undefined as a return policy.
Mathematica: The Webel Units` package has Quantity variables for frequently used units using a naming convention 'unit$[Symbol]' or 'unit[DescriptiveName]' or unit[Acronym], each with a corresponding '$unit...' for the units identifier String(s).
Webel Parsing Analysis: It does not matter whether you use a Package or a Model package. (The informal Webel convention is that Models are used for systems engineering analysis with SysML and Packages are reserved for code-related software engineering.)
Naming: If SISO is 'Single Input Single Output' then 'Double Input Single Output (DISO)' is more consistent than 'Two Input Single Output (TISO)', otherwise you'd have to have a 'One Input Single Input (OISO)' for consistency. But who ever says OISO?
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: 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").
SysML/SysPhS-1.1: Anonymous Property or Action names may not be an option if: You are exporting to Modelica or Simulink; You absolutely need names for generated query reports (such as generated Interface Control Documents).
Block naming: If you find you've got similar blocks named 'Thing' and 'Thing2' then 'Thing' is probably better renamed 'Thing1'
Modelica: Naming convention: Why does the OnePort family of electrical components have 2 Pins? Where is the "one port"?
Webel Twin Pattern: Convention: [MIGHT CHANGE]: A '*' prefix in a Property name of a «digital» @Block in a DigitalTwin model indicates a mapped block property, which must be typed by a non-digital «mappable» Block, and must have the «@» keyword applied.
Webel: Convention: [MIGHT CHANGE]: An '@' prefix in a DigitalTwin model indicates a «digital» Block that maps a non-digital «mappable» Block.
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.
If using "French style" post-adjective naming in English use a trailing underscore after the noun and before the adjective or qualifier: Vin_rouge, Cable_digital. Can be combined with TLA acronyms: Player_DVD.
Webel Parsing Analysis: typically the quoted extract text (body) of a «snippet» is a short phrase, a sentence, or a couple of short sentences (but not dozens of sentences).
Webel use editorial Sterotypes prefixed with ! and ? in and in CAPS in keywords such as: «!». «?», «!ERROR», «!ISSUE», «!CAUTION», «!WARNING», «!CAVEAT», etc.
MagicDraw/Cameo: The default 'Implied Satisfy' relation will claim a Requirement is satisfied by any direct composite aggregation parent Block or composite aggregation ancestor Block of a part property
The name of a «testCase» Behavior may be verbose and may use natural language, but should always start with a Capital letter.
Webel: If you must name your Ports or Pins, name them simply 'i', 'o', or 'io' (or 'oi') to indicate direction UNLESS you have to indicate a special role like 'iRole', 'oAuxiliary'. DO NOT use Port or Pin names like 'input', 'output', etc.
In most Webel examples, the default is chosen to be 'out' if there is a single FlowProperty, so a Port with the type applied will act as a source. If an InterfaceBlock is used, then a Port typed by the conjugating ~InterfaceBlock will act as a sink.
Webel: SysMLv1.x: AVOID (where possible) ValueType names that are the same as the name of units or unit symbols
Avoid punctuation in Property names (except when used to "quote text"). You can usually avoid underscores in Property names (even if they are used in the Type name) if you can "Trust the Type"!
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!
FlowProperty naming. Use anonymous or just 'i' for in, 'o' for out, and 'io' (or 'oi') for inout. "Trust the Type". For conjugation ~InterfaceBlock use 'o' for in, 'i' for out, and 'io' (or 'oi') for inout.
Webel: SysMLv1: Highly recommend creating a "focus" Block Definition Diagram (BDD) for each main Block with expanded feature details and relationships to at least nearest neighbours
