OpenSysML

https://opensysml.org
Admin
OpenSysML is an open-source SysML v2 and KerML execution toolchain and runtime that parses,...
Tokens:212,489
Snippets:1,320
Trust Score:4.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Go client

Source: https://opensysml.org/guide/09-clients

Installs the Go client module. The engine and SysML standard library are included in the module, so no additional setup is needed.

```bash
go get github.com/Open-MBEE/OpenSysML@latest

```

--------------------------------

### Install OpenSysML binaries with make install or manual move

Source: https://opensysml.org/guide/01-install

Installs the built binaries to $GOPATH/bin using make install, or manually moves them to /usr/local/bin with sudo. The manual move requires superuser privileges.

```bash
make install     # installs to $GOPATH/bin
# OR
sudo mv bin/sysml bin/sysml-lsp bin/sysml-grpc /usr/local/bin/
```

--------------------------------

### Install @opensysml/client with npm

Source: https://opensysml.org/reference/node-api

Install the package once the first release is published. Nothing is published yet, so a checkout builds it with 'npm install && npm run build' in clients/node.

```bash
npm install @opensysml/client        # once the first release is published

```

--------------------------------

### Usage Example

Source: https://opensysml.org/reference/api

Example of using the runtime API to instantiate a model, get feature values, and invoke calculations.

```APIDOC
## Usage

### Description
Tier 1-3 (Instances & Expressions) usage example.

### Example
```
// The model-derived part (memoized shapes, targets, literals) is built once and
// shared by every context over it; a context is one run's own state.
shared := runtime.NewModel(model, resolver)
// Honour the OPENSYSML_MAX_* budgets instead of the defaults with:
//   budgets, err := runtime.BudgetsFromEnv()
//   err = ctx.SetBudgets(budgets)
ctx := runtime.NewContext(shared, runtime.DefaultMaxSteps)
inst, _ := ctx.Instantiate(wheelSym)
fv, _ := inst.GetFeatureValue(ctx, "diameter")
result, _ := ctx.InvokeCalc(addSym, []Value{v1, v2}, scope)
```
```

--------------------------------

### Install with Go toolchain

Source: https://opensysml.org/guide/01-install

Use the Go toolchain to install OpenSysML and its LSP server locally, which avoids the quarantine attribute since binaries are built locally.

```bash
go install github.com/Open-MBEE/OpenSysML/cmd/sysml@latest
go install github.com/Open-MBEE/OpenSysML/cmd/sysml-lsp@latest
```

--------------------------------

### Command-line examples for requirements model

Source: https://opensysml.org/manual/authoring

Shows three sysml commands to run a query and render the document in Markdown and HTML forms using the requirements.sysml example file.

```shell
$ sysml docs/manual/examples/requirements.sysml -run-query "Requirements::Reqs root=Requirements::spec"
$ sysml docs/manual/examples/requirements.sysml -render-document Requirements::RequirementsReport
$ sysml docs/manual/examples/requirements.sysml -render-document Requirements::RequirementsReport -doc-form html

```

--------------------------------

### Install Python client

Source: https://opensysml.org/guide/09-clients

Installs the Python client via pip and sets the OPENSYSML_GRPC_VERSION environment variable to request a sysml-grpc release. Alternatively, install sysml-grpc yourself.

```bash
pip install opensysml
export OPENSYSML_GRPC_VERSION=latest   # or install sysml-grpc yourself

```

--------------------------------

### Workspace Usage Example

Source: https://opensysml.org/reference/api

Shows how to create a workspace, add a document, and retrieve diagnostics for it.

```go
ws := model.NewWorkspace()
doc := ws.AddDocument("example.sysml", src)
diagnostics := ws.Diagnostics("example.sysml")
```

--------------------------------

### Install OpenSysML binaries and manual pages with make install-tree

Source: https://opensysml.org/guide/01-install

Installs binaries and manual pages to a custom prefix using make install-tree, then verifies with man sysml. This method respects GNU variables like DESTDIR and prefix for packaging.

```bash
sudo make install-tree prefix=/usr/local
man sysml
```

--------------------------------

### Start Interactive REPL (Default)

Source: https://opensysml.org/reference/cli

Starts the SysML REPL with no arguments, entering interactive mode. Use when you want to explore or evaluate expressions interactively.

```bash
sysml

```

--------------------------------

### Install opensysml from PyPI or from a checkout

Source: https://opensysml.org/guide/09-clients

