Getting Started - planetaryutilities/kotar-support GitHub Wiki

Kotar Overview

Kotar is a browser-based engineering environment for working with SysML v2 and KerML models. It combines textual and graphical model authoring with IDE-style capabilities such as diagnostics, navigation, command-line tools, data handling, and model analysis.

This guide introduces the basic workflow for using Kotar.

For a complete description of available capabilities, see the User Manual(User-Manual).

1. Open Kotar

Open the Kotar URL provided by your organization or administrator.

Depending on your deployment, authentication may be required before Kotar opens.

After startup, Kotar displays the main engineering workspace.

The interface follows the general layout of a modern development IDE. See the diagram below for a quick tour, starting on the left panel and moving clockwise:

  1. Workspace / File Explorer
  2. Textual Model Editor
  3. Graphical Model Editor
  4. Helpful Tools
    • Problems panel
    • Output panel
    • Terminal
    • REPL
    • Version-control tools
    • Tables and data tools
    • Model repository tools
  5. Model Browser

You can easily control the panels that are displayed with the quick layout buttons:

Figure 1: Kotar Overview Diagram

2. Create or Open a Workspace

A workspace is the primary working context in Kotar.

A workspace contains the files, models, scripts, data, and other engineering artifacts associated with a project or activity.

Depending on your environment, a workspace may be created from:

  • a local file directory on the device running Kotar
  • an existing Git repository
  • a project retrieved from a remote SysML v2 service

For your first workspace choose "Create from local folder" and select a location to save your files.

Figure 2: Kotar Workspace Diagram

Saving your work

If you followed the steps above you already connected Kotar to your local file system. You can save your work by selecting File >> Save.

Please note: to protect the privacy of your data by default Kotar does not save any data to the cloud, external servers or local files until you explicitly choose to do so (if you followed the step above you opted to store files locally on your computer). All files are initially stored in a virtual file system, local to the browser Kotar is running in. The virtual file system is not intended to store data long term nor make it available on other devices. If you want to save your work or transfer it to other devices you have the options below:

  • save files to a local directory on the device running Kotar (what you did in the example above)
  • connect a remote git repository to commit and push the textual files (see the User Manual for more info)
  • connect a remote SysMLv2/Flexo service to commit and push the entire model in a graphical database (see the User Manual for more info)

3. Editing/Viewing Your First Model

Use the File Explorer (see Figure 1) to locate a .sysml file. If you are starting a new model, create a new .sysml file in the workspace. Select the file to open it in the textual editor. Edit the SysML or paste the example below.

View your model in the Graphical Model Editor. Note: You can filter the graphical view by package.

Example SysML:

package Example {
 
    part def Vehicle;
 
    part vehicle : Vehicle;
 
}

Kotar analyzes SysML v2 model content as it is edited and provides language-aware functionality such as syntax and semantic analysis.

4. Edit the Model

Edit the SysML v2 text directly in the editor.

As you work, Kotar provides IDE-style assistance such as:

  • syntax highlighting
  • diagnostics
  • code completion
  • navigation
  • model validation
  • formatting
  • linting and quick fixes

Example: quickly jump to the definition of a usage by right-click >> Go to Definition or using the keyboard shortcut (cmd F12).

5. Units, Quantities and Calculations

Kotar helps you model with units and quantities. Try adding units to a value and Kotar will recognize the unit and help you import and type the by the appropriate quantity. Units and quantities come from the SysML v2 standard libraries.

Kotar also performs caluclations automatically and displays the results in line for you. Try the example below to see both in action:

package Package1 {
    private import SI::m;
    private import SI::cm;
    attribute a : ISQ::LengthValue = 5 [m];
    attribute b : ISQ::LengthValue = 10 [cm];

    attribute c : ISQ::LengthValue = a + b;
}

6. Detecting and Resolving Model Problems

As you work, Kotar automatically detects problems in the model. Detected model problems are shown using familiar severity levels such as:

  • Hint
  • Warning
  • Error

To see the problems in your model open the Problems panel by choosing the appropriate Quick Layout button (see figure 1) or by selecting the problem counter at the bottom of the page.

Problems may result from:

  • syntax errors;
  • semantic errors;
  • validation rules;
  • lint rules;
  • other model-analysis checks.

Selecting a problem navigates directly to the affected model element.

Example

The model is missing a ';' at the end of line 5. Selecting the problem in the Problems tab highlights the problem in the model.

7. Apply Quick Fixes

Some diagnostics and linting rules provide automatic corrections.

When a quick fix is available:

  1. Hover over the affected model element or diagnostic to view the problem.
    • Alternatively, right-clicking on a problem in the Problems tab will offer quick fix options (if a quick fix is available).
  2. Open the available quick-fix action.
  3. Select the appropriate correction.

The example below shows the linter recognizing that usage names should be camel case.

Depending on the rule, Kotar may allow you to correct:

  • one occurrence;
  • all occurrences of that rule in the file;
  • multiple automatically fixable lint problems.

8. Format the Model

Kotar includes formatting support for textual SysML v2. Formatting can normalize the textual representation of your model according to the formatting rules available in the workspace. Use formatting periodically to keep model files consistent and readable.

To format the model:

  1. Right-click anywhere in the Textual Editor
  2. Select Format Document

9. View the Model Graphically

Where supported, open the graphical model editor to inspect the model visually.

The textual and graphical editors operate on the same underlying semantic model, allowing users to work with whichever representation is most appropriate for the them and their current task. Changes made in one representation can are automatically reflected in the other.

Things to try:

  1. Select different view type (Structure, Interconnection, etc...)
  2. Filter the diagram to a given set of packages
  3. Change the display style

Recommendation

Use named model elements when possible if a model will be edited interchangeably through graphical and textual representations.

Some operations involving unnamed elements or major textual restructuring may affect graphical identity or layout.

10. Saving, Version control and connecting to remote repositories

As mentioned above, Kotar stores workspace files in a browser-managed virtual file system. It also tracks and version controls the model through local git and a local Model Management System (OpenMBEE Flexo), also running only in the browser. This makes Kotar behave similarly to a desktop development environment, but browser storage should not be treated as the only durable backup of engineering work. Projects that need to be preserved should also use an appropriate persistent mechanism. Kotar provides the following options but is not limited to:

  • saving to a directory on the host device (this is what you already did if you followed the steps above)
  • committing to a remote git repository for textual files
  • committing to a remote SysML v2 Model Management System / Flexo service for models saved in the graph database
  • downloading the SysML files

Important: Do not rely exclusively on browser-local storage for important project data

Refer to the User Manual(User-Manual) for steps to setup remote git and remote flexo.

11. Next Steps

Continue with the User Manual(User-Manual) for detailed information about:

  • textual SysML v2 modeling;
  • graphical modeling;
  • diagnostics and validation;
  • linting and formatting;
  • constraint and requirement analysis;
  • interactive model evaluation;
  • command-line tools;
  • Git and version control;
  • remote model repositories;
  • tables and CSV data;
  • data-to-model transformations;
  • scripting and automation;
  • additional engineering services.

Getting Help

If you encounter a problem:

  1. Search existingGitHub Issues.
  2. If necessary, submit a new issue using the appropriate issue form. When reporting problems, use minimal synthetic examples whenever possible.

Do not submit confidential, proprietary, customer-sensitive, export-controlled, classified, or credential information through public GitHub Issues.