Electronic Structure for Students (ESS)

Project background

Electronic structure theory is the branch of quantum chemistry concerned with computing the distribution of electrons in atoms and molecules. The standard methods are foundational to modern computational chemistry but are usually first encountered by students through dense textbooks and command-line software designed for researchers, not learners.

ESS was conceived as a way to compress that gap: a self-contained mobile application that lets a student define a small molecule, run a real electronic structure calculation on their own device, and inspect the resulting molecular geometry, orbitals, and energetic quantities through a 3D viewer. The intent was never to replace research-grade packages (such as Gaussian or PySCF), but to provide a pedagogically honest environment in which the equations behind those packages become tangible.

How the project originated

During 2021 I was independently studying electronic structure theory and quantum chemistry, working through the standard texts and reproducing small calculations by hand and in scratch code. The motivation was personal: I wanted to understand the methods well enough to implement them from first principles rather than treat them as black boxes. Yep, just for the fun of it.

In parallel, my university launched a funding initiative during the pandemic intended to support educational digital projects: tools that could be used for remote and self-directed learning while in-person laboratories were closed. Together with my thesis advisor, I submitted a proposal to build a student-oriented electronic structure tool that consolidated what I had been studying into a usable application. The proposal was accepted and received around $500,000 MXN in institutional funding ($25,000 USD back then).

The funds were used to purchase specialized equipment for developing the app and to hire staff to work on the iOS version, the web-based learning platform, and the project’s pedagogical design.

Educational goals

The application was shaped by a small set of pedagogical commitments rather than feature targets:

• A student should be able to construct a molecule, choose a method, and run the simulation without first learning a separate input-file syntax.
• The output should be visually and numerically interpretable: orbital energies, equilibrium geometries, and molecular structure rendered in 3D.
• Default parameters should correspond to choices that are reasonable in a teaching context, and the underlying assumptions should be visible to the student rather than hidden.
• The tool should run on commodity Android and iOS hardware, since requiring an specialized workstation would defeat the purpose.

My technical role

I was responsible for the technical work end to end: the numerical core, the Android application, the 3D rendering, the local persistence layer, and the user interface. My advisor’s role was scientific oversight and shaping the pedagogical framing. The engineering implementation was mine.

In practice this meant moving between two modes of work: deriving and verifying the mathematical machinery and then translating that machinery into code that would run inside the constraints of an Android device.

Scientific algorithms and calculations

This section is for those interested in the scientific rigor behind the implementation of computational methods.

The computational core implements the standard methods of single-determinant electronic structure theory in a Gaussian-type orbital basis. The main components include:

• Integral evaluation. Overlap, kinetic energy, nuclear-attraction, and two-electron repulsion integrals over contracted Gaussian basis functions.
• Self-consistent field procedure. A Hartree–Fock solver built around the Roothaan equations: construction of the Fock matrix, diagonalisation in the orthonormalised basis, density matrix update, and convergence by both energy and density criteria. Damping and a simple DIIS-style extrapolation were used to stabilise convergence for less well-behaved starting geometries.
• Basis set handling. Parsing and storage of contracted Gaussian basis sets in a normalised internal format.
• Derived quantities. Orbital energies, total electronic and nuclear-repulsion energies, Mulliken population analysis, and dipole moments, each rendered in 3D alongside the molecule that produced it so the student can see what the numbers physically represent.

Android application development

The application was written in Kotlin using the Android SDK. The structure followed a standard layered design: a numerical layer (the electronic structure engine) with no Android dependencies, a persistence layer over SQLite for stored molecules, basis sets, and calculation results, and a UI layer built from Android views and fragments.

From the user’s perspective the workflow is linear: define or load a molecule, choose calculation settings, run the job, and explore the result. Each completed calculation is stored locally so a student can return to it, compare across methods, or inspect the orbitals without re-running the calculation. The persistence schema was designed so that a “calculation” is a first-class object with its inputs, convergence trace, and final quantities all retrievable as a unit.

