Modelica Studio

Modelica Studio

Model, simulate and plot Modelica systems inside Obsidian: drag components onto a schematic canvas, wire them, run them with the OpenModelica already installed on your machine, and read the result as a plot — in the studio, or in the note itself.

MassSpringDamper — two free masses joined by a spring and damper, with a 1 N step forced on the first. The signal wire is the Blocks library's dark blue, the mechanical wires are translational green: colours and line weights come from the library's own annotations, not from this plugin — including on a dark canvas, where a wire that would vanish is lifted just enough to stay visible.

Status: pre-1.0, and experimental — it works, its examples are verified numerically against independent calculations, and there are rough edges. See Beta status.

• Install · What it does · Worked examples · Documentation · Beta status · Licence

---

Install

Requirements: Obsidian 1.11.4+ on desktop (it runs a compiler — mobile is not supported), and OpenModelica installed separately. The plugin finds omc on your PATH, tells you if it is missing, and uses the Modelica Standard Library that ships with it.

Where to get OpenModelica — the same list the plugin prints when it cannot find omc:

After installing, reload Obsidian (Ctrl/Cmd+R): the plugin looks for omc when it loads. If it cannot find it, the message names the install route for your platform, and OpenModelica path in the settings takes an explicit path to the binary.

From the community directory

Settings → Community plugins → Browse, search for Modelica Studio, install, and enable it. That is the whole of it — this is the route that keeps itself up to date, and the one to prefer.

Obsidian's own copy-link for this plugin is obsidian://show-plugin?id=modelica-studio, which opens the same page in the app. Paste it into a browser rather than clicking it from a page like this one: GitHub strips the obsidian:// scheme, so a link here would go nowhere.

With BRAT, which keeps it updated

BRAT installs a plugin straight from its GitHub releases and updates it for you. The plugin is pre-1.0, so the version numbers are 0.x; from 0.3.0 the releases are ordinary releases rather than pre-releases, and the 0.2.0-beta.* line stays available for anyone pinning an older build.

1. Install BRAT from Settings → Community plugins → Browse.
2. In BRAT's settings, Add Beta Plugin.
3. Enter this repository: AhmedAlfahdi/modelica-studio
4. BRAT installs the latest release. Enable Modelica Studio in Settings → Community plugins.

To pin a version instead of tracking the latest, use BRAT's frozen option and name the release, for example 0.3.18.

BRAT reports a mismatch if a release's tag, its name and the version inside the released manifest.json disagree. They are kept identical here on purpose, so an update is never held back by a version string.

By hand

1. Take main.js, manifest.json and styles.css from a release, or build them (below).
2. Create <your-vault>/.obsidian/plugins/modelica-studio/.
3. Copy those three files into it.
4. Reload Obsidian — a plugin's manifest.json is read at startup, so copying one in while the app is running does not register it.
5. Enable Modelica Studio in Settings → Community plugins.

You do not need a vault of your own to see what it does: the worked examples are readable on GitHub, and the studio's Examples menu opens the same thirty inside your own vault. There is also a ready-made one in examples/vault/ if you would rather not use your own.

Verify what you installed

The three files on a release are built by .github/workflows/release.yml from the tagged commit and carry a signed build-provenance attestation, so you can check that the main.js running in your vault came from this repository rather than from somewhere else:

gh attestation verify main.js --repo AhmedAlfahdi/modelica-studio

Run it inside your vault's .obsidian/plugins/modelica-studio/ — or against any release download — with the GitHub CLI installed. A release from before 0.3.20 has no attestation; the command says so rather than pretending otherwise.

Build it yourself

npm install
npm run build          # typecheck, then bundle to main.js
npm run dev            # rebuild on change
npm test               # ~790 tests, including a numerical audit of the examples
npm run lint           # the plugin directory's own review rules

npm run lint runs eslint-plugin-obsidianmd's recommended config over the source and the CSS checks the directory's published stylelint config applies to styles.css — the same rules a submission is reviewed with — so that list is never seen for the first time during a review. test/lint.test.mjs fails the suite when either is not clean, and carries a canary proving the CSS gate still rejects :has() and display: contents rather than passing because it stopped looking.

npm test runs the real OpenModelica compiler, so it needs omc on your PATH and takes a few minutes. Without it, the simulation-dependent tests skip.

---

What it does

Each of these is a capability, with the picture that goes with it. The screenshots are rendered from the plugin's own code by scripts/readme-images.mjs, so they cannot show something the plugin does not do — and regenerating them after a change is one command.

The whole studio — palette, diagram, inspector, result — looks like this:

Light theme. The palette on the left, the diagram in the middle, the inspector on the right — here on the Traces tab, listing the result's 37 variables with two of them plotted — and the result below, with the sweep controls beside it. The names under the components are placed by the plugin: a name that would land on another symbol or on a wire is moved aside, which is the Move names out of the way setting.

