Command line and configuration¶
Command line¶
| Command | |
|---|---|
python -m undine serve [--host 127.0.0.1] [--port 8700] [--llm-policy ...] [--mcp] [--import-root DIR] [--dep-root DIR] [--dep-host HOST] [--stop-jobs] |
start the server; --import-root (repeatable, default: home) limits where the UI may import GDS / OASIS from. --dep-root (repeatable, default: none) names the directories under which the browser and the HTTP API may add, update or sync a library dependency from a local repository (file://, /path, ~/path); without it they refuse every local one (the lib commands take any). --dep-host (repeatable) adds a remote host they may fetch a dependency or an index from; without it they fetch only from the hosts of the indexes this machine configures (the default index's, github.com, and those in $UNDINE_HOME/config.toml), and the lib and pkg commands fetch from any. A restart loses no work (Restarting the server): the simulations run on and the next server takes them up, unless --stop-jobs (stop them when this server stops) |
python -m undine new PROJECT [--pdk sky130A] |
create a project pinned to a PDK (a bare name picks a version whose PCells Undine runs, the tested one first), with an undine.lock (created undine.lock (format 1)) |
python -m undine set-pdk PROJECT PDK |
pin a project to another PDK version, e.g. sky130A@8afc8346a57f (recorded in pdk_history and in undine.lock, which it creates when the project has none; to the version the project already has, it prints already ... and writes only a missing or other pin in undine.lock; see Moving a project to another PDK version). A format 2 lock stays format 2: it gets the new PDK's pin (full commit and tree hashes, read from the PDK, seconds for one not hashed before); to the PDK it pins already, the pin is kept as it is. Refused, with nothing changed, when a locked package does not accept the new PDK: error: the PDK ... is not accepted by N locked packages:, then a line per package with its chain and reason (exit code 1); a locked package neither in the store nor installed is refused with run lib sync first. To the PDK the project names already it is never refused |
python -m undine import PROJECT LIB FILE (.gds or .oas) |
import a layout (the library is created when missing) |
python -m undine pdk list (also pdks) |
list the PDKs found, with the full commit, where they came from (ciel, volare, - for a plain directory), the directory and the libraries installed (see Checking your PDKs) |
python -m undine pdk verify PROJECT [--pin] [--network] |
hash the installed PDK (seconds the first time, then only the files whose stamp changed) and compare it with the pin in undine.lock; prints what differs, by part and file, then PDK <state> (verified, unverified, modified, missing, not pinned, other version); exit code 1 when the PDK is modified, missing or another version, or a locked library is not installed. Without --pin it never writes undine.lock. --pin pins the PDK as installed here (full commit, ciel source, libraries, a tree hash per part) and writes undine.lock as format 2, the other entries kept; on a format 2 lock it re-pins, and says what the old pin was. A locked package the new pin does not fit is a ! CHAIN: does not fit the PDK ... line, not a refusal (the exit code is the PDK's). --network: a 12-character id whose commit is not installed here may be looked up with ciel ls-remote. See Pinning the PDK |
python -m undine pdk fetch PROJECT [--yes] [--network] |
install the project's PDK with ciel: prints the family, variant, commit, libraries, ciel source and the root it installs into, asks (--yes: does not ask; no answer, or not y: not fetched, exit code 1), runs ciel fetch, then compares the PDK with the lock. The root is the first PDK root scanned that ciel can install into; only ~/.volare is refused. A running server finds the PDK after Rescan PDKs (or POST /api/pdks/rescan). See Fetching a project's PDK |
python -m undine pdk tested FAMILY [--all] |
the PDK commit of a ciel family (sky130, gf180mcu, ihp-sg13) that Undine is tested with, from its built-in profile; --all: every tested commit, one a line, the first the default. Exit code 1 for a family no built-in profile lists. ./setup.sh pdk reads it. Scans no PDK. See PDK profiles |
python -m undine pdk enable FAMILY [COMMIT] |
ciel enable --pdk-family FAMILY COMMIT, COMMIT by default the tested one (pdk tested); prints the command, then ciel's output; the exit code is ciel's. With the global --pdk-root, ciel installs into the first of those roots it can install into, as for pdk fetch (ciel enable --pdk-root ROOT ...). pixi run pdk runs pdk enable sky130. Unlike pdk fetch it needs no project and does not compare anything with a lock |
python -m undine store verify [--dry-run] |
re-hash every file and tree record of the store; removes those that do not match their name (--dry-run: says what it would remove) and makes a writable object read-only again; exit code 1 on any problem. Run lib sync in a project that used a removed one: it takes it again from its installed files, or fetches it |
python -m undine store gc [--dry-run] |
remove the tree records and files of the store that no project here locks or installs: the projects under --root, the working copies of their changesets, and the projects elsewhere that ran a dependency command (the store keeps a list). Prints removed N tree records and M objects, <size> (would remove with --dry-run). A lock it cannot read stops it before it removes anything (nothing was removed: make these locks readable (or remove them), then run store gc again, exit code 1). Kept repositories, PDK records and compiled models stay |
python -m undine doctor |
check the prerequisites (pixi run doctor) |
python -m undine lib add PROJECT NAME GIT [--rev REV] [--subdir DIR] [--package P] |
add a library dependency, pinned in undine.lock: NAME: COMMIT12 (N cells), locked in undine.lock. A package prints NAME: P VERSION at COMMIT12 (N cells, M internal), locked in undine.lock, installed as NAME and P under another local name, + P VERSION as NAMES, via REQUIRER for each package it brought in, and ~ LABEL: WHAT (not trusted): a simulation using it needs python -m undine lib trust PROJECT NAME for each that holds what the trust rule refuses. --package P: the repository's manifest must name package P (written into project.json). Everything is checked first and refused at once, naming every problem (N problems with the dependencies: and a - line each), with nothing changed; a package with dependencies, or under another name, needs lock format 2 (needs lock format 2: run python -m undine lib lock PROJECT --format 2 first). A new name may not be a project or PDK library, devices, or a folder of Xschem's library or of symbol_paths |
python -m undine lib update PROJECT NAME [--rev REV] |
move a dependency to another version (a package from an index: pkg update); prints the changed files and the cells using them, and for packages + P VERSION as NAMES (brought in), P: OLD @ C12 -> NEW @ C12 (moved), - P VERSION as NAMES: no longer needed. Takes the trust of what moved out of project.json. A name only a package places is refused: NAME: placed by X; update or remove that instead |
python -m undine lib remove PROJECT NAME |
remove a dependency, with the packages nothing needs any more: removed P VERSION (installed as NAMES) or removed NAME (git C12) each; a package another dependency still places stays (NAME: still placed by X). Takes their trust out of project.json. A name only a package places is refused as for update |
python -m undine lib trust PROJECT NAME [--untrust] [--yes] |
list what the trust rule finds in the dependency installed as NAME (NAME: P VERSION, trust key P@VERSION, then a line per finding: file, attribute, line, kind and text), then ask trust P@VERSION in PROJECT? [y/N] and add the key to project.json's trusted (P@VERSION: trusted in PROJECT (...)). --yes: does not ask. With no terminal and no --yes, or an answer other than y, nothing is trusted (exit code 1). --untrust: take the trust back, without asking. A dependency without a manifest has the key NAME@COMMIT12. Refused for a name not installed, or an install without a record (not installed by Undine: lib sync). No agent tool or undine call command reaches it |
python -m undine lib sync PROJECT [--offline] |
install the dependencies exactly as locked, and remove any that project.json no longer names (its .undine/deps/<lib>/ and its undine.lock entry; printed as <lib>: removed <commit>); all or nothing: when one fails (a remote unreachable, files that do not match the lock), none is installed and none removed. Each package is installed under every local name the lock gives it; one the locked PDK does not fit is installed all the same, with a ~ CHAIN: does not fit the PDK ... line. Frozen: it resolves nothing, and refuses, before anything is read, a lock that does not pin a dependency as project.json names it (after a pull that changed project.json: run lib lock). A dependency in the store is installed from there, with no network. --offline (or UNDINE_OFFLINE=1) never fetches: what the store and the kept repositories lack is named and nothing is changed |
python -m undine lib lock PROJECT [--format 2] |
lock what undine.lock does not pin as project.json names it (fetching and installing it, printed as <lib>: <commit> (sha ...), with , P VERSION for a package, and + P VERSION as NAMES, via REQUIRER for a package it brought in), and record the PDK and tool versions in use now. Also re-resolves an entry whose package's dependencies the lock does not install. --format 2 then writes the lock as format 2: the PDK pinned by its tree hashes (as pdk verify --pin), the tools with their origin, the entries as they are (each gets a tree the next time lib update or lib lock writes it); on a format 2 lock it leaves the PDK's pin alone. When what it resolves needs format 2 (a package's own dependencies, a package under another name), --format 2 converts the lock and resolves in one write, all or nothing: a refusal leaves the format 1 lock as it was; without --format 2 it is refused with that hint. A package the PDK it pins does not accept is a ! CHAIN: does not fit the PDK ... line, not a refusal |
python -m undine lib status PROJECT |
what differs from undine.lock here: the PDK row (its state, as pdk verify names them), the dependencies, then ! issue, ~ warning and note: lines, and as locked when there is no issue. Exit code 1 on an issue only: a tool of another version or origin, another Undine version or a tools not pinned (pixi.lock not recorded) is a ~ warning, shown with the executable found here; the PDK unverified or unchecked, another Undine commit or another pixi.lock is a note. A dependency project.json no longer names but still installed or locked is leftover. One row per local name: a dependency's row ends with its package and version (-> P VERSION under another local name) and trusted or not trusted; a package another one brought in has via CHAIN on the next line, and the own-name row of a package added directly under another name has = NAME (the same install) |
python -m undine pkg search [QUERY] [--index I] [--project P] |
the packages of an index whose name or description holds QUERY, one line each: NAME VERSION DESCRIPTION (LICENSE), the newest version that is not yanked. --index: a nickname or URL (default: the default index); --project: for the nicknames its project.json names. Exit code 1 when nothing matches |
python -m undine pkg info PACKAGE [--index I] [--project P] |
what the newest version says (git, commit, tree, license, PDK, needs per dependency, exports) and every version listed, (yanked) marked |
python -m undine pkg add PROJECT PACKAGE[@REQ] [--as NAME] [--index I] |
add a package from an index: the newest version that is not yanked, fits the PDK and that every requirement accepts, with the packages it needs; PACKAGE VERSION at COMMIT12 (N cells), requirement REQ, locked in undine.lock, then + P VERSION as NAMES, via REQUIRER per package it brought in. Without @REQ the requirement written to project.json is ^ the version taken. --as: another local name. Needs lock format 2; checked and refused as lib add is |
python -m undine pkg update PROJECT [NAME ...] [--version REQ] |
fetch the index again and move each named package (default: every package from an index in project.json), with what only it reaches, to the newest version its requirement accepts: P: OLD -> NEW per package that moved, NAME: as locked when nothing did. --version: a new requirement for the one name, written to project.json |
python -m undine pkg outdated PROJECT [--offline] |
each locked package from an index with a newer version: locked, the newest its requirement accepts (- for one only a package places), the newest listed, and direct or via who places it. Fetches each index first (--offline: reads the local copies) |
python -m undine pkg tree PROJECT |
the dependencies as locked, as a tree ((*): shown above already) |
python -m undine pkg why PROJECT PACKAGE |
every chain from the project to a locked package |
python -m undine pkg lock PROJECT |
as lib lock |
python -m undine pkg remove PROJECT NAME |
as lib remove |
python -m undine pkg migrate PROJECT NAME [--index I] |
turn the git dependency NAME into a package from an index, when the index lists the version installed (its manifest's; the index's local copy is fetched again once when it does not) and that version's included files equal the installed ones, file by file: NAME: now P VERSION from URL, requirement =VERSION, then the files no longer installed (outside the manifest's [files] include). The requirement written is =VERSION; pkg update PROJECT NAME --version ^VERSION loosens it. A format 1 lock is converted to format 2 first, as lib lock --format 2. Refused, with nothing changed, for a dependency with no manifest, a version the index does not list, or a file that differs |
python -m undine pkg sync PROJECT [--offline] [--from-vendor DIR] |
as lib sync. --from-vendor: first read the trees pkg vendor wrote into DIR (a tapeout bundle, or its vendor/) into the store, each directory hashed and compared with undine.lock before any file enters the store (NAME: imported from vendor/DIR, in store or not vendored), then install offline: no repository and no network. A vendored file changed, added or removed is refused, with nothing imported (Licences and vendoring) |
python -m undine pkg licenses PROJECT [--json] |
the licence of every locked dependency (a package's from its manifest, else from the local copy of its index; a plain git dependency records none, and its top-level LICENSE, COPYING or NOTICE files are named) and of the PDK. Reads the store and the installs; fetches nothing. --json: LICENSES.json as pkg vendor writes it |
python -m undine pkg vendor PROJECT DIR [--offline] [--yes] |
write DIR/vendor/: every locked tree as plain files (<package>@<version>/, a plain git dependency as <name>@<commit>/), vendor.json, LICENSES.json and LICENSES.md; DIR: N files, B bytes per tree. Each written tree is hashed again and compared with the lock before vendor/ is moved into place. A tree in neither the store nor the install is fetched after asking fetch them from their repositories? [y/N] (--yes: without asking; --offline: refused, nothing written). Refused when DIR/vendor/ exists. The PDK is recorded, not copied |
python -m undine pkg index list [--project P] |
the indexes known here (undine, ~/.undine/config.toml's [indexes], project.json's indexes) with their URL and the commit last fetched |
python -m undine pkg index update [NAME ...] [--project P] |
fetch indexes again (default: every one known): NAME: COMMIT12 each |
python -m undine pkg index add NAME URL [--project P] |
give an index a nickname: NAME = "URL" into ~/.undine/config.toml's [indexes] (the rest of the file kept as written), or with --project into the project's project.json indexes, so that a clone finds it. Nothing changes when the name has that URL already; a name with another URL is refused |
python -m undine pkg init LIBRARY [--name N] [--version V] [--license SPDX] [--repository URL] [--force] |
write LIBRARY/undine-package.toml for a library you publish. LIBRARY is the library's directory (its project found by walking up to project.json) or PROJECT/LIBRARY; a dependency's or a PDK's library is refused. Defaults: name the library's, version 0.1.0, exports the cells that have a symbol, the design's [files] include, [pdk] from the project's PDK (commits and built_with its full commit), the project's index dependencies the library's schematics place (^ the locked version), repository the git remote origin. A placed git dependency or project library is written as a comment. Prints each value it guessed (KEY VALUE (from where)) and ~ for what is missing (licence, repository, PDK commit). --license must be an SPDX expression (syntax only). An existing manifest is replaced only with --force |
python -m undine pkg pack LIBRARY [--index I] [--check FILE --check-url URL] |
print the index line of the release: the package's subdirectory without uncommitted or untracked changes and HEAD at the tag v<version> (<name>-v<version> when the repository holds more than one package), else refused saying what to do. The tree is hashed from the local repository's blobs, as a consumer hashes it. A requirement from another index than --index (default: the default index) gets its URL. check is written only with both --check (its SHA-256) and --check-url (an https URL). A git dependency or a manifest without repository is refused |
python -m undine pkg check LIBRARY --no-run [--index I] [--offline] [--out FILE] [--json] |
the checks of a publish that need no PDK, written to <project>/.undine/check/<name>-<version>/undine-check.json (--out: elsewhere; --json: printed too): the repository serves the tag at HEAD (--offline: not checked), file sizes (UNDINE_PKG_FILE_MAX) and LFS pointers, the licence, dependencies (no git ones; solved from the index, fetched first unless --offline), built_with equals the project's PDK commit, the libraries the schematics place, and the code blocks and RTL listed with what the trust rule refuses. Prints a summary, ~ per warning, ! CHECK: MESSAGE per problem and wrote FILE (sha256 HEX): passes or does not pass. DRC, LVS, the symbol and netlist checks and the specs are not run yet, so the report does not pass and the exit code is 1; without --no-run the command is refused for now. A package not clean at its tag is refused, with no report |
python -m undine git-setup PROJECT |
make the project a git repository that diffs layout cells as text (Version control with git) and merges the files of a cell (.sch, .sym, .oas, .netlist.yaml, .intent.yaml) and the operation log object by object, and project.json and undine.lock entry by entry (semantic diff and merge), the merge bases of a criss-cross merge included (merge-driver --virtual-base), and installs a pre-commit hook that refuses unsaved layout edits (precommit; not over a hook of the repository's own, nor with core.hooksPath set: it then prints the command to add). Run it again to upgrade a project set up before, and in every clone; in a hook it installed, only the line that runs undine precommit is replaced, lines added to the hook stay; the lines of Undine's own output its .gitignore lacks (one added since, such as /changesets/requests/) are appended and named, the others kept. It commits nothing, and says when the repository has no commit yet (an applied changeset is committed only onto a branch with one: commit the project's files, or use Make the first commit in the History panel, whose Set up git makes that commit itself after its git init) |
python -m undine textconv FILE.oas |
print a layout file as sorted text (the diff driver git-setup registers) |
python -m undine merge-driver [--virtual-base] BASE OURS THEIRS PATH |
the merge driver git-setup registers (as python -P -m undine merge-driver %O %A %B %P; on Python 3.10, which has no -P, as python -c '<prelude>' merge-driver ..., the prelude taking the current directory off the module path: git runs it in the repository's top directory, whose files are never imported); git runs it for a file both branches changed. It writes the merged file into OURS, then a report into .git/undine-merge/PATH.json (local to the clone), and prints a line: what it merged, or the conflicts left open (a single one in its own words, which say what the file has for it) and the commands to go on with. Exit code 1 when conflicts are open (the file then has ours' value for each) or the merge failed (the file is then ours whole, the report has the error). With --virtual-base (registered as merge.undine-base.driver, which merge.undine.recursive names), the driver git runs to merge the several merge bases of a criss-cross merge into one: the merged file when they merge cleanly, else (a conflict open, or an error) their own base BASE whole (empty when they have none), so that the merge itself sees both branches' changes and stops on the conflict rather than taking one branch's resolution; exit code 0 either way, no report, a line only when it took the base |
python -m undine resolve PATH [--theirs ID ...] [--ours ID ...] [--all-theirs] [--all-ours] |
merge a conflicted file again from git's index, taking the named side for those conflicts (--all-theirs / --all-ours: for every open one); decisions add up across runs. PATH is relative to the current directory or to the repository's top (as the driver prints it; :/PATH: from the top). git add :/PATH marks the file resolved. Exit code 1 while conflicts are open |
python -m undine merge-check [DIR] [--commit C] [--json] |
in the project directory DIR (default: here), during a merge, cherry-pick or rebase, or for the merge commit C: the conflicts still open, the warnings, and the cells to verify with DRC / LVS (cells whose hierarchy is as neither branch had it). The warnings come from the driver's reports, which stay in the clone that merged: for a merge commit, the files it combined that have no report here are listed (their warnings are unknown). An octopus merge (git merge A B) takes every branch as a side and runs no driver: a committed one has no report, and while one is stopped at a conflict only the files resolve merged have one; merge-check says that such files were merged by lines. During a rebase or a cherry-pick of several commits it covers the commit git stopped at, and says so when earlier commits were applied (their warnings were printed when they were merged). After git merge --squash, git cherry-pick -n or git stash pop, which leave no commit for theirs, it shows the conflicted files with their conflicts and warnings, without the cells to verify. Exit code 1 while files are conflicted |
python -m undine precommit |
the pre-commit hook git-setup installs: refuses the commit (exit code 1) when an operation log in the index (history/<lib>.jsonl as staged) holds layout edits not saved to the cell files, naming the library and the cells: save the layout in Undine and stage the files again, or commit with --no-verify to keep the journal (why). The commit that concludes a merge or a cherry-pick refuses only the unsaved edits made while concluding it (in neither branch's log): which of the branches' edits stay pending, the merge decided. That holds for git merge --squash (the other branch is the first commit SQUASH_MSG lists) and git cherry-pick -n too: journal records a merge copied here and not committed yet (merged_seq, not in HEAD's log) are never refused |
python -m undine diff OLD NEW [--kind K] [--json] |
semantic diff of two files, with the merge's identities (the view from the file name, or --kind schematic, symbol, layout, netlist, intent, log) |
python -m undine diff --rev A [B] [--dir DIR] [--json] |
semantic diff of every project file that changed from revision A to B (default: the working tree, with its untracked files that git does not ignore); layouts also show the XOR area per layer |
python -m undine mcp-stdio [--url URL] [--ui-url URL] [--ssh HOST] [--no-start] [--no-open] |
local MCP entry for desktop AI apps: starts or reuses the server, opens the review (Agent and MCP); with --ssh, the server on HOST through an SSH port forward (Undine on another machine) |
python -m undine mcpb [--out FILE] |
build the Claude Desktop extension (pixi run mcpb, into dist/) |
Global options: --root DIR (projects root, default $UNDINE_ROOT or ~/undine-projects) and --pdk-root DIR (repeatable;
replaces the default PDK roots $PDK_ROOT, ~/.ciel and ~/.volare, see Where Undine looks for PDKs).
The lib commands, pdk verify, pdk fetch and set-pdk read undine.lock before they change anything. One they
cannot read is refused with one line (undine: ..., exit code 1), and project.json, undine.lock and .undine/deps/
stay as they were: a lock of a newer format (undine.lock has format 3, made by a newer Undine (this one reads formats
1 and 2) ...: update Undine), or one that is not valid JSON or has a format no Undine writes (fix it, or
git checkout undine.lock). A lock without format is read as format 1. See
troubleshooting.
Lock formats. Today's commands write format 1, and keep a format 2 lock format 2. Only two commands make a lock
format 2: pdk verify PROJECT --pin and lib lock PROJECT --format 2 (undine.lock).
A command that made undine.lock prints created undine.lock (format N). A package
that names dependencies, or is added under a name other than its own, needs format 2: on a format 1 lock lib add,
lib update and lib lock refuse it with needs lock format 2: run python -m undine lib lock PROJECT --format 2
first; nothing was changed.
Restarting the server¶
Restarting Undine (to deploy a change: ./scripts/restart.sh, Ctrl+C and start again, even kill -9) loses no work.
Closing the server's terminal or SSH session (SIGHUP) stops it as Ctrl+C and SIGTERM do:
- Running simulations go on. ngspice runs in a session (a process group) of its own, so it does not stop with the
server (Ctrl+C in the server's terminal does not reach it either). The next server on the same projects root adopts
each run whose ngspice still runs: it holds one of the
UNDINE_SIM_JOBSslots, its time limit counts from its start,cancel_jobstops it (with anything it started), and when it ends it is finished as any run (its log, raw file and measurements read;doneorfailed; whoever waits for it, e.g.wait_for job:<id>, is told). A run whose ngspice finished while no server ran is collected when it is next read. Adopting needs Linux (/proc); elsewhere a server's ngspice still ends with it when it stops (not afterkill -9, which leaves it running with no server to collect it). - Queued simulations go on in their order (
<root>/sim-queue.jsonl). - Calls in flight are not cut. When the server is asked to stop, a call that waits (
wait_for,run_simulation'swait_s,check_specs,sweep,run_checks,extract_parasitics) answers at once with what it has (wait_for:"stopping": true, and a note that says whether the runs go on or were stopped with--stop-jobs; a DRC, LVS, extraction, RTL or LibreLane job it waited for ends with the server and is listed inended), so the server stops within seconds; wait again afterwards, and run again what ended.run_checksandextract_parasiticsanswer"stopping": truetoo: their checks end with the server (and none starts while it stops), so call them again once the server is back. - A run no server can finish (its ngspice was killed or crashed, or the machine restarted) is
interrupted, with why: run it again. So is a DRC, LVS, extraction, RTL or LibreLane run the stopped server left unfinished: only simulations are taken up. A server ends those runs as soon as it is asked to stop (they areinterruptedat once, so the next server, which may already answer, runs such a check anew instead of reusing it), and starts no new one (it answers that the server is stopping: run it again once it is back). One killed outright (kill -9, a crash) cannot: the next server stops what is left of them as soon as it sees the run (its status records the tool's process), andcancel_jobstops it too. - Agents keep their sessions. An MCP session goes on after the restart with the same changesets, the same write
lock owner and its own jobs (
<root>/mcp-sessions.json; a session unused for 30 days is forgotten); an agent the person stopped stays stopped. If the server does not know a session any more, the shell and Python clients start a new one and continue in it the changesets they had open. They, andmcp-stdio, send a call again while the server restarts (connection refused, or 503 from a proxy) for up toUNDINE_RESTART_WAIT_S(120 s), with the same request id, so a write is never done twice; over--sshtoo (the forward accepts the connection and closes it: a call that can be sent twice waits while the server does not answer through it). Anundine callmade while it is down waits for it too, when its--sessionwas with that server (a new session name says at once that Undine is not running). Agents sharing one--session(agent=NAMEeach) keep each other's changesets in the session file. A named--sessionis the agent of that name; one that opened its changeset before this version (unnamed) goes on with it under its name at its next call, its write lock handed over. This happens once: a changeset the session opens later withagent=""stays the unnamed agent's. After the first restart from an Undine before this version, the sessions whose simulations still run in a changeset are taken from those jobs, with that changeset open; another agent opens its changeset again (open_changeset id=...; ano jobanswer names the changeset that has the job).
One server at a time works on a projects root's simulations and keeps its sessions (it holds
<root>/sim-jobs.lock): a second one started on the same root meanwhile (the next one while the last one still stops,
or one too many) runs its own (listed in <root>/sim-queue-<id>.jsonl) and takes the others up once the first has
gone; if the second one stops first, the first takes up what it left within seconds. A server stopping lets a run
whose turn just came start first, so that the next one never starts it twice. A run started by an Undine before this version records no process: it is found by
its directory and command line, and taken up once that server has gone (until then that server finishes it itself);
the runs such a server had queued are interrupted.
To stop the simulations as well, start the server with --stop-jobs: when it stops, queued runs are cancelled and
running ngspice processes are ended, with anything they started. A single run is stopped with cancel_job or Cancel in the simulation panel.
A simulation left running while no server runs is not limited in time until a server takes it up again.
Configuration (environment)¶
| Variable | Default | Used for |
|---|---|---|
UNDINE_ROOT |
~/undine-projects |
projects root (also read by the example scripts) |
PDK_ROOT |
an extra PDK root, searched before ~/.ciel and ~/.volare; also where ciel installs (PDKs) |
|
UNDINE_TOOLS |
the pixi environment under pixi run and in a server mcp-stdio starts from it; unset: the server's own environment (pixi, conda or venv), then ~/undine-tools |
prefix searched (bin/) for ngspice, Xschem, Netgen, Magic before PATH |
UNDINE_PCELL_PYTHON |
.pixi/envs/pcell/bin/python |
Python that runs the sky130 and IHP PCell generators (gdsfactory 8.x with kfactory) |
UNDINE_PCELL_GF180_PYTHON |
.pixi/envs/pcell-gf180/bin/python |
Python that runs the GF180MCU PCell generators (gdsfactory 7.9) |
ANTHROPIC_API_KEY (or ANTHROPIC_AUTH_TOKEN) |
the cloud agent | |
UNDINE_LLM_SERVER_URL / UNDINE_LLM_SERVER_KEY |
http://127.0.0.1:11434/v1 (Ollama) |
the EDA-server agent |
UNDINE_LLM_POLICY |
both |
same as --llm-policy |
UNDINE_MCP |
off | same as --mcp |
UNDINE_ENV, UNDINE_LOG, PORT |
~/.undine/env, /tmp/undine.log, 8700 |
scripts/restart.sh: secrets file it loads, log file, port |
UNDINE_AGENT_MAX_WRITES |
none | an optional cap on the edits an agent may make in one changeset |
UNDINE_SIM_JOBS |
the cores but two | simulations (ngspice) the server runs at once; the others wait in order (queued, with their queue_position) |
UNDINE_SIM_THREADS |
1 |
ngspice threads (num_threads, OMP_NUM_THREADS) per simulation; 0 keeps ngspice's own setting (some builds set 8, which slows a shared machine down) |
UNDINE_SIM_FULL_MODELS |
off | 1: simulations read the PDK's whole model library, not a copy reduced to what the netlist uses (PDK models) |
UNDINE_CACHE |
$XDG_CACHE_HOME/undine (~/.cache/undine) |
reduced model libraries (models/): made again when a library file changes, removed after 30 days unused. No longer used for the compiled Verilog-A models, which go to the store (build/, see UNDINE_STORE): models an earlier Undine compiled into osdi/<PDK id>/ here are still found until ./setup.sh osdi moves them into the store |
UNDINE_SIM_TIMEOUT, UNDINE_SIM_TIMEOUT_MAX |
3600, 43200 |
seconds a simulation may run unless the caller gives time_limit_s, and the most a caller may give; then ngspice is stopped |
UNDINE_LIBRELANE |
librelane on PATH, else nix-shell ~/librelane --run |
how to run LibreLane: an executable, or a wrapper ending in --run (e.g. nix-shell /path/to/librelane --run) |
UNDINE_HOME |
~/.undine |
per-user files: connections added in the UI (connections.json, with their keys), the launcher's server log, the store |
UNDINE_STORE |
$UNDINE_HOME/store |
the store alone: dependency files, kept git repositories, PDK hashes, compiled Verilog-A models (The store) |
UNDINE_STORE_LINK |
link |
copy: dependencies are installed as read-only copies, not hard links into the store |
UNDINE_OFFLINE |
off | 1: lib sync and the sync of the HTTP API never fetch (as lib sync --offline) |
UNDINE_CIEL |
the ciel beside Undine's Python, else PATH |
the ciel pdk fetch and pdk enable run (a path that is not a file: none runs) |
UNDINE_FETCH_MAX |
1073741824 (1 GiB) |
the most bytes the files of one dependency may have (and at most 100 000 files), and the most one fetch of a dependency or an index may receive |
UNDINE_PKG_FILE_MAX |
52428800 (50 MB) |
the most bytes one file of a package may have: pkg check reports a larger file as a problem |
UNDINE_URL, UNDINE_UI_URL, UNDINE_OPEN |
http://127.0.0.1:8700, the server, the browser |
mcp-stdio: server to use or start, where the review opens, the command that opens it ({url} replaced) |
UNDINE_SSH, UNDINE_MCP_TOKEN |
none, read from <projects root>/mcp-token |
mcp-stdio: the host Undine runs on (same as --ssh), the token to use instead of reading it |
UNDINE_RESTART_WAIT_S |
120 |
undine call, the Python client, mcp-stdio: how long a call refused while the server restarts (connection refused, 503 from a proxy) is sent again (Restarting the server) |
UNDINE_CLI_SESSIONS |
~/.undine/cli-sessions.json |
undine call, undine session: the file that keeps the shell's sessions (per server and --session name) between calls; agents side by side may each have one (Scripts and the shell) |
UNDINE_MAX_CHARS |
25000 |
undine call: the characters of a result it prints, shortened inside and still valid JSON (same as --max-chars; 0: all of it; Long results) |