Home

ECCE

This wiki has developer-facing notes for working on the codebase.

How the pieces fit

ECCE runs in one of two ways. With an ECCE server (the default): the data server (Apache/WebDAV: projects, calculations, results, basis sets) and the message broker (Mosquitto), either on your own computer or as a central server for a group or class. On its own (optional, Edit > Preferences > Data folder): the client keeps its projects in a local folder and runs its own broker, with no ECCE server. In both, calculations run on a workstation or cluster that the client reaches over ssh, and the client follows the jobs.

Getting up and running

Start here: GETTING_STARTED.md in the repo — build dependencies, build, package, install, start the background services, create your account, and log in, step by step, for this fork's CMake/CPack build on Debian 13. The README has the same steps plus screenshots and an overview of what the app actually does. Both live in the repo (not the wiki) so they stay in sync with the code they describe as it changes — the wiki won't duplicate them.

As of the v8.0.0 "Phoenix" release, this is an actively maintained, modernized fork: current build system (CMake/CPack), current wxWidgets (3.2, GTK3), current C++ (17), current Python (3), targeting Debian 13. See the latest release for what changed.

Platforms: CI builds on Debian, Ubuntu, Fedora and Rocky Linux (RHEL family) on every push; Debian 13 is the tested platform. ECCE runs on Linux only for now. Native macOS and Windows clients are the goal (#133, #232).

Useful pages

• Work plan — what is being worked on now and what comes next, in order
• Where to find things in the code — codebase orientation for anyone adding a feature or a new computational code
• Branches and releases
• Setting up a central ECCE server — one server for a group or a class, with many clients connecting to it, instead of a data server per user
• Connecting to a cluster that requires 2FA — authenticate once yourself and let ECCE submit and monitor jobs over that connection

Getting help

• Something not working? Run the session that goes wrong with ecce --bug, reproduce the problem, and close the Organizer. It turns diagnostic logging on and collects ECCE's logs, the service logs and ecce-diagnose output into one archive, ~/ecce-bug-<time>.zip (.tar.gz without zip). The archive holds no passwords, but it does contain host names, user names and paths, so look through it before you attach it. If ECCE won't start at all, run ecce-diagnose instead; for a job that didn't start or never finished, give it the job's run directory: ecce-diagnose /path/to/run/dir.
• Bugs, build failures, and feature requests: open an issue on the issue tracker. Attach the ecce --bug archive to a bug report; it usually saves several rounds of questions. ecce --version gives the version.
• Contributions welcome — see the issue tracker for open items, or just open a PR.

We're a small volunteer effort, and what helps most now is using ECCE and telling us what breaks: run your real calculations with it — on your own machine, a cluster, or a teaching lab's central server — and report anything that fails, looks wrong or is confusing, with an ecce --bug archive attached.

A note on AI use: a lot of this modernization effort — including many commits, and many of the comments you'll see on issues and pull requests — was done with heavy use of Claude (Anthropic's AI assistant), under the maintainer's direction and review. This isn't hidden per-comment; this note is the disclosure. Treat AI-authored analysis the same as you would any other contributor's: useful, but verify anything you're relying on, especially root-cause claims in older issue threads.