Install the opensysml package from PyPI or from a local checkout. The dependencies grpcio, protobuf>=7.35.1, filelock, and psutil are installed automatically. Requires CPython 3.10 or later.

```bash
pip install opensysml             # from PyPI
pip install -e clients/python/          # or from a checkout, at the repository root
```

--------------------------------

### opensysml/views response example

Source: https://opensysml.org/reference/lsp

Example response from the opensysml/views request, listing views and pseudo-views. Unsupported views include a reason.

```json
{
  "views": [
    { "name": "KitViews::widgetParts", "kind": "interconnection", "supported": true },
    { "name": "KitViews::widgetSequence", "kind": "sequence", "supported": true },
    {
      "name": "KitViews::widgetGeometry",
      "kind": "geometry",
      "supported": false,
      "reason": "KitViews::widgetGeometry: geometry rendering (view def GeometryView) is not supported"
    }
  ],
  "pseudoViews": ["#action", "#interconnection", "#sequence", "#state", "#table", "#tree"]
}
```

--------------------------------

### Launch the SysML v2 REPL

Source: https://opensysml.org/guide/02-first-model

Starts the interactive SysML v2 REPL. The prompt shows the version and available commands.

```text
$ sysml
SysML v2 REPL — %help for commands, Ctrl-D to exit
sysml> 
```

--------------------------------

### Start REPL and evaluate a declaration

Source: https://opensysml.org/guide/04-repl

Shows a complete REPL session: starting sysml, importing ScalarValues, defining a package with a part definition, and evaluating a feature. The import is required to resolve Real; without it, the declaration is rejected with 'unresolved reference: Real'.

```text
$ sysml
SysML v2 REPL — %help for commands, Ctrl-D to exit
sysml> private import ScalarValues::*;
✓ import ScalarValues::*
sysml> package Demo { part def Wheel { attribute diameter : Real = 16.0; } }
✓ package Demo
sysml> %eval Demo::Wheel::diameter
✓ Demo::Wheel::diameter
  = 16.0

```

--------------------------------

### RunSweep request and response example

Source: https://opensysml.org/reference/wire-contract

Example of a RunSweep request and its response, showing a sweep over parameter 'b' with integer values -1, 0, and 1. The response includes rows with inputs, outputs, and for the failed row, an error and failure reason. The example demonstrates the response format with parameters and rows.

```shell
$ … /RunSweep -d '{"modelHash":"a6dc…4849","symbolId":"An::CostAnalysis","subjectSymbolId":"An::barge","ranges":[{"parameter":"tax","start":{"realValue":0.0},"end":{"realValue":1.0},"step":{"realValue":0.5}}]}'
```

```json
{"rows":[{"inputs":[{"name":"b","value":{"intValue":"-1"}}],"outputs":[{"name":"result","value":{"realValue":-4}}],"elapsedMicros":"18"},
         {"inputs":[{"name":"b","value":{"intValue":"0"}}],"elapsedMicros":"6",
          "error":"calc An::Ratio: evaluating the returned expression: division by zero","failureReason":"FAILURE_REASON_EVALUATION"},
         {"inputs":[{"name":"b","value":{"intValue":"1"}}],"outputs":[{"name":"result","value":{"realValue":4}}]}],
 "parameters":["b"]}
```

--------------------------------

### Stage OpenSysML installation for packaging with DESTDIR

Source: https://opensysml.org/guide/01-install

Stages the installation into a package build root without writing outside it. The DESTDIR variable is set to the package directory and prefix to /usr, allowing distribution packages to collect files.

```bash
make install-tree DESTDIR="$pkgdir" prefix=/usr
```

--------------------------------

### ExecuteAction with default schedule (reverse)

Source: https://opensysml.org/reference/wire-contract

Example request and response for ExecuteAction with no schedule specified, showing the default reverse policy and a choice-point diagnostic.

```shell
$ … /ExecuteAction -d '{"modelHash":"81b1…73fc","actionSymbolId":"Test::tally"}'
{"outputs":{"leftCount":{"intValue":"1"},"rightCount":{"intValue":"10"}},"diagnostics":[{"severity":"info","message":"choice point: step 3: tokens 2@left, 3@right (unordered; took 3@right first)","span":{"file":"tally.sysml","startLine":2,"startCol":2,"endLine":20,"endCol":2},"code":"choice-point"}]}
```

--------------------------------

### In-body failure examples for various methods

Source: https://opensysml.org/reference/wire-contract

Examples of in-body failure responses for Instantiate, ExecuteState, and Evaluate methods. Each shows the error message and optional failureReason. The Python client maps 'symbol not found:' to SymbolNotFoundError and other errors to ModelError or ExecutionError.

