essim — system digital twin

Interactive simulator for the inter-card connections inside a system. Built around a domain model of modules → parts → pins / signals → connections, with importers for Mentor Graphics, Altium and ODS pinout sheets, a TUI shell with scripting, snapshots and BFS net analysis.

Status: early work-in-progress.

Quick start

cmake -S . -B build
cmake --build build -j
./build/essim

Inside the shell, type help for the live command list — or read the auto-generated reference at doc/user/commands.md. A worked bring-up script is at test/system.essim; load it with source test/system.essim.

To run a script without the TUI and print its output to stdout (CI-friendly):

./build/essim --batch --source bring-up.essim

Step-by-step walkthroughs for both the batch and TUI workflows are in doc/user/tutorial.md.

Dependencies

• C++17 compiler and CMake 3.14+.
• System libraries libzip and pugixml — install the development packages:
  • Debian/Ubuntu — sudo apt install libzip-dev libpugixml-dev
  • Arch — sudo pacman -S libzip pugixml
  • Fedora — sudo dnf install libzip-devel pugixml-devel
• libbsdl — the standalone BSDL parser, a sibling repo expected at ../libbsdl, pulled in via add_subdirectory and linked dynamically. Override its location with -DBSDL_DIR=/path/to/libbsdl. Powers the attach-bsdl command and the pin/JTAG checks.
• Fetched automatically at configure time via FetchContent (nothing to install): FTXUI v6.1.9 and doctest v2.4.11.
• Optional, only for the doc target: doxygen and python3.

Tests

./build/essim_tests
# or
ctest --test-dir build

Skip building tests entirely:

cmake -S . -B build -DBUILD_TESTING=OFF

Documentation

• doc/user/ — user guide, command reference, scripting.
• doc/api/ — auto-generated C++ API reference.
• DESIGN.md — implementation notes (domain conventions, TUI internals, gotchas).
• doc/README.md — how the doc pipeline is wired.

Regenerate auto-generated parts after substantive code changes:

cmake --build build --target doc      # needs doxygen + python3

Project layout

src/system/   domain model (Module/Part/Pin/Signal, Connection, Transform, …)
src/imports/  Mentor / Altium / ODS netlist importers
src/tui/      FTXUI shell (commands, screens, completion, history)
tests/        doctest suite
doc/          api/ + user/ Markdown trees, Doxyfile.in, gen_api_md.py
test/         sample netlists + system.essim bring-up script

Full layout & rationale in DESIGN.md.

Licence

Copyright (c) 2026 François Dausseur

Licensed under the European Union Public Licence (EUPL), Version 1.2 — the "Licence". You may not use this work except in compliance with the Licence. You may obtain a copy of the Licence in the LICENSE file or at https://joinup.ec.europa.eu/software/page/eupl.

Unless required by applicable law or agreed to in writing, software distributed under the Licence is distributed on an "AS IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the Licence for the specific language governing permissions and limitations under the Licence.

SPDX-License-Identifier: EUPL-1.2