SysML-Sandbox

A SysMLv2 sandbox based on Eve Online. Eve Online sets the backstage for experimenting with SysMLv2 with support of AI (Large Language Models) given the extensive freely open documentation available and the possibility to experience first hand the systems to be modelled. Experience in the game, even limited to a basic tutorial, is needed to understand the models. The game is Free-to-Play at eveonline.com.

This package is the approved baseline of a larger modeling effort. You do not edit it: you build your own project on top of it, as a contributor to a large programme builds on the released main branch.

The model: a mining frigate in a mining operation

The model follows one thread from a business goal down to the products that are bought off the shelf: a mining corporation needs its pilots to earn a competitive income; that need is broken down into the mining rate of a Venture-class mining frigate, then into its mining lasers, its yield enhancer, its ship controller and processor, and its power subsystem, until every branch ends in a component or a commercial off-the-shelf (COTS) product.

On the way the model shows:

• a concept of operations (ConOps) and an operational concept (OpsCon), with the causal effects that make an operation profitable or safe;
• requirements that are derived level by level, with budgets allocated by analysis;
• the frigate seen as a blackbox, a graybox (its logical architecture), and a whitebox (its integration with ports and interfaces);
• alternative laser fittings released as configurations, and one doctrine per security zone chosen by trade study;
• two standards: the Imperial fitting standard (how modules fit a ship) and the capsule standard (how a pilot flies a ship);
• COTS products with supplier-declared behavior and states;
• verification cases that check the requirements against the integrated configurations.

The model is structured by the Recursive Architecture Wave Pattern (RAWP), by Hugo Ormo: the same blackbox → graybox → whitebox wave repeats at every level, and each level hands its children their needs. The RAWP Framework is copied into Framework/ and tailored: the operational level does not use UAF, so it is built from the same kind of files as the other levels.

Suggested reading order

1. Level 0 - MiningOperations/MiningOperations_LifeCycleConcepts.sysml: why the operation exists and what makes it profitable.
2. Level 0 - MiningOperations/MiningOperations_Requirements.sysml and _AnalysisCases.sysml: the pilot income requirement and how it is split into budgets.
3. Level 0 - MiningOperations/MiningOperations_Configuration.sysml: the operation's context, which your project extends.
4. Level 1 - Systems/MiningFrigate/MiningFrigate_Configuration.sysml: the frigate's blackbox, graybox, and whitebox, and its released configurations.
5. Level 2 - Subsystems/MiningLaser: a subsystem realized by COTS products, with their states.
6. Level 2 - Subsystems/ShipController: a designed leaf with its own behavior.
7. Level 2 - Subsystems/PowerSubsystem and its components in Level 3 - Components: a subsystem decomposed one level further.
8. The _VerificationCases files: how each requirement is verified.

Your task: a transport ship

Today every mining frigate warps back and forth to a refinery to unload its ore. The ConOps captures that loss only as an assumption: the logisticsEfficiency of the operation (the time the frigates lose to hauling) is a scenario value. Your task is to design a transport ship that collects the ore in the belt, so the frigates keep mining. That is a new solution on the existing set-up:

• new operational scenarios in a new OpsCon,
• new needs and requirements, and
• new architecture elements: the transport ship, its decomposition, and its integration into the operation.

Treat it as exploratory work that a change control board (CCB) would review: once approved, it would become a new doctrine of the corporation.

1. Set up your project

You need sysand and the Syside CLI.

mkdir transport-ship && cd transport-ship
sysand init --publisher <your-name> --name transport-ship
sysand add hugoormo/sysmlv2-sandbox "^1.0.0"

The version constraint ^1.0.0 pins your project to the 1.x baseline: it accepts any 1.x release and never a 2.0.0, which may change the baseline in ways your model must follow. sysand-lock.toml records the exact version you use.

sysand add installs the sandbox under .sysand/lib/, where you can read it. Do not edit it there: your work goes in your own files.

2. Mirror the sandbox's layout