```text
$ … /EvaluateCalc -d '{"modelHash":"b4e0…ded9","symbolId":"Demo::sedan"}'
{"error":"calc invocation failed: not a calc: Demo::sedan is a part usage, not a calc definition or usage","failureReason":"FAILURE_REASON_WRONG_KIND"}
```

```text
{"error":"symbol not found: Demo::Nope"}                                    Instantiate
{"error":"state machine not found: Test::NoMachine"}                        ExecuteState
{"error":"action execution failed: initialize action: invalid action flow: no initial node found in action noStart"}
{"error":"evaluation failed: object has no such feature: member nothing not found in instance"}  Evaluate
{"error":"evaluation failed: unresolved reference: sqrt — did you mean RealFunctions::sqrt or QuantityCalculations::sqrt?"}
```

--------------------------------

### RunAnalysis with verification verdicts

Source: https://opensysml.org/reference/wire-contract

Runs a verification case and returns outputs, verdicts, instances, and verification verdicts. The example shows a pass verdict for the case and a pass for the subcase.

```shell
$ … /RunAnalysis -d '{"modelHash":"96c9…994d","symbolId":"Ver::checkSlow"}'
{"outputs":[{"name":"result","value":{"enumLiteral":{"literalId":"VerificationCases::VerdictKind::pass","enumerationId":"VerificationCases::VerdictKind","name":"VerdictKind::pass"}}}],"verdicts":[{"kind":"objective","elementId":"Ver::checkSlow::obj","element":"obj","holds":true,"instanceId":"1","instanceTypeId":"Ver::slow"}],"instances":[…],"verificationVerdicts":[{"caseId":"Ver::checkSlow","kind":"pass"}]}
```

--------------------------------

### Parse, evaluate, and re-parse with -cache-size 1

Source: https://opensysml.org/reference/wire-contract

Shows a sequence of commands against a service started with -cache-size 1. The first ParseSources returns a hash, Evaluate succeeds, then parsing a second model evicts the first. Evaluating the evicted hash returns 404 with "model not found:", and re-parsing the original document returns the same deterministic hash.

```shell
$ … /ParseSources -d '{"documents":[{"name":"a.sysml","content":"package A { attribute x = 1; }"}]}'
{"modelHash":"f90104e75e9172ab29c8648e3529a103e178756d35b4643d03c8c64419eaabae","roots":[{"kind":"RootNamespace","childIds":["A"]}]}

$ … /Evaluate -d '{"modelHash":"f90104e75e9172ab29c8648e3529a103e178756d35b4643d03c8c64419eaabae","expression":"A::x"}'
{"result":{"intValue":"1"}}

$ … /ParseSources -d '{"documents":[{"name":"b.sysml","content":"package B { attribute y = 2; }"}]}'
{"modelHash":"ca693643bf449df4d2904900963596195409a34bbc51f243964952077ab99eb3","roots":[{"kind":"RootNamespace","childIds":["B"]}]}

$ … /Evaluate -d '{"modelHash":"f90104e75e9172ab29c8648e3529a103e178756d35b4643d03c8c64419eaabae","expression":"A::x"}'
HTTP/1.1 404 Not Found
{"code":"not_found","message":"model not found: f90104e75e9172ab29c8648e3529a103e178756d35b4643d03c8c64419eaabae"}

$ … /ParseSources -d '{"documents":[{"name":"a.sysml","content":"package A { attribute x = 1; }"}]}'
{"modelHash":"f90104e75e9172ab29c8648e3529a103e178756d35b4643d03c8c64419eaabae","roots":[{"kind":"RootNamespace","childIds":["A"]}]}

```

--------------------------------

### RunAnalysis command and response with evaluations

Source: https://opensysml.org/reference/wire-contract

Shows a `RunAnalysis` command with a JSON request and the corresponding response containing `evaluations` for three alternatives. The response includes `outputs`, `verdicts`, `instances`, and `evaluations` with `selected` and `tied` flags. The example illustrates a tie where two alternatives have the same result, with the first selected and the second marked as tied.

