# AtomECS
> Simulate cold atoms with rust.

**New:** Paper out now on [arxiv](https://arxiv.org/abs/2105.06447)

[![crate_version](https://img.shields.io/crates/v/atomecs.svg?style=flat)](https://crates.io/crates/atomecs)
[![crate_version](https://img.shields.io/badge/docs-latest-blue.svg?style=flat)](https://docs.rs/atomecs)
[![build](https://github.com/TeamAtomECS/AtomECS/actions/workflows/build.yml/badge.svg)](https://github.com/TeamAtomECS/AtomECS/actions/workflows/build.yml) [![unit_tests](https://github.com/TeamAtomECS/AtomECS/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/TeamAtomECS/AtomECS/actions/workflows/unit-tests.yml)

`atomecs` is a rust crate for simulating ultracold atom experiments. It supports numerous features:
* Laser-cooling of atoms by optical scattering forces.
* Doppler forces on atoms that scatter light, including the random fluctuations that give rise to the Doppler temperature limit.
* Magnetic fields, implemented on a grid or through simple analytical models.
* Hot atoms generated by an oven.
* Hot atoms generated on the surface of a simulation volume (eg, to simulate thermal vapor in a chamber).
* Cooling light beams, defined by their detuning and gaussian intensity profiles.
* Volumes that define bounds for the simulation.
* File output in binary or text format.
* Thorough unit testing to ensure simulation results are correct.
* Good parallel performance on modern multi-core CPUs.
* Simulations can be wrapped using python/matlab, as shown in the [source_optimisation_example](https://github.com/TeamAtomECS/source_optimisation_example) or the [matlab examples](https://github.com/TeamAtomECS/matlab_examples).
* Optical dipole force traps.
* Confinement of atoms by magnetic fields, e.g. quadrupole and TOP traps.

# Getting Started

Instructions for installing rust can be found on the [rust website](https://www.rust-lang.org/tools/install), which includes the rust toolchain and `cargo` command line tool.

After cloning this repository using git, you can run examples using the `cargo` command line tool, e.g. `cargo run --release --example 1d_mot`.
The [matlab examples](https://github.com/TeamAtomECS/matlab_examples) show how to load and plot simulation results.

You can build the program documentation using `cargo doc`.

## Data-oriented design

`atomecs` follows the data-oriented Entity-Component-System (ECS) pattern, which is implemented using [specs](https://github.com/slide-rs/specs).
ECS is well suited to high-performance simulations, and is sufficiently flexible to accomodate changing design goals.

_If you are unfamiliar with data-oriented design - for instance, if you come from an object-oriented background - it is strongly recommended that you read up before diving into the code._ Some useful ECS resources are:
* Mike Acton's [GDC talk](https://www.youtube.com/watch?v=p65Yt20pw0g), which discusses the advantages of ECS + DOD (in the context of the Unity game engine).
* The [specs book](https://specs.amethyst.rs/docs/tutorials/) which describes the ECS used in `atomecs`.
* Although written for Unity/C#, the concepts in the [Unity Entities Package Documentation](https://docs.unity3d.com/Packages/com.unity.entities@0.14/manual/ecs_core.html) are very useful to understand.

## Current Limitations

* atom-atom interactions are not implemented. Most of our current work deals with atom sources, which have low steady-state number densities, so we haven't implemented this. Results for steady-state 3D MOTs should be interpreted carefully.

# Getting Involved

Our goal is to make AtomECS user-friendly, with friendly developers! Please feel free to use the issue tracker to ask questions, or join the conversations happening within the issues.

If you would like to submit a contribution:
* Take a look at the issues page to see if there is something suitable for a new user.
* Freely develop and change your own fork.
* When a feature is finished, raise a pull request to merge your changes back into the AtomECS repository. The team will openly review your code and suggest changes/improvements.

## The Team

The current developers of `atomecs` are:
* Dr. [Elliot Bentine](https://github.com/ElliotB256), Oxford
* Dr. [Tiffany Harte](https://github.com/tiffanyharte), Cambridge
* [Xuhui Chen](https://github.com/Pi-sun), Oxford
* [Maurice Zeuner](https://github.com/MauriceZeuner), Cambridge

The long term goal for `atomecs` is to have a complete simulation suite for cold atom experiments.
If you'd like to get involved in development, please do!