Intro
=====

Substrate
----------
The substrate is defined as a periodic function, either a monochromatic superposition of plane waves or a potential well of a given shape repeated on a Bravais lattice.
The relevant module is ``flake.substrate``.

For a plane-wave (sinusoidal) substrate, the wave vectors are generated by ``flake.substrate.get_ks``; the number of vectors controls the symmetry and the length sets the spacing [1].

For a lattice of wells, the substrate is defined by the well shape parameters (Gaussian, tanh, or flat) and the lattice vectors [2–5].
The lattice can be decorated with a multi-site basis.

Parameters are specified in a YAML file and loaded via ``flake.substrate.substrate_from_params``.
See ``examples/0-Substrate_types.ipynb`` for details.

Cluster
-------
The cluster is a collection of points (optionally decorated with a basis) belonging to a 2D Bravais lattice, cut to a given shape.
Available shapes: circle, hexagon, rectangle, triangle, parallelogram, ellipse, or arbitrary polygon via the `Shapely package <https://shapely.readthedocs.io/en/stable/>`_.
The relevant module is ``flake.cluster``.

See ``examples/1-Cluster_creation.ipynb`` for details.

Static maps
-----------

See ``examples/2-Cluster_on_substrate.ipynb`` for details on the following functions in ``flake.maps``.

Translations
++++++++++++
``flake.maps.translational_map`` explores :math:`E(x_\mathrm{cm}, y_\mathrm{cm})` at fixed orientation.

Rotations
++++++++++++
``flake.maps.rotational_map`` explores :math:`E(\theta)` at fixed CM.

Roto-translations
+++++++++++++++++
``flake.maps.rototrasl_map`` searches for the global minimum in :math:`(x_\mathrm{cm}, y_\mathrm{cm}, \theta)` space.

Barrier finding
---------------
``flake.string_method.find_mep`` finds the minimum energy path (MEP) between two configurations using the string algorithm [6], similar to NEB methods.
The idea: place a string between two points in configuration space and let it relax. The string slides downhill until the gradient perpendicular to the string vanishes, tracing the lowest-energy route between the two minima (the mountain pass).

See ``examples/3-Barrier_from_string.ipynb`` for details.

Molecular dynamics
------------------
``flake.dynamics.run_md`` integrates the overdamped Langevin equation for the center of mass and orientation (no inertial term).
``flake.sweep.sweep_md`` parallelises trajectories over a grid of external drives.

See ``examples/4-Dynamics.ipynb`` for depinning sweeps.

Equations of motion
+++++++++++++++++++
In the overdamped limit:

.. math::
   \gamma_{t} \frac{d\mathbf{r}}{dt} = \mathbf{F}_\mathrm{ext} - \nabla U + \text{noise}

   \gamma_{r} \frac{d\theta}{dt} = \tau_\mathrm{ext} - \frac{dU}{d\theta} + \text{noise}

The drag coefficients for a cluster of :math:`N` particles are:
:math:`\gamma_t = N \gamma`
and
:math:`\gamma_r = \gamma \sum_i r_i^2`, where :math:`r_i` is the distance of the :math:`i`-th particle from the CM.

The dissipation constant :math:`\gamma` sets the time scale. Lowering :math:`\gamma` speeds up the simulation relative to the substrate potential time scale.

Units
-------
No internal units conversion is performed; the user chooses a coherent set.

Colloids
+++++++++

A coherent set for colloidal experiments [2, 3]:

  * energy: zJ = 10 :sup:`-21` J
  * length: :math:`\mu\mathrm{m}`
  * mass: fg = 10 :sup:`-15` g

From which follows:

  * force: fN
  * torque: fN :math:`\cdot \mu \mathrm{m}`
  * time: ms
  * damping: fg/ms

Nanoscale
+++++++++

A coherent set for nanoscale / AFM experiments:

  * energy: eV = 1.602176634 × 10 :sup:`-19` J
  * length: Å = 10 :sup:`-10` m

From which follows:

  * force: eV/Å ≈ 1.602176634 nN
  * time: :math:`100 \sqrt{10/1.602176634}` ns

References
----------
1. Vanossi, Manini, Tosatti. *Proc. Natl. Acad. Sci.* **109**, 16429 (2012). https://doi.org/10.1073/pnas.1213930109
2. Panizon, Silva et al. *Nanoscale* **15**, 1299 (2023). https://doi.org/10.1039/D2NR04532J
3. Cao, Silva et al. *Phys. Rev. X* **12**, 021059 (2022). https://doi.org/10.1103/PhysRevX.12.021059
4. Cao et al. *Nature Physics* **15**, 776 (2019). https://doi.org/10.1038/s41567-019-0515-7
5. Cao et al. *Phys. Rev. E* **103**, 012606 (2021). https://doi.org/10.1103/PhysRevE.103.012606
6. E, Ren, Vanden-Eijnden. *J. Chem. Phys.* **126**, 164103 (2007). https://doi.org/10.1063/1.2720838