The Coexist Library’s Documentation#

A Python library for autonomously learning simulation parameters from experimental data, from the micro to the macro, from laptops to clusters.

Calibrated simulation vs. experimental photo.

Coupling Macroscopic Measurements with Microscopic Simulation Parameters#

Autonomously learn a given set of free parameters, such that an experiment is synchronised with an equivalent simulation. This synchronisation can be done in one of two ways:

  • Microscopically: in a Discrete Element Method (DEM) context, all simulated particles follow their experimental counterparts exactly. Naturally, this technique is limited to dilute systems and experimental imaging techniques that can capture the 3D position of all moving particles (e.g. PIV) - however, it provides information about the fundamental aspects of particle collision.

  • Macroscopically: a given simulation reproduces a system-specific macroscopic quantity (e.g. residence time distribution, angle of repose). This technique is completely agnostic to the simulation method and the quantity to be reproduced. In a DEM context, it can train coarse-grained simulations, using larger meso-particles to model multiple smaller ones.

The two corresponding algorithms are:

  • CoExSiST: Coupled Experimental-Simulational Study Tool.

  • ACCES: Autonomous Characterisation and Calibration via Evolutionary Simulation.

ACCESS was implemented in the coexist.Access class, providing an interface that is easy to use, but powerful enough to automatically parallelise arbitrary Python scripts automatically through code inspection and metaprogramming. It was used successfully from laptop-scale shared-memory machines to multi-node supercomputing clusters.

Tutorials and Documentation#

At the top of this page, see the “Getting Started” tab for installation help; the “Tutorials” section has some explained high-level examples of the library. Finally, all exported functions are documented in the “Manual”.


This library is still in its early stages, so large changes and improvements (sometimes breaking) are still expected; on the flipside, you can still shape the future of it! Sharing tutorials, documentation, suggestions and new functionality is more than welcome.

Indices and tables#