Create your files in the same folder and package scheme as the sandbox:

Level 0 - HaulingOperations/HaulingOperations_Configuration.sysml
Level 1 - Systems/TransportShip/TransportShip_Taxonomy.sysml
Level 1 - Systems/TransportShip/TransportShip_Configuration.sysml

Your packages share one namespace with the sandbox's, so never reuse a sandbox package name (e.g. do not create your own MiningOperations_Configuration).

3. Give the transport ship a context

The transport ship is a new L1 system: a taxonomy collection and a context with its blackbox.

package TransportShip_Taxonomy {
    doc
    /* The vocabulary of the transport ship. */

    abstract part transportShips subsets MySystemOntology::systems [0..*] {
        doc
        /* The transport ships that haul ore from the mining frigates to the refinery. */
    }
}

package TransportShip_Configuration {
    doc
    /* The transport ship is described in this package. */

    private import MyFramework::MyFrameworkSystemArchitecture::**;

    part def TransportShipContext {
        doc
        /* Context of the transport ship. */

        #BlackBox part transportShip_bb subsets TransportShip_Taxonomy::transportShips [1] {
            doc
            /* The transport ship as a whole. */
        }
    }
}

4. Specialize the operational context

You cannot change MiningOperationsContext, but you can specialize it. Your context inherits everything the sandbox has (the frigate, the pilot, the asteroid belt, the requirements, the whitebox integration) and adds the transport ship: it mounts the ship's context, adds the ship to the graybox, and carries it into the whitebox.

package HaulingOperations_Configuration {
    doc
    /* The mining operation extended with a transport ship that hauls the ore. */

    private import MyFramework::MyFrameworkSystemArchitecture::**;

    part def HaulingOperationsContext specializes MiningOperations_Configuration::MiningOperationsContext {
        doc
        /* The mining operation of the sandbox, extended with a transport ship. */

        part transportShipContext defined by TransportShip_Configuration::TransportShipContext [1] {
            doc
            /* The mounted L1 configuration of the transport ship. */
        }

        #GrayBox part miningOperation_gb redefines miningOperation_gb {
            doc
            /* The mining operation decomposed into its constituents, now including the
             * transport ship.
             */
            part transportShip subsets transportShipContext.transportShip_bb [1] {
                doc
                /* The transport ship that hauls the ore. */
            }
        }

        #WhiteBox part miningOperation_wb redefines miningOperation_wb subsets miningOperation_gb {
            doc
            /* The integration of the mining operation, now including the transport ship. */
            part transportShip redefines HaulingOperationsContext::miningOperation_gb::transportShip {
                doc
                /* The transport ship's contract. */
            }
        }
    }
}

Two details matter:

• The graybox and the whitebox are both redefined. The sandbox's whitebox subsets the sandbox's graybox, so a whitebox you do not redefine never sees your transport ship.
• Your whitebox subsets miningOperation_gb, which inside your context is your redefined graybox.

5. Register your files and check

sysand only knows the files you include. Include each new file once, then check your project together with the sandbox:

sysand include "Level 1 - Systems/TransportShip/TransportShip_Taxonomy.sysml"
sysand include "Level 1 - Systems/TransportShip/TransportShip_Configuration.sysml"
sysand include "Level 0 - HaulingOperations/HaulingOperations_Configuration.sysml"
sysand sources | tr '\n' '\0' | xargs -0 syside check

If syside check reports "No files found", it has checked nothing: a file is not included yet.

6. Where to go next

From here, follow the wave the sandbox shows, level by level:

1. OpsCon: describe how the transport ship changes the operation (new scenarios, the ship as a new role), in your own HaulingOperations_LifeCycleConcepts.
2. ConOps and analysis: turn the logisticsEfficiency assumption into the transport ship's contribution, and show the effect on the pilot's income.
3. Needs and requirements: every constituent the graybox introduces receives a vertical need. Specialize the sandbox's derived operational requirement to add the transport ship's need, then transform it into the ship's own requirement.
4. The transport ship's own wave: its Needs use case, graybox, whitebox, and leaves, in Level 1 - Systems/TransportShip and below.
5. A doctrine: release your operation as a configuration (an instance of HaulingOperationsContext), as the sandbox's MiningOperationsConfigurations does, and verify it.

