# 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

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

Requirements:

- A C++17 compiler.
- CMake 3.14+.
- System packages: `libzip` and `pugixml` (Arch: `pacman -S libzip pugixml`).
- FTXUI (v6.1.9) and doctest (v2.4.11) are fetched at configure time via
  `FetchContent`.

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

## Tests

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

Skip building tests entirely:

```sh
cmake -S . -B build -DBUILD_TESTING=OFF
```

## Documentation

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

Regenerate auto-generated parts after substantive code changes:

```sh
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`](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`](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