Skip to content

Home

Jump to bottom
andy edited this page Oct 29, 2026 · 39 revisions

ECCE

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

How the pieces fit

Two ways to run ECCE: with an ECCE server (the default), or the client on its own with its projects in a local folder; in both, jobs go to the compute machine over ssh

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 and an overview of what the app does; the Gallery has screenshots of ECCE 9. 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 9 (the recommended version) also has native macOS and Windows clients, which are experimental (#133, #232); 8.18.x is Linux only.

First steps

  • At the first question, choose Store data on this computer.
  • File > Open Example Calculations gives finished calculations to look at.
  • Right-click Local data and choose New... > Project.... A project is a folder. Right-click the project to create a calculation.
  • ECCE-QM is built in. Other codes: see Running codes on Linux, macOS or Windows in the built-in help.
  • Register a code under Tools > Register Machines.... ORCA, Gaussian 16, NWChem, MOPAC and xTB are fully supported; on Debian and Ubuntu, sudo apt install xtb gives xTB.
  • File > New > Workflow... chains calculations: select a box and a code to add a step that starts from that box's final geometry, charge and multiplicity (e.g. xTB first, then ORCA). File > Open Example Calculations > Workflows has a finished one, hydrated Na+. Workflows are new in 9.5.0 and still a preview.
  • Results open as panels beside the 3-D view in the Viewer. A panel whose plot or table needs more room can be dragged out by its title bar into a window of its own (a second screen works too); Tools > Dock Floating Panels puts them all back. See Arranging the Viewer's panels.
  • Help > ECCE Help (Ctrl+H) opens the help.

Video tutorials

  • The chem4eva YouTube channel: installing ECCE on Windows and macOS, a first calculation with ECCE-QM and with ORCA, and more (with English and Swedish subtitles).

Useful pages

Getting help

  • Something not working? In the program, Help > Report a Problem... builds an archive with diagnostic data. It works on Linux, macOS and Windows, with no terminal command.
  • On Linux, or from a terminal: 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.

Clone this wiki locally