Because these calculations can take noticeable time on a phone, the numerical work runs off the main thread with progress reported back to the UI, both a convergence indicator and the live energy at each iteration.

3D molecular rendering

Molecular visualisation was implemented directly in OpenGL ES rather than through a higher-level library, both to keep the dependency footprint small and because the rendering requirements were specific enough that an existing library would have been more constraint than help.

The renderer draws atoms as shaded spheres and bonds as cylinders, with a simple Phong-style lighting model implemented in GLSL shaders. Geometry for spheres and cylinders is generated procedurally once at startup and reused via instanced transforms, so the per-frame cost scales with the number of atoms and bonds rather than with mesh complexity. The camera is an orbit camera driven by touch gestures: single-finger rotation, two-finger pan, and pinch zoom, all mapped onto a stable trackball model so that orientation behaves predictably regardless of where the user starts dragging.

Beyond ball-and-stick geometry, the viewer renders isosurfaces of selected molecular orbitals computed from the calculation result, which is the part students tend to remember: seeing the electron density surrounding the most electronegative atoms as an actual shape in space, alongside the energy that produced it.

Technologies used

• Language. Kotlin (Android SDK).
• Persistence. SQLite via Android’s built-in database APIs.
• Graphics. OpenGL ES with custom GLSL shaders.
• Numerics. Custom Kotlin implementation of integral evaluation and SCF; no external quantum chemistry dependencies.
• Concurrency. Coroutines for off-thread SCF execution and progress reporting.
• Build. Gradle, Android Studio.
• Validation. Cross-checks against reference values from established electronic structure packages on a small benchmark set

Technical challenges

Several problems were genuinely non-trivial and required deliberate work to resolve:

• Numerical stability on mobile floating-point. Two-electron integrals and Fock-matrix elements span many orders of magnitude. Naive summation produced visible round-off drift in convergence behaviour, and the calculation procedure had to be structured to control accumulated error.
• Memory pressure. Storing the two-electron integral tensor naively is the fastest way to exhaust a phone’s heap. Sparsity, symmetry reduction, and direct (on-the-fly) Fock construction were combined to keep memory bounded for the molecule sizes the application targets.
• SCF convergence behaviour. For a teaching tool, “fails to converge” is a bad outcome even when it is technically the right answer. Damping, level shifting, and a simple extrapolation strategy were used to broaden the set of starting geometries from which the calculation would settle, while still surfacing genuine failures honestly rather than hiding them.
• Orbital isosurface extraction on a phone. Evaluating a molecular orbital on a 3D grid and extracting an isosurface in real time, at a resolution that looks like an orbital and not a Minecraft-cube model, required tuning the grid generation, the marching-cubes pass, and the upload of the resulting mesh to the GPU so that the frame rate stayed acceptable on mid-range hardware.
• Bridging two disciplines in one codebase. The numerical layer and the Android layer have very different conventions and concerns. Keeping the interface between them clean, so that the physics did not leak into the UI and the platform did not leak into the physics, was an ongoing design effort throughout the project.

Lessons learned

• Between two worlds. A lot of scientific software development sits in the seam between two distinct skill sets. The physics has to be right and the engineering has to be right too. A wrong sign in an integral and a wrong lifecycle on an Android fragment will both crash your application, but only one of them will be obvious from a stack trace.
• Technical precision above everything. It was the first time I had to take responsibility for a piece of software where being ~roughly~ right was not enough: the numbers had to actually match reference values, or there was no point.
• A special love for graphics. I also came away with a durable appreciation for graphics programming as a discipline. Writing the renderer from the GLSL level up made the rest of the application’s performance characteristics legible to me in a way that no other documentation could have produced.
• Self-taught is an achievable way of creating stuff. ESS was a demonstration, mostly to my self, that self-directed study of a difficult scientific topic could be carried all the way through to a working artefact, and that the path from a textbook chapter to a piece of software running on a phone is long but entirely achievable.