Quickstart

Running simulations

flatspin comes with flexible tools for running simulations from the command-line.

Use flatspin-run to run one simulation, for example:

flatspin-run -o myrun -m SquareSpinIceClosed -e sin -p H=7 -p phi=45 -p periods=1

The above command runs a simulation of square spin ice (with “closed” edges), with a sinusoidal external field. The external field is set to have an amplitude of H=7 (in reduced units), applied at an angle of phi=45 degrees, with a duration of 1 period. The results are stored in the directory myrun.

Notice how all relevant parameters can be set from the command-line with -p/--param. You can list the available parameters with --list-params:

flatspin-run -m SquareSpinIceClosed -e sin --list-params

Multiple simulations can be run through a parameter sweep with flatspin-run-sweep:

flatspin-run-sweep -o mysweep -m SquareSpinIceClosed -e sin -s 'H=[5,6,7,8]' -p phi=45 -p periods=1

The above command will result in four simulations with increasing amplitude of the external field. You can sweep multiple parameters by adding several -s arguments, which will create an exhaustive sweep over all combinations of the given parameters.

If you are simulating stochastic systems, e.g., with disorder or thermal fields, you can repeat each run N times with -n N.

Viewing results

The results can be visualized with flatspin-vectors:

flatspin-vectors -b myrun --arrows -t ::1

You can also view sweeps:

flatspin-vectors -b mysweep --arrows -t ::1

Plot timeseries with flatspin-plot:

flatspin-plot -b mysweep -x t -y h_extx -k H

See ??? for more about viewing results.

Datasets

The result of a run or sweep are stored in a directory called a dataset. Each dataset contains the result of each simulation run, as well as some files with metadata about the dataset.

index.csv is a table of all the runs in the dataset. For example, mysweep/index.csv would cointain the following:

H	outdir
5	square-closed.000000.npz
6	square-closed.000001.npz
7	square-closed.000002.npz
8	square-closed.000003.npz

In addition to the location for the result of each run (the outdir column), the index has one column for each swept parameter.

params.csv contains the parameters common to all the runs, while info.csv contains some auxillary information.

The results from each run are stored in its own directory, whose name is listed in the outdir column. Each outdir contains a set of files containing tabular data. Let’s inspect square-closed.000000.npz:

$ flatspin-inspect -b mysweep -s outdir=square-closed.000000.npz
[0] H=5 outdir=square-closed.000000.npz:
    tables (12): energy[t], geometry, h_ext[t], hc, init, input[t], mag[t], params, spin[t], stats, steps[t], temp[t]

The tables marked [t] contain timeseries data from the run. Other tables contain information about the system being simulated, e.g., geometry contains the positions and rotations of all the magnets.

Note that, depending on the selected output format, outdir can either be a directory or an archive file. See output-formats for a list of supported output formats.

Filtering datasets

All analysis tools, such as flatspin-vectors, accept a common set of arguments to select subsets of the dataset:

-l: lists the contents of the dataset
-i INDEX or -i START:STOP[:STEP]: Selects a subset of the runs by the numerical index. For example -i 1 or -i 2:3.
-s KEY=VALUE or KEY=START:STOP: Selects a subset of the runs by column value or range. For example -s H=6 or -s H=7:8.

Running from Python

flatspin models can also be invoked directly from Python:

import numpy as np
from flatspin.model import SquareSpinIceClosed

model = SquareSpinIceClosed()
for h in np.linspace(4, 6, 10):
    model.set_h_ext([-h, -h])
    model.relax()
    print(model.vertex_count())

Reading datasets from Python

Datasets can be read and analyzed using the Dataset class:

from flatspin.data import Dataset, read_table

dataset = Dataset.read("mysweep")
for ds in dataset:
    energy = read_table(ds.tablefile("energy"), index_col="t")
    # energy is a pandas DataFrame
    print(energy.describe())