# CALiPPSO: A Linear Programming Algorithm for Jamming Hard Spheres

The CALiPPSO algorithm was introduced in our paper (we = *Artiaco, Díaz, Parisi, and Ricci-Tersenghi*). A Julia implementation of this algorithm is available through the CALiPPSO.jl package, developed by ourselves. This is the documentation of such Julia package.

As we explain in our paper, CALiPPSO is an iterative Linear Programming algorithm to produce jammed packings of hard-spheres (HS) *in arbitrary* dimensions, $d$. Besides, it works for both *mono*- and *poly*disperse packings, as shown below

(Left: Monodisperse packing of 16k particles; coloured according to their number of contacts. Right: Polydisperse packing of 1024 disks, with radii from a log-normal distribution, and network of contacts drawn.

Essentially, our method consists on a **C**hain of **A**pproximate **Li**near **P**rogramming for **P**acking **S**pherical **O**bjects.

The code contained in the CALiPPSO.jl package is written in pure Julia, and makes extensive use of the (wonderful) optimization and modelling package JuMP.jl, as well as other existing packages (StaticArrays.jl, GLPK.jl, etc.).

This package is licensed under the MIT license, so please feel free to use/modify/improve this code as better suits you. We only ask you to cite our work if you find it useful.

```
@article{calippso,
title = {{{CALiPPSO}}: {{A Linear Programming Algorithm}} for {{Jamming Hard Spheres}}},
shorttitle = {{{CALiPPSO}}},
author = {Artiaco, Claudia and Rojas, Rafael D{\'i}az Hern{\'a}ndez and Parisi, Giorgio and {Ricci-Tersenghi}, Federico},
year = {2022},
month = mar,
journal = {arXiv},
eprint = {2203.05654},
eprinttype = {arxiv},
primaryclass = {cond-mat, physics:physics},
url = {http://arxiv.org/abs/2203.05654},
archiveprefix = {arXiv}
}
```

If you already know how CALiPPSO works (or know the theory behind our paper), you can skip to Installation or Basic usage sections (if you have already installed the package). Otherwise, the Theory behind CALiPPSO section provides the essentials to understand our method.

## Before reading this documentation

In the next sections we describe in some detail our implementation of the CALiPPSO algorithm. But before reading how our code works we suggest that if you're new to Julia it might be useful to have its documentation at hand, specially for understanding some terminology (although we tried to keep it to a minimum). Besides, several of the functions we define rely on JuMP's functionality, so if you are unfamiliar with this package consider skimming through its documentation (specially the parts on creating a model and defining/accessing constraints).

## Contents

- Introduction: how CALiPPSO works and some terminology
- Installation
- Basic usage
- How
`produce_jammed_configuration!`

works - Changing the default options
- List of default values
- Parameters related to the precision; accessed through
`default_parameters["Precision parameters"]`

- Parameters related to convergence criteria; accessed through
`default_parameters["Convergence parameters"]`

- Parameters related to the default solver and its behaviour; accessed through
`default_parameters["Solver parameters"]`

- Other parameters defined; accessed through
`default_parameters["Other parameters"]`

- Parameters related to the precision; accessed through
- Controlling
`produce_jammed_configuration!`

with keyword arguments (a.k.a. kwargs) - Kwargs for controlling how constraints are assigned to
`LP_model`

and setting bounds on displacements - Kwargs for controlling convergence and termination criteria of the main loop
- Kwargs for controlling precision of overlaps, testing force balance, and updating lists of distances
- Kwargs for controlling output printing on terminal

- Kwargs for controlling how constraints are assigned to
- Changing the solver/optimizer

- Tests and examples provided
- Types (aka
`Struct`

s) defined in this package - Problem solving
- Library