From 71aadd3010c4b4732f146f333299fcb7eea79fc6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chlo=C3=A9=20Aben?= Date: Thu, 31 Jul 2025 10:19:57 +0200 Subject: [PATCH 1/2] include text and figure --- src/how-to-guides/ESL/dependency-network.md | 28 ++++++++++++++++++--- src/how-to-guides/assets/all_mdm_2.svg | 1 + 2 files changed, 25 insertions(+), 4 deletions(-) create mode 100644 src/how-to-guides/assets/all_mdm_2.svg diff --git a/src/how-to-guides/ESL/dependency-network.md b/src/how-to-guides/ESL/dependency-network.md index 74c3668..7d4e08c 100644 --- a/src/how-to-guides/ESL/dependency-network.md +++ b/src/how-to-guides/ESL/dependency-network.md @@ -10,8 +10,28 @@ many system architecture models. Feel free to check out the [Dependency derivations](../../reference/2_dependency-derivations.md) section of for the mathematical basis of the derived dependency graph. -!!! warning +!!! note + Check the [Dependency Structure Matrices](../../explanation/01-engineering-design.md#dependency-structure-matrices) section or visit [https://dsmweb.org/](https://dsmweb.org/) for more information on how to interpret dependency structure matrix models. + +!!! note + Many conventional requirement management and system architecting tools require a user to manually identify, create, define, and maintain dependencies between elements of a system specification or system architecture model. With the use of ESL this is fully automated! + +Figure 1 shows all dependencies that are derived from the final pump specification at the second decomposition. The rows are labelled with components, function-specifications, behavior-specifications, design-specifications, variables, needs, and relations specifications. + +
+ ![Full dependency network](../assets/all_mdm_2.svg) +
+Figure 1: Full dependency network derived from the pump example specification at the second decomposition level +
+
- This content is not fully migrated, yet. Please hop over to this page on - [docs.ratio-case.nl](https://docs.ratio-case.nl/manuals/esl_manual/index.html#generated-dependency-graphs) - for the source content. +The tree structure at the top left of the figure denotes the system decomposition structure as specified. Here we find the components `pump`, `power-source`, `motor`, and `power-switch` to be the leaf components of the specified decomposition tree. + +The pie-charts within the matrix denote the derived dependencies between elements of the specification. The colors of the wedges denote the different labels that are attached to each dependency. The labels are based on the variable types that are used within the specification. + +The pie-charts within the matrix denote the derived dependencies between elements of the specification. The colors of the wedges denote the different labels that are attached to each dependency. The labels are based on the variable types that are used within the specification. + +Note that the compiler derives multiple dependency kinds, being functional, logical, design, coordination, traceability and mapping dependencies. Figure 1 shows all these dependency kinds between all ESL elements which makes it difficult to interpret (Especially if one would specify a real system). Hence in the next sections we will create several views on the system. + +!!! note + In the user manual we use multi-domain-matrices to visualize the resulting dependency structures. \ No newline at end of file diff --git a/src/how-to-guides/assets/all_mdm_2.svg b/src/how-to-guides/assets/all_mdm_2.svg new file mode 100644 index 0000000..82c2427 --- /dev/null +++ b/src/how-to-guides/assets/all_mdm_2.svg @@ -0,0 +1 @@ +pumppower-sourcemotorpower-Switchconvert-torqueconvert-potentialconvert-powerprovide-powersend-control-signalprovide-torquetoggle-powermin-water-flowdc-drive-lengthtorquewater-flowdrive-lengthpump-lengthpower-potentialpowermotor-control-signalefficiency-modelcontrol-signalelectrical-energy-flowenergy-potentialliquid-material-flowmechanical-energy-flowspatial-measure \ No newline at end of file -- GitLab From 07007d9b466127a1f8760101996ab1c53106bb0a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chlo=C3=A9=20Aben?= Date: Thu, 31 Jul 2025 11:14:01 +0200 Subject: [PATCH 2/2] include esl file used for graph generation --- mkdocs.yml | 1 + src/how-to-guides/ESL/dependency-network.md | 9 ++ .../specs/water-pump-specification.esl | 142 ++++++++++++++++++ 3 files changed, 152 insertions(+) create mode 100644 src/how-to-guides/specs/water-pump-specification.esl diff --git a/mkdocs.yml b/mkdocs.yml index c70af80..095097d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -50,6 +50,7 @@ markdown_extensions: - "src/governance/json" - "src/governance/mermaid" - "src/governance/syntax" + - "src/how-to-guides/specs" check_paths: true - pymdownx.superfences: custom_fences: diff --git a/src/how-to-guides/ESL/dependency-network.md b/src/how-to-guides/ESL/dependency-network.md index 7d4e08c..eaeae02 100644 --- a/src/how-to-guides/ESL/dependency-network.md +++ b/src/how-to-guides/ESL/dependency-network.md @@ -16,6 +16,15 @@ many system architecture models. !!! note Many conventional requirement management and system architecting tools require a user to manually identify, create, define, and maintain dependencies between elements of a system specification or system architecture model. With the use of ESL this is fully automated! +We will use the following specification as an example for the dependency graph generation: + +=== "File" + + ```elephant title="water-pump-specification.esl" + ---8<--- "../specs/water-pump-specification.esl" + ``` + + Figure 1 shows all dependencies that are derived from the final pump specification at the second decomposition. The rows are labelled with components, function-specifications, behavior-specifications, design-specifications, variables, needs, and relations specifications.
diff --git a/src/how-to-guides/specs/water-pump-specification.esl b/src/how-to-guides/specs/water-pump-specification.esl new file mode 100644 index 0000000..02469ba --- /dev/null +++ b/src/how-to-guides/specs/water-pump-specification.esl @@ -0,0 +1,142 @@ +# Specification of a drive-mechanism driving a pump. +define type + mechanical-energy-flow is a real with unit Nm + electrical-energy-flow is a real with unit W + liquid-material-flow is a real with unit L/s + energy-potential is a real with unit Wh + control-signal is a boolean + distance is a real with unit m + spatial-measure is a distance of at least 0.0 [m] + efficiency is a real of at least 0.0 and at most 1.0 + + +define verb + provide to + convert into + send to + + +define relation + battery-efficiency-model + relating parameters + * potential is an energy-potential + * output is an electrical-energy-flow + + +world + variables + torque is a mechanical-energy-flow #< Comments on variable torque. + water-flow is a liquid-material-flow + drive-length is a spatial-measure + pump-length is a spatial-measure + + components + pump is a CentrifugalPump with arguments + * torque + * water-flow + * pump-length + + drive-mechanism is an ElectricalDriveMechanism with arguments + * torque + * drive-length + + comments + pump #< Can be sourced by manufacturer XYZ. + #< Part number CFG.PMP.0.1 + + goal-requirements + provide-torque: drive-mechanism must provide torque to pump + + design-requirements + min-water-flow: water-flow must be at least 1.0 [L/s] + + design-constraints + dc-drive-length: drive-length must be equal to pump-length + + need + IP68: drive-mechanism must be IP68 compliant + + +define component CentrifugalPump + parameters + torque is a mechanical-energy-flow + water-flow is a liquid-material-flow + length is a spatial-measure property + + transformation-requirements + convert-torque: must convert torque into water-flow + + +define component ElectricalDriveMechanism + parameters + torque is a mechanical-energy-flow + length is a spatial-measure property + + variables + power-potential is an energy-potential + power is an electrical-energy-flow + motor-control-signal is a control-signal + + transformation-requirements + convert-power-potential: must convert power-potential into torque + + components + power-source is a Battery with arguments + * power-potential + * power + + motor is a BrushlessMotor with arguments + * power + * torque + + power-Switch is a Switch with arguments + * motor-control-signal + + goal-requirements + provide-power: power-source must provide power to motor + send-control-signal: power-Switch must send motor-control-signal to power-source + + behavior-requirements + toggle-power: + case on: + when + * c1: motor-control-signal is equal to True [-] + then + * r1: power must be at least 300 [W] + case off: + when no other case applies + then + * r2: power must be equal to 0 [W] + + +define component BrushlessMotor + parameters + power is an electrical-energy-flow + torque is a mechanical-energy-flow + + variables + conversion is an efficiency + + transformation-requirements + convert-power: must convert power into torque with subclauses + * s1: conversion must be at least 0.8 + + +define component Battery + parameters + power-potential is an energy-potential + power is an electrical-energy-flow + + transformation-constraints + convert-potential: does convert power-potential into power + + relations + efficiency-model: battery-efficiency-model + relating arguments + * power-potential + * power + + +define component Switch + parameters + motor-control-signal is a control-signal \ No newline at end of file -- GitLab