Configure Matrix Views

A matrix view is a traceability tool. Each row and column is an element from an independent expose / filter selection. Each cell is marked where a recognised relationship exists between the corresponding pair.

This page covers the SysML authoring pieces specific to matrices. See also:

Foundations - shared concepts (library, ContentView flags, expose / filter mechanics)
Use Grid Views - in-editor workflows (add and remove links, disabled cells)

Structure

Every MatrixView redefines three built-in sub-views:

rowView and columnView define the two axes independently using their own expose / filter scope. The two axes can draw from different packages, use different filters, and expose different element types
cellView points to the namespace that contains the relationships between row and column elements

A relationship is shown in the matrix only when both its endpoints resolve to elements present on the two axes (see Strong vs Weak Matching) and the relationship itself is reachable from the cellView expose scope.

A minimal example (see Complete Example for full reference):

package MyViews {
    private import SysideViews::*;

    view myTraceMatrix : MVD::MatrixView {
        view :>> rowView {
            expose MyModel::Requirements::*;
            filter hastype SysML::RequirementUsage;
        }
        view :>> columnView {
            expose MyModel::Components::*;
            filter hastype SysML::PartUsage;
        }
        view :>> cellView {
            expose MyModel::**;
        }
    }
}

Cell View

The cellView expose statement points to one or more namespaces that contain the relationships between row and column elements. The following relationship types are recognised:

ConnectionUsage
AllocationUsage
Derivation relationships (ConnectionUsage tagged with #derivation metadata)

Directional Matching

By default a matrix is undirected: a cell is marked whenever the row element and column element appear on either end of a relationship, regardless of order. The cellView accepts a direction attribute to make the matrix directional. Dir is the short alias for MatrixTraceabilityDirection:

Value	Symbol	Meaning
`Dir::undirected`	`✔` (default)	Either end of the relationship may be on the row or column axis.
`Dir::row2col`	`↗`	Source must be a row element, target must be a column element.
`Dir::col2row`	`↙`	Source must be a column element, target must be a row element.

view myAllocationMatrix : MatrixView {
    view :>> rowView {
        expose MyModel::LogicalFunctions::*;
        filter hastype SysML::ActionUsage;
    }
    view :>> columnView {
        expose MyModel::PhysicalComponents::*;
        filter hastype SysML::PartUsage;
    }
    view :>> cellView {
        expose MyModel::**;
        attribute :>> direction = Dir::row2col; // function -> component
    }
}

Strong vs Weak Matching

Relationships in SysML are written at the usage level: a connection or allocation names specific usage instances as its endpoints. The matrix axes, however, are often populated with definitions. The matrix bridges this gap by expanding each endpoint through two levels.

Strong Match

When an endpoint of a relationship is a usage, the matrix automatically considers the definition that types it as an additional candidate. This is the primary mechanism that makes definition-axis matrices work without requiring every relationship to reference definitions explicitly.

For example, if engine : Engine and powertrain : Powertrain are connected, and the matrix axes contain Engine and Powertrain definitions, that connection produces a strong match for the Engine x Powertrain cell because Engine is the direct type of engine and Powertrain is the direct type of powertrain.

// Matrix with Engine (rows) x Powertrain (columns):
part def Engine;
part def Powertrain;

part def Vehicle {
    part engine : Engine;
    part powertrain : Powertrain;

    // strong match: Engine and Powertrain are direct types
    connect engine to powertrain;
}

Weak Match

A weak match occurs when the axis element is not the direct type of a usage endpoint, but is reachable through the heritage chain of that type. Using the same example: if the matrix also has a PoweredComponent axis element that Engine specialises, the PoweredComponent x Powertrain cell would be weakly marked, because PoweredComponent is an ancestor of Engine, not its direct type.

// Matrix with PoweredComponent (rows) x Powertrain (columns):
part def PoweredComponent;
part def Engine :> PoweredComponent;
part def Powertrain;

part def Vehicle {
    part engine : Engine;
    part powertrain : Powertrain;

    // weak match: Engine is a descendant of PoweredComponent,
    // not its direct type
    connect engine to powertrain;
}

By default, weak matches are hidden. The showWeakTraceability attribute on cellView controls this (see Matrix Attributes). When both a strong and a weak match exist for the same cell, the strong match takes precedence.

Editable Matrix Views

Editable matrix views allow adding and removing relationships directly from the matrix UI. Rather than writing a custom filter, pick one of three concrete presets from the SysideViews library, each specialised for a specific relationship type:

Preset	Relationship type	Created pattern
`MVD::ConnectionMatrixView`	`ConnectionUsage`	`connection connect a to b`
`MVD::AllocationMatrixView`	`AllocationUsage`	`allocate a to b`
`MVD::RequirementMatrixView`	Requirement derivation	#RequirementDerivation::DerivationMetadata connection { end #RequirementDerivation::OriginalRequirementMetadata ::> a; end #RequirementDerivation::DerivedRequirementMetadata ::> b; }

All three presets inherit from EditableMatrixView, which automatically restricts rowView and columnView to Definition elements (filter istype SysML::Definition); this filter does not need to be written explicitly.

Warning

The cellView expose of an editable preset must point to a single Type (not a package wildcard). The extension walks all features of that type, looking for Usages directly typed by a Definition on the row or column axis. This is how new relationships are anchored when a cell is clicked to create one.

Matrix Attributes

Set on rowView, columnView, or cellView as noted.

Attribute	Set on	Default	Description
`representation`	rowView, columnView	`Rep::name`	Label shown in matrix headers. Values: `Rep::name`, `Rep::shortName`, `Rep::qualifiedName`. See Header Representation.
`verticalColumnNames`	rowView, columnView	`false`	Rotates column header text 90 degrees to save horizontal space. Toggleable in the UI. See Header Representation.
`direction`	cellView	`Dir::undirected`	Constrains which end of a relationship may sit on which axis. See Directional Matching.
`showWeakTraceability`	cellView	`false`	Includes weak matches alongside strong matches. See Strong vs Weak Matching.
`portsAreTransparent`	cellView	`false`	Treats connections to a port as direct connections to the port’s owner. Applies to `ConnectionUsage` only; has no effect on `AllocationUsage`, derivation relationships, or relationship creation in editable matrices. See Port Transparency.

Header Representation

The representation attribute controls the label text shown in matrix headers. Rep is the short alias for MatrixElementRepresentation:

view :>> rowView {
    expose MyModel::Requirements::*;
    filter hastype SysML::RequirementUsage;
    attribute :>> representation = Rep::shortName; // show <'REQ-001'> etc.
}

The verticalColumnNames attribute rotates column headers 90 degrees to save horizontal space when there are many columns:

view :>> columnView {
    expose MyModel::Components::*;
    filter hastype SysML::PartUsage;
    attribute :>> verticalColumnNames = true;
}

Matrix with column headers rotated 90 degrees using verticalColumnNames

Port Transparency

When portsAreTransparent is set to true, connections to a port are treated as direct connections to the port’s owner. This is useful when connections are wired through ports and the matrix should show the logical owner-to-owner relationship rather than owner-to-port:

part def Sender {
    port out : DataPort;
}
part def Receiver {
    port in : DataPort;
}
part def System {
    part s : Sender;
    part r : Receiver;
    connect s.out to r.in;
}

Without portsAreTransparent, the matrix would not mark the Sender x Receiver cell because the connection endpoints are ports, not the parts themselves. With it set, the port lookup is transparent and the cell is marked:

view :>> cellView {
    expose MyModel::System::*;
    attribute :>> portsAreTransparent = true;
}

Complete Example

A reference template combining an editable preset, a ContentView flag, and matrix attributes:

package MyViews {
    private import SysideViews::*;

    view myAllocationMatrix : MVD::AllocationMatrixView {
        view :>> rowView {
            expose MyModel::LogicalFunctions::*;
            filter hastype SysML::ActionUsage;
            attribute :>> exposeFeaturesAndHeritage = true; // from ContentView, see Foundations
            attribute :>> representation = Rep::shortName;
        }
        view :>> columnView {
            expose MyModel::PhysicalComponents::*;
            filter hastype SysML::PartUsage;
            attribute :>> verticalColumnNames = true;
        }
        view :>> cellView {
            expose MyModel::Traceability::TraceabilityContext;
            attribute :>> direction = Dir::row2col; // function -> component
            attribute :>> showWeakTraceability = true;
        }
    }
}