sjtuzhanglei / dribble

Monte Carlo percolation simulations

Dribble - Monte Carlo Percolation Simulations

What is Dribble?

The main purpose of the Dribble package is simulating ionic transport properties in atomic structures using a Monte Carlo algorithm. In essence, Dribble solves the site percolation problem of percolation theory for a given set of percolation rules. These rules can be quite complex and reflect the physical interactions of the percolating species with other atomic species in the structure.

For more information about the method and for actual applications see:

A.Urban, J.Lee, and G.Ceder, Adv. Energy Mater. 4 (2014) 1400478 (https://doi.org/10.1002/aenm.201400478).
J.Lee, A.Urban, X.Li, D.Su, G.Hautier, and G.Ceder, Science 343 (2014) 519-522 (https://doi.org/10.1126/science.1246432 ).

Installation

Dribble can be installed just as any Python package. To use pip, run the following command inside the dribble diretory:

pip install -e . --user

This will install the dribble package for the present user only.

Dribble package

The two main object classes needed for most applications are Lattice and Percolator. The Lattice class holds the lattice that the simulation is run on, and the Percolator class implements the percolation Monte Carlo algorithm. For the sake of convenience, a third class, Input, is provided to parse input files in the JSON format. Provided an input file parameters.json, a minimal example of a percolation simulation is:

from dribble.io import Input
from dribble.lattice import Lattice
from dribble.percolator import Percolator

inp = Input.from_file('parameters.json')
lat = Lattice.from_input_object(inp)
percol = Percolator.from_input_object(inp, lattice)

percol.percolation_point(inp.flip_sequence)

Here an example input file:

{
    "structure": "POSCAR",
    "formula_units": 240,
    "sublattices": {
        "oct": {
            "description": "octahedral site",
            "sites": {"species": ["Li", "Mn", "Nb"]}
        },
        "oxygen": {
            "description": "oxygen sites",
            "sites": {"species": ["O"]},
            "ignore": true
        }
    },
    "bonds": [
        {
            "sublattices": ["oct", "oct"],
            "bond_rules": [
                ["MinCommonNNNeighborsBR", {"num_neighbors": 2}]
            ]
        }
    ],
    "percolating_species": ["Li"]
}

See also the examples directory which contains a number of Jupyter notebooks explaining different aspects of simulations with Dribble.

Command line tool

Along with the python package, a command line tool also named dribble is installed.

Display usage information with the --help flag:

usage: dribble [-h] [--supercell SUPERCELL SUPERCELL SUPERCELL]
               [--inaccessible SPECIES] [--pc] [--check] [--pinf] [--pwrap]
               [--samples SAMPLES] [--file-name FILE_NAME] [--save-clusters]
               [--save-raw] [--debug]
               input_file [structure_file]

Dribble - Percolation Simulation on Lattices

Analyze the ionic percolation properties of an input structure.

positional arguments:
  input_file            Input file in JSON format
  structure_file        Input file in JSON format

optional arguments:
  -h, --help            show this help message and exit
  --supercell SUPERCELL SUPERCELL SUPERCELL
                        List of multiples of the lattice cell in the three
                        lattice directions
  --inaccessible SPECIES, -i SPECIES
                        Calculate fraction of inaccessible sites for given
                        reference species
  --pc, -p              Calculate critical site concentrations
  --check               Check, if the initial structure is percolating.
  --pinf, -s            Estimate P_infinity and percolation susceptibility
  --pwrap, -w           Estimate P_wrap(p)
  --samples SAMPLES     number of samples to be averaged
  --file-name FILE_NAME
                        base file name for all output files
  --save-clusters       save wrapping clusters to file
  --save-raw            Also store raw data before convolution (where
                        available).
  --debug               run in debugging mode