# Konjugate 0.7.2: Causal inference can now recover product/interaction relationships

Interaction terms: recovering product/bilinear relationships

Every relationship causal inference has fit so far has been a function of one variable at a time — a source's own polynomial expansion, or a target's own self-lag. That's exactly right for a relationship that decomposes additively, but it can't represent a non-separable coupling — one that isn't a sum of single-variable terms — and the canonical case is bilinear/product coupling: mass-action kinetics, Lotka-Volterra predator-prey, SIR-style epidemiological compartments.

• New checkbox in the review UI: "Also test for interaction effects between related variables" (off by default — most systems don't need it, and it costs a little extra fitting time to try). When on, causal inference additionally tries a product term (rate × source × target) for each candidate relationship, on top of everything it already tries.
• Selection and acceptance reuse the existing machinery end to end — no separate mechanism: it's one more axis in the same lag/degree/penalty search, gated by the same held-out score and the same aggregate-magnitude acceptance test.
• No schema or execution-engine change was needed — an interaction term renders as an ordinary edge equation referencing both endpoints' own symbols, the same pattern the component library's relative-position templates already use.
• Verified end-to-end against a synthetic bilinear system: recovered linear coefficient 1.99 (true 2.0), interaction coefficient 0.79 (true 0.8), self-rate −0.59 (true −0.6).

Causal inference: replay a column's real recorded values instead of guessing its dynamics

Found and fixed while reviewing what actually happens when a causal-inference model is run forward: a column nothing in the CSV predicts (a "root" variable) got no dynamics at all — not even a frozen value at its last known point, but a hardcoded zero, regardless of what the data actually showed.

• Every newly created state's initial value is now seeded from that column's own first recorded row, not zero.
• Any mapped column — not just a root one — can be marked "input" in the review UI: this replays that column's exact recorded trajectory during the run, computed from a generated local-slope provider rather than a fitted equation. It's exact at any solver resolution, not just the CSV's own sampling interval, since a constant-rate segment integrates exactly under Euler regardless of substep count.
• Marking a column as input correctly supersedes any self-term or edge that would otherwise also target it, so nothing gets double-counted.
• Measured on our own 8-node validation system: forward-simulated downstream error is 0.90 with root columns replayed this way, versus 10.15 — over 11× worse — left to their own fitted self-decay alone.

Both features are documented in Causal inference, with the full design history (including approaches considered and rejected) in Interaction terms and Input replay. Both are covered by permanent regression tests, including one that commits and runs a real project through the actual engine rather than a hand-rolled simulation.

Installation notes: Konjugate isn't code-signed yet (an active choice while the project is in alpha), so your OS may show a security warning on first launch. This doesn't mean the download is corrupted.

• macOS — if you see "is damaged and can't be opened": move Konjugate.app to Applications, then in Terminal run xattr -cr /Applications/Konjugate.app. Or: System Settings → Privacy & Security → Open Anyway.
• Windows — if you see a blue "Windows protected your PC" warning from SmartScreen, click More info, then click the Run anyway button that appears.

Full Changelog: v0.7.1...v0.7.2

Konjugate 0.7.1: Correctly running causal inference

Causal inference now produces equations that actually run correctly

Every equation causal inference proposes — cross-relationships and each node's own self-lag — is now a genuine continuous-time rate, compatible with Konjugate's dx/dt solver by construction, not a raw discrete-step coefficient placed directly into the derivative. Previously, a fitted relationship's coefficient was a per-CSV-row multiplier; treating it as a rate was a real unit mismatch that, run forward, tended to diverge — sometimes explosively, since nothing was damping a node's own state.

What changed under the hood:

• Every fitted coefficient is transformed via rate = coefficient / Δt (and rate = (selfLagCoefficient − 1) / Δt for a target's own persistence), where Δt is the CSV's own sampling interval — the exact solution to "what rate makes one Euler step reproduce this fitted discrete transition." No approximation, no matrix decomposition, and it applies cleanly to curved (polynomial) relationships too.
• A node's own self-lag — previously fit only as an internal control term and then discarded — is now kept and committed as a local equation on that node's own state, giving recovered models real persistence/decay dynamics instead of none at all.
• This is the only path now — there's no separate "continuous-time" toggle to remember. Multi-step-lag search was dropped from the default candidate search, since a relationship more than one CSV row old was never representable as a correct equation anyway (Konjugate has no delay-buffer mechanism), so nothing usable was actually lost.
• One honest, documented limitation: a recovered rate is calibrated to one Euler step at the CSV's own sampling interval. Running Konjugate with a much finer time step than that drifts — measured at roughly 6–7× the calibrated-resolution error on our own validation system — though the drift stays bounded rather than diverging. This is now guarded by a permanent regression test.

See Causal inference for the full method, and Discrete fit vs. continuous rate for the math (including the matrix-logarithm approach we tried first, and why it was rejected).

Fixed: About/Examples windows appearing under the title bar

The About Konjugate and Example Guide windows could open positioned with their own title bar under the real menu bar — a saved position left over from a moved or disconnected display, or simply centering on a parent window that itself sat flush against the screen top. These windows are now clamped to the current display's visible work area.

Installation notes: Konjugate isn't code-signed yet (an active choice while the project is in alpha), so your OS may show a security warning on first launch. This doesn't mean the download is corrupted.

• macOS — if you see "is damaged and can't be opened": move Konjugate.app to Applications, then in Terminal run xattr -cr /Applications/Konjugate.app. Or: System Settings → Privacy & Security → Open Anyway.
• Windows — if you see a blue "Windows protected your PC" warning from SmartScreen, click More info, then click the Run anyway button that appears.

Full Changelog: v0.7.0...v0.7.1

Konjugate v0.7.0: Causal Inference

Causal inference

Import a CSV of multivariate time-series data and Konjugate proposes the causal graph behind it: which columns drive which, with what lag, and whether the relationship is linear or curved.

• Two-stage pipeline: a lagged partial-correlation skeleton pass finds which variables are related at all, then a joint ridge regression fit determines the direction of each relationship and fits it as a linear or polynomial equation.
• Three nonlinearity modes — "Linear only," "Allow curvature up to degree N," or "Let the tool decide" (compares linear vs. polynomial per relationship and keeps whichever fits better).
• Every proposed node and edge is reviewable — checked in or out — before it's added to your model, through the same pipeline the AI assistant uses.
• Imported nodes default to a sphere shape and auto-arrange in a circle sized to their count, so edges stay legible instead of overlapping.

Fixed

• Pose Visualizer's playback could report itself finished a frame before the timeline had actually caught up, due to a race between a seek request and its confirmation.

Installation notes: Konjugate isn't code-signed yet (an active choice while the project is in alpha), so your OS may show a security warning on first launch. This doesn't mean the download is corrupted.

• macOS — if you see "is damaged and can't be opened": move Konjugate.app to Applications, then in Terminal run xattr -cr /Applications/Konjugate.app. Or: System Settings → Privacy & Security → Open Anyway.
• Windows — if you see a blue "Windows protected your PC" warning from SmartScreen, click More info, then click the Run anyway button that appears.

Full Changelog: v0.6.6...v0.7.0

Konjugate v0.6.6: Edge groups, new robotics shapes, and a truer 2D lock

New: Edge groups

• Select several nodes and define one shared relationship across all of them at once, instead of authoring the same equation node pair by node pair. It expands into a full mesh automatically — one directed edge each way between every member pair — so a coupling like convective heat exchange between a dozen battery cells is one equation, not sixty-six.
• Membership is live: add a node to an existing group, or detach one and its connections to the rest of the group stay behind as ordinary, independently editable edges rather than disappearing.
• Editing a group's equation, implementation or parameters updates every member edge immediately — the same autosave-as-you-type behavior as the node and edge editors, no separate save step.
• An "automatically add missing state variables" option (on by default) fills in a state a member is missing rather than leaving the group broken.
• See the new Edge and relationship directionality guide for exactly how a group's mesh differs numerically from an ordinary bidirectional edge — worth reading before writing a group's equation, since a two-member group is not the same thing as a bidirectional edge between the same two nodes.

New: Robotics shapes and multi-domain shape categorization

• Five new bundled shapes for the Robotics domain: Servo Actuator, Articulated Link, Parallel Gripper, Drive Wheel and Propeller Rotor, covering manipulator joints, mobile-robot wheels and drone rotors.
• A shape can now belong to more than one domain category at once (e.g. the Spur Gear is both Mechanical and Robotics), so it shows up under every relevant filter instead of forcing a single choice.

Fixed: 2D lock now actually keeps things flat

• Locking to a 2D view previously only constrained the camera. New nodes, pasted copies and dragged nodes could still land off the visible plane with no warning — most easily noticed via copy/paste, where a pasted copy's depth could drift silently because the paste offset had no idea which view was locked.
• Copy/paste now zeroes out whichever axis is "depth" for the currently locked view, so a paste always lands in the same plane as the original, on any of the six locked views.
• A newly created node now matches whatever plane the rest of the visible model already agrees on (checked independently per axis), instead of always dropping at the same fixed default position regardless of what's already on screen.

Installation notes: Konjugate isn't code-signed yet (an active choice while the project is in alpha), so your OS may show a security warning on first launch. This doesn't mean the download is corrupted.

• macOS — if you see "is damaged and can't be opened": move Konjugate.app to Applications, then in Terminal run xattr -cr /Applications/Konjugate.app. Or: System Settings → Privacy & Security → Open Anyway.
• Windows — if you see a blue "Windows protected your PC" warning from SmartScreen, click More info, then click the Run anyway button that appears.

Full Changelog: v0.6.5...v0.6.6

Konjugate v0.6.5: macOS codesigning fix and Node.js 24 upgrade

Fixed

• Fixed macOS packaged builds shipping a bundled METIS library with a broken code signature. Preparing METIS for bundling rewrites its dylib install name, which was leaving the library re-signed incorrectly (or not at all); it's now explicitly re-signed as part of packaging, closing the same class of "unsigned nested binary" problem that previously affected the engine binary itself.
• macOS builds now consistently target macOS 11, end to end — the engine, its C++ providers, and the packaged app itself — instead of each picking up whatever minimum version the local build machine happened to default to.

Internal / release process

• Upgraded the required Node.js version to 24 (LTS) everywhere: local development, packaging, and CI. npm run setup / npm run dev now expect Node.js 24.19 or newer.

Installation notes: Konjugate isn't code-signed yet (an active choice while the project is in alpha), so your OS may show a security warning on first launch. This doesn't mean the download is corrupted.

• macOS — if you see "is damaged and can't be opened": move Konjugate.app to Applications, then in Terminal run xattr -cr /Applications/Konjugate.app. Or: System Settings → Privacy & Security → Open Anyway.
• Windows — if you see a blue "Windows protected your PC" warning from SmartScreen, click More info, then click the Run anyway button that appears.

Full Changelog: v0.6.3...v0.6.5

Konjugate v0.6.3: Extensions, computational-node providers and packaging fixes

New: Extensions system for add-ons and plugins

• Replaced the bare "Install" button with a proper Extensions dialog — browse installed add-ons and plugins (bundled and user-installed), see their identity, version and permissions, and install new ones from the same place.
• Add-ons and plugins can now be uninstalled, not just installed.
• Add-ons and plugins can now be enabled or disabled independently of installing/uninstalling — takes effect immediately, no restart required.
• The bundled "Hello World" add-on now ships disabled by default.

New: Computational-node providers

• The engine can now execute stateful, checkpointable computational-node providers (Python) — nodes whose entire dynamics are owned by external code rather than an equation. This is what controllers, accumulators and similar stateful components need.
• Checkpoint/restore for these providers is wired into the engine's own checkpoint and restart mechanism, so a provider's internal state (e.g. a controller's integral term) survives pause/resume and restart, not just the ordinary state vector.
• This builds on an expanded plugin infrastructure that now supports node-level provider contributions, not just relationship/edge providers.

Fixed

• Fixed a real bug where an installed (packaged) add-on was never actually discovered by the app after installing it — the discovery scan was looking one directory level too shallow.
• Fixed macOS packaging: the engine binary and bundled METIS library were shipping completely unsigned inside the app bundle. Apple Silicon refuses to execute an unsigned nested binary at all, which could surface as a validation/run failure with no diagnostic output.
• Fixed a deadlock that could hang the engine indefinitely on Linux after a run completed normally (a background control-stream reader thread holding stdin's lock while blocked, colliding with glibc's exit-time stdio flush).

Internal / release process

• Packaged-build verification (spawning the actual packaged engine binary and running the full test suite against it) is now part of the release pipeline, so packaging and signing regressions get caught automatically before a release ships, instead of after.

Installation notes: Konjugate isn't code-signed yet (an active choice while the project is in alpha), so your OS may show a security warning on first launch. This doesn't mean the download is corrupted.

• macOS — if you see "is damaged and can't be opened": move Konjugate.app to Applications, then in Terminal run xattr -cr /Applications/Konjugate.app. Or: System Settings → Privacy & Security → Open Anyway.
• Windows — if you see a blue "Windows protected your PC" warning from SmartScreen, click More info, then click the Run anyway button that appears.

Full Changelog: v0.6.0...v0.6.3

Konjugate v0.6.0: Command-line mode and a few old examples back

Command-line mode

Konjugate can now run a project headlessly from a terminal; no window opens, and it exits when the run finishes. This makes it possible to script simulation runs, batch multiple models, or automate result generation without touching the GUI at all.

# macOS
/Applications/Konjugate.app/Contents/MacOS/Konjugate --cli run model.kjt --target-time 30 --output-kjt result.kjt --output-csv result.csv

# Windows
Konjugate.exe --cli run model.kjt --target-time 30 --output-kjt result.kjt --output-csv result.csv

# Linux (AppImage)
./Konjugate-*-linux-x64.AppImage --cli run model.kjt --target-time 30 --output-kjt result.kjt --output-csv result.csv

• --cli run <project.kjt> --target-time <seconds> runs the project's active run configuration (or --configuration <name-or-id> to pick another).
• --output-kjt <path> writes a new .kjt with the result embedded, exactly like saving after a run in the GUI.
• --output-csv <path> exports the same signal columns the GUI's CSV export produces — opens directly in Excel or any spreadsheet app.
• --cli validate <project.kjt> prints a validation report as JSON and exits 0 if valid, 2 if not.
• An encrypted .kjt reads its password from a KONJUGATE_PASSWORD environment variable, never a command-line flag, so it never lands in shell history.

A CLI invocation always runs as its own independent process, even while a GUI instance is already open elsewhere. Under the hood, a headless run also skips the live-progress streaming the GUI needs, so long unattended runs spend their time on the simulation itself rather than on progress bookkeeping nobody's watching.

A few examples are back

Heated Water Tank, Spring–Mass–Damper, Two-Room Building and Thermal Equilibrium have rejoined the bundled example set, each with a guide rewritten to match the rest of the library — governing equations, how they map onto the model's actual edges and source terms, and what to expect when you run them. They round out the set with simple, single-concept models (a bare thermal tank, a classic mechanical oscillator, a multi-zone building and the bidirectional-edge feature in isolation) alongside the more elaborate robotics examples already there.

Fixes

• Corrected a packaging test that had drifted out of sync with how the app is actually packaged, so it once again verifies that third-party notices and licenses ship correctly.

---

Installation notes: Konjugate isn't code-signed yet (an active choice while the project is in alpha), so your OS may show a security warning on first launch. This doesn't mean the download is corrupted.

• macOS — if you see "is damaged and can't be opened": move Konjugate.app to Applications, then in Terminal run xattr -cr /Applications/Konjugate.app. Or: System Settings → Privacy & Security → Open Anyway.
• Windows — if you see a blue "Windows protected your PC" warning from SmartScreen, click More info, then click the Run anyway button that appears.

Full Changelog: v0.5.13...v0.6.0

Konjugate v0.5.13: Multiple windows, edge waypoints and a new pump example

Open and compare multiple models at once

Konjugate can now have more than one project window open at the same time; press Cmd/Ctrl+N or use the new window button to start a second model from scratch, so you can compare models, copy nodes between them, or reference one while building another. Double-clicking a .kjt file now opens it directly (in a new window if Konjugate's already running), the same way any other document type behaves on your OS.

Route edges around obstacles with waypoints

Edges no longer have to cut straight through unrelated nodes. Press and hold an edge to select it and reveal its waypoint handles, then right-click anywhere along the edge to drop a new point and drag it to reroute the connection. Right-click a waypoint to remove it; all fully undoable, same as everything else in the model.

Lock the camera to a 2D plane

A new lock button next to the view cube snaps the camera to the nearest orthogonal view and constrains dragging to pan instead of orbit, for anyone modelling primarily in one plane.

New example: transient pump suction hydraulics

A new bundled example models NPSH margin during a reciprocating pump's suction stroke, including a physically-correct half-rectified pump waveform and a tunable safety-margin readout; see the in-app guide for the full derivation.

Also in this release

• Hovering the "Konjugate" title in the titlebar now shows the running version; clicking it opens the About page.
• Fixed the About page failing to open in packaged builds (it was being silently excluded from the package).

---

Installation notes: Konjugate isn't code-signed yet (an active choice while the project is in alpha), so your OS may show a security warning on first launch. This doesn't mean the download is corrupted.

• macOS — if you see "is damaged and can't be opened": move Konjugate.app to Applications, then in Terminal run xattr -cr /Applications/Konjugate.app. Or: System Settings → Privacy & Security → Open Anyway.
• Windows — if you see a blue "Windows protected your PC" warning from SmartScreen, click More info, then click the Run anyway button that appears.

Full Changelog: v0.5.12...v0.5.13

Konjugate v0.5.12: A conversational AI assistant and shape library previews

AI assistant

The model assistant now holds a conversation instead of treating every request in isolation. It remembers the last few turns of back-and-forth, so a follow-up like "make it 20% higher" correctly builds on what you just asked for rather than starting from scratch.

When a request is ambiguous — an unclear target, a missing value, or an unspecified node to disable — the assistant now asks a clarifying question instead of failing outright, and where possible offers suggestion chips you can click to fill in an answer without retyping.

Fixed a bug where the prompt field wasn't cleared after a question was answered, and a CSS issue that could show the assistant's empty state and its clarification prompt stacked on top of each other. The "New conversation" button is now a clearer "+" icon and asks for confirmation before clearing your conversation history.

AI-generated proposals that use LaTeX operator notation (\operatorname{Max}, \operatorname{Min}, and similar) for named functions are now understood correctly instead of being rejected by validation.

Shape library

Browsing the shape library no longer means clicking through shapes one at a time to see what they look like. Every shape now shows a static thumbnail directly in the grid, generated once and cached, so you can scan the whole library at a glance.

Selecting a shape also opens a live, rotatable 3D preview in a detail pane — drag to inspect it from any angle before committing. Applying a shape is now an explicit step (an "Apply shape" button) rather than happening the instant you click a card, so a stray click can no longer swap a node's geometry by accident.

Also in this release

• The Example Guide window's scrollbar no longer cuts through the title bar.
• Fixed a source of intermittent interaction test failures around drag-based node selection.

Konjugate v0.5.11: Node Rotate, Scale, and a Visual Examples Browser

Highlights

• Rotate and scale nodes directly on the canvas — new Rotate and Scale toolbar tools sit alongside the existing Move tool, each constrained to a precise axis via the same gizmo interaction. Precise numeric rotation/scale fields were also added to the node editor's Appearance tab, for exact values instead of eyeballing a drag.
• Uniform scaling — hold Shift while dragging any scale handle (a single axis or a two-axis corner) to scale a node evenly in all three directions at once.
• Group rotate — rotating a multi-node selection now revolves every other selected node around the pivot as a rigid body, instead of each node just spinning in place around its own centre.
• Pose Visualizer respects editor transforms — a node's canvas-authored rotation and scale now carry over into the Pose Visualizer add-on when "Editor shapes" is enabled, composing correctly with the live simulated pose.
• Examples Explorer — the old text dropdown for bundled example projects is now a searchable dialog with domain filters, a thumbnail grid, and a detail preview pane.
• User shape library — shapes uploaded via "Import file" (STL/STEP) are now automatically saved into a personal shape library alongside the bundled one, for reuse across projects.

Fixes

• Long equations in example guides (e.g. the Four Bar Linkage's Rod X equation) no longer hide their left-most portion when scrolled.

Also in this release

• macOS release builds now cover both Apple Silicon and Intel Macs.