Values the sandbox binds with = are commitments of the baseline and cannot be redefined. Values it gives with default are assumptions you may redefine in your own context. The assumptions are the operating conditions of the two nominal scenarios, lowSecNominalScenario and highSecNominalScenario in MiningOperations_AnalysisCases::MiningOperationsAnalysisContext, logisticsEfficiency among them. A redefinition in your own analysis context is a new scenario, not a change to the baseline:

part def HaulingAnalysisContext specializes MiningOperations_AnalysisCases::MiningOperationsAnalysisContext {
    attribute redefines lowSecNominalScenario {
        attribute redefines logisticsEfficiency = 1.0;
    }
}

Modeling conventions

These are the conventions the sandbox follows, and your project should follow them too. The normative text is the Framework itself: each section names the Framework rules it follows (search Framework/Framework.sysml for the rule name).

Folder and file layout

Each element has its own folder, and each file in it holds one package named <Element>_<Kind>:

An element has only the files it needs: a leaf has a _Behavior file, and a decomposed element has none.

Framework rules: localTaxonomyOwnershipRule, foundationLayeringRule, attributeDeclarationPlacementRule.

Definitions and usages

• Structural definitions (part, item, port, interface, connection defs) live only in _Taxonomy packages, the Framework, the COTS library, and the standards. The other part defs are contexts: each element's context and its configurations collection in _Configuration, and the analysis context in _AnalysisCases.
• Each other file kind defines only its own kind of element: requirement defs in _Requirements, use case defs in _UseCases and _LifeCycleConcepts, action defs in _Behavior, analysis and verification defs in _AnalysisCases and _VerificationCases.
• The system itself is built from usages that subsets or redefines other usages. Structure is not built by specializing part defs, with one exception: a contributor extends a released context it cannot edit by specializing it, as in step 4 of the task.
• Concrete usages are owned by a context part def, never declared directly in a package. A parent context mounts the child's context as a part (part powerGeneratorContext defined by PowerGenerator_Configuration::PowerGeneratorContext [1]). Abstract collections in a package (e.g. abstract part transportShips) are allowed.
• A feature of a part def is reached through a usage that mounts it, never by a qualified name into the def.

Relationship keywords and imports

