//////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2010, 2026 Contributors to the Eclipse Foundation
//
// See the NOTICE file(s) distributed with this work for additional
// information regarding copyright ownership.
//
// This program and the accompanying materials are made available
// under the terms of the MIT License which is available at
// https://opensource.org/licenses/MIT
//
// SPDX-License-Identifier: MIT
//////////////////////////////////////////////////////////////////////////////

include::_part_attributes.asciidoc[]

:leveloffset: -2

[[tools-chapter-relations]]
== CIF relations collector

indexterm:[CIF relations collector]
indexterm:[tools,CIF relations collector]

The CIF relations collector analyzes a CIF specification and produces three DMMs with the results.
The DMMs describe found connections between plants and requirements.
By automatically or manually studying the connections, the dependency structure between the CIF plants and requirements becomes more clear.
The found structure can be exploited to split or modify a CIF specification in a useful way.
For example, the <<tools-chapter-multilevel,multilevel>> tool uses it to create partial specifications.

indexterm:[CIF relations collector,start]

[[tools-chapter-relations-start]]
=== Starting the transformation

The transformation can be started in the following ways:

* In Eclipse, right click a `.cif` or `.cifx` file in the _Project Explorer_ tab or _Package Explorer_ tab and choose menu:CIF analysis tools[Collect relations...].

* In Eclipse, right click an open text editor for a `.cif` or `.cifx` file and choose menu:CIF analysis tools[Collect relations...].

* Use the `cifrelations` tool in a ToolDef script.
See the <<tools-scripting-chapter-intro,scripting documentation>> and <<tools-scripting-chapter-tools,tools overview>> page for details.

* Use the `cifrelations` command-line tool.

indexterm:[CIF relations collector,options]

[[tools-chapter-relations-options]]
=== Options

Besides the general application options, this application has the following options:

* _Input file_: The absolute or relative file system path to the input CIF file.

* _Plant-groups output file path_: The absolute or relative file system path to write the plant-groups DMM file.
  By default, or if no path is supplied, the application writes the plant groups DMM to a modified path of the _Input file_ option.
  The path modification takes the file system path of the _Input file_ option, then removes either a `.cif` or a `.cifx` suffix if it exists, and appends `.plant-groups.csv`.
  To skip writing the plant groups DMM, use `no` as file system path.

* _Requirement-groups output file path_: The absolute or relative file system path to write the requirement-groups DMM file.
  By default, or if no path is supplied, the application writes the requirement groups DMM to a modified path of the _Input file_ option.
  The path modification takes the file system path of the _Input file_ option, then removes either a `.cif` or a `.cifx` suffix if it exists, and appends `.requirement-groups.csv`.
  To skip writing the requirement groups DMM, use `no` as file system path.

* _Plants-requirements output file path_: The absolute or relative file system path to write the plants-requirements DMM file.
  By default, or if no path is supplied, the application writes the plants-requirements DMM to a modified path of the _Input file_ option.
  The path modification takes the file system path of the _Input file_ option, then removes either a `.cif` or a `.cifx` suffix if it exists, and appends `.plants-requirements.csv`.
  To skip writing the plant requirements DMM, use `no` as file system path.

* _RFC-4180 compliance_: Comma-separated value (CSV) files are defined in the link:https://www.rfc-editor.org/rfc/rfc4180[RFC-4180] standard.
  The standard requires Windows style line delimiters, but using such files on other operating systems may cause problems.
  As a work-around, the CSV file writer can also use Unix style line delimiters, although that is not allowed in the RFC-4180 standard.
  However, as CSV files with Unix style line delimiters are accepted by all common operating systems including the Windows operating system, the default of this option is to ignore the Windows style line delimiter requirement of the standard and write Unix style line delimiters instead.
  If a fully compliant RFC-4180 CSV file is however required, enabling this option will cause CSV files to be written using Windows style line delimiters.
+
Further details about the Windows and Unix style line delimiters, see the Wikipedia link:https://en.wikipedia.org/wiki/Newline[Newline] article.

indexterm:[CIF relations collector,preprocessing]

[[tools-chapter-relations-preprocessing]]
=== Preprocessing

The following <<tools-cif2cif-chapter-index,CIF to CIF transformations>> are applied as preprocessing (in the given order), to increase the subset of CIF specifications that can be transformed:

* <<tools-cif2cif-chapter-remove-annos>>
* <<tools-cif2cif-chapter-elim-comp-def-inst>>
* <<tools-cif2cif-chapter-elim-self>>
* <<tools-cif2cif-chapter-simplify-values>>
* <<tools-cif2cif-chapter-remove-io-decls>>

[[tools-chapter-relations-supported-specs]]
=== Supported specifications