Dark theme.

How it talks to OpenModelica

The plugin never implements a simulator. It writes a model out as Modelica source, hands that text to the omc you already have installed, and reads the result file back:

flowchart TD
  subgraph plugin["In Obsidian: the plugin"]
    canvas["Diagram canvas<br/>drag, wire, rotate"]
    src["Modelica source<br/>the .mo file in your vault"]
    plot["Plot<br/>in the studio or in a note"]
  end
  subgraph omc["OpenModelica: omc"]
    t["Translate<br/>flatten and type-check"]
    cc["Compile to C, link"]
    run["Run the executable<br/>writes a result file"]
  end
  lib[("Modelica Standard Library")]

  canvas -->|serialize| src
  src -->|"Simulate: one .mos script"| t
  t -->|ok| cc
  cc --> run
  run -->|"the result file: a time series"| plot
  t -.->|"errors, with line numbers"| src
  lib -.->|"icons, colours, parameters"| canvas

Nothing is hidden in the middle: Simulate is those four steps in order, and everything omc reports comes back with its line number and is shown against the code. The library is read once to draw the palette and the symbols, and the model imports it by its ordinary name — so a file written here compiles in any other Modelica tool too.

A schematic editor that draws what the library declares

Drag a class from the palette onto the canvas, wire the pins, drag a wire vertex to route it, rotate, resize, copy and paste, undo. The search is fuzzy (tank finds OpenTank), whole libraries can be hidden, and the diagram is stored as real Modelica source with graphical annotations — so a file round-trips through OMEdit and the other Modelica tools.

Symbol outlines, wire colours, wire weights and pin shapes are read from the library: an electrical connection is the electrical blue, a shaft is ink, a bus is yellow at double width, and a component's own icon text (R=100, a valve's state) is drawn as the library wrote it. Help → Diagrams lists every domain's colour, measured from the installed library rather than copied into the source.

Run it, and read the result where you are

Simulate serializes the diagram, compiles it with omc, runs it and plots the result. Traces are grouped onto one or two value axes by magnitude, so a pressure in the hundreds of thousands and a flow in hundredths are both readable; the legend names the run, and the cursor reads every visible trace at the instant under it.

The first mass's position and the coupling's deflection — the two quantities this model is about, and the two its example opens with. Nothing is anchored, so mass1.s drifts upward; coupling.s_rel is the gap, which rings and settles at F·m₂/(c(m₁+m₂)) = 1/75 m rather than at F/c, because both ends are free. Both curves are the numbers OpenModelica returned; nothing in this README is redrawn by hand.

A sweep runs the model once per value of one parameter and overlays the results as a family, dotted per run; Δ vs measures a trace against the run on screen, so "this valve opens 12 ms later" is a number rather than an impression. A changed parameter re-runs in tens of milliseconds by overriding it in the compiled binary; a structural change recompiles.

The same thing, in a note

A fenced modelica block renders a live diagram and a plot in the note itself, and simulates when the note opens. The block's text is the model, so the diagram travels with the note and can be diffed, copied and committed like any other text.

It carries its own toolbar, takes options from a directive on its first line, and runs itself exactly once — Using it in a note explains why, and what the directive can set.

A calculation, solved instead of typed

A fenced modelica-solve block holds a relationship rather than a number, and the answer is recomputed when the note opens:

sqrt(x) + x^2 - 56 = 67

x = 10.940400921

The unknown does not have to be alone on the left of anything. The block asks OpenModelica for the model's initialisation — the nonlinear solve it performs before every simulation — so nothing is rearranged, by you or by the plugin.

It is not only arithmetic. Each of these has been run against OpenModelica, and the answer is the one that came back:

The equation above each answer is typeset where it can be read as mathematics, and kept as source where it cannot — so a comprehension stays legible while everything around it is drawn.

The calculation block is the reference, and twelve examples to try have each been run against OpenModelica.

Help that quotes the library

The Help window, in the studio, carries the shortcuts (read from the code that implements them, so a key that does not exist cannot be documented), the domain colours, the connection rules quoted from the library's own documentation, and what this installation actually is — the OpenModelica version, the library, the class count.

Every colour in that table is measured from the installed library by a test, so a row cannot describe a library that no longer says it. The connection rules are quoted from the library's own UsersGuide.

Ask the diagram what it is set to

Resting the pointer on a component shows what its parameters are set to — the ones this instance overrides first, so the answer to "why is this different from the library default" is one hover away. Reading a diagram's settings otherwise means selecting every component in turn.

Resting on the coupling in MassSpringDamper: c=50, d=1, the two values this instance sets, with the library's own defaults for the rest. On a class with a conditional connector, the connector is dimmed and cannot be wired until the parameter that declares it is on.