• Write specializes, subsets, redefines, references, and defined by in full. The shortcut operators :>, :>>, ::>, and : are not used in the model, because they hide which relationship is meant. The Framework copy keeps RAWP's original notation in a few places.
• In a flow, subsets comes before of.
• Wildcard imports (private import Pkg::**;) go at the top of the package. A single-element import goes in the innermost namespace that uses it (e.g. inside the requirement that nests #Need requirements).

The box wave: blackbox, graybox, whitebox

Every element's context holds three views of the element, each subsetting the previous one:

A child need on the parent's graybox becomes the child's transformed requirement on its blackbox: the wave repeats at every level until the leaves. Every constituent the graybox introduces receives a vertical need, either a budget or a functional need.

Framework rules: recursiveClosureRule, grayboxDecompositionRule, parentGrayboxToChildBlackboxRule, whiteboxMountingTunnelingRule, whiteboxValuePlacementRule, immutableValueCommitmentRule.

Configurations and alternatives

• No variation/variant notation.
• Where alternatives coexist (the three COTS mining lasers, the security-zone doctrines), the element releases configurations: separate instances of the whole context, collected in a configurations part def (e.g. MiningFrigateConfigurations), each redefining only the replaceable feature.
• Each configuration is evaluated on its own; choosing among released configurations is a trade study over them.
• An element with a single design has no configurations.

Framework rule: configurationReplacementRule.

Behavior

• Above the leaves, behavior is stated by use cases only: the - Needs use case of the _bb and the - Design use case of the _gb, which includes the constituents' - Needs use cases.
• Executable behavior exists only in leaves (designed leaves and COTS products), in the _Behavior package. The leaf's _bb performs it (perform action … references …).
• A state machine is a kind of action and follows the same placement rule. It is exhibited (exhibit state), never performed, and it belongs to the part whose condition it reflects. States take item parameters, not ports, and the whitebox binds the port items to those parameters.
• One leaf action runs once per command: it holds no memory between commands.

Framework rules: delegatedBehaviorExecutionRule, blackboxBehavioralRealizationRule, useCaseIntentTraceabilityRule.

Connections, interfaces, ports

• Designed parts declare no ports. Connections bring interfaces, and interfaces bring ports.
• The graybox connects action parameters only (a logical architecture). The whitebox connection subsets the graybox connection and adds the interface.
• bind statements are written port item left, parameter right (bind <connection>.<interface>.<port>.<item> = <leaf action>.<parameter>;). The parameter's type specializes the port item's type.
• A COTS product on a standard boundary (the Imperial fitting standard) owns no port: it declares its slot category, and the standard's connection brings the ports.

Framework rules: bindVersusFlowSemanticsRule, exchangeContractRequirementRule, bottomUpExchangeRealizationRule, COTSConnectorBoundaryRule.

Requirements

• Each element's requirements are one requirement container def (PowerSubsystemRequirements) with one usage of it.

• A chain keeps one stem across levels, suffixed by the element and the step:

  Name	Meaning
  <stem>Operational	The operational requirement (Level 0 only).
  <stem><Element>	The transformed requirement on the element's blackbox.
  <stem><Element>Derived	The derived requirement on the element's graybox.
  <stem><Constituent>Need	A child need nested in the derived requirement, tagged #Need.
  <stem><Element>Req, <stem><Element>DerivedReq	The satisfy usages on _bb and _gb/_wb.

  Example: pilotProfitabilityPowerSubsystem → pilotProfitabilityPowerSubsystemDerived → pilotProfitabilityPowerGeneratorNeed → pilotProfitabilityPowerGenerator.

• Each requirement statement carries a short name <'REQ-nnnn'> and each verification case usage a short name <'VC-nnnn'>: one sequence per prefix across the model, never reused, encoding nothing. The sandbox uses REQ-0001 to REQ-0043 and VC-0001 to VC-0014; start your own numbering above them.

• Acceptance criteria belong to the requirement. Requirement values come from the requirement chain or an analysis, never from a configuration.

Framework rules: requirementNamingRule, identificationRule, concernFramingRule, lifeCycleConceptRule, standardComplianceOverlayRule.

Analysis and verification

• Analyses specialize the Framework's analysis meta-patterns (AllocationSelectionAnalysis, EvaluationAnalysis, TradeStudyAnalysis). An analysis case has a single return and no out features. A specialized analysis redefines every inherited input explicitly, in order, before adding its own.
• A verification case verifies a satisfy usage on the element's whitebox subject, measuring into the features the requirement constrains. Its objective constraints only add evidential checks.
• Verdicts stay in reference mode: illustrative values are not evidence about a real product.

Framework rules: analysisValuePlacementRule, verificationSubjectAndObjectiveRule, verificationMethodRule, realizedContributionMeasurementRule, referenceModeVerdictRule, illustrativeContentRule, projectAdoptionRule.

Viewpoints and views

• Each developed element has a <Element>_ViewpointsAndViews package in its _StakeholdersViews file. The off-the-shelf mining laser and mining yield enhancer have none: the frigate's views cover them.
• <Element>GenericViews applies the Framework's purpose views (MyFramework::MyFrameworkViews) to the element: requirements traceability, the box views, interface control, compliance, verification planning and more. Each view exposes a whole scope of the element (its requirements, its context, or its whitebox) and leaves the selection to the Framework's filter; no view lists elements by hand. A view with nothing to show for its element, such as the graybox views of a leaf, says so in its doc.
• <Element>ConcernDrivenViews holds a view per concern a stakeholder of that element originates. The view declares its viewpoint inside itself and frames the concern.
• Views live in a context part def, never directly in a package, so they do not become features of every element.
• A diagram renderer such as Syside's draws the selection. The table and matrix renders of the purpose views name their columns as a contract for a tool to implement; a view that selects only interfaces has nothing a diagram can draw.

Framework rules: genericViewpointRule, concernDrivenViewRule, viewLayeringRule.

Standards and COTS

• ImperialStandard regulates how modules are fitted to a ship (slots, the module control channel, the capacitor channel, the power grid capacity). CapsuleStandard regulates the handoff between pilot and ship. An element complies by subsetting the standard's category and exchanging the standard's items. Each compliance claim is verified by the owner of what it inspects.
• MyCOTSLibrary holds one package per product. Several products of one kind share a product-family package (e.g. MiningLaserCOTSProductFamily) that declares the supplier's resources, behavior, and states once; each product package sets only its values.
• Supplier-declared behavior and states are COTS requirements, outside the project's requirement chain.

Documentation and comments

• doc /* … */ describes the element as it is in the model: purpose, rationale, and meaning. It never describes the model's history ("formerly", "no longer", "in a later step").
• Notes for modelers are named comments, comment <name>ModelerComment about <element> locale "en_US" /* … */, so they stay part of the model and can be found.
• // is used only to mark the end of a package (} // package PowerGrid_Behavior).
• Units are stated in the docs of the attributes; mining rate is in m³/s throughout.

Checking

A clean syside check proves that the model is well-formed, not that its values close. Evaluate the values that matter (budgets, closures, verification observations) with the syside Python API.

Known limits

• The values are illustrative, chosen so that the chain closes; they are not game data and are not evidence about real products.

• The model is evaluated statically. The behavior of the exhibited states over time (e.g. the capacitor running empty during a cycle) is modeled but not verified; that would need simulation.

• Syside's evaluator does not carry a redefined assumption into the analyses that use it: it evaluates the nested analysis in the sandbox's definition, so the income stays as in the baseline. The model's meaning is correct. To see the effect in evaluated values, also redefine, empty, each nested usage down to the connections that use the value:

  part def HaulingAnalysisContext specializes MiningOperations_AnalysisCases::MiningOperationsAnalysisContext {
      attribute redefines lowSecNominalScenario {
          attribute redefines logisticsEfficiency = 1.0;
      }
      analysis redefines lowSecPilotProfitabilityAllocationAnalysis {
          use case redefines operationsConcept {
              connection redefines oreExtraction;
              connection redefines pilotIncome;
          }
      }
  }
  

• Only the mining thread is designed down to components. Protection and drone defense enter the operation only as rates in the ConOps; navigation, drone control, scanners, and target locking are not modeled as subsystems.

License

The sandbox is licensed under the MIT License (see LICENSES/MIT.txt). Framework/Framework.sysml and Framework/Ontology.sysml are adapted from RAWP by Hugo Ormo, licensed CC-BY-4.0 (see LICENSES/CC-BY-4.0.txt); the rawpTailoringProvenance comment in Framework.sysml names the source commit and the tailoring. Do not upload copyrighted EVE Online assets (images, sounds, etc.) in work built on the sandbox.

Initiated by

Hugo Ormo is an engineer who studied at ETSEIB in Barcelona. He is a certified GfSE Level A, approved trainer by the GfSE and has been preparing candidates for the GfSE certification levels B and C since 2022. Voluntarily, he leads the UAF working group of GfSE and is a member of the UAF working group of OMG.

Disclaimer

This project is a fan-made educational initiative using EVE Online as a thematic inspiration. EVE Online and all related trademarks are the property of CCP Games. This project is not affiliated with, endorsed by, or sponsored by CCP Games.