Quick Start

Installation

Download the repository and call make in the root directory to compile the library:

make

To use in a program, include the minim.h header file and compile with the -lminim flag:

mpic++ -I$(MINIM)/include -L$(MINIM)/bin -lminim -DPARALLEL script.cpp -o run.exe

Refer to the examples folder for simple demonstrations of how to use the library.

A first program

A minimisation consists of a potential, a state, and a minimiser. The potential defines the energy, the state holds the coordinates, and the minimiser performs the iterations.

#include "minim.h"

using namespace minim;

int main(int argc, char **argv) {
  mpi.init(&argc, &argv);

  // Define the system
  Lj3d potential = Lj3d();
  State state(potential, {0,0,0, 2,0,0, 1,1,0, 5,1,1});
  state.convergence = 1e-4;

  // Minimise
  Lbfgs min = Lbfgs();
  auto result = min.minimise(state);

  print("Complete after", min.iter, "iterations.");
  return 0;
}

The available minimisers are L-BFGS, FIRE, gradient descent and simulated annealing.

See also the examples/ directory for other simple example scripts.

Configuring a potential

Potentials are configured via a fluent interface of setter methods. For example, a droplet on a surface using the PhaseField potential:

PhaseField pot;
pot.setGridSize({nx, ny, 1});
pot.setSolid([](int x, int y, int z){ return (y==0); });
pot.setContactAngle(60);
pot.setVolumeFixed(true);

State state(pot, initCoords());

See the potentials pages for the available potentials and their parameters.

Logging during minimisation

Pass a log format to minimise to print information during the minimisation. The format is [fields]-[iter], where fields can include:

e — the energy
g — the gradient norm
eg — both

For example, min.minimise(state, "eg-100") prints the energy and gradient norm every 100 iterations.

Parallelisation

Minim can distribute a state over multiple MPI processes and share the work of each processor over multiple OpenMP threads. See Parallelisation for how to run in parallel, including under Slurm, and how the parallelisation is implemented.