The CIF relations collector tool has performed pre-processing before performing the checks below, which means that:

* Annotations are ignored, except for <<lang-tut-annotations-reachability-requirement,reachability requirement>> annotations (see also below).
* I/O declarations are ignored.
A warning is printed if the specification contains a CIF/SVG input mapping.
* Component definitions and instantiations are allowed (they have been eliminated already).
* Automata references with `self` are allowed (they have been rewritten).

The CIF relations collector allows a subset of CIF specifications.
The restrictions are:

* All automata must be either a plant or a requirement automaton.
  Kindless and supervisor automata are not allowed.
* Only requirement invariants are allowed.
  Kindless, plant and supervisor invariants are not allowed.
* Automata must have exactly one initial location, and it must be possible to determine this statically.
* The specification must have at least one input variable or one plant automaton.
  (An input variable counts as plant.)
* Discrete variables must have exactly one initial value, and it must be possible to determine this statically.
* The specification must have at least one requirement automaton or one requirement invariant.
* State requirement invariants are not allowed.
  Only state/event exclusion requirement invariants are allowed.
* Invariants in locations are not allowed.
  Only invariants in components are allowed.
* <<lang-tut-annotations-reachability-requirement,Reachability requirement>> annotations are not allowed.
* Tau events are not allowed.
* Continuous variables are not allowed.
* Equations are not allowed.
* Component types are not allowed.

indexterm:[CIF relations collector,output]

[[tools-chapter-relations-output]]
=== Output of the CIF relations collector

The CIF relations collector analyzes the plants and requirements of a CIF specification, and can produce three Domain Mapping Matrix (DMM) files that contain the results.
A DMM is a variant of a link:https://en.wikipedia.org/wiki/Design_structure_matrix[Design Structure Matrix (DSM)], where connections between two different domains are expressed.
In a DMM, each row represents a value of the first domain, and each column represents a value of the second domain.
Each entry `(row, column)` in the matrix has the value `1` if the `row` value of the first domain is related to the `column` value of the second domain, otherwise the entry is `0`.

The following DMM files can be produced as results:

* The 'plant-groups' DMM describes how elementary CIF plant groups are combined into larger plant groups.
* The 'requirement-groups' DMM describes how elementary CIF requirement groups are combined into larger requirement groups.
* The 'plants-requirements' DMM describes how requirement groups relate to plant groups.

==== Elementary groups

Each plant automaton and each input variable is considered to be a plant group.
Each requirement automaton and each requirement state/event exclusion invariant in a component is considered to be a requirement group.

==== Merging plant groups and merging requirement groups

Each plant group and each requirement group should be self-contained.
This goal is achieved by repeatedly merging two plant groups into one (larger) group, or merging two requirement groups into one (larger) group.

Two plant groups should be merged if and only if at least one of the following holds:

* One plant group owns and the other plant group accesses a same location or discrete variable.
* Both plant groups access a same location or discrete variable.
* Both plant groups access a same input variable or event.

Two requirement groups should be merged if and only if at least one of the following holds:

* One requirement group owns and the other requirement group accesses a same location or discrete variable.
* Both requirement groups access an event that is not accessed by any plant group.

Ownership of a discrete variable by a group means that the discrete variable is in a plant automaton of that group.
Ownership of a location by a group means that the location is in a plant automaton of that group.
Accessing means that the group refers to a CIF element by its name.
For example, a requirement like `requirement start needs aut.ready` accesses the `start` event and the `ready` location of automaton `aut`.

==== Relating plant groups with requirement groups

A plant group is related to a requirement group if and only if at least one of the following holds:

* One group owns a location and the other group accesses that location.
* One group owns a discrete variable and the other group accesses that variable.
* Both groups access the same input variable.
* Both groups access the same event.

Note that having a requirement group that is not related to any of the plant groups is allowed by these rules.
As this may indicate a modeling mistake, the tool warns about such requirement groups.

[[tools-chapter-relations-further-reading]]
=== Further reading

The definition of plant groups, requirement groups, and plants-requirements relations is based on <<relations-goorden20>>, but with extensions.

* The CIF relations collector is more aligned with features available in CIF.
* The CIF relations collector features requirement groups to handle requirements that are only indirectly related to plants, which is new with respect to the paper.

[bibliography]
=== References

* [[[relations-goorden20,Goorden et al. (2020)]]] Martijn Goorden, Joanna van de Mortel-Fronczak, Michel Reniers, Wan Fokkink and Jacobus Rooda, "Structuring Multilevel Discrete-Event Systems With Dependence Structure Matrices", IEEE Transactions on Automatic Control, volume 65, issue 4, pages 1625-1639, 2020, doi:link:https://doi.org/10.1109/TAC.2019.2928119[10.1109/TAC.2019.2928119]