```json
$ … /RunAnalysis -d '{"modelHash":"3f1a…50c2","symbolId":"Trade::lightest","schedule":"explore"}'
{"outputs":[{"name":"selectedAlternative","value":{"instanceId":"2"}}],
 "verdicts":[{"kind":"objective","elementId":"Trade::lightest::tradeStudyObjective","element":"tradeStudyObjective","holds":true}],
 "instances":[{"id":"1","typeSymbolId":"Trade::a",…},{"id":"2","typeSymbolId":"Trade::b",…},{"id":"3","typeSymbolId":"Trade::c",…}],
 "evaluations":[{"functionId":"Trade::lightest::evaluationFunction","arguments":[{"instanceId":"1"}],"result":{"realValue":30}},
                {"functionId":"Trade::lightest::evaluationFunction","arguments":[{"instanceId":"2"}],"result":{"realValue":10},"selected":true},
                {"functionId":"Trade::lightest::evaluationFunction","arguments":[{"instanceId":"3"}],"result":{"realValue":10},"tied":true}]}
```

--------------------------------

### VerifyConstraint response with instances

Source: https://opensysml.org/reference/wire-contract

The response for the third VerifyConstraint example, showing a verdict without a holds key (indicating false) and the instances array with the instantiated sedan. The instanceId and instanceTypeId fields are present because a subject was instantiated.

```json
{
  "verdict": {
    "kind": "constraint",
    "elementId": "Demo::Vehicle::massLight",
    "element": "Demo::Vehicle::massLight",
    "condition": "mass < 100.0",
    "instanceId": "1",
    "instanceTypeId": "Demo::sedan"
  },
  "instances": [
    {
      "id": "1",
      "typeSymbolId": "Demo::sedan",
      "featureValues": {
        "lightEnough":  {"featureName": "lightEnough"},
        "mass":         {"featureName": "mass", "value": {"realValue": 1200}, "materialized": true},
        "massLight":    {"featureName": "massLight"},
        "massPositive": {"featureName": "massPositive"},
        "tiny":         {"featureName": "tiny"}
      }
    }
  ]
}
```

--------------------------------

### ExecuteAction with declared schedule and invalid seed error

Source: https://opensysml.org/reference/wire-contract

Two examples: one showing the response with the 'declared' schedule, and one showing a 400 error for an invalid seed value.

```shell
$ … /ExecuteAction -d '{"modelHash":"81b1…73fc","actionSymbolId":"Test::tally","schedule":"declared"}'
{"outputs":{"leftCount":{"intValue":"1"},"rightCount":{"intValue":"10"}},"diagnostics":[{"severity":"info","message":"choice point: step 3: tokens 2@left, 3@right (unordered; took 2@left first)","span":{"file":"tally.sysml","startLine":2,"startCol":2,"endLine":20,"endCol":2},"code":"choice-point"}]}
```

```shell
$ … /ExecuteAction -d '{"modelHash":"81b1…73fc","actionSymbolId":"Test::tally","schedule":"seed:abc"}'
HTTP/1.1 400 Bad Request
{"code":"invalid_argument","message":"invalid scheduling policy \"seed:abc\": seed \"abc\" is not a non-negative decimal integer"}
```

--------------------------------

### Build and run the LSP server

Source: https://opensysml.org/internals/architecture

Builds the sysml-lsp binary and runs it in stdio mode for editor integration. Requires Go toolchain.

```shell
go build -o sysml-lsp ./cmd/sysml-lsp
./sysml-lsp  # stdio mode for editors

```

--------------------------------

### Load model and evaluate from Node.js

Source: https://opensysml.org/guide/09-clients

Imports `loads` from `@opensysml/client` to load a SysML model from a string, then evaluates an expression, gets a symbol, and instantiates a part. Uses `await using` for async-disposable cleanup. The package is not published yet; build it from a checkout with `npm install && npm run build` in `clients/node`.

```javascript
import { loads } from "@opensysml/client";

await using model = await loads(`package Demo {
  part def Wheel { attribute radius : ScalarValues::Real = 0.3; }
  part def Car { part wheels : Wheel[4]; attribute mass : ScalarValues::Real = 1500.0; }
}`);

const value = await model.eval("2 + 2");
const car = await model.symbol("Demo::Car");
const tree = await model.instantiate("Demo::Car");
tree.get("wheels");
```

--------------------------------

### Install OpenSysML with Homebrew or Go

Source: https://opensysml.org/

Install OpenSysML on macOS using Homebrew or with a Go toolchain. The Homebrew command installs the 'opensysml' tap, while the Go command installs the 'sysml' command-line tool.

```bash
# macOS
brew install Open-MBEE/tap/opensysml

# with a Go toolchain
go install github.com/Open-MBEE/OpenSysML/cmd/sysml@latest
```

--------------------------------

### opensysml/views request example

Source: https://opensysml.org/reference/lsp

