diff --git a/.github/workflows/build-guides.yml b/.github/workflows/build-guides.yml index c8a0250..db638b8 100644 --- a/.github/workflows/build-guides.yml +++ b/.github/workflows/build-guides.yml @@ -2,42 +2,84 @@ name: Build Guides on: push: - branches-ignore: [ 'temp/*' ] + branches-ignore: + - 'temp/*' + tags: + - '*' pull_request: - branches: [ main ] + branches: + - 'main' + +concurrency: + group: "pages" + cancel-in-progress: false jobs: - build-guides: - name: Build SSP Traceability Guides + + generate-html: + runs-on: ubuntu-24.04 + steps: - runs-on: ubuntu-22.04 + - name: Checkout + uses: actions/checkout@v6 + with: + submodules: recursive - steps: - - name: checkout - uses: actions/checkout@v4 - - name: prepare - run: mkdir build && mkdir build/workflow-guide - - name: build workflow guide + - name: Generate revnumber + run: | + [[ $GITHUB_REF_TYPE == "tag" ]] && REVNUMBER=${GITHUB_REF:11} || REVNUMBER=${GITHUB_SHA:0:7} + echo GITHUB_SHA: $GITHUB_SHA + echo GITHUB_REF_TYPE: $GITHUB_REF_TYPE + echo GITHUB_REF: $GITHUB_REF + echo REVNUMBER: $REVNUMBER + echo "REVNUMBER=$REVNUMBER" >> $GITHUB_ENV + + - name: Create build directory + run: | + mkdir -p build/workflow-guide/images + + - name: Generate HTML uses: avattathil/asciidoctor-action@master with: - program: "asciidoctor -D build/workflow-guide --backend=html5 --attribute=revnumber=${GITHUB_REF#refs/heads/}-$GITHUB_SHA --attribute=revdate=$(date +%F) workflow-guide/index.adoc" - - name: copy images - run: tar cf - workflow-guide/images | tar xfC - build - - name: archive workflow guide - uses: actions/upload-artifact@v4 + program: "asciidoctor --base-dir workflow-guide --destination-dir=../build/workflow-guide --backend=html5 --attribute=revnumber=${{ env.REVNUMBER }} --attribute=revdate=$(date +%F) workflow-guide/index.adoc" + + - name: Copy resources + run: | + cp workflow-guide/images/* build/workflow-guide/images + + - name: Create ZIP archive + uses: actions/upload-artifact@v6 with: name: Workflow-Guide path: build/workflow-guide/* if-no-files-found: error - - name: extract branch name + + - name: Extract branch name id: extract_branch shell: bash - run: echo "##[set-output name=branch;]$(echo ${GITHUB_REF#refs/heads/})" - - name: deploy + run: echo "branch=$(echo ${GITHUB_REF#refs/heads/})" >> $GITHUB_OUTPUT + + - name: Move to published directory if: github.ref == 'refs/heads/main' && github.event_name == 'push' - uses: peaceiris/actions-gh-pages@v3.7.0-8 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: build - destination_dir: ${{ steps.extract_branch.outputs.branch }} - enable_jekyll: true + shell: bash + run: mkdir _site && mv build _site/${{ steps.extract_branch.outputs.branch }} + + - name: Upload Pages artifact + if: github.ref == 'refs/heads/main' && github.event_name == 'push' + uses: actions/upload-pages-artifact@v4 + + publish-html: + needs: generate-html + if: github.ref == 'refs/heads/main' && github.event_name == 'push' + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-24.04 + steps: + + - name: Deploy to Github Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/workflow-guide/0___preamble.adoc b/workflow-guide/0___preamble.adoc index 5227164..40a091a 100644 --- a/workflow-guide/0___preamble.adoc +++ b/workflow-guide/0___preamble.adoc @@ -1,4 +1,4 @@ -The SSP Traceability Workflow Guide is a supplementary documentation to the SSP Traceability Specification 1.0. While the SSP Traceability Specification 1.0 essentially describes a data format for STMD files in the sense of a normative document, the SSP Traceability Workflow Guide addresses how and in which way Glue Paerticles are used in industrial practice. It thus addresses topics and answers questions that the SSP Traceability Specification 1.0 as a normative document cannot address and answer. +The SSP Traceability Workflow Guide is a supplementary documentation to the SSP Traceability Specification 1.0. While the SSP Traceability Specification 1.0 essentially describes a data format for STMD files in the sense of a normative document, the SSP Traceability Workflow Guide addresses how and in which way the SSP Traceability can be used in industrial practice. It thus addresses topics and answers questions that the SSP Traceability Specification 1.0 as a normative document cannot address and answer. This is a development version of the SSP Traceability Workflow Guide. https://github.com/PMSFIT/SSPTraceabilityGuides/releases[Releases] and https://github.com/PMSFIT/SSPTraceabilityGuides/issues[issues] can be found on https://github.com/PMSFIT/SSPTraceabilityGuides[github.com/PMSFIT/SSPTraceabilityGuides]. diff --git a/workflow-guide/1___introduction.adoc b/workflow-guide/1___introduction.adoc index 67515c2..fb179db 100644 --- a/workflow-guide/1___introduction.adoc +++ b/workflow-guide/1___introduction.adoc @@ -1,79 +1,8 @@ == Introduction -Based on typical scenarios in the simulation of complex systems, the SSP Traceability Workflow Guide intends to show how simulation processes and model creation processes may be documented using the Glue Particle approach. A Glue Particle is an XML file in which all simulation or model creation relevant resources and information are described or linked. The goals of the glue particle approach are: +=== Purpose and structure of the user guide -* Traceable documentation of simulation and modeling processes for retrospective analyses - -* Replacement of order-relevant information and resources for simulation and modeling processes in cross-company collaboration - -* Transfer of simulation or modeling process relevant information and resources within the company between departments or IT tools - -* Reuse of simulation-relevant resources and informtion (e.g., models, parameters, tools, etc.) for simulation repetition - -* Reuse resources such as simulation models or parameters for similar simulations. - -#Align these gpals with the scenarios in chapter <># - - - - - -The SSP Traceability Workflow Guide intends to provide support on how to handle Glue Particles with the focus on workflows and processes in industrial practice. In industrial practice topics come into focus that go beyond the scope of a data format specification, including the topics in the following list. - -- Consistency and quality assurance - -- Glue Particle data management - -- Dealing with complex multi Glue Particle constellations - -- Retrospective interpretation of Glue Particles - -- Reuse of Glue Particles - -- Exchange of Glue Particles between IT tools and systems - -- Cross-company exchange of Glue Particles - -- and many more - -This is where the SSP Traceability Workfkow Guide comes in. The Workflow Guide addresses these issues and provides recommendations for handling Glue Particles in industrial practice. - -=== Definition of esential term - -In the context of the development of the SSP Traceability Standrd, the terms scenarios, workflow, process and use case are frequently used. These terms will be explained and distinguished from each other but also positioned in relation to each other. - -*Scenario* - -A scenario describes the situation from a business perspective in which Glue Particles may be used and offer or generate significant added value. The description of a scenario includes the naming of the organization or roles involved as well as the business goals of the organization or roles involved. - -The term scenario in this context should not be confused with the term scenario as used in the context of automated and autonomous driving. In automated and autonomous driving, a scenario refers to a complex traffic situation with a number of moving and non-moving objects in the road space and a complex constellation of many boundary conditions in which an automated or autonomous vehicle is to move. - -*Workflow* - -The workflow describes how Glue Particle will be used in each scenario and how they may provide and generate the expected added value. The process flow of each scenario is described by at least one, or if necessary, by several alternative or complementary workflows. Essentially, process diagrams and additional textual descriptions are used. Here, the focus is on the process-related handling of the Glue Particle - -*Use case* - -A use case describes how the Glue Particle is handled in very specific, narrowly defined situations, or how it is interacted with manually or technically. The main question here is who does what with the Glue Particle and when, and what the respective result of the interaction is. The focus here is on the operational handling of the glue particle. - -*Process* - -The term process may be used on different levels and means that interrelated activities, interactions and communications have a certain causal and temporal sequence. In addition, the term may also be part of fixed and thus predetermined terms, such as commissioning process, requirements process or export process. The term process may therefore appear in this documentation in the context of scenarios as well as in the context of workflows and use cases. - - - -=== Conventions used in this document - -* The version number of this documentation is to be interpreted according to the _Semantic Versioning Specification (SemVer) 2.0.0_ <>. - -* The key words *MUST*, *MUST NOT*, *REQUIRED*, *SHALL*, *SHALL NOT*, *SHOULD*, *SHOULD NOT*, *RECOMMENDED*, *NOT RECOMMENDED*, *MAY*, and *OPTIONAL* in this document are to be interpreted as described in _RFC 2119_ <>. - -=== Document structure - -#Hier zum Schluss noch die Dokumentstruktur einführen# - -## -* Glue Particle Approach -* Szenarien und Workflows -* Use Cases für GP Handlig -## \ No newline at end of file +The user guide is intended to provide information and examples of how the SSP Layered Standard Traceability can be applied. +It is important to note that the Layered Standard SSP Traceability is in XML format, which is clearly structured and readable, but should be created and modified using appropriate tool support. +This is comparable to the use of FMUs or SSP. +Further introductory information is described in chapters 1-3 of the SSP LS Traceability <>. diff --git a/workflow-guide/2___glue_particle_approach.adoc b/workflow-guide/2___glue_particle_approach.adoc deleted file mode 100644 index 5043eef..0000000 --- a/workflow-guide/2___glue_particle_approach.adoc +++ /dev/null @@ -1,177 +0,0 @@ -[#sec-glueparticleapproach] -== The Glue Particle approach - -The essential core of the Glue Particle approach is the in-process, machine-readable documentation of information about a credible simulation or modeling task in a standardized format. - -=== Credibble simulation/modeling process - -Both a credible simulation process and a credible modeling process are very similar and both - -- have a fixed start in terms of time - -- usually start with defined and communicated goals - -- are completed at a certain point in time - -- are completed upon achievement of the defined goals - -- can be structurally divided into execution phases and execution steps. - -=== Glue Particle - -The task of the Glue Particle is to bundle all relevant information about a credible simulation/modeling process in a standardized format in XML files. This includes, among other things, the inclusion of information about resources used. The inclusion of resources in the Glue Particle may be done in three different ways. - -- Resource information may be written directly into the XML file. This procedure is suitable for single or very few atomic information. - -- The far more elegant way is to outsource the information into own files and to refer to this outsourced information from the Glue Particle file. This is more suitable for a bigger amount of information. - -- A third option is to link the Glue Particle file to relevant resources stored in IT systems. - -<> illustrates these three ways to include resources. - -[#im-threeKindOfResourceInclusion] -.Three ways to include resource information into a Glue Particle -image::ThreeKindOfResourceInclusion.png[500, 500] - -<<#sec-EmbeddingAndReferencingResources>> goes into more detail about these three options. - -A credible simulation/modeling process typically goes through the following execution phases, starting with the analysis of the actual objective of the simulation or modeling task and ending with the decision whether this objective has been met. - -- Analysis phase - -- Requirements phase - -- Design phase - -- Implementation phase - -- Execution phase - -- Evaluation phase - -- Fulfillment phase - -Therefore, the Glue Particle, which is supposed to document the information about these execution phases, contains seven correspondingly named segments to structure this phase-specific information. In addition, there is a segment with general information about the respective Glue Particle file. - -Each execution phase of a credible simulation/modeling process may include one or more execution steps. For example, in the requirements phase, - -- Requirements for models, - -- Requirements on parameters, - -- Requirements to the simulation environment - -- Requirements for simulation integration - -- Requirements for test cases, - -- requirements for quality assurance - -may be specified. In addition, a final review of all results of an execution phase and their formal confirmation may be useful. For example, at the end of the requirements phase, there may be a verification of all requirements and their compatibility, as well as the confirmation and release of all requirements. Therefore, in each phase segment there is a final sub-segment that contains information about this verification step. - -Therefore, in a Glue Particle File, each phase segment has one or more step segments for the individual execution steps of an execution phase. Each of these step segments again has the same uniform structure. A segment for a step in a phase is structured according to input, procedure, output, rational and life cycle information. <> shows the basic structure of a Glue Particle using a section of the STMD XML schema as an example. - -[#im-GlueParticleStructureSchema] -.Basic structure of a Glue Particle -image::GlueParticleStructureSchema.png[1000, 1000] - -It is important to understand what a Glue Particle is and what it is *NOT*, or what it may and *may not* be used for. - -What is a "Glue Particle"? - -- A Glue Particle is a bundle or compilation of relevant information for a credible simulation/modeling process. - -- A Glue Particle is a file used to exchange information between IT tools and systems (data management systems, authoring systems, etc.). - -- A Glue Particle is a file used to exchange information between organizations (departments, companies, etc.). - -What is a Glue Particle *NOT?* - - -- A Glue Particle is *NOT* a data format used to organize information in IT systems. - -- A Glue Particle is *NOT* a process format for controlling technical or organizational processes. - - -=== Integration of Glue Particles into the work processes - -The Glue Particles may be used both for company-internal documentation to ensure traceability and to support the reusability of information and artifacts as well as for the exchange of information and artifacts across company boundaries. It would be conceivable, for example, - -- for a company-internal department to commission another department within a company for a system simulation - -- or to commision an external service provider to create simulation models in order to carry out a simulation task, - -- or to outsource the execution of the actual simulation to an external computing center. - -In all these cases, the Glue Particles serve both - -- to provide or exchange information and artifacts needed to perform the commissioned task or -- to provide and exchange the documentation on the execution of the task and the documentation of the results. - -As an example for a commision, a simulation task may be defined in the context of a component or system development and handed over to a simulation engineer or to a simulation department. As another example, a modelling task may be generated from a simulation task, or to be more specific, from the implementation phase of the simulation task and handed over to a modeling expert. <> shows schematically how a modeling task is generated from a simulation task and <> illustrates the role of the Glue Particles in this scenario. -[#im-modelingRequest] -.A modeling request is handed over to an external partner -image::ModelingRequest.png[800, 800] - -[#im-DataView] -.Role of the Glue Particle in simulation and modeling process couplings -image::DataView.png[800, 800] - -<> shows schematically how a complete phase or even more that one phase of the credible simulation task is handed over to an external partner. - -[#im-processHandover] -.A complete phase of the credible simulation process is handed over to an external partner -image::ProcessHandover.png[800, 800] - -=== Role of Glue Particle in terms of traceabitity - -One of the core goals of the Glue Particle approach is the traceability of simulation and modeling processes. This means that it should be retrospectively traceable what was simulated, how it was simulated, which models and which parameters were used for the simulation, which IT tools were used for the simulation and last but not least, which methods were used for the simulation, which assumptions were made and with which rationale these assumptions were made. - -All this information is to be bundled in the Glue Particle and with the help of the Glue Particle. The entire simulation or modeling process is covered and the Glue Particle is stored permanently so that it may be consulted at a later point in time if required. The Glue Particle, i.e. the STMD file, is thus the central information carrier for traceability. - -=== Role of Glue Particle in terms of credibility - -In product and system development projects, numerous design decisions are made based on simulation results. If you want to make design decisions with certainty, you may have to trust simulation results. This trust is strongly linked to the credibility of the simulation results and to the credibility of the entire simulation process. A complete high-quality and traceable documentation of the simulation process may significantly and decisively improve the credibility and trust in the simulation process and in the simulation results and thus may ease design decisions. - -=== Role of Glue Particle in terms of reusability - -In system and product development processes it may be necessary to repeat a simulation. This may be an exact repetition or a repetition with slightly modified boundary conditions. In this case, it is not only important to know what was simulated and how (traceability), but it is also extremely helpful if the resources used can be accessed directly. Here, too, a Glue Particle may play an important role, as it supports the reusability of resources. - -=== Integration of the Glue Particle approach into the SSP standard - -The SSP Traceability Specification is a so-called layered standard in the sense of the https://ssp-standard.org/[Systems Structure and Parameterization (SSP)] standard of the https://www.modelica.org/[Modelica Association]. In particular, the Glue Particle approach uses the System Structure Package format of SSP. A System Structure Package is a zip archive containing a so-called System Structure Description file (SSD file) and all resources like models and parameter files needed to describe a system structure. - -Glue Particles are also packed according to this principle. A Glue Particle for a credibble simulation/modeling process is a zip archive containing at least one SSD file (according to the requirements of the SSP standard) and at least one STMD file. The STMD file represents the actual Glue Particle. If local resources are referenced by the STMD file, they must also be included in the Glue Particle zip archive. When sharing Glue Particles across companies, all external references usually point to files within the zip archive. - -<> shows a typical System Structure Package as specified in the SSP standard specification. The SSD file is mandatory. All othre data files are optional according to the business needs. The meaning of the file extensions are - -* The system structure description (SSD) is a mandatory part of every system structure package that is used to describe -hierarchical and functional structures of a whole FMU network. -* A system structure parameter values (SSV) element is used to describe parameters and external parameter sets that -can be applied to an FMU, thus parameterizing it. -* A system structure parameter mapping (SSM) is used to describe parameter mappings that may be required to -parameterize FMUs. -* A system structure signal dictionary (SSB) is used to describe signals. - -All files are encoded in XML. - -[#im-SspSystemStructurePackage] -.System Structure Package as specified in the SSP standard -image::SpsSystemStructurePackage.png.png[800, 800] - -In order to use the Suytem Structure Package as a standardized container mechanism for carrying Glue Particles along with local file ressources the SSD file must be included in the System Struncture Package archive to remain compatible with the SSP standard. This may be a business compatible SSD file that represents the system being simulated or may also be a "dummy" SSD file that is practically empty with no business related content. The meaning of the file extensions are - -* The STMD file is the core file of the Glue Particle. - -* The SRMD file is a file that describes simulation resources. - -* The SMMD file comprises simulation model medadata, the business related metadata for the Functional Mock-up Unit (FMU). - -All files are encoded in XML. - -im-SspSystemStructurePackageForGlueParticle illustrates an System STructure Package applied for carrying a Glue Particle. - -[#im-SspSystemStructurePackageForGlueParticle] -.System Structure Package applied for carrying Glue Particles -image::SpsSystemStructurePackageForGlueParticle.png[800, 800] - diff --git a/workflow-guide/2___objectives.adoc b/workflow-guide/2___objectives.adoc new file mode 100644 index 0000000..0a82937 --- /dev/null +++ b/workflow-guide/2___objectives.adoc @@ -0,0 +1,64 @@ +== Objectives, Structure, and Application of SSP Traceability + +Objectives: + +* Structuring of information +* Traceability of simulations and their results +* Reuse of simulations +* Use, exchange in heterogeneous simulation and IT infrastructures +* Cooperation with partners + +In the following it is described how the SSP Traceability STMD Schema supports the Credible Simulation Process <>. + +NOTE: More information on the relationship between SSP LS Traceability and the Credible Simulation Process Framework can be found in https://modelica.github.io/ssp-ls-traceability/main/#sec-crediblesimulationprocessframework[section 2] of the SSP LS Traceability. + +The typical procedure in a development or simulation process is shown in <>. +Many recursions take place in such a process. +The Credible Simulation Process (CSP) therefore does not represent the chronological sequence but the logical order of the sequence. +This is required for traceability. + +IMPORTANT: The CSP is therefore a documentation schema and not a chronological process description. + +[#im-csp-recursions] +.The Credible Simulation Process and the STMD Format supports the logical order +image::CSP-recursions.png[] + +<> illustrates how the information, the CSP, and the corresponding SSP traceability data format “Simulation Task Meta Data” (STMD) interact with one another. + +The STMD format is part of the information. +The data is linked to the STMD XML schema file according to its type. + +This STMD XML file with the links can then be saved or exchanged and forms the building block for traceability. + +SSP LS Traceability requires that the import and export tools as well as the data management systems support this standard and this structure. +However, no specifications are provided regarding how the data management tool must internally structure the data. + +[#im-csp-workflow] +.Linkage between information, Credible Simulation Process and STMD +image::CSP-workflow.png[CSP-workflow, 1000, 1000] + +The following three layers should be distinguished in implementation and application (<>): + +* Process +** Structuring of information according to logical context +* Data +** Data and version management +* Workflow +** Interfaces corresponding to the application + +[#im-csp-3layer] +.Use of a 3-layer approach for implementation +image::CSP-3Layer.png[] + +The SSP LS Traceability focuses on supporting the process level. +Clear logical structuring as the basis for traceability. +The data is linked to the SSP Traceability Schema. +Links to any data management system can be used. +For exchange with partners who do not have direct access to these systems, this data can be packaged and sent as part of an SSP container. +The specifications of this structure are part of the SSP LS Traceability specification. + +Users should only enter their information via a workflow interface and use the Credible Simulation Process indirectly. +At the workflow interface, the information should be provided in the form and order that corresponds to typical use. +Here, a mapping of names that are intuitively understandable for the user in the input masks to the IT systems' unique naming conventions should also take place. +These naming conventions are usually not directly intuitive or cumbersome for the user to understand. +The user guide focuses on the application and use of the STMD schema that support the process level. diff --git a/workflow-guide/3___application_csp.adoc b/workflow-guide/3___application_csp.adoc new file mode 100644 index 0000000..7468dac --- /dev/null +++ b/workflow-guide/3___application_csp.adoc @@ -0,0 +1,194 @@ +== Structure and Application of the Credible Simulation Process + +A detailed description of the Credible Simulation Process Framework is available as <>. +< shows a more detailed structure of the Credible Simulation Process. +Each phase is further divided into sub-elements called process steps. +These steps have a uniform structure, as is also known from process descriptions: + +* Inputs +* Procedure +* Rationale +* Outputs + +The STMD schema maps this structure. +In the application, the existing information of a simulation task can now be linked accordingly. + +[#im-csp-details] +.Detailed structure of the Credible Simulation Process +image::CSP-details.png[] + +=== Allocation and Linking of Information + +The SSP structure has been supplemented with a directory `extra` for layered standard extensions. +Each layered standard has its own specific folder, e.g., for the simulation task `org.ssp-standard.ssp-traceability.stmd`. +The necessary information and files specific to the SSP layered standard are then stored in this folder. +<> shows the structure for the example explained below. +For ease of understanding, the files are numbered according to their logical order. +The last file shown here is the simulation task meta data file (.stmd), which contains the structure and links of the information. + +[#im-ssp-trace-structure] +.SSP LS Traceability file structure +image::SSP-Trace-structure.png[] + +==== Linking Information in the STMD File + +<> shows how and where information is linked in the STMD schema. +The STMD XML schema maps a simulation process. +Information and files can now be linked to the appropriate locations within it according to their content. + +[#im-stmd-links] +.Linking information to the STMD file +image::STMD-Links.png[] + +==== Information from Simulation Request + +A simulation request typically contains administrative information and information describing the simulation task. +The administrative information is necessary for linking to the commissioning processes, development, (name of the product, product development, simulation task, commissioning agency, etc.). +When describing the simulation task, information is required about what is to be examined and simulated, the name of the item to be simulated, and the objectives of the simulation. +This information from the simulation request can be provided as a single file or separated into administrative and content-related information. +The administrative information is linked under administrative information. +The information describing the simulation task is linked under Input in the Analysis Phase. +Any number of sources can be linked here, e.g., a Markdown description and a supplementary PDF. +If the information is only available in a single file, this file can be linked to several places. + +==== Linking to Phases, Steps, Inputs, Outputs + +The location of the links to the information should allow assignment to specific phases. +For larger simulation tasks, a distinction is made within the phases as to whether this information is specific to the models, parameterization, etc. +These steps have a uniform structure, as is also known from process descriptions: + +* Inputs +* Procedure +* Outputs +* Rationale + +If complete traceability of all details is required, the following should be linked under + +* Inputs: +** all information necessary for processing +* Procedure: +** all information used for processing +* Outputs: +** the results that were achieved +* Rationale: +** information on why it was done this way is important for quality assurance + +In the example, this is done for the Analysis step. +The results under Output are then linked as input to the subsequent phase, Steps (see markings in <>). + +In practice, for example, in the design specification phase, there is often only one common source of information for models, parameters, test cases, and simulation environment (tooling), where the interaction is also described. +In such cases, this information should be linked in the simulation integration step. + +If complete traceability of all details is not required, however, at least the information in the outputs of all phases should be available. +This also enables traceability, with the restriction that it is not possible to directly trace which information was used to achieve the output. + +=== Metadata + +Metadata serves to provide keywords. +In the SSP LS Traceability Layered Standard, the classification element was introduced for this purpose. +Metadata (classifications) can also be combined into a separate Simulation Resource Meta Data (SRMD) file. + +==== Usage of Metadata + +* Metadata can be created and used directly as classifications +* Created and linked as an SRMD file +* Attached to linked sources as classifications (metadata), see <>, red frame +* Metadata as an SRMD file in FMUs + +==== Metadata using Example General (Administrative) Information + +The following example shows that there are several options for placing administrative information in the STMD file, +see Phase Admin + +* As classifications (see line 7 onwards in <>) +* As an srmd file (see <> and <>, green frame) +* Any format, e.g., Markdown (see line 5 in <> and <>) + +[#im-admin-classif] +.Use of classifications for metadata +image::Admin-classif.png[] + +[#im-admin-srmd] +.SRMD file for describing metadata +image::Admin-SRMD.png[] + +[#im-admin-markdown] +.Administrative information as an md file +image::Admin-markdown.png[] + +The options are equivalent. +Which approach you choose depends on the form in which the information is available and how the simulation task is to be further evaluated. +A request file can also be included, and some relevant metadata can be attached as classifications. +Here, however, it is important to note what is the single source of truth and what are copies or interpretations in the metadata. + +==== Structuring and Multiplicity of Metadata + +The SSP LS Traceability supports metadata with the classification approach (details see at the specification). +It is important that namespaces are defined using “type.” +This makes it possible to define specific attributes as desired and means that they do not have to be aligned globally. +Multiplicity of classifications are possible, so for example the classification parameter can be used several times to list a set of parameters. +The classification schema was deliberately kept simple so that it can be supported relatively easily by tools. +Therefore, it does not support sub-structuring or other features. +The ordering of classification has no syntactical meaning. + +* If structuring is needed, this can be done using naming conventions, e.g., using dots (execution.tool.name and execution.tool.version). +* If a kind of grouping is needed, like for two tools to express their names and version, the Modelica convention of brackets and numbers can be used (see <>). + +[#im-metadata-multi] +.Sets, multiplicity of metadata, classifications +image::Metadata-Multi.png[] + +==== Metadata for Basic Use Cases + +The information and metadata required depend on the use case. +The following proposes a set of metadata that enables basic functionality for search, analysis, reuse, and traceability. +A key factor for user acceptance is that most of this information can be provided by the used IT systems. +The listed process phase "Administrative" is not a phase itself but it is part of the STMD-File and contains the relevant administrative information. +This set of metadata can be used as starting point in implementation metadata for simulation. + +[cols="1>m,2^e,7<",width="100%",align="center",frame="topbot",options="header"] +|=== +| Attribute Name| Process Phase | Classification | Description | Typical Source +| Ordering project | Administrative | administrative.ordering-project.name | Unique name of the ordering project | Project management tool +| Specific Product | Administrative | administrative.specific-product.name | Unique name of the specific product | Project management tool +| Simulation Request | Administrative | administrative.simulation-request.name | Unique name of the Simulation Request | Project management tool +| Simulation task | Administrative | administrative.simulation-task.name | Unique name of the simulation task | Project management tool +| Item under Test | Analysis | analysis.item-under-test.name | System, component, or product being analyzed | Tool / system +| Simulation Objective | Analysis | analysis.simulation-task.objectives | Objective or purpose of the simulation | User +| Quality criterion | Analysis |analysis.quality-aspects | Criteria used to evaluate simulation success | User +| Used Model | Execution | execution.model.name | Model used for the simulation | Tool / system +| Used Parameter | Execution | execution.parameters.name | Parameter used for the simulation | user (selection) +| Used Tool | Execution | execution.tool.name | Tool used for the simulation | Tool / system +| Task status | Fulfillment | fulfillment.task-status | Is the task still in progress abortet, finished | User +| Quality fulfilled | Fulfillment | fulfillment.quality | Documentation of the quality fulfillment decision | User +| Objectives fulfilled | Fulfillment | fulfillment.objectives | Documentation of the objectives fulfillment decision | User +|=== + +The following illustrates how this information is linked to the development and simulation process. + +[plantuml] +---- +Decision Task + | + v +Simulation Request + | + v +Simulation Task + | + v +Simulation Results + +Simulation Results --> Search +Simulation Results --> Analysis +Simulation Results --> Reuse +---- + +This minimum set of metadata can already be used to perform basic evaluations, searches and reuse. + +*Basic Use Cases* + +* I am looking for the corresponding simulations for a project +* For which applications was Model Z used? +* In which simulations was a tool used in Version X with models of Version Y +* Which existing simulation settings can possibly be used as a template for a new simulation task? diff --git a/workflow-guide/3___scenarios.adoc b/workflow-guide/3___scenarios.adoc deleted file mode 100644 index f704c29..0000000 --- a/workflow-guide/3___scenarios.adoc +++ /dev/null @@ -1,32 +0,0 @@ -== SSP collaboration and traceability scenarios - -=== Cross-company coupled simulation or modeling processes - -=== Integrated cross-company simulation and modeling process - -=== Interdepartmental simulation and modeling processes - -=== In-house coupling of simulation and modeling relevant IT tools - -=== Reduction of development and validation effort through reuse - -=== Company internal evaluation of knowledge by criteria - -=== Retrospective tracing of simulation and modeling processes - -=== Extension of SDM infrastructures with SSP traceability management - -=== Library and market place management for models and parameters - - - - - -//// - -The affected CSP sectios are shown in <<#im-CSP-UC1>>. - -[#im-CSP-UC1] -.Primarily affected CSP sections (red framed) and Co-affected CSP sections (light red framed ) -image::CSP-UC1.png[800, 800] -//// diff --git a/workflow-guide/4___design_spec_ssp.adoc b/workflow-guide/4___design_spec_ssp.adoc new file mode 100644 index 0000000..d1b1d17 --- /dev/null +++ b/workflow-guide/4___design_spec_ssp.adoc @@ -0,0 +1,19 @@ +== Design Specification with SSP, SSP LS Traceability + +The SSP standard <> is intended to support + +. the exchange of interconnected simulation models and their parameterization, and +. the simulation design by specifying empty components through their interface templates + +In a simulation request, it is generally sufficient to describe the simulation task and its objective. +However, no further specifications are made regarding the type of simulation and the models used (as in the example in <> and <>). + +However, more detailed information, such as design specifications or parts of the implementation and test environments, is often specified. +A simple example is provided in the chapter examples (see <> and `SSP-Trace-DesignSpec.ssp`), the electromagnetic part of the DC motor is transferred as an FMU, while only the shell description with interfaces is provided for the mechanical part. +It makes sense to use SSP LS Traceability directly as a container for the artifacts here. +The FMUs whose interconnection is specified as SSD are linked as inputs to the implementation phase (<>). +This approach makes it possible to trace what was input and what was created in the simulation task itself. + +[#im-designspec] +.Transfer of design and implementation specifications +image::DesignSpec.png[] diff --git a/workflow-guide/4___embedding_referencing_resources.adoc b/workflow-guide/4___embedding_referencing_resources.adoc deleted file mode 100644 index 7313f05..0000000 --- a/workflow-guide/4___embedding_referencing_resources.adoc +++ /dev/null @@ -1,74 +0,0 @@ -[#sec-EmbeddingAndReferencingResources] -== Embedding and referencing resources - -A Glue Particle provides in several sections three alternative options to include information about resources, e.g., resources for inputs, outputs or procedure information. - -- Resource information may be written directly into the XML file. This procedure is suitable for single or very few atomic information. - -- The far more elegant way is to outsource the information into own files and to refer to this outsourced information from the Glue Particle file. This is more suitable for a bigger amount of information. - -- A third option is to link the Glue Particle file to relevant resources stored in IT systems. - -This chapter outlines how these options may be used and when best to use which of these options. - -=== Embedding resources - -Resources are specified using the __ element. To embed information about resources directly in the Glue Particle, the element __ must be created within the element __. Any content may then be created in the __ element. - -<<#im-embeddedresourceinformationschema>> shows how this construct is built up in the Glue Particle XML Schema for a Credible Simulation Process. - -[#im-embeddedresourceinformationschema] -.Embedding resource information directly in a Glue Paerticle file -image::embeddedResourceInformationSchema.png[800, 800] - -Direct embedding of resource information may be useful when the information is very compact and very limited, e.g., for single or very few information. <> provides an example for embedding resource information by means of a XML element __ Element. Note that the source attribute in the XML element __ is not used. - -[#im-embeddedresourceInformationExample] -.Embedded resource information in a Glue Particle -image::EmbeddedresourceInformationExample.png[800, 800] - -=== Referencing external resources - -As soon as a larger amount of information is to be specified per resource, it is no longer useful to write it directly into the Glue Particle XML file for several reasons. - -* The file size of a Glue Particle may increase significantly if too much resource information is embedded into a Glue Particle file. This effect would carry over to each new version of the Glue Particle with successive development of a Glue Particle. - -* Referencing resources that are external to the Glue Particle improves the possibilities for resource reuse. In principle, an external resource may be referenced by multiple Glue Particles simultaneously and consistently. - -* Many resources can be expressed in standardized data formats or are available in standardized formats. Therefore, it would be inefficient to recode this information from the standardized data format into a Glue Particle compatible format for embedding. It is more efficient to leave a resource in its standardized data format and thus also facilitate the processing of the information in the collaborative engineering processes. - -Basically, two types of resources may be distinguished. - -* *File-based resources:* These are resources that are available as a file and are added to the System Structure Package, the container for the Glue Particle. - -* *Remote ressources:* Resources that are managed in a data management system. From the point of view of the Glue Particle, these may also be referred to as remote resources. - -Regardless of which type of resource is to be referenced, the URI, i.e. either the relative path to a file within the Glue Particle container or the URL to a resource in a data management system, is written to the _source_ attribute of the XML element __. If the _source_ attribute is missing, the resource is provided inline as contents of the __ element, which must not be present otherwise - -<<#im-referencedResourcesSchema>> shows how this construct is represented in the Glue Particle XML Schema for a Credible Simulation Process. - -[#im-referencedResourcesSchema] -.Referencing resources via URI -image::ReferencedResourcesSchema.png[1000, 1000] - -Below are two examples of how the references are implemented. - -<> provides an example for referenced local resource information by means of the attribute _source_ in the a XML element __ Element. Note that there do not exist any __ elements in the XML element __. - -[#im-referencdLocalresourceInformationExample] -.Referenced local resource information in a Glue Particle -image::ReferencedLocalResourceInformationExample.png[800, 800] - -#Beispielcode Remote Resource# - -Whether file-based resource or a remote resource is used depends on the context. In the following, the respective context-specific advantages and disadvantages are described. - -* When referencing to resources in managed source systems, there is no additional redundancy. - -* Since information in data management systems is usually managed with version accuracy, the reference to resources in source systems significantly improves traceability. - -* Since information in data management systems is usually stored persistently and is specially protected by backup mechanisms, the reference to resources in source systems provides improved security against data loss or undesired data modification. - -* On the other hand, the references to remote resources usually no longer work when the Glue Particle is exchanged across companies, as access to the source system then probably no longer works. - -* There may also be restrictions within the company if a consumer of a Glue Particle does not have access to the source system. diff --git a/workflow-guide/5___data_management.adoc b/workflow-guide/5___data_management.adoc new file mode 100644 index 0000000..d6f7910 --- /dev/null +++ b/workflow-guide/5___data_management.adoc @@ -0,0 +1,14 @@ +== Data Management and Versioning + +=== SSP LS Traceability for Data Exchange + +All common data management systems support configuration, versioning, metadata, and labeling, especially for metadata, but usually as proprietary specific implementations. +The SSP LS Traceability now supports the exchange of information between these systems and to and between simulation tools in a standardized form (<>). + +[#im-datamanagement] +.SSP LS Traceability for data exchange in heterogeneous environments +image::DataManagement.png[] + +=== Using GitLab, GitHub for Data Management + +A simple implementation of data management when using GIT is that the zip structure is unzipped directly in GIT and stored and managed in this way. diff --git a/workflow-guide/5___internal_system_couplings.adoc b/workflow-guide/5___internal_system_couplings.adoc deleted file mode 100644 index b41c94b..0000000 --- a/workflow-guide/5___internal_system_couplings.adoc +++ /dev/null @@ -1,31 +0,0 @@ -[#sec-companyInternalSystemCouplings] -== Company internal IT tool couplings - - -#Tobe defined# - -[#sec-synchroniousSystemCouplings] -=== Synchronious IT tool couplings - -#Tobe defined# - -[#sec-asynchroniousSystemCouplings] -=== Asynchronious IT tool couplings - -Glue Particle may be used within companies to successively collect information such as inputs, outputs, procedures and their rationales during the simulation process (Credible Simulation Process) for the individual phases and steps of the process and store them in the Glue Particle, thus gradually enriching the Glue Particle. - -The Glue Particle is to be carried through the process and the Glue Particle transports information through the IT tool chain. This means that the IT tools and systems used in the simulation process must be able to read or import a Glue Particle and write or export it. - -* An IT tool used in phase x of the simulation process would write resources generated by that tool to the Glue Particle or link resources and then export or save the Glue Particle. - -* An IT Tool used in phase x-1,x+2 etc. of the simulation process would read or import the Glue Particle and may use the resources provided by it. - -This type of IT system coupling via the export - import processes is referred to as asynchronous coupling. The IT systems involved do not have a direct interface with each other and are therefore not directly connected. Therefore, both systems do not have to be in operation at the same time. - -<> illustrates the asynchronous system coupling. - -[#im-asynchronousCoupling] -.Asynchrous IT tool coupling by means of Glue Particle -image::AsynchronousCoupling.png[800, 800] - -By using the Glue Particle to establish an asynchronous coupling of IT tools and systems involved in the process, the number of interfaces required can be reduced compared to synchronous coupling. This reduction effect increases with the number of IT tools and systems involved in the process and the complexity of the information transport through the process. \ No newline at end of file diff --git a/workflow-guide/6___cross_company_exchange.adoc b/workflow-guide/6___cross_company_exchange.adoc deleted file mode 100644 index 085c8e2..0000000 --- a/workflow-guide/6___cross_company_exchange.adoc +++ /dev/null @@ -1,8 +0,0 @@ -== Cross-company exchange of Glue Particle - -An exchange of data, especially engineering data, is usually linked to a business relationship between the companies involved, or the need for an exchange of data is conditioned by a business relationship. This is also the case with the exchange of Glue Particles. - -A cross-company exchange of information typically couples two different processes using the transferred information. On the one hand, there is a process at the customer's side, e.g., a simulation process, and on the other hand, there is a process on the contractor's side, e.g., a modeling process. At the customer's side, a simulation is carried out as part of a product development and for this simulation the simulation model of a supplied component is required. The simulation model is to be provided by the supplier. The simulation process and the modeling process are linked, for example, by a modeling order or a model request and by the transfer of the model to the customer. #<<>> illustrates this exchange constellation on a high level.# - - - \ No newline at end of file diff --git a/workflow-guide/6___ssp_ls_traceability_examples.adoc b/workflow-guide/6___ssp_ls_traceability_examples.adoc new file mode 100644 index 0000000..2ae73a3 --- /dev/null +++ b/workflow-guide/6___ssp_ls_traceability_examples.adoc @@ -0,0 +1,24 @@ +== SSP LS Traceability Examples + +All examples are based on the simulation task of a DC-motor (see <>). + +[#im-dc-motor] +.Simulation task is pre-selection of a DC-motor +image::DC-motor.png[DC-motor, 1000, 1000] + +*https://github.com/PMSFIT/SSPTraceabilityGuides/tree/main/workflow-guide/examples[List of Examples]* + +. *Linking of Sources* +** Example of how sources are linked. <> and <> are taken from this example. +. *Usage of metadata* +** Extension of example 1. <>, <>, and <> are taken from this example. +. *Simulation of a DC-motor with basic additional information* +** Simulatable on every tool which supports SSP. +. *Example with Simulation request which contains design specification* +** <> is taken from this example. +. *Example with extended information set, design specification, simulation* +** covers also modeling and testing of a sub-model + +As an extended example 5 also contains the design specification and the test environment for the mechanical part of the DC motor. +This example also includes a large amount of documentation and metadata. +The amount of documentation depends on the required level of traceability and comprehensibility, as this involves a certain amount of effort. diff --git a/workflow-guide/7___workflow_examples.adoc b/workflow-guide/7___workflow_examples.adoc deleted file mode 100644 index f26093e..0000000 --- a/workflow-guide/7___workflow_examples.adoc +++ /dev/null @@ -1,98 +0,0 @@ -== Use cases for the handling of Glue Particle files - -=== Re-use of Glue Particles - -The re-use of Glue Particles, respectively of STMD files is one of the main applications of the Glue Particle approach. Glue Particles reference resources that are consistent with each other for a given simulation or modeling task. These resources may be simulation models, parameters, test cases, tools used for the simulation, and other relevant resources. The compilation of these resources and additional information documenting procedures, assumptions and simplifications and respective rationales in a Glue Particle represents a considerable added value. This applies especially if a Glue Particle is entirely or partially re-used for nother simulation tasks. Four examples of re-using Glue Particles are introduced here. - -* Re-use of Glue Particles for a simulation of a DC motor with the same objectives, conditions and resources -* Re-use of Glue Particles for a simulation of a DC motor with the same objectives but aother set of parameters -* Re-use of Glue Particles for a simulation of a DC motor with the same objectives but another motor model -* Re-use of Glue Particles for a simulation with the same objectives in another simulation tool environment - -==== Re-use a Glue Particle unchanged - -#tbd# - -==== Re-use a Glue Particle and replace parameters - -A repetition of a simulation with another set of parameters requires a replacement of the parameter file by another parameter file in case the parameters are stored in a local digital file. Assuming the new parameter file may be named differently also the resource link must be adapted for referencing the new parameter file. In case the parameters are stored in an IT system, e.g. in a parameter database, only the resource link has to be adapted. - -*Preconditions* - -* The simulation objectives and requirements remain unchanged -* The design specification for the parameters remains unchanged - -*Affected CSP sections* - -The parameters are implemented in the CSP step __Implement Parameters__ #(see also ???)# of the CSP phase __Implement and Asure Quality for Simulation Setup__ #(see also ???)# and the implemented parameters are referenced as an outpout of this CSP step. Therefore if the parameters are replaced by other parameters the CSP step __Implement Parameter__ ist primarily affected. -Because the parameters have been replaced it is necessary to also check whether the replacement has any influences on the simulation setup integration. Additionally, there may be a formal necessity for re-verifying the information in the Glue Particle section __ImplementationPhase__ in order to assure and conform the simulation setup quality. - -Primarily affected CSP sections are - -* Implement Parameters - -Co-affected CSP sections are - -* Integrate Simulation Environment, Models, Parameters -* Assure Simulation Setup Quality -* Derive Simulation Setup Quality Verdict - -The affected CSP sectios are shown in <<#im-CSP-UC1>>. - -[#im-CSP-UC1] -.Primarily affected CSP sections (red framed) and Co-affected CSP sections (light red framed ) -image::CSP-UC1.png[800, 800] - -*Pre-state Glue Particle* - -#Relevanter Ausschnitt vom Glue Particle# - -*User Operations* - -If parameters are replaced, the user must proceed as follows to ensure consistent documentation of the new simulation task. - -* In case the parameters sre provided as a local digital file replace the parameter file with a new parameter file -* Replace the existing resource link with a new link, either to the new local digital file or to a new target in an IT system -* Check whether the new parameters are syntactically compatible with the associated model and are semantically valid -* Document in the __Procedure__ field of the STMD step section __ImplementParameter__ in the STMD phase stection __ImplementationPhase__ the replacement procedure, if applicable, e.g. __file physically replaced__ or __file edited__ -* Document in the __Rational__ field of the STMD step section __ImplementParameter__ in the STMD phase stection __ImplementationPhase__ the reason for the replacement of the parameters, e.g. __simulation with more precised parameters__ or __simulation with upscaled parameters to represent a larger DC motor__ -* Check whether the replacement of the parameters has any influences on its integration into the overall simulation setpup -* Implement all required measures to assure the simulation setup quality with the new parameters -* Document the assurance of the simulation setup quality in the STMD step section __AssureSimulationSetupQuality__ of the STMD phase section ImplementationPhase. - -*Tools Functionalities* - -A tool designed to handle Glue Particles resp. STMD files may support the user in the folliwing activities. - -* Replacement ot the parameters -* Replacement resp. the editing of the resource link -* Script-based compability check of the parameters -* Filling out the __Procedure__ and the __Rationale__ field in the Glue Particle - -*Derivation chain* - -It is important that the trace to the original Glue Particle is preserved. Corresponding information should be entered in the STMD section __DerivationChain__ in the STDM section __GeneralInformation__. - -*Handling metadata* - -This use case does not result in any specific additional requirements for handling metadata. The general requirements as documented in chapter ??? apply here. - -*Data Management Operations* -When a Glue Particle is revised, a new Glue Particle respectively a new version of the Glue Particle is actually created. -The link betwen a Glue Particle and the original Glue Particle might be managed and displayed at the data management level. - -*Post-state Glue Particle* - -#Relevanter Ausschnitt vom Glue Particle# - -*Post-conditions* - -* A new Glue Particle is available -* The new Glue Particle has a trace to the Glue Particle from which it originated -* The Glue Particle references new parameters -* The procedure and the reason of the replacement are documented -* The integrity of the entire simulation setup with the new parameters has been checked and confirmed according to the requirements of the Credible Simulation Process - -==== Re-use a Glue Particle and replace simulation model - -==== Re-use a Glue Particle and replace tool environment \ No newline at end of file diff --git a/workflow-guide/B___literature.adoc b/workflow-guide/B___literature.adoc index 20e356b..51b5633 100644 --- a/workflow-guide/B___literature.adoc +++ b/workflow-guide/B___literature.adoc @@ -5,7 +5,14 @@ - [[[SEMVER200]]] Preston-Werner, T.: **Semantic Versioning 2.0.0**. https://semver.org/spec/v2.0.0.html -- [[[SSP10]]] Modelica Association: **System Structure and Parameterization 1.0**. March 2019. https://ssp-standard.org/publications/SSP10/SystemStructureAndParameterization10.pdf +- [[[SSP201]]] Modelica Association: **System Structure and Parameterization 2.0.1**. May 2026. https://ssp-standard.org/docs/2.0.1/ -- [[[STMD]]] Modelica Association: **SSP Traceability Version 1.0.0-Beta2,unreleased** -#Link hinzufügen# \ No newline at end of file +- [[[SSPLST]]] Modelica Association: **SSP Layered Standard Traceability Version 1.0**. August 2025. https://ssp-standard.org/ssp-ls-traceability/1.0.0/ + +- [[[MIC]]] prostep ivip, IRT SystemX: **MIC-Core 1.2**. September 2025. +https://mic-core.github.io/MIC-Core/main/ + +- [[[SIC]]] prostep ivip, IRT SystemX: **SIC-Core 0.1**. May 2026. +https://mic-core.github.io/MIC-Core/main/ + +- [[[CSP]]] prostep ivip: **Credible Simulation Process Framework** in prostep ivip SmartSE Recommendation 2025 PSI 11 V4.0 Part H: https://www.prostep.org/en/medialibrary/detail?ai%5Baction%5D=detail&ai%5Bcontroller%5D=Catalog&ai%5Bd_name%5D=prostep-ivip-smartse-recommendation-2025-psi-11-v-4-0-part-h-credible-simulation-process&ai%5Bd_pos%5D=2 diff --git a/workflow-guide/X___backlog.adoc b/workflow-guide/X___backlog.adoc deleted file mode 100644 index 5ad5859..0000000 --- a/workflow-guide/X___backlog.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[appendix] -== Backlog - - -* Using SSD-files to specify models -* Image for generic illustration of cross-company Glue Particle couplings. -* Distinction from the internal exchange of Glue Particles -* Central concepts for cross-company Glue Particle couplings -* Example: Simulation request to a supplier -* Example: Transfer of simulation results -* Example: Model request to a supplier -* Example: Model handover to customer diff --git a/workflow-guide/___glue_particle_data_management.adoc b/workflow-guide/___glue_particle_data_management.adoc deleted file mode 100644 index b6d1d3a..0000000 --- a/workflow-guide/___glue_particle_data_management.adoc +++ /dev/null @@ -1,57 +0,0 @@ -== Glue Particle data management - -=== Versioning mechnisms for Glue Particles - -==== Situation - -A Glue Particle always represents the processing status at a specific point in time. By viewing an STMD file, it is not possible to determine what the contents of the file looked like at an earlier point in time. A Glue Particle does not store a version history. In order to be able to trace the history of a Glue Particle, several processing statuses of a Glue Particle must be stored separately so that the processing statuses can be viewed in their chronological order. - -<> shows a typical version history for a Glue Particle in which the individual Glue Particle files have a different fill level.In the first version, only general information and information on the analysis phase is included, while in the subsequent versions the Glue Particle is gradually filled. - -[#im-versionmechnismsforglueparticle] -.Versioning mechnisms for Glue Particles -image::VersioningMechanismForGlueParticle.png[500, 500] - -The STMD Glue Particle specification lists two different fields for entering a version information at the __SimulationTaskMetaData__ XML element. - - -[#tb-simulationtaskmetadataattributes] -.SimulationTaskMetaData element attributes (excerpt) -[width="100%",options="header"] -|=== -| Attribute name | Optional / Mandatory | Atrribute description -| version | Mandatory | Version of STMD format, 0.x for this pre-release. -| fileversion | Optional | This attribute gives a version number for this file's content. -|=== - -The attribute __version__ represents the version of the STMD XML schema and is mandatory. The attribute __fileversion__ can be used to provide the Glue Particle with a version. However, it is not suitable for controlling a formal versioning process based on it. On the one hand the attribute is optional and on the other hand it can be edited freely. It is therefore an informal attribute. - -Since a Glue Particle does not support an explicit version mechanism according to the specification, technical mechanisms of either the operating system of a computer or a data management system must be used to represent a version history. - -==== Workflow solution - -When building a Glue Particle version history supported by a data management system, the editing of a Glue Particle is typically done in conjunction with a check-out/check-in mechanism, where a Glue Particle is locked for editing by other persons or systems after check-out (exclusive check-out). On the one hand, this ensures that there is no inconsistency of information due to parallel processing, and on the other hand, it ensures that a Glue Particle is stored again where it was stored before processing by the check-in. The check-in also ensures that the Glue Particle is saved as a new version of the Glue Particle. - -<> shows the Glue Particle version history from <> as it would appear in a data management system. - -[#im-glueparticleversionhistory] -.Glue Particle version history -image::GlueParticleVersionHistory.png[500, 500] - -<> illustrates how the check-out and check-in mechnism is utilized for editin Glue Particles. As long as a glue Particle version is checked out it is locked for changes by other persons or systems. Whe a Glue Particle version is checked back in it is unlocked and saved a a new version. - -[#im-checkoutcheckin] -.Check-out and check-in mechanism for editing Glue Particle -image::CheckOutCheckIn.png[500, 500] - -==== Recommendation for working with Glue Particle versions and version histories - -The following recommendations for handling glue particle versions and the entire version history of a glue particle are to be understood as basic recommendations. This means that situation-related exceptions would be permissible in principle, as long as transparency is maintained in these exceptional cases. - -* In general, only the latest version of a Glue Particle should be edited, as otherwise inconsistencies within the version history may occur, which could make a later retrospective interpretation of the version history more difficult. -* Ideally, it should only be possible to edit the latest version of a glue particle, i.e. it should only be possible to check out the latest version. - -=== Workingwith Glue Particles variants - -=== Working with interconnected Glue Particles - diff --git a/workflow-guide/examples/1-SSP-Trace-Basic.ssp b/workflow-guide/examples/1-SSP-Trace-Basic.ssp new file mode 100644 index 0000000..cceb0c9 Binary files /dev/null and b/workflow-guide/examples/1-SSP-Trace-Basic.ssp differ diff --git a/workflow-guide/examples/2-SSP-Trace-Metadata.ssp b/workflow-guide/examples/2-SSP-Trace-Metadata.ssp new file mode 100644 index 0000000..82e2784 Binary files /dev/null and b/workflow-guide/examples/2-SSP-Trace-Metadata.ssp differ diff --git a/workflow-guide/examples/3-SSP-Trace-SimBasic.ssp b/workflow-guide/examples/3-SSP-Trace-SimBasic.ssp new file mode 100644 index 0000000..a2aa620 Binary files /dev/null and b/workflow-guide/examples/3-SSP-Trace-SimBasic.ssp differ diff --git a/workflow-guide/examples/4-SSP-Trace-DesignSpec.ssp b/workflow-guide/examples/4-SSP-Trace-DesignSpec.ssp new file mode 100644 index 0000000..d3f5a12 --- /dev/null +++ b/workflow-guide/examples/4-SSP-Trace-DesignSpec.ssp @@ -0,0 +1 @@ + diff --git a/workflow-guide/examples/5-SSP-Trace-SimFull.ssp b/workflow-guide/examples/5-SSP-Trace-SimFull.ssp new file mode 100644 index 0000000..d3f5a12 --- /dev/null +++ b/workflow-guide/examples/5-SSP-Trace-SimFull.ssp @@ -0,0 +1 @@ + diff --git a/workflow-guide/images/Admin-SRMD.png b/workflow-guide/images/Admin-SRMD.png new file mode 100644 index 0000000..7661b32 Binary files /dev/null and b/workflow-guide/images/Admin-SRMD.png differ diff --git a/workflow-guide/images/Admin-classif.png b/workflow-guide/images/Admin-classif.png new file mode 100644 index 0000000..9d3f2b6 Binary files /dev/null and b/workflow-guide/images/Admin-classif.png differ diff --git a/workflow-guide/images/Admin-markdown.png b/workflow-guide/images/Admin-markdown.png new file mode 100644 index 0000000..d0d77bc Binary files /dev/null and b/workflow-guide/images/Admin-markdown.png differ diff --git a/workflow-guide/images/AsynchronousCoupling.png b/workflow-guide/images/AsynchronousCoupling.png deleted file mode 100644 index fad82e6..0000000 Binary files a/workflow-guide/images/AsynchronousCoupling.png and /dev/null differ diff --git a/workflow-guide/images/CMP-3Layer.png b/workflow-guide/images/CMP-3Layer.png new file mode 100644 index 0000000..d0b67b4 Binary files /dev/null and b/workflow-guide/images/CMP-3Layer.png differ diff --git a/workflow-guide/images/CSP-3Layer.png b/workflow-guide/images/CSP-3Layer.png new file mode 100644 index 0000000..3d8a6ea Binary files /dev/null and b/workflow-guide/images/CSP-3Layer.png differ diff --git a/workflow-guide/images/CSP-details.png b/workflow-guide/images/CSP-details.png new file mode 100644 index 0000000..be28d92 Binary files /dev/null and b/workflow-guide/images/CSP-details.png differ diff --git a/workflow-guide/images/CSP-recursions.png b/workflow-guide/images/CSP-recursions.png new file mode 100644 index 0000000..9bc3fa8 Binary files /dev/null and b/workflow-guide/images/CSP-recursions.png differ diff --git a/workflow-guide/images/CSP-workflow.png b/workflow-guide/images/CSP-workflow.png new file mode 100644 index 0000000..ace93b5 Binary files /dev/null and b/workflow-guide/images/CSP-workflow.png differ diff --git a/workflow-guide/images/DC-motor.png b/workflow-guide/images/DC-motor.png new file mode 100644 index 0000000..76ccbb6 Binary files /dev/null and b/workflow-guide/images/DC-motor.png differ diff --git a/workflow-guide/images/DataManagement.png b/workflow-guide/images/DataManagement.png new file mode 100644 index 0000000..d77463b Binary files /dev/null and b/workflow-guide/images/DataManagement.png differ diff --git a/workflow-guide/images/DesignSpec.png b/workflow-guide/images/DesignSpec.png new file mode 100644 index 0000000..3703a1a Binary files /dev/null and b/workflow-guide/images/DesignSpec.png differ diff --git a/workflow-guide/images/Metadata-Multi.png b/workflow-guide/images/Metadata-Multi.png new file mode 100644 index 0000000..f040002 Binary files /dev/null and b/workflow-guide/images/Metadata-Multi.png differ diff --git a/workflow-guide/images/Metadata-Reuse.png b/workflow-guide/images/Metadata-Reuse.png new file mode 100644 index 0000000..52ba610 Binary files /dev/null and b/workflow-guide/images/Metadata-Reuse.png differ diff --git a/workflow-guide/images/Metadata-Search.png b/workflow-guide/images/Metadata-Search.png new file mode 100644 index 0000000..84260e4 Binary files /dev/null and b/workflow-guide/images/Metadata-Search.png differ diff --git a/workflow-guide/images/Metadata-basic-CSP.png b/workflow-guide/images/Metadata-basic-CSP.png new file mode 100644 index 0000000..1215cc2 Binary files /dev/null and b/workflow-guide/images/Metadata-basic-CSP.png differ diff --git a/workflow-guide/images/Metadata-usage.png b/workflow-guide/images/Metadata-usage.png new file mode 100644 index 0000000..aa89138 Binary files /dev/null and b/workflow-guide/images/Metadata-usage.png differ diff --git a/workflow-guide/images/MetadataTraceCSP.png b/workflow-guide/images/MetadataTraceCSP.png new file mode 100644 index 0000000..52f5139 Binary files /dev/null and b/workflow-guide/images/MetadataTraceCSP.png differ diff --git a/workflow-guide/images/SSP-Trace-structure.png b/workflow-guide/images/SSP-Trace-structure.png new file mode 100644 index 0000000..ab52af8 Binary files /dev/null and b/workflow-guide/images/SSP-Trace-structure.png differ diff --git a/workflow-guide/images/STMD-Links.png b/workflow-guide/images/STMD-Links.png new file mode 100644 index 0000000..da54830 Binary files /dev/null and b/workflow-guide/images/STMD-Links.png differ diff --git a/workflow-guide/index.adoc b/workflow-guide/index.adoc index e465964..a9fae3e 100644 --- a/workflow-guide/index.adoc +++ b/workflow-guide/index.adoc @@ -18,20 +18,16 @@ include::0___preamble.adoc[] include::1___introduction.adoc[] -include::2___glue_particle_approach.adoc[] +include::2___objectives.adoc[] -include::3___scenarios.adoc[] +include::3___application_csp.adoc[] -include::4___embedding_referencing_resources.adoc[] +include::4___design_spec_ssp.adoc[] -include::5___internal_system_couplings.adoc[] +include::5___data_management.adoc[] -include::6___cross_company_exchange.adoc[] - -include::7___workflow_examples.adoc[] +include::6___ssp_ls_traceability_examples.adoc[] include::A___glossary.adoc[] include::B___literature.adoc[] - -include::X___backlog.adoc[]