SpinW documentation



Summary line.

[b1, b2] = doctest2(a,b)

Extended description of function.

  • a1 – Description of arg1.
  • a2 – Description of arg2.

  • b1 – Description of return value.
  • b2 – Other output.


This will calculate the spectrum:

doctest(obj, varargin)

performs simulated annealing on the magnetic structure

The simulated annealing is performed using the Metropolis algorithm with parallel updating non-interacting sublattices. The function can deal with arbitrary exchange interactions, anisotropies in 1,2 and 3 dimensions.

stat = ANNEAL(obj, 'paramName', value1, ...)


The calculated energies doesn’t contain the self energy (moment coupled to itself), thus the energies calculated with this function can differ from the result of the energy() function. Also the g-tensor is fixed to 2.

  • obj – Input object contains structural data, sw type.
  • spinDim

    Dimensionality of the magnetic moments:

    • 1: Ising spins
    • 2: XY spins
    • 3: Heisenberg spins (default)

    For Ising (spinDim=1) and XY (spinDim=2) models only isotropic exchange interaction and magnetic field can be used. For Ising the direction of the spins are along x-axis, for XY model the the xy-plane. Magnetic fields perpendicular to these directions are omitted.

  • initT – The initial temperature, can be any positive number, unit is Kelvin. Default is 1.
  • endT – Temperature at which to stop, can be any positive number smaller than InitTemp, unit is Kelvin. Default value is 1e-3.
  • cool

    Generates a new temperature from the previous one. Any function handle that takes a scalar as input and returns a smaller but positive scalar as output. Default value is:

    @(T) (.92*T)
  • random – Random initial conditions, if initial spin configuration is undefined (sw.mag_str.S is empty) the initial configuration is automaticly random independently of the value of random. Default is false.
  • nMC – Number of Monte-Carlo steps per spin at each temperature step to reach thermal equilibrium. Default is 100.
  • nORel – Number of over-relaxation steps after every Monte-Carlo steps. It rotates the spins around the direction of the local field by 180 \(^\circ\). It is reversible and microcanonical if the single ion anisotropy is zero. Default is 0.
  • nStat – Number of cycles at the last temperature to calculate statistical averages. It has to be smaller or equal nMC. Default value is 100.
  • boundary

    Boundary conditions of the extended unit cell.

    • ‘free’: Free, interactions between extedned unit cells are omitted.
    • ‘per’: Periodic, interactions between extended unit cells are retained.

    Default value is {'per' 'per' 'per'}.

  • verbosity

    Controls output to the screen. Possible values:

    • 0: suppresses all output
    • 1: gives final report only
    • 2: plots temperature changes and final report [default]
  • nExt – The size of the magnetic cell in number of unit cells, to provide input information to ‘fStat’. Default is from obj.mag_str.N_ext.
  • fStat

    Function handle to evaluate after at the end of the cooling scedule during the last nStat Monte-Carlo steps. The function returns a single structure and takes fixed input parameters:

    struct = fStat(state, struct, T, E, M, nExt).

    The function is called once before the annealing process when state=1 to initialise the parameters. The function is called after every Monte-Carlo steps with state=2 and the output of the previous function call is assigned to the input struct. fStat is called once again in the end with state=3 to calculate final parameters (in the last run, input struct.param contains all the annealing parameters). Default is sw_fstat().

  • fSub

    Function to define sublattices for Monte-Carlo speedup, with header:

    cGraph = fSub(conn,nExt)

    where cGraph is a (1,nMagExt) sized vector, conn is a (2,nConn) size matrix and nExt is equal to ‘nExt’. Default value is sw_fsub().

  • subLat – Vector that assigns all magnetic moments into non-interacting sublattices, contains a single index (1,2,3...) for every magnetic moment, size is (1,nMagExt). If undefined, the function defined in ‘fSub’ will be used to partition the lattice.
  • title – Gives a title string to the simulation that is saved in the output.
  • autoK – Bin length of the autocorrelation vector. Should be a few times smaller than nMC. Default is zero, no autocorrelation function is calculated.

stat – Struct that contains the calculated thermodynamical averages and the parameters of the simulation in the following fields:

fields definition
param All input parameter values of the anneal function.
obj The copy of the input sw class obj with the final magnetic structure.
M Components of the magnetisation after the last annealing run, dimensions are [3 nMagExt].
E Magnetic energy of the system after the last annealing run.
T Final temperature of the sample.

Depending on the ‘fStat’ parameter, additional fields are included. Using the default function (sw_fstat()) the following parameters are calculated:

fields definition
avgM Average components of the magnetisation over nStat runs, dimensions are [3 nMagExt].
stdM Standard deviation of the mgnetisation components over nStat runs, dimensions are [3 nMagExt].
avgE Average system energy per spin over nStat runs, scalar.
stdE Standard deviation of the system energy per spin over nStat runs, scalar.
Cp Heat capacity of the sample: \((\langle E^2\rangle-\langle E\rangle^2)/k_B/T^2\).
Chi Magnetic susceptibility of the sample: \((\langle M^2\rangle-\langle M\rangle^2)/k_B/T\).

Return type:



The following example does annealing on a triangular lattice:

model1 = sw_model('triAF',1);


S. Kirkpatrick, et al., “Optimization by Simulated Annealing”, Science, 220, 671 (1983).

Indices and tables