The model object#

In this chapter we will get familiar with the flatspin model object, which implements the theoretical model. We will cover how to create a model object, setting parameters, and different model attributes.

This guide is written as a Jupyter notebook, which can be downloaded by clicking the download link from the top of the page.

The main object in flatspin is the model (flatspin.model). Each model class defines a spin ice geometry, which specifies the positions and angles of the spins. The SquareSpinIceClosed class, for instance, creates a square spin ice geometry (with “closed” edges):

from flatspin.model import SquareSpinIceClosed

model = SquareSpinIceClosed()
model.plot();

flatspin comes with model classes for some common geometries, shown in the gallery below:

import flatspin.model

class_names = ['SquareSpinIceClosed', 'SquareSpinIceOpen',
               'KagomeSpinIce', 'KagomeSpinIceRotated',
               'PinwheelSpinIceDiamond', 'PinwheelSpinIceLuckyKnot',
              ]

n_cols = 3
n_rows = int(np.ceil(len(class_names) / n_cols))
plt.figure(figsize=(2*n_cols, 2*n_rows))
for i, name in enumerate(class_names):
    cls = getattr(flatspin.model, name)
    plt.subplot(n_rows, n_cols, i+1)
    plt.title(name)
    model = cls()
    model.plot()
    plt.axis(False)
plt.tight_layout(w_pad=8)

If you would like to add your own geometries, see Extending flatspin.

Model parameters#

Properties of the model can be changed through parameters, which are passed as keyword arguments to the model class. Note that the model only accepts keyword arguments (and no positional arguments).

For example, we may change the size parameter to create a larger spin ice:

model = SquareSpinIceClosed(size=(10,5))
print(f"10x5 square ASI has", model.spin_count, "spins")
model.plot();

10x5 square ASI has 115 spins

Note that size is geometry-specific: for SquareSpinIceClosed, the size specifies the number of columns (rows) of horizontal (vertical) magnets. For KagomeSpinIce, the size denotes the number of hexagonal units:

from flatspin.model import KagomeSpinIce
model = KagomeSpinIce(size=(10,5))
print(f"10x5 kagome ASI has", model.spin_count, "spins")
model.plot();

10x5 kagome ASI has 179 spins

Other important parameters include alpha (the coupling strength), hc (the coercive field), disorder (random variations in the coercive fields) and temperature (absolute temperature in Kelvin). For a list of available parameters, see SpinIce.

Dealing with spins#

The state of all the spins is stored in the spin array. Spin values are either 1 or -1, and are all initialized to 1 at model instantiation.

model = SquareSpinIceClosed()
model.spin

array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
       1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1], dtype=int8)

You may access elements of this array directly to read or modify the state of spins. Alternatively, use flip() to flip a single spin, set_spin() to set the state of all spins, or polarize() to reset all spins to 1 or -1.

model.spin[0] = -1
model.spin[-1] = -1
model.flip(4)
model.plot();

The spin array has a flat index, where spins are ordered sequentially. Sometimes it can be easier to work in a different coordinate system, which is where spin labels come in. The left plot below shows the index of each spin. The right plot shows the corresponding labels, for SquareSpinIceClosed, which uses a (row, col) labeling scheme.

plt.figure(figsize=(8,4))
plt.subplot(121)
plt.title("Spin indices")
model.plot()
for i in model.indices():
    plt.text(model.pos[i,0], model.pos[i,1], str(i), ha='center', va='center')

plt.subplot(122)
plt.title("Spin labels")
model.plot()
for i, l in enumerate(model.labels):
    plt.text(model.pos[i,0], model.pos[i,1], tuple(l), ha='center', va='center')

You can use the L object to look up the spin index of a label, or a label range:

L = model.L
print("(4,2):", L[4,2])
print("Row 3:", L[3])
print("Column 4:", L[:,4])
print("Rows 1-3:", L[1:4])
print("Odd rows:", L[1::2])

(4,2): 20
Row 3: [13 14 15 16 17]
Column 4: [ 8 17 26 35]
Rows 1-3: [ 4  5  6  7  8  9 10 11 12 13 14 15 16 17]
Odd rows: [ 4  5  6  7  8 13 14 15 16 17 22 23 24 25 26 31 32 33 34 35]

Geometry#

Spin ice geometry is defined by the positions and angles of all the spins, and are stored in the pos and angle attributes. Positions are in reduced units, defined by alpha (see Theory). The angles are in radians and define the rotation for the spins assuming a positive spin value of 1.

Please note that these attributes are considered read-only and cannot be changed after model initialization.

print(f"Spin 0 has position {model.pos[0]} and angle {np.rad2deg(model.angle[0])}")
print(f"Spin 4 has position {model.pos[4]} and angle {np.rad2deg(model.angle[4])}")

Spin 0 has position [0.5 0. ] and angle 0.0
Spin 4 has position [0.  0.5] and angle 90.0

As an alternative to tuning the coupling strength alpha, the distance between spins may be adjusted by the lattice_spacing parameter. This affects the positions of the spins directly, as opposed to indirectly through alpha (see Theory).

model2 = SquareSpinIceClosed(lattice_spacing=10)
# Notice change in x/y labels when we plot()
model2.plot();

Magnetization vectors#

As mentioned above, angle is independent of the current spin state. To obtain the magnetization direction, use vectors.

print(f"Spin 0 has magnetization {model.vectors[0]}")
print(f"Spin 1 has magnetization {model.vectors[1]}")
print(f"Spin 4 has magnetization {model.vectors[4]}")

Spin 0 has magnetization [-1. -0.]
Spin 1 has magnetization [1. 0.]
Spin 4 has magnetization [-6.123234e-17 -1.000000e+00]

Coercive fields and disorder#

The coercive field defines the critical field strength required to flip a spin (see also Switching). The coercive fields for all spins are stored in the threshold array of the model object. By default, the coercive fields are uniformly set to the parameter hc. We can introduce small variations in the coercive fields by setting the disorder parameter, in which case the thresholds are sampled from a normal distribution with mean hc and standard deviation disorder * hc.

Below we plot a histogram of the coercive fields with 1% and 5% disorder.

model1 = SquareSpinIceClosed(size=(25,25), hc=0.1, disorder=0.01)
model5 = SquareSpinIceClosed(size=(25,25), hc=0.1, disorder=0.05)
bins = np.linspace(0.08, 0.12, 21) - 0.001
plt.hist(model1.threshold, bins=bins, label='1% disorder', alpha=0.5)
plt.hist(model5.threshold, bins=bins, label='5% disorder', alpha=0.5)
plt.legend()
plt.xlabel("hc");

GPU acceleration#

flatspin provides GPU acceleration to speed up calculations on the GPU, but note that this must be explicitly enabled by setting the parameter use_opencl=True. It is primarily the calculations of the magnetic fields that benefit from running on the GPU.

The model object

Contents