Skip to content

README.md

Latest commit

 

History

History
180 lines (131 loc) · 8.09 KB

README.md

File metadata and controls

180 lines (131 loc) · 8.09 KB
بسم الله الرحمن الرحيم
In the name of Allah, the Compassionate, the Merciful

ModelScript

GitHub Sponsor CI/CD npm @modelscript/core npm @modelscript/cli npm @modelscript/tree-sitter-modelica Docker API Docker Morsel Docker Web Docker IDE VS Marketplace Open VSX

ModelScript is a comprehensive Modelica compilation, simulation, optimization, and visualization framework. It provides a robust engine for parsing Modelica code, performing semantic analysis, flattening models, simulating dynamic systems, solving optimal control problems, and rendering interactive diagrams — all from the browser or the command line.

Monorepo Structure

This project is a monorepo managed with Lerna, Nx, and npm workspaces.

Package Description
@modelscript/core Compiler engine — parsing, semantic analysis, flattening, simulation, linting
@modelscript/cli msc command-line interface — flatten, simulate, optimize, lint, render, and more
@modelscript/api REST API server — simulation, publishing, GraphQL, SPARQL, and RDF
@modelscript/morsel Visual Modelica editor — code editing, diagram viewer, simulation, and plotting
@modelscript/web Web frontend for browsing and exploring Modelica libraries
@modelscript/ide VS Code Web IDE — browser-based Modelica development environment
@modelscript/lsp Language Server Protocol — completions, hover, diagnostics, formatting, colors
@modelscript/vscode VS Code extension — syntax highlighting, LSP client, diagram view
@modelscript/tree-sitter-modelica Tree-sitter grammar for Modelica (native + WASM)

Core Features

  • Accurate Parsing — custom Tree-sitter grammar for efficient, incremental parsing
  • Semantic Analysis — full scope and name resolution for complex Modelica hierarchies
  • Flattening — transforms hierarchical models into flat Differential Algebraic Equations (DAE)
  • Simulation — ODE/DAE solver with Pantelides index reduction and BLT ordering
  • Optimization — optimal control problem solver using direct collocation
  • Diagram Rendering — interactive SVG diagrams and X6-based visual layouts with auto-placement
  • Language Server — completions, hover, diagnostics, formatting, and color provider
  • Linting — 15+ lint rules covering syntax, types, semantics, and equations
  • Modelica Scripting — interpreter for evaluating Modelica expressions and algorithms
  • i18n Support — extracting translatable strings from Modelica models

Getting Started

Prerequisites

  • Node.js ≥ 24 (see .nvmrc)
  • emsdk (required for building the Tree-sitter WASM parser): 
    git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh

Installation

git clone https://github.com/modelscript/modelscript.git
cd modelscript
npm install

Building

Build all packages (in dependency order via Nx):

npm run build

Running (Development)

Start all services concurrently:

npm run dev

This launches:

Service URL Description
Morsel (editor) http://localhost:3002 Visual editor with diagrams and simulation
Web (library browser) http://localhost:3001 Browse and explore Modelica libraries
API http://localhost:3000 REST API for simulation, publishing, queries
IDE (VS Code Web) http://localhost:3003 Browser-based VS Code with Modelica support

AI Chat (Optional)

The IDE includes a browser-local AI assistant powered by WebLLM (Qwen3-0.6B). To enable it, download the model weights (~350 MB, one-time):

npm run download-model --workspace=@modelscript/ide

Once downloaded, restart npm run dev and open the ModelScript AI panel in the IDE sidebar.

CLI Usage

After building, the CLI is available as msc:

# Flatten a model to DAE
npx msc flatten Modelica.Electrical.Analog.Examples.CauerLowPassAnalog path/to/MSL

# Simulate a model (outputs CSV by default)
npx msc simulate BouncingBall model.mo --stop-time 5

# Simulate with JSON output
npx msc simulate BouncingBall model.mo --format json

# Solve an optimal control problem
npx msc optimize MyModel model.mo \
  --objective "u^2" --controls "u" --control-bounds "u:-1:1" --stop-time 10

# Lint Modelica files
npx msc lint model.mo

# Render a diagram to SVG (outputs to stdout)
npx msc render MyModel model.mo > diagram.svg

Testing

Run the test suite across all packages:

npm test

Linting

npm run lint

Formatting

npm run format

Docker

Pre-built images are published to the GitHub Container Registry on every push to main.

Run the latest images without building:

docker compose pull    # Pull latest images from ghcr.io/modelscript/*
docker compose up -d   # Start containers
docker compose down    # Stop containers
docker compose logs -f # Tail logs

To build from source instead:

npm run docker:build   # Build images locally
npm run docker:up      # Start containers
Service Port URL
API 3000 http://localhost:3000
Morsel 3002 http://localhost:3002
Web 3001 http://localhost:3001
IDE 3003 http://localhost:3003

License

ModelScript is licensed under the AGPL-3.0-or-later. See COPYING for more details.