Example request body for the opensysml/views request, specifying the text document URI.

```json
{ "textDocument": { "uri": "file:///tmp/kit.sysml" } }
```

--------------------------------

### Command-line migration examples

Source: https://opensysml.org/reference/sysml-v1-migration

Shows four command-line invocations of the `sysml` tool to convert SysML v1 models to SysML v2 notation or RDF, with optional migration reports and explicit input format. The input format is inferred from `.xmi`, `.uml`, and `.mdzip` extensions; other names require `-from xmi`. `-convert xmi` is refused because v2 has no v1 form.

```bash
sysml Model.xmi   -convert sysml -o Model.sysml -migration-report Model.report.txt
sysml Model.uml   -convert ttl   -o Model.ttl   -migration-report Model.report.json
sysml Model.mdzip -convert sysml -o Model.sysml
sysml export.xml  -convert sysml -from xmi
```

--------------------------------

### Run conformance suite for all protocols

Source: https://opensysml.org/reference/service-transports

Runs the entire conformance scenario list against all three protocols (gRPC, Connect with protobuf body, Connect with JSON body) using make conformance.

```shell
$ make conformance                                    # all three protocols

```

--------------------------------

### Install via Homebrew with explicit tap trust (macOS)

Source: https://opensysml.org/guide/01-install

Alternative Homebrew installation that taps the repository, trusts the formula (or tap), and then installs. Required when not using the fully qualified name due to Homebrew 6 trust requirements.

```bash
brew tap Open-MBEE/tap
brew trust --formula Open-MBEE/tap/opensysml   # or: brew trust Open-MBEE/tap, for the whole tap
brew install opensysml

```

--------------------------------

### Run all tests and build

Source: https://opensysml.org/internals/architecture

Use `go test ./...` to run all tests and `go build ./...` to ensure a clean build. These commands verify that all tests pass and the project compiles without errors.

```bash
go test ./...
```

```bash
go build ./...
```

--------------------------------

### Engine manifest entry example

Source: https://opensysml.org/reference/external-engines

Example of an engine manifest entry in JSON, showing the required members and their values for a spin-bridge engine.

```json
{
  "kind": "engine",
  "name": "spin-bridge",
  "version": "1.4.0",
  "command": ["/opt/spin-bridge/bin/spin-bridge", "--serve"],
  "transport": "stdio",
  "protocol": 1,
  "answers": ["holds", "outcomes"],
  "subjects": ["action"],
  "model": ["sources", "graphs:1"],
  "bounds": ["depth", "steps", "runs"],
  "witness": "schedule",
  "authority": "bounded"
}
```

--------------------------------

### Five ways to provide the sysml-grpc binary

Source: https://opensysml.org/guide/09-clients

Commands and environment variables to provide the sysml-grpc binary. Options include downloading a release, setting OPENSYSML_GRPC_VERSION, building from source, setting OPENSYSML_BINARY, or installing on PATH. The binary is located in the order: $OPENSYSML_BINARY, ~/.opensysml/bin/sysml-grpc, a release download, then sysml-grpc on $PATH.

```bash
# 1. Download the release build (verified against the digest pinned in opensysml)
python -c "from opensysml.binary import download_binary; download_binary('latest')"

# 2. Have opensysml.connect() download it on first use
export OPENSYSML_GRPC_VERSION=latest      # or a tag like v0.0.5

# 3. Build from source
make build-grpc && mkdir -p ~/.opensysml/bin && cp bin/sysml-grpc ~/.opensysml/bin/

# 4. Name a build to start, wherever it is
export OPENSYSML_BINARY=$PWD/bin/sysml-grpc

# 5. Install one on $PATH, with a package manager or `go install`
```

--------------------------------

### Load a SysML file with sysml

Source: https://opensysml.org/reference/cli

Loads the file 'demo.sysml' and summarizes the declared package and part definition. The REPL prompt is shown after the summary.

```shell
$ sysml demo.sysml
package Demo
  part def Vehicle {
    attribute speed : Real;
  }
SysML v2 REPL — %help for commands, Ctrl-D to exit
sysml> 

```

--------------------------------

### Install Node/TypeScript client

Source: https://opensysml.org/guide/09-clients

Installs the Node client package and sets OPENSYSML_GRPC_VERSION to request a sysml-grpc release. The package is not published yet, so this command is for after the first release.

```bash
npm install @opensysml/client          # once the first release is published
export OPENSYSML_GRPC_VERSION=latest

```
Tokens:
Raw