Sweep a parameter, and measure the difference

A sweep runs the model once per value of one parameter and overlays the results as a family — the run on screen solid, the others dashed, so which curve is which is never in doubt. Δ vs then reads how far each member is from the run on screen at the cursor, which turns "this valve opens a little later" into a number.

MassSpringDamper swept over the coupling stiffness — c=25, c=50 (the run on screen) and c=100 — with each family member's distance from it at the cursor. Each value is one simulation of the same compiled binary: a parameter change overrides it at run time, which is why a sweep is seconds rather than minutes. A structural change recompiles.

The rest of it

• Diagram and code modes. The same model, built by dragging or edited as source with syntax highlighting, completion from the library, and inline diagnostics.
• Models as files. Create a model and save it as .mo. Models go into a Modelica/ folder at the vault root by default — they are source for a compiler, not notes. A saved model opens four ways: right-click → Open in Modelica Studio, drag it onto the canvas or the code pane, the command palette, or click it and read the source as text (that last one is deliberately still the default: the file is source).
• Parameters, without hunting. Hovering a component shows what its parameters are set to, with the ones this instance overrides first. A connector a class only declares conditionally — a heat port before useHeatPort is true — is dimmed and cannot be wired until the parameter is on.
• Optional AI assistance. With your own API key, describe a model in words and have it written into the editor, or ask for a compile error to be fixed. See AI assistance.
• 30 worked examples across electrical, mechanical, fluid, thermal, aerospace, control and discrete domains, each with a derivation, the live model, and a table comparing an independent calculation against the simulation. Every table is re-checked against a real OpenModelica run by test/audit.test.mjs on every test run, so a stale number fails the suite rather than misleading a reader.
• A record of what went wrong. Testing findings lists every expectation that failed, which side was wrong, and the five models dropped for being unverifiable.

What it accesses, and what leaves your machine

Stated plainly, because a plugin that runs a compiler should say so. The plugin directory's own analysis flags five capabilities here; this is what each one is for.

Files, and what for. Everything inside your vault is reached through Obsidian's own API, and the plugin writes only where you ask it to: .mo files in the model folder (Modelica/ by default), the diagrams you embed in notes, and its own state under your Obsidian configuration folder (<config>/plugins/modelica-studio/ — history, the library index cache, and optionally an AI request log). The one other file it writes is .modelica-studio.log in the vault root, only when you turn Write diagnostic log on, and it keeps its most recent 512 KB rather than growing without end.

Outside the vault it touches two things, both because the compiler lives there:

• the Modelica library folders of your OpenModelica installation — on Linux ~/.openmodelica/libraries, and the equivalent per-platform location elsewhere — read once to index the classes for the palette and the symbols, cached as JSON above, and re-read when a library changes;
• the system temporary folder, where omc translates and compiles a model (<tmp>/modelica-studio/<pid>). That is OpenModelica's own scratch space: a compiled model is tens of megabytes of generated C. It is not in your vault, nothing there is read by anything but the compiler, and the folders left by earlier sessions — whose process has exited, so nothing can reuse them — are removed when the plugin starts. A folder belonging to a running Obsidian is left alone.

Nothing else is read or written, and no file is uploaded anywhere.

One file to read. The plugin's whole system surface — every file it reads and writes, the compiler it spawns, the hashes it computes, the environment it looks at — is reached through src/host/node.ts, which declares exactly those calls. No other file in the source imports a Node module or touches process, and a test fails the suite if one does. That file is the complete answer to "what does this plugin do to my machine".

Network. The plugin makes no network requests unless you turn on AI assistance. With it off — the default, and it stays off until you enter a key — it works entirely offline. With it on, and only when you press AI, it sends the prompt you wrote, the current model source, and OpenModelica's compiler output for that model to the provider you configured:

• OpenAI (api.openai.com), DeepSeek (api.deepseek.com), Groq (api.groq.com) or OpenRouter (openrouter.ai), or
• any OpenAI-compatible base URL you type in instead, including a local Ollama or llama.cpp server — in which case nothing leaves the machine.

What it sends is the prompt, the model source, the compiler's output, the OpenModelica version, the names of the libraries you have indexed, and your run settings. It does not send file paths, your vault's contents, or anything identifying the machine.

The benchmark (modelicaStudio.bench(), documented under Debugging) is the one exception, and it is a developer tool: it measures a fixed set of prompts and reports the timings, from your console.

The key is stored in Obsidian's keychain and sent only to that provider. The plugin has no telemetry, no analytics and no update check: it never contacts this repository or anyone else on its own, and updating is Obsidian's or BRAT's job. There is no account to create and nothing to pay for; the only cost of the AI feature is your own provider bill.

---

