.. _quickstart:

Quickstart
==========


Running simulations
-------------------

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

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

.. code-block:: text

    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``:

.. code-block:: text

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

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

.. code-block:: text

    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``:

.. code-block:: text

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

.. image:: _static/myrun.gif

You can also view sweeps:

.. code-block:: text

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

.. image:: _static/mysweep.gif

Plot timeseries with ``flatspin-plot``:

.. code-block:: text

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

.. image:: _static/h_extx.svg

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``:

.. code-block:: text

    $ 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 :ref:`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:

.. code-block:: 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:

.. code-block:: python

    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())

More reading
------------

Ready to learn more?