Worked examples

Thirty built-in examples, each with a note that derives its physics, embeds the model as a live block, and puts the numbers an independent calculation predicts beside the numbers the simulation produces. Every one has a closed-form answer computed without running the simulation; where that was not possible — a chaotic double pendulum, a correlation-limited pipe friction — the note says so and checks an invariant instead.

Read them here on GitHub, or open the same set in the studio's Examples menu. Start with Modelica in ten minutes, then the full index or any of these:

Documentation

The README is the front door: what the plugin is, how to install it, and what it does. The reference is in docs/, one page per subject.

Beta status

Experimental, and it wants more testing. Specifically:

• Requires Obsidian 1.11.4+, for the keychain the AI feature stores its key in. Earlier builds are refused rather than downgraded to plain-text storage.
• Tested against one OpenModelica build (1.27.0) on one platform (Linux). Windows and macOS are untested, and so is every other OpenModelica version.
• MSL 4.1.0 is what the examples use. Other library versions have not been tried.
• Not all of Modelica is supported. Array-valued connectors, redeclare model refinements, and bitmap icons have known gaps. Conditional connectors are handled — they are dimmed and unwireable until their parameter is on — but an array port is not captured, so a class with one is reported rather than silently mis-drawn. Unsupported constructs surface as compiler errors rather than silently.
• The audit covers the built-in examples, not your models. A hand-built model may hit a parser or serializer limitation the examples do not.
• Listed in the community directory, and not manually reviewed. It is installable from Browse like any other community plugin, which means it passed the submission checks the directory runs — the automated ones, over this repository's own linter output, the release build and the manifest. Obsidian's listing says so in as many words: "This plugin has not been manually reviewed by Obsidian staff." Nobody has read it end to end but its author.

If something fails, enabling Write diagnostic log in settings writes a diagnostic log to .modelica-studio.log in the vault — the most recent 512 KB of it, trimmed as it fills — and Show coordinate diagnostics overlays the editor's geometry.

Repository layout

src/
  main.ts              plugin entry, commands, settings, embeds
  ai/                  prompt construction and the OpenAI-compatible client
  modelica/            parser, serializer, library index, examples
  render/              canvas drawing of Modelica graphical primitives
  view/                schematic editor, studio view, plots, inline blocks
  omc/                 OpenModelica process, build cache, result reading
test/                  unit and integration tests, and the numerical audit
showcase/notes/        the 30 worked examples, readable as markdown
showcase/              the generator behind them (math, explanations)
examples/vault/        the test vault, with the generated notes
docs/                  the reference, one page per subject -- see Documentation above
  design.md            why it is built this way, and the measurements behind it
  testing-findings.md  every failed expectation and what it turned out to be
research/              background research kept from development
scripts/               bundle checks

License

GNU General Public License, version 3 or later — see LICENSE. Copyright (C) 2026 Ahmed N. Alfahdi.

Use it for anything, including commercially, and change it however you like. Two things come with that, and they are the point of choosing this licence:

• It stays free. Anyone who distributes this code or a modified version must pass on the same freedoms — the source has to come with it. Nobody can take it closed.
• It stays attributed. The copyright notice and this licence travel with every copy, and modified versions have to say that they are modified. A fork cannot present itself as the original work.

Nothing else is asked of you: running it, building models with it, publishing results from those models, or using it inside a company are all unrestricted.

Citing

If this plugin contributes to work you publish, please cite it — as a favour to a student, not as a condition of the licence, because a citation requirement cannot be part of an open-source licence (the GNU FAQ says so explicitly, and Debian patched exactly such a notice out of GNU parallel). GitHub's "Cite this repository" button reads CITATION.cff, which gives the version-independent form:

Alfahdi, A. N. (2026). Modelica Studio: a visual Modelica modelling and simulation environment for Obsidian [Computer software]. https://github.com/AhmedAlfahdi/modelica-studio

Third-party notices

Neither Modelica nor OpenModelica is bundled, so neither licence reaches this plugin:

• OpenModelica is installed separately and invoked as a separate program (omc); it is subject to its own licence.
• The Modelica Standard Library is not redistributed either — it is parsed from the copy already installed on the machine. It is licensed under the 3-Clause BSD licence, which is compatible with this one. Two sentences of its documentation are quoted in the Help window, with their source named where they appear.
• Obsidian's API is imported at run time from the application, not distributed with the plugin. Icons are drawn by Obsidian's own setIcon, so the plugin ships no artwork.
• Lucide is the icon set Obsidian draws those icons from. scripts/readme-icons.json holds the 29 shapes the toolbar and menus use, vendored under Lucide's ISC licence for one reason: the README's screenshots are rendered by a script, and without the shapes the toolbar came out as a row of empty squares. Nothing in the plugin reads that file.