From 8252de42e11c01abb3b3caaf102529ff9265a903 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Wed, 1 Nov 2023 03:45:05 +0000 Subject: [PATCH] build based on efd5ce6 --- dev/.documenter-siteinfo.json | 2 +- dev/library.html | 54 +++++++++++++++++------------------ 2 files changed, 28 insertions(+), 28 deletions(-) diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 44e77eb5f..22572ae8a 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-11-01T03:44:35","documenter_version":"1.1.2"}} \ No newline at end of file +{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-11-01T03:44:54","documenter_version":"1.1.2"}} \ No newline at end of file diff --git a/dev/library.html b/dev/library.html index 845bc8d3c..d7ee2d00d 100644 --- a/dev/library.html +++ b/dev/library.html @@ -1,8 +1,8 @@ -Library API · Sunny documentation
GitHub

Library API

This page describes the public types and functions exported by Sunny. This documentation can be also be accessed using the Julia help system (enter ? at the Julia command prompt).

Sunny.Site — Type
(cell1, cell2, cell3, i) :: Site

Four indices identifying a single site in a System. The first three indices select the lattice cell and the last selects the sublattice (i.e., the atom within the unit cell).

This object can be used to index dipoles and coherents fields of a System. A Site is also required to specify inhomogeneous interactions via functions such as set_external_field_at! or set_exchange_at!.

Note that the definition of a cell may change when a system is reshaped. In this case, it is convenient to construct the Site using position_to_site, which always takes a position in fractional coordinates of the original lattice vectors.

source
Sunny.Units — Constant
Units.meV
-Units.theory

The unit system is implicitly determined by the definition of two physical constants: the vacuum permeability $μ₀$ and the Bohr magneton $μ_B$. Temperatures are effectively measured in units of energy ($k_B = 1$) and time is effectively measured in units of inverse energy ($ħ = 1$). The default unit system, Units.meV, employs (meV, Å, tesla). Select alternatively Units.theory for a units system defined so that $μ₀ = μ_B = 1$.

See also meV_per_K

source
Sunny.meV_per_K — Constant
meV_per_K = 0.086173332621451774

A physical constant. Useful for converting kelvin into the default energy units, meV.

source
Sunny.BinningParameters — Type
BinningParameters(binstart,binend,binwidth;covectors = I(4))
+Library API · Sunny documentation
GitHub
Library API
This page describes the public types and functions exported by Sunny. This documentation can be also be accessed using the Julia help system (enter ? at the Julia command prompt).
Sunny.Site — Type
(cell1, cell2, cell3, i) :: Site
Four indices identifying a single site in a System. The first three indices select the lattice cell and the last selects the sublattice (i.e., the atom within the unit cell).
This object can be used to index dipoles and coherents fields of a System. A Site is also required to specify inhomogeneous interactions via functions such as set_external_field_at! or set_exchange_at!.
Note that the definition of a cell may change when a system is reshaped. In this case, it is convenient to construct the Site using position_to_site, which always takes a position in fractional coordinates of the original lattice vectors.
source
Sunny.Units — Constant
Units.meV
+Units.theory
The unit system is implicitly determined by the definition of two physical constants: the vacuum permeability $μ₀$ and the Bohr magneton $μ_B$. Temperatures are effectively measured in units of energy ($k_B = 1$) and time is effectively measured in units of inverse energy ($ħ = 1$). The default unit system, Units.meV, employs (meV, Å, tesla). Select alternatively Units.theory for a units system defined so that $μ₀ = μ_B = 1$.
See also meV_per_K
source
Sunny.meV_per_K — Constant
meV_per_K = 0.086173332621451774
A physical constant. Useful for converting kelvin into the default energy units, meV.
source
Sunny.BinningParameters — Type
BinningParameters(binstart,binend,binwidth;covectors = I(4))
 BinningParameters(binstart,binend;numbins,covectors = I(4))
Describes a 4D parallelepided histogram in a format compatible with experimental Inelasitic Neutron Scattering data. See generate_mantid_script_from_binning_parameters to convert BinningParameters to a format understandable by the Mantid software, or load_nxs to load BinningParameters from a Mantid .nxs file.
The coordinates of the histogram axes are specified by multiplication  of (q,ω) with each row of the covectors matrix, with q given in [R.L.U.]. Since the default covectors matrix is the identity matrix, the default axes are (qx,qy,qz,ω) in absolute units.
The convention for the binning scheme is that:
  • The left edge of the first bin starts at binstart
  • The bin width is binwidth
  • The last bin contains binend
  • There are no "partial bins;" the last bin may contain values greater than binend. C.f. count_bins.
A value can be binned by computing its bin index:
coords = covectors * value
-bin_ix = 1 .+ floor.(Int64,(coords .- binstart) ./ binwidth)
source
Sunny.Bond — Type
Bond(i, j, n)
Represents a bond between atom indices i and j. n is a vector of three integers specifying unit cell displacement in terms of lattice vectors.
source
Sunny.Crystal — Type
An object describing a crystallographic unit cell and its space group symmetry. Constructors are as follows:
Crystal(filename; symprec=1e-5)
Reads the crystal from a .cif file located at the path filename.  The optional parameter symprec controls the precision tolerance for spacegroup symmetries.
Crystal(latvecs, positions; types=nothing, symprec=1e-5)
Constructs a crystal from the complete list of atom positions positions, with coordinates (between 0 and 1) in units of lattice vectors latvecs. Spacegroup symmetry information is automatically inferred. The optional parameter types is a list of strings, one for each atom, and can be used to break symmetry-equivalence between atoms.
Crystal(latvecs, positions, spacegroup_number; types=nothing, setting=nothing, symprec=1e-5)
Builds a crystal by applying symmetry operators for a given international spacegroup number. For certain spacegroups, there are multiple possible unit cell settings; in this case, a warning message will be printed, and a list of crystals will be returned, one for every possible setting. Alternatively, the optional setting string will disambiguate between unit cell conventions.
Currently, crystals built using only the spacegroup number will be missing some symmetry information. It is generally preferred to build a crystal from a .cif file or from the full specification of the unit cell.
Examples
# Read a Crystal from a .cif file
+bin_ix = 1 .+ floor.(Int64,(coords .- binstart) ./ binwidth)
source
Sunny.Bond — Type
Bond(i, j, n)
Represents a bond between atom indices i and j. n is a vector of three integers specifying unit cell displacement in terms of lattice vectors.
source
Sunny.Crystal — Type
An object describing a crystallographic unit cell and its space group symmetry. Constructors are as follows:
Crystal(filename; symprec=1e-5)
Reads the crystal from a .cif file located at the path filename.  The optional parameter symprec controls the precision tolerance for spacegroup symmetries.
Crystal(latvecs, positions; types=nothing, symprec=1e-5)
Constructs a crystal from the complete list of atom positions positions, with coordinates (between 0 and 1) in units of lattice vectors latvecs. Spacegroup symmetry information is automatically inferred. The optional parameter types is a list of strings, one for each atom, and can be used to break symmetry-equivalence between atoms.
Crystal(latvecs, positions, spacegroup_number; types=nothing, setting=nothing, symprec=1e-5)
Builds a crystal by applying symmetry operators for a given international spacegroup number. For certain spacegroups, there are multiple possible unit cell settings; in this case, a warning message will be printed, and a list of crystals will be returned, one for every possible setting. Alternatively, the optional setting string will disambiguate between unit cell conventions.
Currently, crystals built using only the spacegroup number will be missing some symmetry information. It is generally preferred to build a crystal from a .cif file or from the full specification of the unit cell.
Examples
# Read a Crystal from a .cif file
 Crystal("filename.cif")
 
 # Build an FCC crystal using the primitive unit cell. The spacegroup number
@@ -25,7 +25,7 @@
 # overall unit cell translation.
 latvecs = lattice_vectors(1, 1, 1, 90, 90, 90)
 positions = [[1, 1, 1] / 4]
-cryst = Crystal(latvecs, positions, 227; setting="1")
See also lattice_vectors.
source
Sunny.FormFactor — Method
FormFactor(ion::String; g_lande=2)
The magnetic form factor for a given magnetic ion and charge state. When passed to an intensity_formula, determines a $|𝐪|$-dependent scaling of the structure factor.
The parameter ion must be one of the following strings:
Am2, Am3, Am4, Am5, Am6, Am7, Au1, Au2, Au3, Au4, Au5, Ce2, Co0, Co1, Co2, Co3,
+cryst = Crystal(latvecs, positions, 227; setting="1")
See also lattice_vectors.
source
Sunny.FormFactor — Method
FormFactor(ion::String; g_lande=2)
The magnetic form factor for a given magnetic ion and charge state. When passed to an intensity_formula, determines a $|𝐪|$-dependent scaling of the structure factor.
The parameter ion must be one of the following strings:
Am2, Am3, Am4, Am5, Am6, Am7, Au1, Au2, Au3, Au4, Au5, Ce2, Co0, Co1, Co2, Co3,
 Co4, Cr0, Cr1, Cr2, Cr3, Cr4, Cu0, Cu1, Cu2, Cu3, Cu4, Dy2, Dy3, Er2, Er3, Eu2,
 Eu3, Fe0, Fe1, Fe2, Fe3, Fe4, Gd2, Gd3, Hf2, Hf3, Ho2, Ho3, Ir0a, Ir0b, Ir0c,
 Ir1a, Ir1b, Ir2, Ir3, Ir4, Ir5, Ir6, Mn0, Mn1, Mn2, Mn3, Mn4, Mo0, Mo1, Nb0,
@@ -40,30 +40,30 @@
     "Ir0a" -- 6s⁰5d⁹
     "Ir0b" -- 6s¹5d⁸
     "Ir0c" -- 6s²5d⁷
The form factor is approximated as
$F(s) = ⟨j_0(s)⟩ + \frac{2-g}{g} ⟨j_2(s)⟩ s^2$,
involving the Landé $g$-factor. The $⟨j_l(s)⟩$ are radial integrals associated with the $l$th Bessel function of the magnetic dipole, where $s = |k|/4π$, and $|k|$ is the magnitude of momentum transfer. 
The radial integrals have been calculated using Hartree-Fock for transition metals, or Dirac-Fock for the rare earths and actinide series [1–3]. Sunny uses approximate fits as a sum of Gaussians,
\[⟨j_0(s)⟩ = A e^{-as^2} + B e^{-bs^2} + C e^{-cs^2} + D e^{-ds^2} + E \
-⟨j_l(s)⟩ = (A e^{-as^2} + B e^{-bs^2} + C e^{-cs^2} + D e^{-ds^2} + E) s^2\]
References:
  1. https://www.ill.eu/sites/ccsl/ffacts/ffachtml.html
  2. J. Brown, The Neutron Data Booklet, 2nd ed., Sec. 2.5 Magnetic Form Factors (2003)
  3. K. Kobayashi, T. Nagao, M. Ito, Acta Cryst. A, 67 pp 473–480 (2011)
source
Sunny.ImplicitMidpoint — Type
ImplicitMidpoint(Δt::Float64; atol=1e-12) where N
Energy-conserving spin dynamics. One call to the step! function will advance a System by Δt units of time.
Uses the spherical midpoint integration scheme for dipole systems and the Schrödinger midpoint integration scheme for SU(N) spin systems. Both integration schemes are symplectic, and therefore avoid energy drift over long periods of simulation time.
source
Sunny.Langevin — Type
Langevin(Δt::Float64; λ::Float64, kT::Float64)
Spin dynamics with coupling to a Langevin thermostat, which includes damping and noise terms. One call to the step! function will advance a System by Δt units of time.
Assuming ergodicity, the Langevin dynamics will sample from thermal equilibrium for the target temperature kT. The empirical parameter λ determines the strength of the coupling to the thermal bath. In other words, 1/λ is the decorrelation time-scale. If $λ = 0$, then the spin dynamics coincides with ImplicitMidpoint.
An alternative approach to sampling is LocalSampler, which may be preferred when the allowed spin values become effective discrete (e.g. Ising spins).
source
Sunny.LocalSampler — Type
LocalSampler(; kT, nsweeps=1.0, propose=propose_uniform)
Monte Carlo simulation involving Metropolis updates to individual spins. One call to the step! function will perform nsweeps of MCMC sampling for a provided System. The default value of 1.0 means that step! performs, on average, one trial update per spin.
Assuming ergodicity, the LocalSampler will sample from thermal equilibrium for the target temperature kT. 
The trial spin updates are sampled using the propose function. Built-in options include propose_uniform, propose_flip, and propose_delta. Multiple proposals can be mixed with the macro @mix_proposals.
The returned object stores fields ΔE and Δs, which represent the cumulative change to the net energy and dipole, respectively.
An alternative approach to sampling is Langevin, which may be preferred for simulating continuous spins, especially in the presence of long-range dipole-dipole interactions (cf. enable_dipole_dipole!).
source
Sunny.SpinInfo — Type
SpinInfo(atom::Int; S, g=2)
Characterizes the spin at a given atom index within the crystal unit cell. S is an integer multiple of 1/2 and gives the spin angular momentum in units of ħ. g is the g-factor or tensor, such that an angular momentum dipole $s$ produces a magnetic moment $g s$ in units of the Bohr magneton.
source
Sunny.SpinWaveTheory — Type
SpinWaveTheory(sys, energy_ϵ::Float64=1e-8)
Constructs an object to perform linear spin wave theory. Use it with dispersion and dssf functions.
The optional parameter energy_ϵ adds a small positive shift to the diagonal of the dynamical matrix $D$ to avoid numerical issues with zero-energy quasi-particle modes.
source
Sunny.System — Method
System(crystal::Crystal, latsize, infos, mode; units=Units.meV, seed::Int)
Construct a System of spins for a given Crystal symmetry. The latsize parameter determines the number of unit cells in each lattice vector direction. The infos parameter is a list of SpinInfo objects, which determine the magnitude $S$ and $g$-tensor of each spin.
The two primary options for mode are :SUN and :dipole. In the former, each spin-$S$ degree of freedom is described as an SU(N) coherent state, i.e. a quantum superposition of $N = 2S + 1$ levels. This formalism can be useful to capture multipolar spin fluctuations or local entanglement effects. 
Mode :dipole projects the SU(N) dynamics onto the restricted space of pure dipoles. In practice this means that Sunny will simulate Landau-Lifshitz dynamics, but single-ion anisotropy and biquadratic exchange interactions will be renormalized to improve accuracy. To disable this renormalization, use the mode :dipole_large_S which applies the $S → ∞$ classical limit. For details, see the documentation page: Interaction Strength Renormalization.
The default units system of (meV, Å, tesla) can be overridden by with the units parameter; see Units. 
An optional seed may be provided to achieve reproducible random number generation.
All spins are initially polarized in the $z$-direction.
source
Sunny.add_sample! — Method
add_sample!(sc::SampledCorrelations, sys::System)
add_trajectory uses the spin configuration contained in the System to generate a correlation data and accumulate it into sc. For static structure factors, this involves analyzing the spin-spin correlations of the spin configuration provided. For a dynamic structure factor, a trajectory is calculated using the given spin configuration as an initial condition. The spin-spin correlations are then calculating in time and accumulated into sc. 
This function will change the state of sys when calculating dynamical structure factor data. To preserve the initial state of sys, it must be saved separately prior to calling add_sample!. Alternatively, the initial spin configuration may be copied into a new System and this new System can be passed to add_sample!.
source
Sunny.available_energies — Method
available_energies(sc::SampledCorrelations; negative_energies=false)
Return the ω values for the energy index of a SampledCorrelations. By default, only returns values for non-negative energies, which corresponds to the default output of intensities. Set negative_energies to true to retrieve all ω values.
source
Sunny.available_wave_vectors — Method
available_wave_vectors(sc::SampledCorrelations; bzsize=(1,1,1))
Returns all wave vectors for which sc contains exact values. bsize specifies the number of Brillouin zones to be included.
source
Sunny.axes_bincenters — Method
axes_bincenters(params::BinningParameters)
Returns tick marks which label the bins of the histogram described by BinningParameters by their bin centers.
The following alternative syntax can be used to compute bin centers for a single axis:
axes_bincenters(binstart,binend,binwidth)
source
Sunny.broaden_energy — Method
broaden_energy(sc::SampledCorrelations, vals, kernel::Function; negative_energies=false)
Performs a real-space convolution along the energy axis of an array of intensities. Assumes the format of the intensities array corresponds to what would be returned by intensities_interpolated. kernel must be a function that takes two numbers: kernel(ω, ω₀), where ω is a frequency, and ω₀ is the center frequency of the kernel. Sunny provides lorentzian for the most common use case:
newvals = broaden_energy(sc, vals, (ω, ω₀) -> lorentzian(ω-ω₀, 0.2))
source
Sunny.count_bins — Method
count_bins(binstart,binend,binwidth)
Returns the number of bins in the binning scheme implied by binstart, binend, and binwidth. To count the bins in a BinningParameters, use params.numbins.
This function defines how partial bins are handled, so it should be used preferentially over computing the number of bins manually.
source
Sunny.dispersion — Method
dispersion(swt::SpinWaveTheory, qs)
Computes the spin excitation energy dispersion relations given a SpinWaveTheory and an array of wave vectors qs. Each element $q$ of qs must be a 3-vector in units of reciprocal lattice units. I.e., $qᵢ$ is given in $2π/|aᵢ|$ with $|aᵢ|$ the lattice constant of the original chemical lattice.
The first indices of the returned array correspond to those of qs. A final index, corresponding to mode, is added to these. Each entry of the array is an energy.
source
Sunny.dmvec — Method
dmvec(D)
Antisymmetric matrix representation of the Dzyaloshinskii-Moriya pseudo-vector,
  [  0    D[3] -D[2]
+⟨j_l(s)⟩ = (A e^{-as^2} + B e^{-bs^2} + C e^{-cs^2} + D e^{-ds^2} + E) s^2\]
References:
  1. https://www.ill.eu/sites/ccsl/ffacts/ffachtml.html
  2. J. Brown, The Neutron Data Booklet, 2nd ed., Sec. 2.5 Magnetic Form Factors (2003)
  3. K. Kobayashi, T. Nagao, M. Ito, Acta Cryst. A, 67 pp 473–480 (2011)
source
Sunny.ImplicitMidpoint — Type
ImplicitMidpoint(Δt::Float64; atol=1e-12) where N
Energy-conserving spin dynamics. One call to the step! function will advance a System by Δt units of time.
Uses the spherical midpoint integration scheme for dipole systems and the Schrödinger midpoint integration scheme for SU(N) spin systems. Both integration schemes are symplectic, and therefore avoid energy drift over long periods of simulation time.
source
Sunny.Langevin — Type
Langevin(Δt::Float64; λ::Float64, kT::Float64)
Spin dynamics with coupling to a Langevin thermostat, which includes damping and noise terms. One call to the step! function will advance a System by Δt units of time.
Assuming ergodicity, the Langevin dynamics will sample from thermal equilibrium for the target temperature kT. The empirical parameter λ determines the strength of the coupling to the thermal bath. In other words, 1/λ is the decorrelation time-scale. If $λ = 0$, then the spin dynamics coincides with ImplicitMidpoint.
An alternative approach to sampling is LocalSampler, which may be preferred when the allowed spin values become effective discrete (e.g. Ising spins).
source
Sunny.LocalSampler — Type
LocalSampler(; kT, nsweeps=1.0, propose=propose_uniform)
Monte Carlo simulation involving Metropolis updates to individual spins. One call to the step! function will perform nsweeps of MCMC sampling for a provided System. The default value of 1.0 means that step! performs, on average, one trial update per spin.
Assuming ergodicity, the LocalSampler will sample from thermal equilibrium for the target temperature kT. 
The trial spin updates are sampled using the propose function. Built-in options include propose_uniform, propose_flip, and propose_delta. Multiple proposals can be mixed with the macro @mix_proposals.
The returned object stores fields ΔE and Δs, which represent the cumulative change to the net energy and dipole, respectively.
An alternative approach to sampling is Langevin, which may be preferred for simulating continuous spins, especially in the presence of long-range dipole-dipole interactions (cf. enable_dipole_dipole!).
source
Sunny.SpinInfo — Type
SpinInfo(atom::Int; S, g=2)
Characterizes the spin at a given atom index within the crystal unit cell. S is an integer multiple of 1/2 and gives the spin angular momentum in units of ħ. g is the g-factor or tensor, such that an angular momentum dipole $s$ produces a magnetic moment $g s$ in units of the Bohr magneton.
source
Sunny.SpinWaveTheory — Type
SpinWaveTheory(sys, energy_ϵ::Float64=1e-8)
Constructs an object to perform linear spin wave theory. Use it with dispersion and dssf functions.
The optional parameter energy_ϵ adds a small positive shift to the diagonal of the dynamical matrix $D$ to avoid numerical issues with zero-energy quasi-particle modes.
source
Sunny.System — Method
System(crystal::Crystal, latsize, infos, mode; units=Units.meV, seed::Int)
Construct a System of spins for a given Crystal symmetry. The latsize parameter determines the number of unit cells in each lattice vector direction. The infos parameter is a list of SpinInfo objects, which determine the magnitude $S$ and $g$-tensor of each spin.
The two primary options for mode are :SUN and :dipole. In the former, each spin-$S$ degree of freedom is described as an SU(N) coherent state, i.e. a quantum superposition of $N = 2S + 1$ levels. This formalism can be useful to capture multipolar spin fluctuations or local entanglement effects. 
Mode :dipole projects the SU(N) dynamics onto the restricted space of pure dipoles. In practice this means that Sunny will simulate Landau-Lifshitz dynamics, but single-ion anisotropy and biquadratic exchange interactions will be renormalized to improve accuracy. To disable this renormalization, use the mode :dipole_large_S which applies the $S → ∞$ classical limit. For details, see the documentation page: Interaction Strength Renormalization.
The default units system of (meV, Å, tesla) can be overridden by with the units parameter; see Units. 
An optional seed may be provided to achieve reproducible random number generation.
All spins are initially polarized in the $z$-direction.
source
Sunny.add_sample! — Method
add_sample!(sc::SampledCorrelations, sys::System)
add_trajectory uses the spin configuration contained in the System to generate a correlation data and accumulate it into sc. For static structure factors, this involves analyzing the spin-spin correlations of the spin configuration provided. For a dynamic structure factor, a trajectory is calculated using the given spin configuration as an initial condition. The spin-spin correlations are then calculating in time and accumulated into sc. 
This function will change the state of sys when calculating dynamical structure factor data. To preserve the initial state of sys, it must be saved separately prior to calling add_sample!. Alternatively, the initial spin configuration may be copied into a new System and this new System can be passed to add_sample!.
source
Sunny.available_energies — Method
available_energies(sc::SampledCorrelations; negative_energies=false)
Return the ω values for the energy index of a SampledCorrelations. By default, only returns values for non-negative energies, which corresponds to the default output of intensities. Set negative_energies to true to retrieve all ω values.
source
Sunny.available_wave_vectors — Method
available_wave_vectors(sc::SampledCorrelations; bzsize=(1,1,1))
Returns all wave vectors for which sc contains exact values. bsize specifies the number of Brillouin zones to be included.
source
Sunny.axes_bincenters — Method
axes_bincenters(params::BinningParameters)
Returns tick marks which label the bins of the histogram described by BinningParameters by their bin centers.
The following alternative syntax can be used to compute bin centers for a single axis:
axes_bincenters(binstart,binend,binwidth)
source
Sunny.broaden_energy — Method
broaden_energy(sc::SampledCorrelations, vals, kernel::Function; negative_energies=false)
Performs a real-space convolution along the energy axis of an array of intensities. Assumes the format of the intensities array corresponds to what would be returned by intensities_interpolated. kernel must be a function that takes two numbers: kernel(ω, ω₀), where ω is a frequency, and ω₀ is the center frequency of the kernel. Sunny provides lorentzian for the most common use case:
newvals = broaden_energy(sc, vals, (ω, ω₀) -> lorentzian(ω-ω₀, 0.2))
source
Sunny.count_bins — Method
count_bins(binstart,binend,binwidth)
Returns the number of bins in the binning scheme implied by binstart, binend, and binwidth. To count the bins in a BinningParameters, use params.numbins.
This function defines how partial bins are handled, so it should be used preferentially over computing the number of bins manually.
source
Sunny.dispersion — Method
dispersion(swt::SpinWaveTheory, qs)
Computes the spin excitation energy dispersion relations given a SpinWaveTheory and an array of wave vectors qs. Each element $q$ of qs must be a 3-vector in units of reciprocal lattice units. I.e., $qᵢ$ is given in $2π/|aᵢ|$ with $|aᵢ|$ the lattice constant of the original chemical lattice.
The first indices of the returned array correspond to those of qs. A final index, corresponding to mode, is added to these. Each entry of the array is an energy.
source
Sunny.dmvec — Method
dmvec(D)
Antisymmetric matrix representation of the Dzyaloshinskii-Moriya pseudo-vector,
  [  0    D[3] -D[2]
    -D[3]   0    D[1]
-    D[2] -D[1]   0  ]
Useful in the context of set_exchange!.
source
Sunny.dssf — Method
dssf(swt::SpinWaveTheory, qs)
Given a SpinWaveTheory object, computes the dynamical spin structure factor,
\[    𝒮^{αβ}(𝐤, ω) = 1/(2πN)∫dt ∑_𝐫 \exp[i(ωt - 𝐤⋅𝐫)] ⟨S^α(𝐫, t)S^β(0, 0)⟩,\]
using the result from linear spin-wave theory,
\[    𝒮^{αβ}(𝐤, ω) = ∑_n |A_n^{αβ}(𝐤)|^2 δ[ω-ω_n(𝐤)].\]
qs is an array of wave vectors of arbitrary dimension. Each element $q$ of qs must be a 3-vector in reciprocal lattice units (RLU), i.e., in the basis of reciprocal lattice vectors.
The first indices of the returned array correspond to those of qs. A final index, corresponding to mode, is added to these. Each entry of this array is a tensor (3×3 matrix) corresponding to the indices $α$ and $β$.
source
Sunny.dynamical_correlations — Method
dynamical_correlations(sys::System; Δt, nω, ωmax, 
-    process_trajectory=:none, observables=nothing, correlations=nothing)
Creates an empty SampledCorrelations object for calculating and storing dynamical structure factor intensities $𝒮(𝐪,ω)$. Call add_sample! to accumulate data for the given configuration of a spin system. Internally, this will run a dynamical trajectory and measure time correlations. The $𝒮(𝐪,ω)$ data can be retrieved by calling intensities_interpolated. Alternatively, instant_intensities_interpolated will integrate out $ω$ to obtain $𝒮(𝐪)$, optionally applying classical-to-quantum correction factors.
Three keywords are required to specify the dynamics used for the trajectory calculation.
  • Δt: The time step used for calculating the trajectory from which dynamic   spin-spin correlations are calculated. The trajectories are calculated with   an ImplicitMidpoint integrator.
  • ωmax: The maximum energy, $ω$, that will be resolved.
  • nω: The number of energy bins to calculated between 0 and ωmax.
Additional keyword options are the following:
  • observables: Allows the user to specify custom observables. The   observables must be given as a list of complex N×N matrices or   LinearMaps. It's recommended to name each observable, for example:   observables = [:A => a_observable_matrix, :B => b_map, ...]. By default,   Sunny uses the 3 components of the dipole, :Sx, :Sy and :Sz.
  • correlations: Specify which correlation functions are calculated, i.e. which   matrix elements $αβ$ of $𝒮^{αβ}(q,ω)$ are calculated and stored.   Specified with a vector of tuples. By default Sunny records all auto- and   cross-correlations generated by all observables. To retain only the xx and   xy correlations, one would set correlations=[(:Sx,:Sx), (:Sx,:Sy)] or   correlations=[(1,1),(1,2)].
source
Sunny.enable_dipole_dipole! — Method
enable_dipole_dipole!(sys::System)
Enables long-range dipole-dipole interactions,
\[    -(μ_0/4π) ∑_{⟨ij⟩}  (3 (𝐌_j⋅𝐫̂_{ij})(𝐌_i⋅𝐫̂_{ij}) - 𝐌_i⋅𝐌_j) / |𝐫_{ij}|^3\]
where the sum is over all pairs of spins (singly counted), including periodic images, regularized using the Ewald summation convention. The magnetic moments are $𝐌_i = μ_B g 𝐒_i$ where $g$ is the g-factor or g-tensor, and $𝐒_i$ is the spin angular momentum dipole in units of ħ. The Bohr magneton $μ_B$ and vacuum permeability $μ_0$ are physical constants, with numerical values determined by the unit system.
source
Sunny.generate_mantid_script_from_binning_parameters — Method
generate_mantid_script_from_binning_parameters(params::BinningParameters)
Generate a Mantid script which bins data according to the  given BinningParameters.
Units
Take care to ensure the units are correct (R.L.U. or absolute). You may want to call Sunny.bin_rlu_as_absolute_units! or Sunny.bin_absolute_units_as_rlu! first.
source
Sunny.global_position — Method
global_position(sys::System, site::Site)
Position of a Site in global coordinates.
To precompute a full list of positions, one can use eachsite as below:
pos = [global_position(sys, site) for site in eachsite(sys)]
source
Sunny.instant_correlations — Method
instant_correlations(sys::System; process_trajectory=:none, observables=nothing, correlations=nothing)
Creates an empty SampledCorrelations object for calculating and storing instantaneous structure factor intensities $𝒮(𝐪)$. Call add_sample! to accumulate data for the given configuration of a spin system. Call instant_intensities_interpolated to retrieve averaged $𝒮(𝐪)$ data.
Important note: When dealing with continuous (non-Ising) spins, consider creating using dynamical_correlations instead of instant_correlations. The former will provide full $𝒮(𝐪,ω)$ data, from which $𝒮(𝐪)$ can be obtained by integrating out $ω$. During this integration step, Sunny can incorporate temperature- and $ω$-dependent classical-to-quantum correction factors to produce more accurate $𝒮(𝐪)$ estimates. See instant_intensities_interpolated for more information.
The following optional keywords are available:
  • observables: Allows the user to specify custom observables. The   observables must be given as a list of complex N×N matrices or   LinearMaps. It's recommended to name each observable, for example:   observables = [:A => a_observable_matrix, :B => b_map, ...]. By default,   Sunny uses the 3 components of the dipole, :Sx, :Sy and :Sz.
  • correlations: Specify which correlation functions are calculated, i.e. which   matrix elements $αβ$ of $𝒮^{αβ}(q,ω)$ are calculated and stored.   Specified with a vector of tuples. By default Sunny records all auto- and   cross-correlations generated by all observables. To retain only the xx and   xy correlations, one would set correlations=[(:Sx,:Sx), (:Sx,:Sy)] or   correlations=[(1,1),(1,2)].
source
Sunny.instant_intensities_interpolated — Method
instant_intensities_interpolated(sc::SampledCorrelations, qs; kwargs...)
Return $𝒮(𝐪)$ intensities at wave vectors qs. The functionality is very similar to intensities_interpolated, except the returned array has dimensions identical to qs. If called on a SampledCorrelations with dynamical information, i.e., $𝒮(𝐪,ω)$, the $ω$ information is integrated out.
source
Sunny.integrate_axes! — Method
integrate_axes!(params::BinningParameters; axes)
Integrate over one or more axes of the histogram by setting the number of bins in that axis to 1. Examples:
integrate_axes!(params; axes = [2,3])
-integrate_axes!(params; axes = 2)
source
Sunny.intensities_bands — Method
dispersion, intensities = intensities_bands(swt::SpinWaveTheory, ks, formula::SpinWaveIntensityFormula)
Computes the scattering intensities at each energy band for each momentum transfer k in ks, according to Linear Spin Wave Theory and the given intensity formula. The formula must have a delta-function kernel, e.g.:
formula = intensity_formula(swt, :perp, formula; kernel = delta_function_kernel)
or else the bands will be broadened, and their intensity can not be computed.
The outputs will be arrays with indices identical to ks, with the last index giving the band index. dispersions reports the energy of each band, while intensities reports the scattering intensity.
source
Sunny.intensities_binned — Method
intensity, counts = intensities_binned(sc::SampledCorrelations, params::BinningParameters, formula; integrated_kernel)
Given correlation data contained in a SampledCorrelations and BinningParameters describing the shape of a histogram, compute the intensity and normalization for each histogram bin using a given intensity_formula.
The BinningParameters are expected to accept (q,ω) in R.L.U. for the (possibly reshaped) crystal associated with sc.
This is an alternative to intensities_interpolated which bins the scattering intensities into a histogram instead of interpolating between them at specified qs values. See unit_resolution_binning_parameters for a reasonable default choice of BinningParameters which roughly emulates intensities_interpolated with interpolation = :round.
If a function integrated_kernel(Δω) is passed, it will be used as the CDF of a kernel function for energy broadening. For example, integrated_kernel = Δω -> atan(Δω/η)/pi (c.f. integrated_lorentzian implements Lorentzian broadening with parameter η. Energy-dependent energy broadening can be achieved by providing an integrated_kernel(ω,Δω) whose first argument is the energy transfer ω.
Currently, energy broadening is only supported if the BinningParameters are such that the first three axes are purely spatial and the last (energy) axis is [0,0,0,1].
source
Sunny.intensities_broadened — Method
intensities_broadened(swt::SpinWaveTheory, ks, ωvals, formula)
Computes the scattering intensities at each (Q,ω) according to Linear Spin Wave Theory and the given intensity formula. The required formula must have a non-delta-function kernel, e.g.:
formula = intensity_formula(swt, :perp; kernel = lorentzian(0.05))
or else the intensity at ωvals which are not exactly on the dispersion curve can not be calculated.
The intensity is computed at each wave vector in ks and each energy in ωvals. The output will be an array with indices identical to ks, with the last index matching ωvals.
Note that ks is an array of wave vectors of arbitrary dimension. Each element $k$ of ks must be a 3-wavevector in absolute units.
source
Sunny.intensities_interpolated — Method
intensities_interpolated(sc::SampledCorrelations, qs, formula:ClassicalIntensityFormula; interpolation=nothing, negative_energies=false)
The basic function for retrieving $𝒮(𝐪,ω)$ information from a SampledCorrelations. Maps an array of wave vectors qs to an array of structure factor intensities, including an additional energy index. The values of $ω$ associated with the energy index can be retrieved by calling available_energies. The three coordinates of each wave vector are measured in reciprocal lattice units, i.e., multiples of the reciprocal lattice vectors.
  • interpolation: Since $𝒮(𝐪, ω)$ is calculated on a finite lattice, data   is only available at discrete wave vectors. By default, Sunny will round a   requested q to the nearest available wave vector. Linear interpolation can   be applied by setting interpolation=:linear.
  • negative_energies: If set to true, Sunny will return the periodic   extension of the energy axis. Most users will not want this.
source
Sunny.intensity_formula — Method
formula = intensity_formula(sc::SampledCorrelations)
Establish a formula for computing the intensity of the discrete scattering modes (q,ω) using the correlation data $𝒮^{αβ}(q,ω)$ stored in the SampledCorrelations. The formula returned from intensity_formula can be passed to intensities_interpolated or intensities_binned.
intensity_formula(sc,...; kT = Inf, formfactors = ...)
There are keyword arguments providing temperature and form factor corrections:
  • kT: If a temperature is provided, the intensities will be rescaled by a   temperature- and ω-dependent classical-to-quantum factor. kT should be   specified when making comparisons with spin wave calculations or   experimental data. If kT is not specified, infinite temperature (no   correction) is assumed.
  • formfactors: To apply form factor corrections, provide this keyword with a   list of FormFactors, one for each symmetry-distinct site in the crystal.   The order of FormFactors must correspond to the order of site symmetry   classes, e.g., as they appear when printed in display(crystal).
source
Sunny.intensity_formula — Method
A custom intensity formula can be specifed by providing a function intensity = f(q,ω,correlations) and specifying which correlations it requires:
intensity_formula(f,sc::SampledCorrelations, required_correlations; kwargs...)
The function is intended to be specified using do notation. For example, this custom formula sums the off-diagonal correlations:
required = [(:Sx,:Sy),(:Sy,:Sz),(:Sx,:Sz)]
+    D[2] -D[1]   0  ]
Useful in the context of set_exchange!.
source
Sunny.dssf — Method
dssf(swt::SpinWaveTheory, qs)
Given a SpinWaveTheory object, computes the dynamical spin structure factor,
\[    𝒮^{αβ}(𝐤, ω) = 1/(2πN)∫dt ∑_𝐫 \exp[i(ωt - 𝐤⋅𝐫)] ⟨S^α(𝐫, t)S^β(0, 0)⟩,\]
using the result from linear spin-wave theory,
\[    𝒮^{αβ}(𝐤, ω) = ∑_n |A_n^{αβ}(𝐤)|^2 δ[ω-ω_n(𝐤)].\]
qs is an array of wave vectors of arbitrary dimension. Each element $q$ of qs must be a 3-vector in reciprocal lattice units (RLU), i.e., in the basis of reciprocal lattice vectors.
The first indices of the returned array correspond to those of qs. A final index, corresponding to mode, is added to these. Each entry of this array is a tensor (3×3 matrix) corresponding to the indices $α$ and $β$.
source
Sunny.dynamical_correlations — Method
dynamical_correlations(sys::System; Δt, nω, ωmax, 
+    process_trajectory=:none, observables=nothing, correlations=nothing)
Creates an empty SampledCorrelations object for calculating and storing dynamical structure factor intensities $𝒮(𝐪,ω)$. Call add_sample! to accumulate data for the given configuration of a spin system. Internally, this will run a dynamical trajectory and measure time correlations. The $𝒮(𝐪,ω)$ data can be retrieved by calling intensities_interpolated. Alternatively, instant_intensities_interpolated will integrate out $ω$ to obtain $𝒮(𝐪)$, optionally applying classical-to-quantum correction factors.
Three keywords are required to specify the dynamics used for the trajectory calculation.
  • Δt: The time step used for calculating the trajectory from which dynamic   spin-spin correlations are calculated. The trajectories are calculated with   an ImplicitMidpoint integrator.
  • ωmax: The maximum energy, $ω$, that will be resolved.
  • nω: The number of energy bins to calculated between 0 and ωmax.
Additional keyword options are the following:
  • observables: Allows the user to specify custom observables. The   observables must be given as a list of complex N×N matrices or   LinearMaps. It's recommended to name each observable, for example:   observables = [:A => a_observable_matrix, :B => b_map, ...]. By default,   Sunny uses the 3 components of the dipole, :Sx, :Sy and :Sz.
  • correlations: Specify which correlation functions are calculated, i.e. which   matrix elements $αβ$ of $𝒮^{αβ}(q,ω)$ are calculated and stored.   Specified with a vector of tuples. By default Sunny records all auto- and   cross-correlations generated by all observables. To retain only the xx and   xy correlations, one would set correlations=[(:Sx,:Sx), (:Sx,:Sy)] or   correlations=[(1,1),(1,2)].
source
Sunny.enable_dipole_dipole! — Method
enable_dipole_dipole!(sys::System)
Enables long-range dipole-dipole interactions,
\[    -(μ_0/4π) ∑_{⟨ij⟩}  (3 (𝐌_j⋅𝐫̂_{ij})(𝐌_i⋅𝐫̂_{ij}) - 𝐌_i⋅𝐌_j) / |𝐫_{ij}|^3\]
where the sum is over all pairs of spins (singly counted), including periodic images, regularized using the Ewald summation convention. The magnetic moments are $𝐌_i = μ_B g 𝐒_i$ where $g$ is the g-factor or g-tensor, and $𝐒_i$ is the spin angular momentum dipole in units of ħ. The Bohr magneton $μ_B$ and vacuum permeability $μ_0$ are physical constants, with numerical values determined by the unit system.
source
Sunny.generate_mantid_script_from_binning_parameters — Method
generate_mantid_script_from_binning_parameters(params::BinningParameters)
Generate a Mantid script which bins data according to the  given BinningParameters.
Units
Take care to ensure the units are correct (R.L.U. or absolute). You may want to call Sunny.bin_rlu_as_absolute_units! or Sunny.bin_absolute_units_as_rlu! first.
source
Sunny.global_position — Method
global_position(sys::System, site::Site)
Position of a Site in global coordinates.
To precompute a full list of positions, one can use eachsite as below:
pos = [global_position(sys, site) for site in eachsite(sys)]
source
Sunny.instant_correlations — Method
instant_correlations(sys::System; process_trajectory=:none, observables=nothing, correlations=nothing)
Creates an empty SampledCorrelations object for calculating and storing instantaneous structure factor intensities $𝒮(𝐪)$. Call add_sample! to accumulate data for the given configuration of a spin system. Call instant_intensities_interpolated to retrieve averaged $𝒮(𝐪)$ data.
Important note: When dealing with continuous (non-Ising) spins, consider creating using dynamical_correlations instead of instant_correlations. The former will provide full $𝒮(𝐪,ω)$ data, from which $𝒮(𝐪)$ can be obtained by integrating out $ω$. During this integration step, Sunny can incorporate temperature- and $ω$-dependent classical-to-quantum correction factors to produce more accurate $𝒮(𝐪)$ estimates. See instant_intensities_interpolated for more information.
The following optional keywords are available:
  • observables: Allows the user to specify custom observables. The   observables must be given as a list of complex N×N matrices or   LinearMaps. It's recommended to name each observable, for example:   observables = [:A => a_observable_matrix, :B => b_map, ...]. By default,   Sunny uses the 3 components of the dipole, :Sx, :Sy and :Sz.
  • correlations: Specify which correlation functions are calculated, i.e. which   matrix elements $αβ$ of $𝒮^{αβ}(q,ω)$ are calculated and stored.   Specified with a vector of tuples. By default Sunny records all auto- and   cross-correlations generated by all observables. To retain only the xx and   xy correlations, one would set correlations=[(:Sx,:Sx), (:Sx,:Sy)] or   correlations=[(1,1),(1,2)].
source
Sunny.instant_intensities_interpolated — Method
instant_intensities_interpolated(sc::SampledCorrelations, qs; kwargs...)
Return $𝒮(𝐪)$ intensities at wave vectors qs. The functionality is very similar to intensities_interpolated, except the returned array has dimensions identical to qs. If called on a SampledCorrelations with dynamical information, i.e., $𝒮(𝐪,ω)$, the $ω$ information is integrated out.
source
Sunny.integrate_axes! — Method
integrate_axes!(params::BinningParameters; axes)
Integrate over one or more axes of the histogram by setting the number of bins in that axis to 1. Examples:
integrate_axes!(params; axes = [2,3])
+integrate_axes!(params; axes = 2)
source
Sunny.intensities_bands — Method
dispersion, intensities = intensities_bands(swt::SpinWaveTheory, ks, formula::SpinWaveIntensityFormula)
Computes the scattering intensities at each energy band for each momentum transfer k in ks, according to Linear Spin Wave Theory and the given intensity formula. The formula must have a delta-function kernel, e.g.:
formula = intensity_formula(swt, :perp, formula; kernel = delta_function_kernel)
or else the bands will be broadened, and their intensity can not be computed.
The outputs will be arrays with indices identical to ks, with the last index giving the band index. dispersions reports the energy of each band, while intensities reports the scattering intensity.
source
Sunny.intensities_binned — Method
intensity, counts = intensities_binned(sc::SampledCorrelations, params::BinningParameters, formula; integrated_kernel)
Given correlation data contained in a SampledCorrelations and BinningParameters describing the shape of a histogram, compute the intensity and normalization for each histogram bin using a given intensity_formula.
The BinningParameters are expected to accept (q,ω) in R.L.U. for the (possibly reshaped) crystal associated with sc.
This is an alternative to intensities_interpolated which bins the scattering intensities into a histogram instead of interpolating between them at specified qs values. See unit_resolution_binning_parameters for a reasonable default choice of BinningParameters which roughly emulates intensities_interpolated with interpolation = :round.
If a function integrated_kernel(Δω) is passed, it will be used as the CDF of a kernel function for energy broadening. For example, integrated_kernel = Δω -> atan(Δω/η)/pi (c.f. integrated_lorentzian implements Lorentzian broadening with parameter η. Energy-dependent energy broadening can be achieved by providing an integrated_kernel(ω,Δω) whose first argument is the energy transfer ω.
Currently, energy broadening is only supported if the BinningParameters are such that the first three axes are purely spatial and the last (energy) axis is [0,0,0,1].
source
Sunny.intensities_broadened — Method
intensities_broadened(swt::SpinWaveTheory, ks, ωvals, formula)
Computes the scattering intensities at each (Q,ω) according to Linear Spin Wave Theory and the given intensity formula. The required formula must have a non-delta-function kernel, e.g.:
formula = intensity_formula(swt, :perp; kernel = lorentzian(0.05))
or else the intensity at ωvals which are not exactly on the dispersion curve can not be calculated.
The intensity is computed at each wave vector in ks and each energy in ωvals. The output will be an array with indices identical to ks, with the last index matching ωvals.
Note that ks is an array of wave vectors of arbitrary dimension. Each element $k$ of ks must be a 3-wavevector in absolute units.
source
Sunny.intensities_interpolated — Method
intensities_interpolated(sc::SampledCorrelations, qs, formula:ClassicalIntensityFormula; interpolation=nothing, negative_energies=false)
The basic function for retrieving $𝒮(𝐪,ω)$ information from a SampledCorrelations. Maps an array of wave vectors qs to an array of structure factor intensities, including an additional energy index. The values of $ω$ associated with the energy index can be retrieved by calling available_energies. The three coordinates of each wave vector are measured in reciprocal lattice units, i.e., multiples of the reciprocal lattice vectors.
  • interpolation: Since $𝒮(𝐪, ω)$ is calculated on a finite lattice, data   is only available at discrete wave vectors. By default, Sunny will round a   requested q to the nearest available wave vector. Linear interpolation can   be applied by setting interpolation=:linear.
  • negative_energies: If set to true, Sunny will return the periodic   extension of the energy axis. Most users will not want this.
source
Sunny.intensity_formula — Method
formula = intensity_formula(sc::SampledCorrelations)
Establish a formula for computing the intensity of the discrete scattering modes (q,ω) using the correlation data $𝒮^{αβ}(q,ω)$ stored in the SampledCorrelations. The formula returned from intensity_formula can be passed to intensities_interpolated or intensities_binned.
intensity_formula(sc,...; kT = Inf, formfactors = ...)
There are keyword arguments providing temperature and form factor corrections:
  • kT: If a temperature is provided, the intensities will be rescaled by a   temperature- and ω-dependent classical-to-quantum factor. kT should be   specified when making comparisons with spin wave calculations or   experimental data. If kT is not specified, infinite temperature (no   correction) is assumed.
  • formfactors: To apply form factor corrections, provide this keyword with a   list of FormFactors, one for each symmetry-distinct site in the crystal.   The order of FormFactors must correspond to the order of site symmetry   classes, e.g., as they appear when printed in display(crystal).
source
Sunny.intensity_formula — Method
A custom intensity formula can be specifed by providing a function intensity = f(q,ω,correlations) and specifying which correlations it requires:
intensity_formula(f,sc::SampledCorrelations, required_correlations; kwargs...)
The function is intended to be specified using do notation. For example, this custom formula sums the off-diagonal correlations:
required = [(:Sx,:Sy),(:Sy,:Sz),(:Sx,:Sz)]
 intensity_formula(sc,required,return_type = ComplexF64) do k, ω, off_diagonal_correlations
     sum(off_diagonal_correlations)
-end
If your custom formula returns a type other than Float64, use the return_type keyword argument to flag this.
source
Sunny.intensity_formula — Method
formula = intensity_formula(swt::SpinWaveTheory; kernel = ...)
Establish a formula for computing the scattering intensity by diagonalizing the hamiltonian $H(q)$ using Linear Spin Wave Theory.
If kernel = delta_function_kernel, then the resulting formula can be used with intensities_bands.
If kernel is an energy broadening kernel function, then the resulting formula can be used with intensities_broadened. Energy broadening kernel functions can either be a function of Δω only, e.g.:
kernel = Δω -> ...
or a function of both the energy transfer ω and of Δω, e.g.:
kernel = (ω,Δω) -> ...
The integral of a properly normalized kernel function over all Δω is one.
source
Sunny.intensity_formula — Method
intensity_formula([swt or sc], contraction_mode::Symbol)
Sunny has several built-in formulas that can be selected by setting contraction_mode to one of these values:
  • :trace (default), which yields $\operatorname{tr} 𝒮(q,ω) = ∑_α 𝒮^{αα}(q,ω)$
  • :perp, which contracts $𝒮^{αβ}(q,ω)$ with the dipole factor $δ_{αβ} - q_{α}q_{β}$, returning the unpolarized intensity.
  • :full, which will return all elements $𝒮^{αβ}(𝐪,ω)$ without contraction.
source
Sunny.lattice_params — Method
lattice_params(latvecs::Mat3)
Compute the lattice parameters $(a, b, c, α, β, γ)$ for the three lattice vectors provided as columns of latvecs. The inverse mapping is lattice_vectors.
source
Sunny.lattice_vectors — Method
lattice_vectors(a, b, c, α, β, γ)
Return the lattice vectors, as columns of the $3×3$ output matrix, that correspond to the conventional unit cell defined by the lattice constants $(a, b, c)$ and the angles $(α, β, γ)$ in degrees. The inverse mapping is lattice_params.
source
Sunny.magnetic_moment — Method
magnetic_moment(sys::System, site::Site)
Get the magnetic moment for a Site. This is the spin dipole multiplied by the Bohr magneton and the local g-tensor.
source
Sunny.merge_correlations — Method
merge_correlations(scs::Vector{SampledCorrelations)
Accumulate a list of SampledCorrelations into a single, summary SampledCorrelations. Useful for reducing the results of parallel computations.
source
Sunny.minimize_energy! — Method
minimize_energy!(sys::System{N}; maxiters=100, subiters=20,
-                 method=Optim.ConjugateGradient(), kwargs...) where N
Optimizes the spin configuration in sys to minimize energy. A total of maxiters iterations will be attempted, with restarts after every subiters iterations. The remaining kwargs will be forwarded to the optimize method of the Optim.jl package.
source
Sunny.position_to_site — Method
position_to_site(sys::System, r)
Converts a position r to four indices of a Site. The coordinates of r are given in units of the lattice vectors for the original crystal. This function can be useful for working with systems that have been reshaped using reshape_supercell.
Example
# Find the `site` at the center of a unit cell which is displaced by four
+end
If your custom formula returns a type other than Float64, use the return_type keyword argument to flag this.
source
Sunny.intensity_formula — Method
formula = intensity_formula(swt::SpinWaveTheory; kernel = ...)
Establish a formula for computing the scattering intensity by diagonalizing the hamiltonian $H(q)$ using Linear Spin Wave Theory.
If kernel = delta_function_kernel, then the resulting formula can be used with intensities_bands.
If kernel is an energy broadening kernel function, then the resulting formula can be used with intensities_broadened. Energy broadening kernel functions can either be a function of Δω only, e.g.:
kernel = Δω -> ...
or a function of both the energy transfer ω and of Δω, e.g.:
kernel = (ω,Δω) -> ...
The integral of a properly normalized kernel function over all Δω is one.
source
Sunny.intensity_formula — Method
intensity_formula([swt or sc], contraction_mode::Symbol)
Sunny has several built-in formulas that can be selected by setting contraction_mode to one of these values:
  • :trace (default), which yields $\operatorname{tr} 𝒮(q,ω) = ∑_α 𝒮^{αα}(q,ω)$
  • :perp, which contracts $𝒮^{αβ}(q,ω)$ with the dipole factor $δ_{αβ} - q_{α}q_{β}$, returning the unpolarized intensity.
  • :full, which will return all elements $𝒮^{αβ}(𝐪,ω)$ without contraction.
source
Sunny.lattice_params — Method
lattice_params(latvecs::Mat3)
Compute the lattice parameters $(a, b, c, α, β, γ)$ for the three lattice vectors provided as columns of latvecs. The inverse mapping is lattice_vectors.
source
Sunny.lattice_vectors — Method
lattice_vectors(a, b, c, α, β, γ)
Return the lattice vectors, as columns of the $3×3$ output matrix, that correspond to the conventional unit cell defined by the lattice constants $(a, b, c)$ and the angles $(α, β, γ)$ in degrees. The inverse mapping is lattice_params.
source
Sunny.magnetic_moment — Method
magnetic_moment(sys::System, site::Site)
Get the magnetic moment for a Site. This is the spin dipole multiplied by the Bohr magneton and the local g-tensor.
source
Sunny.merge_correlations — Method
merge_correlations(scs::Vector{SampledCorrelations)
Accumulate a list of SampledCorrelations into a single, summary SampledCorrelations. Useful for reducing the results of parallel computations.
source
Sunny.minimize_energy! — Method
minimize_energy!(sys::System{N}; maxiters=100, subiters=20,
+                 method=Optim.ConjugateGradient(), kwargs...) where N
Optimizes the spin configuration in sys to minimize energy. A total of maxiters iterations will be attempted, with restarts after every subiters iterations. The remaining kwargs will be forwarded to the optimize method of the Optim.jl package.
source
Sunny.position_to_site — Method
position_to_site(sys::System, r)
Converts a position r to four indices of a Site. The coordinates of r are given in units of the lattice vectors for the original crystal. This function can be useful for working with systems that have been reshaped using reshape_supercell.
Example
# Find the `site` at the center of a unit cell which is displaced by four
 # multiples of the first lattice vector
 site = position_to_site(sys, [4.5, 0.5, 0.5])
 
 # Print the dipole at this site
-println(sys.dipoles[site])
source
Sunny.powder_average_binned — Method
powder_average_binned(sc::SampledCorrelations, radial_binning_parameters; formula
-                     ω_binning_parameters, integrated_kernel = nothing, bzsize = nothing)
This function emulates the experimental situation of "powder averaging," where only the magnitude (and not the direction) of the momentum transfer is resolvable. The intensities are binned similarly to intensities_binned, but the histogram x-axis is |k| in absolute units, which is a nonlinear function of kx,ky,kz. The y-axis is energy.
Radial binning parameters are specified as tuples (start,end,bin_width), e.g. radial_binning_parameters = (0,6π,6π/55).
Energy broadening is supported in the same way as intensities_binned, and this function accepts the same kind of intensity_formula.
source
Sunny.primitive_cell_shape — Method
primitive_cell_shape(cryst::Crystal)
Returns the shape of the primitive cell as a 3×3 matrix, in fractional coordinates of the conventional lattice vectors. May be useful for constructing inputs to reshape_supercell.
Examples
# Valid if `cryst` has not been reshaped
-@assert cryst.prim_latvecs ≈ cryst.latvecs * primitive_cell_shape(cryst)
source
Sunny.print_bond — Method
print_bond(cryst::Crystal, bond::Bond; b_ref::Bond)
Prints symmetry information for bond bond. A symmetry-equivalent reference bond b_ref can optionally be provided to fix the meaning of the coefficients A, B, ...
source
Sunny.print_site — Method
print_site(cryst, i; R=I)
Print symmetry information for the site i, including allowed g-tensor and allowed anisotropy operator. An optional rotation matrix R can be provided to define the reference frame for expression of the anisotropy.
source
Sunny.print_stevens_expansion — Method
function print_stevens_expansion(op)
Prints a local Hermitian operator as a linear combination of Stevens operators. The operator op may be a finite-dimensional matrix or an abstract spin polynomial in the large-$S$ limit.
Examples
S = spin_matrices(2)
+println(sys.dipoles[site])
source
Sunny.powder_average_binned — Method
powder_average_binned(sc::SampledCorrelations, radial_binning_parameters; formula
+                     ω_binning_parameters, integrated_kernel = nothing, bzsize = nothing)
This function emulates the experimental situation of "powder averaging," where only the magnitude (and not the direction) of the momentum transfer is resolvable. The intensities are binned similarly to intensities_binned, but the histogram x-axis is |k| in absolute units, which is a nonlinear function of kx,ky,kz. The y-axis is energy.
Radial binning parameters are specified as tuples (start,end,bin_width), e.g. radial_binning_parameters = (0,6π,6π/55).
Energy broadening is supported in the same way as intensities_binned, and this function accepts the same kind of intensity_formula.
source
Sunny.primitive_cell_shape — Method
primitive_cell_shape(cryst::Crystal)
Returns the shape of the primitive cell as a 3×3 matrix, in fractional coordinates of the conventional lattice vectors. May be useful for constructing inputs to reshape_supercell.
Examples
# Valid if `cryst` has not been reshaped
+@assert cryst.prim_latvecs ≈ cryst.latvecs * primitive_cell_shape(cryst)
source
Sunny.print_bond — Method
print_bond(cryst::Crystal, bond::Bond; b_ref::Bond)
Prints symmetry information for bond bond. A symmetry-equivalent reference bond b_ref can optionally be provided to fix the meaning of the coefficients A, B, ...
source
Sunny.print_site — Method
print_site(cryst, i; R=I)
Print symmetry information for the site i, including allowed g-tensor and allowed anisotropy operator. An optional rotation matrix R can be provided to define the reference frame for expression of the anisotropy.
source
Sunny.print_stevens_expansion — Method
function print_stevens_expansion(op)
Prints a local Hermitian operator as a linear combination of Stevens operators. The operator op may be a finite-dimensional matrix or an abstract spin polynomial in the large-$S$ limit.
Examples
S = spin_matrices(2)
 print_stevens_expansion(S[1]^4 + S[2]^4 + S[3]^4)
 # Prints: (1/20)𝒪₄₀ + (1/4)𝒪₄₄ + 102/5
 
 S = spin_matrices(Inf)
 print_stevens_expansion(S[1]^4 + S[2]^4 + S[3]^4)
-# Prints: (1/20)𝒪₄₀ + (1/4)𝒪₄₄ + (3/5)𝒮⁴
source
Sunny.print_suggested_frame — Method
print_suggested_frame(cryst, i; digits=4)
Print a suggested reference frame, as a rotation matrix R, that can be used as input to print_site(). The purpose is to simplify the description of allowed anisotropies.
source
Sunny.print_symmetry_table — Method
print_symmetry_table(cryst::Crystal, max_dist)
Print symmetry information for all equivalence classes of sites and bonds, up to a maximum bond distance of max_dist. Equivalent to calling print_bond(cryst, b) for every bond b in reference_bonds(cryst, max_dist), where Bond(i, i, [0,0,0]) refers to a single site i.
source
Sunny.print_wrapped_intensities — Method
print_wrapped_intensities(sys::System; nmax=10)
For Bravais lattices: Prints up to nmax wavevectors according to their instantaneous (static) structure factor intensities, listed in descending order. For non-Bravais lattices: Performs the same analysis for each spin sublattice independently; the output weights are naïvely averaged over sublattices, without incorporating phase shift information. This procedure therefore wraps all wavevectors into the first Brillouin zone. Each wavevector coordinate is given between $-1/2$ and $1/2$ in reciprocal lattice units (RLU).  The output from this function will typically be used as input to suggest_magnetic_supercell.
Because this function does not incorporate phase information in its averaging over sublattices, the printed weights are not directly comparable with experiment. For that purpose, use instant_correlations instead.
source
Sunny.propose_delta — Method
propose_delta(magnitude)
Generate a proposal function that adds a Gaussian perturbation to the existing spin state. In :dipole mode, the procedure is to first introduce a random three-vector perturbation $𝐬′ = 𝐬 + |𝐬| ξ$ and then return the properly normalized spin $|𝐬| (𝐬′/|𝐬′|)$. Each component of the random vector $ξ$ is Gaussian distributed with a standard deviation of magnitude; the latter is dimensionless and typically smaller than one. 
In :SUN mode, the procedure is analogous, but now involving Gaussian perturbations to each of the $N$ complex components of an SU(N) coherent state.
In the limit of very large magnitude, this function coincides with propose_uniform.
For use with LocalSampler.
source
Sunny.propose_flip — Method
propose_flip
Function to propose pure spin flip updates in the context of a LocalSampler. Dipoles are flipped as $𝐬 → -𝐬$. SU(N) coherent states are flipped using the time-reversal operator.
source
Sunny.propose_uniform — Function
propose_uniform
Function to propose a uniformly random spin update in the context of a LocalSampler. In :dipole mode, the result is a random three-vector with appropriate normalization. In :SUN mode, the result is a random SU(N) coherent state with appropriate normalization.
source
Sunny.reciprocal_space_path — Method
reciprocal_space_path(cryst::Crystal, qs, density)
Returns a pair (path, xticks). The path return value is a list of wavevectors that samples linearly between the provided wavevectors qs. The xticks return value can be used to label the special $𝐪$ values on the x-axis of a plot.
Special note about units: the wavevectors qs must be provided in reciprocal lattice units (RLU) for the given crystal, but the sampling density must be specified in the global frame. Specifically, the density is given as number of sample points per unit of radian inverse length, where the unit of length is the same as that used to specify the lattice vectors of the Crystal. The path will therefore include more samples between q-points that are further apart in absolute Fourier distance.
source
Sunny.reciprocal_space_path_bins — Method
reciprocal_space_path_bins(sc,qs,density,args...;kwargs...)
Takes a list of wave vectors, qs in R.L.U., and builds a series of histogram BinningParameters whose first axis traces a path through the provided points. The second and third axes are integrated over according to the args and kwargs, which are passed through to slice_2D_binning_parameters.
Also returned is a list of marker indices corresponding to the input points, and a list of ranges giving the indices of each histogram x-axis within a concatenated histogram. The density parameter is given in samples per reciprocal lattice unit (R.L.U.).
source
Sunny.reciprocal_space_shell — Method
reciprocal_space_shell(cryst::Crystal, radius, n)
Sample n points on the reciprocal space sphere with a given radius (units of inverse length).
Examples
# Sample wavevectors on the sphere at fixed density
-reciprocal_space_shell(cryst, r, 4π*r^2*density)
source
Sunny.reference_bonds — Method
reference_bonds(cryst::Crystal, max_dist)
Returns a full list of bonds, one for each symmetry equivalence class, up to distance max_dist. The reference bond b for each equivalence class is selected according to a scoring system that prioritizes simplification of the elements in basis_for_symmetry_allowed_couplings(cryst, b).
source
Sunny.remove_periodicity! — Method
remove_periodicity!(sys::System, dims)
Remove periodic interactions along the dimensions where dims is true. The system must support inhomogeneous interactions via to_inhomogeneous.
Example
# Remove periodic boundaries along the 1st and 3rd dimensions
-remove_periodicity!(sys::System, (true, false, true))
source
Sunny.reshape_supercell — Method
reshape_supercell(sys::System, shape)
Maps an existing System to a new one that has the shape and periodicity of a requested supercell. The columns of the $3×3$ integer matrix shape represent the supercell lattice vectors measured in units of the original crystal lattice vectors.
source
Sunny.resize_supercell — Method
resize_supercell(sys::System{N}, latsize::NTuple{3,Int}) where N
Creates a System with a given number of conventional unit cells in each lattice vector direction. Interactions and other settings will be inherited from sys.
Convenience function for:
reshape_supercell(sys, [latsize[1] 0 0; 0 latsize[2] 0; 0 0 latsize[3]])
See also reshape_supercell.
source
Sunny.rotate_operator — Method
rotate_operator(A, R)
Rotates the local quantum operator A according to the $3×3$ rotation matrix R.
source
Sunny.rotation_in_rlu — Method
rotation_in_rlu(cryst::Crystal, axis, angle)
Returns a $3×3$ matrix that rotates wavevectors in reciprocal lattice units (RLU). The axis vector is a real-space direction in absolute units (but arbitrary magnitude), and the angle is in radians.
source
Sunny.set_coherent! — Method
set_coherent!(sys::System, Z, site::Site)
Set a coherent spin state at a Site using the $N$ complex amplitudes in Z.
For a standard SpinInfo, these amplitudes will be interpreted in the eigenbasis of $𝒮̂ᶻ$. That is, Z[1] represents the amplitude for the basis state fully polarized along the $ẑ$-direction, and subsequent components represent states with decreasing angular momentum along this axis ($m = S, S-1, …, -S$).
source
Sunny.set_exchange! — Method
set_exchange!(sys::System, J, bond::Bond)
Sets a 3×3 spin-exchange matrix J along bond, yielding a pairwise interaction energy $𝐒_i⋅J 𝐒_j$. This interaction will be propagated to equivalent bonds in consistency with crystal symmetry. Any previous interactions on these bonds will be overwritten. The parameter bond has the form Bond(i, j, offset), where i and j are atom indices within the unit cell, and offset is a displacement in unit cells.
The parameter J may be scalar or matrix-valued. As a convenience, dmvec(D) can be used to construct the antisymmetric part of the exchange, where D is the Dzyaloshinskii-Moriya pseudo-vector. The resulting interaction will be $𝐃⋅(𝐒_i×𝐒_j)$.
For more general interactions, such as biquadratic, use set_pair_coupling! instead.
Examples
# An explicit exchange matrix
+# Prints: (1/20)𝒪₄₀ + (1/4)𝒪₄₄ + (3/5)𝒮⁴
source
Sunny.print_suggested_frame — Method
print_suggested_frame(cryst, i; digits=4)
Print a suggested reference frame, as a rotation matrix R, that can be used as input to print_site(). The purpose is to simplify the description of allowed anisotropies.
source
Sunny.print_symmetry_table — Method
print_symmetry_table(cryst::Crystal, max_dist)
Print symmetry information for all equivalence classes of sites and bonds, up to a maximum bond distance of max_dist. Equivalent to calling print_bond(cryst, b) for every bond b in reference_bonds(cryst, max_dist), where Bond(i, i, [0,0,0]) refers to a single site i.
source
Sunny.print_wrapped_intensities — Method
print_wrapped_intensities(sys::System; nmax=10)
For Bravais lattices: Prints up to nmax wavevectors according to their instantaneous (static) structure factor intensities, listed in descending order. For non-Bravais lattices: Performs the same analysis for each spin sublattice independently; the output weights are naïvely averaged over sublattices, without incorporating phase shift information. This procedure therefore wraps all wavevectors into the first Brillouin zone. Each wavevector coordinate is given between $-1/2$ and $1/2$ in reciprocal lattice units (RLU).  The output from this function will typically be used as input to suggest_magnetic_supercell.
Because this function does not incorporate phase information in its averaging over sublattices, the printed weights are not directly comparable with experiment. For that purpose, use instant_correlations instead.
source
Sunny.propose_delta — Method
propose_delta(magnitude)
Generate a proposal function that adds a Gaussian perturbation to the existing spin state. In :dipole mode, the procedure is to first introduce a random three-vector perturbation $𝐬′ = 𝐬 + |𝐬| ξ$ and then return the properly normalized spin $|𝐬| (𝐬′/|𝐬′|)$. Each component of the random vector $ξ$ is Gaussian distributed with a standard deviation of magnitude; the latter is dimensionless and typically smaller than one. 
In :SUN mode, the procedure is analogous, but now involving Gaussian perturbations to each of the $N$ complex components of an SU(N) coherent state.
In the limit of very large magnitude, this function coincides with propose_uniform.
For use with LocalSampler.
source
Sunny.propose_flip — Method
propose_flip
Function to propose pure spin flip updates in the context of a LocalSampler. Dipoles are flipped as $𝐬 → -𝐬$. SU(N) coherent states are flipped using the time-reversal operator.
source
Sunny.propose_uniform — Function
propose_uniform
Function to propose a uniformly random spin update in the context of a LocalSampler. In :dipole mode, the result is a random three-vector with appropriate normalization. In :SUN mode, the result is a random SU(N) coherent state with appropriate normalization.
source
Sunny.reciprocal_space_path — Method
reciprocal_space_path(cryst::Crystal, qs, density)
Returns a pair (path, xticks). The path return value is a list of wavevectors that samples linearly between the provided wavevectors qs. The xticks return value can be used to label the special $𝐪$ values on the x-axis of a plot.
Special note about units: the wavevectors qs must be provided in reciprocal lattice units (RLU) for the given crystal, but the sampling density must be specified in the global frame. Specifically, the density is given as number of sample points per unit of radian inverse length, where the unit of length is the same as that used to specify the lattice vectors of the Crystal. The path will therefore include more samples between q-points that are further apart in absolute Fourier distance.
source
Sunny.reciprocal_space_path_bins — Method
reciprocal_space_path_bins(sc,qs,density,args...;kwargs...)
Takes a list of wave vectors, qs in R.L.U., and builds a series of histogram BinningParameters whose first axis traces a path through the provided points. The second and third axes are integrated over according to the args and kwargs, which are passed through to slice_2D_binning_parameters.
Also returned is a list of marker indices corresponding to the input points, and a list of ranges giving the indices of each histogram x-axis within a concatenated histogram. The density parameter is given in samples per reciprocal lattice unit (R.L.U.).
source
Sunny.reciprocal_space_shell — Method
reciprocal_space_shell(cryst::Crystal, radius, n)
Sample n points on the reciprocal space sphere with a given radius (units of inverse length).
Examples
# Sample wavevectors on the sphere at fixed density
+reciprocal_space_shell(cryst, r, 4π*r^2*density)
source
Sunny.reference_bonds — Method
reference_bonds(cryst::Crystal, max_dist)
Returns a full list of bonds, one for each symmetry equivalence class, up to distance max_dist. The reference bond b for each equivalence class is selected according to a scoring system that prioritizes simplification of the elements in basis_for_symmetry_allowed_couplings(cryst, b).
source
Sunny.remove_periodicity! — Method
remove_periodicity!(sys::System, dims)
Remove periodic interactions along the dimensions where dims is true. The system must support inhomogeneous interactions via to_inhomogeneous.
Example
# Remove periodic boundaries along the 1st and 3rd dimensions
+remove_periodicity!(sys::System, (true, false, true))
source
Sunny.reshape_supercell — Method
reshape_supercell(sys::System, shape)
Maps an existing System to a new one that has the shape and periodicity of a requested supercell. The columns of the $3×3$ integer matrix shape represent the supercell lattice vectors measured in units of the original crystal lattice vectors.
source
Sunny.resize_supercell — Method
resize_supercell(sys::System{N}, latsize::NTuple{3,Int}) where N
Creates a System with a given number of conventional unit cells in each lattice vector direction. Interactions and other settings will be inherited from sys.
Convenience function for:
reshape_supercell(sys, [latsize[1] 0 0; 0 latsize[2] 0; 0 0 latsize[3]])
See also reshape_supercell.
source
Sunny.rotate_operator — Method
rotate_operator(A, R)
Rotates the local quantum operator A according to the $3×3$ rotation matrix R.
source
Sunny.rotation_in_rlu — Method
rotation_in_rlu(cryst::Crystal, axis, angle)
Returns a $3×3$ matrix that rotates wavevectors in reciprocal lattice units (RLU). The axis vector is a real-space direction in absolute units (but arbitrary magnitude), and the angle is in radians.
source
Sunny.set_coherent! — Method
set_coherent!(sys::System, Z, site::Site)
Set a coherent spin state at a Site using the $N$ complex amplitudes in Z.
For a standard SpinInfo, these amplitudes will be interpreted in the eigenbasis of $𝒮̂ᶻ$. That is, Z[1] represents the amplitude for the basis state fully polarized along the $ẑ$-direction, and subsequent components represent states with decreasing angular momentum along this axis ($m = S, S-1, …, -S$).
source
Sunny.set_exchange! — Method
set_exchange!(sys::System, J, bond::Bond)
Sets a 3×3 spin-exchange matrix J along bond, yielding a pairwise interaction energy $𝐒_i⋅J 𝐒_j$. This interaction will be propagated to equivalent bonds in consistency with crystal symmetry. Any previous interactions on these bonds will be overwritten. The parameter bond has the form Bond(i, j, offset), where i and j are atom indices within the unit cell, and offset is a displacement in unit cells.
The parameter J may be scalar or matrix-valued. As a convenience, dmvec(D) can be used to construct the antisymmetric part of the exchange, where D is the Dzyaloshinskii-Moriya pseudo-vector. The resulting interaction will be $𝐃⋅(𝐒_i×𝐒_j)$.
For more general interactions, such as biquadratic, use set_pair_coupling! instead.
Examples
# An explicit exchange matrix
 J1 = [2 3 0;
      -3 2 0;
       0 0 2]
@@ -71,7 +71,7 @@
 
 # An equivalent Heisenberg + DM exchange 
 J2 = 2*I + dmvec([0,0,3])
-set_exchange!(sys, J2, bond)
source
Sunny.set_exchange_at! — Method
set_exchange_at!(sys::System, J, site1::Site, site2::Site; offset=nothing)
Sets an exchange interaction `𝐒_i⋅J 𝐒_j along the single bond connecting two Sites, ignoring crystal symmetry. Any previous coupling on this bond will be overwritten. The system must support inhomogeneous interactions via to_inhomogeneous.
If the system is relatively small, the direction of the bond can be ambiguous due to possible periodic wrapping. Resolve this ambiguity by passing an explicit offset vector, in multiples of unit cells.
For more general interactions, such as biquadratic, use set_pair_coupling_at! instead.
See also set_exchange!.
source
Sunny.set_external_field_at! — Method
set_external_field_at!(sys::System, B::Vec3, site::Site)
Sets a Zeeman coupling between a field B and a single spin. Site includes a unit cell and a sublattice index.
source
Sunny.set_onsite_coupling! — Method
set_onsite_coupling!(sys::System, op, i::Int)
Set the single-ion anisotropy for the ith atom of every unit cell, as well as all symmetry-equivalent atoms. The operator op may be provided as an abstract function of the local spin operators, as a polynomial of spin_matrices, or as a linear combination of stevens_matrices.
Examples
# An easy axis anisotropy in the z-direction
+set_exchange!(sys, J2, bond)
source
Sunny.set_exchange_at! — Method
set_exchange_at!(sys::System, J, site1::Site, site2::Site; offset=nothing)
Sets an exchange interaction `𝐒_i⋅J 𝐒_j along the single bond connecting two Sites, ignoring crystal symmetry. Any previous coupling on this bond will be overwritten. The system must support inhomogeneous interactions via to_inhomogeneous.
If the system is relatively small, the direction of the bond can be ambiguous due to possible periodic wrapping. Resolve this ambiguity by passing an explicit offset vector, in multiples of unit cells.
For more general interactions, such as biquadratic, use set_pair_coupling_at! instead.
See also set_exchange!.
source
Sunny.set_external_field_at! — Method
set_external_field_at!(sys::System, B::Vec3, site::Site)
Sets a Zeeman coupling between a field B and a single spin. Site includes a unit cell and a sublattice index.
source
Sunny.set_onsite_coupling! — Method
set_onsite_coupling!(sys::System, op, i::Int)
Set the single-ion anisotropy for the ith atom of every unit cell, as well as all symmetry-equivalent atoms. The operator op may be provided as an abstract function of the local spin operators, as a polynomial of spin_matrices, or as a linear combination of stevens_matrices.
Examples
# An easy axis anisotropy in the z-direction
 set_onsite_coupling!(sys, S -> -D*S[3]^3, i)
 
 # The unique quartic single-ion anisotropy for a site with cubic point group
@@ -80,31 +80,31 @@
 
 # An equivalent expression of this quartic anisotropy, up to a constant shift
 O = stevens_matrices(spin_label(sys, i))
-set_onsite_coupling!(sys, O[4,0] + 5*O[4,4], i)
source
Sunny.set_pair_coupling! — Method
set_pair_coupling!(sys::System, op, bond)
Sets an arbitrary coupling op along bond. This coupling will be propagated to equivalent bonds in consistency with crystal symmetry. Any previous interactions on these bonds will be overwritten. The parameter bond has the form Bond(i, j, offset), where i and j are atom indices within the unit cell, and offset is a displacement in unit cells. The operator op may be provided as an anonymous function that accepts two spin dipole operators, or as a matrix that acts in the tensor product space of the two sites.
Examples
# Bilinear+biquadratic exchange involving 3×3 matrices J1 and J2
+set_onsite_coupling!(sys, O[4,0] + 5*O[4,4], i)
source
Sunny.set_pair_coupling! — Method
set_pair_coupling!(sys::System, op, bond)
Sets an arbitrary coupling op along bond. This coupling will be propagated to equivalent bonds in consistency with crystal symmetry. Any previous interactions on these bonds will be overwritten. The parameter bond has the form Bond(i, j, offset), where i and j are atom indices within the unit cell, and offset is a displacement in unit cells. The operator op may be provided as an anonymous function that accepts two spin dipole operators, or as a matrix that acts in the tensor product space of the two sites.
Examples
# Bilinear+biquadratic exchange involving 3×3 matrices J1 and J2
 set_pair_coupling!(sys, (Si, Sj) -> Si'*J1*Sj + (Si'*J2*Sj)^2, bond)
 
 # Equivalent expression using an appropriate fixed matrix representation
 S = spin_matrices(1/2)
 Si, Sj = to_product_space(S, S)
-set_pair_coupling!(sys, Si'*J1*Sj + (Si'*J2*Sj)^2, bond)
See also spin_matrices, to_product_space.
source
Sunny.set_pair_coupling_at! — Method
set_pair_coupling_at!(sys::System, op, bond)
Sets an arbitrary coupling along the single bond connecting two Sites, ignoring crystal symmetry. Any previous coupling on this bond will be overwritten. The operator op may be provided as an anonymous function that accepts two spin dipole operators, or as a matrix that acts in the tensor product space of the two sites. The documentation for set_pair_coupling! provides examples constructing op.
The system must support inhomogeneous interactions via to_inhomogeneous.
If the system is relatively small, the direction of the bond can be ambiguous due to possible periodic wrapping. Resolve this ambiguity by passing an explicit offset vector, in multiples of unit cells.
source
Sunny.set_spiral_order! — Method
set_spiral_order!(sys; q, axis, S0)
Initializes the system with a spiral order described by the wavevector q, an axis of rotation axis, and an initial dipole direction S0 at the real-space origin. The wavevector is expected in repicrocal lattice units (RLU), while the direction vectors axis and S0 are expected in global Cartesian coordinates.
Example
# Spiral order for a wavevector propagating in the direction of the first
+set_pair_coupling!(sys, Si'*J1*Sj + (Si'*J2*Sj)^2, bond)
See also spin_matrices, to_product_space.
source
Sunny.set_pair_coupling_at! — Method
set_pair_coupling_at!(sys::System, op, bond)
Sets an arbitrary coupling along the single bond connecting two Sites, ignoring crystal symmetry. Any previous coupling on this bond will be overwritten. The operator op may be provided as an anonymous function that accepts two spin dipole operators, or as a matrix that acts in the tensor product space of the two sites. The documentation for set_pair_coupling! provides examples constructing op.
The system must support inhomogeneous interactions via to_inhomogeneous.
If the system is relatively small, the direction of the bond can be ambiguous due to possible periodic wrapping. Resolve this ambiguity by passing an explicit offset vector, in multiples of unit cells.
source
Sunny.set_spiral_order! — Method
set_spiral_order!(sys; q, axis, S0)
Initializes the system with a spiral order described by the wavevector q, an axis of rotation axis, and an initial dipole direction S0 at the real-space origin. The wavevector is expected in repicrocal lattice units (RLU), while the direction vectors axis and S0 are expected in global Cartesian coordinates.
Example
# Spiral order for a wavevector propagating in the direction of the first
 # reciprocal lattice vector (i.e., orthogonal to the lattice vectors ``𝐚_2``
 # and ``𝐚_3``), repeating with a period of 10 lattice constants, and spiraling
 # about the ``ẑ``-axis. The spin at the origin will point in the direction
 # ``𝐒_0 = ŷ + ẑ``.  Here, ``(x̂, ŷ, ẑ)`` are the axes of Cartesian coordinate
 # system in the global frame.
-set_spiral_order!(sys; q=[1/10, 0, 0], axis=[0, 0, 1], S0=[0, 1, 1])
See also set_spiral_order_on_sublattice!.
source
Sunny.set_spiral_order_on_sublattice! — Method
set_spiral_order_on_sublattice!(sys, i; q, axis, S0)
Initializes sublattice i with a spiral order described by the wavevector q, an axis of rotation axis, and an initial dipole direction S0. The phase is selected such that the spin at sys.dipole[1,1,1,i] will point in the direction of S0. The wavevector is expected in repicrocal lattice units (RLU), while the direction vectors axis and S0 are expected in global Cartesian coordinates.
This function is not available for systems with reshaped unit cells.
See also set_spiral_order!.
source
Sunny.set_vacancy_at! — Method
set_vacancy_at!(sys::System, site::Site)
Make a single site nonmagnetic. Site includes a unit cell and a sublattice index.
source
Sunny.slice_2D_binning_parameters — Method
slice_2D_binning_parameter(sc::SampledCorrelations, cut_from_q, cut_to_q, cut_bins::Int64, cut_width::Float64; plane_normal = [0,0,1],cut_height = cutwidth)
Creates BinningParameters which make a cut along one dimension of Q-space.
The x-axis of the resulting histogram consists of cut_bins-many bins ranging from cut_from_q to cut_to_q.  The width of the bins in the transverse direciton is controlled by cut_width and cut_height.
The binning in the transverse directions is defined in the following way, which sets their normalization and orthogonality properties:
cut_covector = normalize(cut_to_q - cut_from_q)
+set_spiral_order!(sys; q=[1/10, 0, 0], axis=[0, 0, 1], S0=[0, 1, 1])
See also set_spiral_order_on_sublattice!.
source
Sunny.set_spiral_order_on_sublattice! — Method
set_spiral_order_on_sublattice!(sys, i; q, axis, S0)
Initializes sublattice i with a spiral order described by the wavevector q, an axis of rotation axis, and an initial dipole direction S0. The phase is selected such that the spin at sys.dipole[1,1,1,i] will point in the direction of S0. The wavevector is expected in repicrocal lattice units (RLU), while the direction vectors axis and S0 are expected in global Cartesian coordinates.
This function is not available for systems with reshaped unit cells.
See also set_spiral_order!.
source
Sunny.set_vacancy_at! — Method
set_vacancy_at!(sys::System, site::Site)
Make a single site nonmagnetic. Site includes a unit cell and a sublattice index.
source
Sunny.slice_2D_binning_parameters — Method
slice_2D_binning_parameter(sc::SampledCorrelations, cut_from_q, cut_to_q, cut_bins::Int64, cut_width::Float64; plane_normal = [0,0,1],cut_height = cutwidth)
Creates BinningParameters which make a cut along one dimension of Q-space.
The x-axis of the resulting histogram consists of cut_bins-many bins ranging from cut_from_q to cut_to_q.  The width of the bins in the transverse direciton is controlled by cut_width and cut_height.
The binning in the transverse directions is defined in the following way, which sets their normalization and orthogonality properties:
cut_covector = normalize(cut_to_q - cut_from_q)
 transverse_covector = normalize(plane_normal × cut_covector)
-cotransverse_covector = normalize(transverse_covector × cut_covector)
In other words, the axes are orthonormal with respect to the Euclidean metric.
If the cut is too narrow, there will be very few scattering vectors per bin, or the number per bin will vary substantially along the cut. If the output appears under-resolved, try increasing cut_width.
The four axes of the resulting histogram are:
  1. Along the cut
  2. Fist transverse Q direction
  3. Second transverse Q direction
  4. Energy
This function can be used without reference to a SampledCorrelations using this alternate syntax to manually specify the bin centers for the energy axis:
slice_2D_binning_parameter(ω_bincenters, cut_from, cut_to,...)
where ω_bincenters specifies the energy axis, and both cut_from and cut_to are arbitrary covectors, in any units.
source
Sunny.spin_label — Method
spin_label(sys::System, i::Int)
If atom i carries a single spin-$S$ moment, then returns the half-integer label $S$. Otherwise, throws an error.
source
Sunny.spin_matrices — Method
spin_matrices(S)
Returns a triple of $N×N$ spin matrices, where $N = 2S+1$. These are the generators of SU(2) in the spin-S representation.
If S == Inf, then the return values are abstract symbols denoting infinite-dimensional matrices that commute. These can be useful for repeating historical studies, or modeling micromagnetic systems. A technical discussion appears in the Sunny documentation page: Interaction Strength Renormalization.
Example
S = spin_matrices(3/2)
+cotransverse_covector = normalize(transverse_covector × cut_covector)
In other words, the axes are orthonormal with respect to the Euclidean metric.
If the cut is too narrow, there will be very few scattering vectors per bin, or the number per bin will vary substantially along the cut. If the output appears under-resolved, try increasing cut_width.
The four axes of the resulting histogram are:
  1. Along the cut
  2. Fist transverse Q direction
  3. Second transverse Q direction
  4. Energy
This function can be used without reference to a SampledCorrelations using this alternate syntax to manually specify the bin centers for the energy axis:
slice_2D_binning_parameter(ω_bincenters, cut_from, cut_to,...)
where ω_bincenters specifies the energy axis, and both cut_from and cut_to are arbitrary covectors, in any units.
source
Sunny.spin_label — Method
spin_label(sys::System, i::Int)
If atom i carries a single spin-$S$ moment, then returns the half-integer label $S$. Otherwise, throws an error.
source
Sunny.spin_matrices — Method
spin_matrices(S)
Returns a triple of $N×N$ spin matrices, where $N = 2S+1$. These are the generators of SU(2) in the spin-S representation.
If S == Inf, then the return values are abstract symbols denoting infinite-dimensional matrices that commute. These can be useful for repeating historical studies, or modeling micromagnetic systems. A technical discussion appears in the Sunny documentation page: Interaction Strength Renormalization.
Example
S = spin_matrices(3/2)
 @assert S'*S ≈ (3/2)*(3/2+1)*I
 @assert S[1]*S[2] - S[2]*S[1] ≈ im*S[3]
 
 S = spin_matrices(Inf)
-@assert S[1]*S[2] - S[2]*S[1] == 0
See also print_stevens_expansion.
source
Sunny.step! — Function
step!(sys::System, dynamics)
Advance the spin configuration one dynamical time-step. The dynamics object may be a continuous spin dynamics, such as Langevin or ImplicitMidpoint, or it may be a discrete Monte Carlo sampling scheme such as LocalSampler.
source
Sunny.stevens_matrices — Method
stevens_matrices(S)
Returns a generator of Stevens operators in the spin-S representation. The return value O can be indexed as O[k,q], where $0 ≤ k ≤ 6$ labels an irrep of SO(3) and $-k ≤ q ≤ k$. This will produce an $N×N$ matrix where ``N = 2S
  • 1``. Linear combinations of Stevens operators can be used as a "physical
basis" for decomposing local observables. To see this decomposition, use print_stevens_expansion.
If S == Inf, then symbolic operators will be returned. In this infinite dimensional limit, the Stevens operators become homogeneous polynomials of commuting spin operators.
Example
O = stevens_matrices(2)
+@assert S[1]*S[2] - S[2]*S[1] == 0
See also print_stevens_expansion.
source
Sunny.step! — Function
step!(sys::System, dynamics)
Advance the spin configuration one dynamical time-step. The dynamics object may be a continuous spin dynamics, such as Langevin or ImplicitMidpoint, or it may be a discrete Monte Carlo sampling scheme such as LocalSampler.
source
Sunny.stevens_matrices — Method
stevens_matrices(S)
Returns a generator of Stevens operators in the spin-S representation. The return value O can be indexed as O[k,q], where $0 ≤ k ≤ 6$ labels an irrep of SO(3) and $-k ≤ q ≤ k$. This will produce an $N×N$ matrix where ``N = 2S
  • 1``. Linear combinations of Stevens operators can be used as a "physical
basis" for decomposing local observables. To see this decomposition, use print_stevens_expansion.
If S == Inf, then symbolic operators will be returned. In this infinite dimensional limit, the Stevens operators become homogeneous polynomials of commuting spin operators.
Example
O = stevens_matrices(2)
 S = spin_matrices(2)
 
 A = (1/20)O[4,0] + (1/4)O[4,4] + (102/5)I
 B = S[1]^4 + S[2]^4 + S[3]^4
-@assert A ≈ B
See also spin_matrices and Interaction Strength Renormalization.
source
Sunny.subcrystal — Method
subcrystal(cryst, types) :: Crystal
Filters sublattices of a Crystal by atom types, keeping the space group unchanged.
subcrystal(cryst, classes) :: Crystal
Filters sublattices of Crystal by equivalence classes, keeping the space group unchanged.
source
Sunny.suggest_magnetic_supercell — Method
suggest_magnetic_supercell(qs; tol=1e-12, maxsize=100)
Suggests a magnetic supercell, in units of the crystal lattice vectors, that is consistent with periodicity of the wavevectors qs in RLU. If the wavevectors are incommensurate (with respect to the maximum supercell size maxsize), one can select a larger error tolerance tol to find a supercell that is almost commensurate.
Prints a $3×3$ matrix of integers that is suitable for use in reshape_supercell.
Examples
# A magnetic supercell for a single-Q structure. Will print
+@assert A ≈ B
See also spin_matrices and Interaction Strength Renormalization.
source
Sunny.subcrystal — Method
subcrystal(cryst, types) :: Crystal
Filters sublattices of a Crystal by atom types, keeping the space group unchanged.
subcrystal(cryst, classes) :: Crystal
Filters sublattices of Crystal by equivalence classes, keeping the space group unchanged.
source
Sunny.suggest_magnetic_supercell — Method
suggest_magnetic_supercell(qs; tol=1e-12, maxsize=100)
Suggests a magnetic supercell, in units of the crystal lattice vectors, that is consistent with periodicity of the wavevectors qs in RLU. If the wavevectors are incommensurate (with respect to the maximum supercell size maxsize), one can select a larger error tolerance tol to find a supercell that is almost commensurate.
Prints a $3×3$ matrix of integers that is suitable for use in reshape_supercell.
Examples
# A magnetic supercell for a single-Q structure. Will print
 q1 = [0, -1/4, 1/4]
 suggest_magnetic_supercell([q1])       # [1 0 0; 0 2 1; 0 -2 1]
 
@@ -117,11 +117,11 @@
 suggest_magnetic_supercell([[0, 0, 1/√5], [0, 0, 1/√7]]; tol=1e-2)
 
 # This prints [1 0 0; 0 1 0; 0 0 16], which becomes commensurate under the
-# approximations `1/√5 ≈ 7/16` and `1/√7 ≈ 3/8`.
source
Sunny.symmetry_equivalent_bonds — Method
symmetry_equivalent_bonds(sys::System, bond::Bond)
Given a Bond for the original (unreshaped) crystal, return all symmetry equivalent bonds in the System. Each returned bond is represented as a pair of Sites, which may be used as input to set_exchange_at!. Reverse bonds are not included (no double counting).
Example
for (site1, site2, offset) in symmetry_equivalent_bonds(sys, bond)
+# approximations `1/√5 ≈ 7/16` and `1/√7 ≈ 3/8`.
source
Sunny.symmetry_equivalent_bonds — Method
symmetry_equivalent_bonds(sys::System, bond::Bond)
Given a Bond for the original (unreshaped) crystal, return all symmetry equivalent bonds in the System. Each returned bond is represented as a pair of Sites, which may be used as input to set_exchange_at!. Reverse bonds are not included (no double counting).
Example
for (site1, site2, offset) in symmetry_equivalent_bonds(sys, bond)
     @assert site1 < site2
     set_exchange_at!(sys, J, site1, site2; offset)
-end
source
Sunny.to_product_space — Method
to_product_space(A, B, Cs...)
Given lists of operators acting on local Hilbert spaces individually, return the corresponding operators that act on the tensor product space. In typical usage, the inputs will represent local physical observables and the outputs will be used to define quantum couplings.
source
Sunny.unit_resolution_binning_parameters — Method
unit_resolution_binning_parameters(sc::SampledCorrelations)
Create BinningParameters which place one histogram bin centered at each possible (q,ω) scattering vector of the crystal. This is the finest possible binning without creating bins with zero scattering vectors in them.
This function can be used without reference to a SampledCorrelations using an alternate syntax to manually specify the bin centers for the energy axis and the lattice size:
unit_resolution_binning_parameters(ω_bincenters,latsize,[reciprocal lattice vectors])
The last argument may be a 3x3 matrix specifying the reciprocal lattice vectors, or a Crystal.
Lastly, binning parameters for a single axis may be specifed by their bin centers:
(binstart,binend,binwidth) = unit_resolution_binning_parameters(bincenters::Vector{Float64})
source
Sunny.@mix_proposals — Macro
@mix_proposals weight1 propose1 weight2 propose2 ...
Macro to generate a proposal function that randomly selects among the provided functions according to the provided probability weights. For use with LocalSampler.
Example
# A proposal function that proposes a spin flip 40% of the time, and a
+end
source
Sunny.to_product_space — Method
to_product_space(A, B, Cs...)
Given lists of operators acting on local Hilbert spaces individually, return the corresponding operators that act on the tensor product space. In typical usage, the inputs will represent local physical observables and the outputs will be used to define quantum couplings.
source
Sunny.unit_resolution_binning_parameters — Method
unit_resolution_binning_parameters(sc::SampledCorrelations)
Create BinningParameters which place one histogram bin centered at each possible (q,ω) scattering vector of the crystal. This is the finest possible binning without creating bins with zero scattering vectors in them.
This function can be used without reference to a SampledCorrelations using an alternate syntax to manually specify the bin centers for the energy axis and the lattice size:
unit_resolution_binning_parameters(ω_bincenters,latsize,[reciprocal lattice vectors])
The last argument may be a 3x3 matrix specifying the reciprocal lattice vectors, or a Crystal.
Lastly, binning parameters for a single axis may be specifed by their bin centers:
(binstart,binend,binwidth) = unit_resolution_binning_parameters(bincenters::Vector{Float64})
source
Sunny.@mix_proposals — Macro
@mix_proposals weight1 propose1 weight2 propose2 ...
Macro to generate a proposal function that randomly selects among the provided functions according to the provided probability weights. For use with LocalSampler.
Example
# A proposal function that proposes a spin flip 40% of the time, and a
 # Gaussian perturbation 60% of the time.
-@mix_proposals 0.4 propose_flip 0.6 propose_delta(0.2)
source
Optional Makie extensions
The following will be enabled through a package extension if either GLMakie or WGLMakie is loaded.
Sunny.plot_spins — Function
plot_spins(sys::System; arrowscale=1.0, color=:red, colorfn=nothing,
+@mix_proposals 0.4 propose_flip 0.6 propose_delta(0.2)
source
Optional Makie extensions
The following will be enabled through a package extension if either GLMakie or WGLMakie is loaded.
Sunny.plot_spins — Function
plot_spins(sys::System; arrowscale=1.0, color=:red, colorfn=nothing,
            colormap=:viridis, colorrange=nothing, show_cell=true, orthographic=false,
-           ghost_radius=0, dims=3
Plot the spin configuration defined by sys. Optional parameters are:
  • arrowscale: Scale all arrows by dimensionless factor.
  • color: Arrow colors. May be symbolic or numeric. If scalar, will be shared among all sites.
  • colorfn: Function that dynamically maps from a site index to a numeric color value. Useful for animations.
  • colormap, colorrange: Used to populate colors from numbers following Makie conventions.
  • show_cell: Show original crystallographic unit cell.
  • orthographic: Use camera with orthographic projection.
  • ghost_radius: Show translucent periodic images up to a given distance (length units).
  • dims: Spatial dimensions of system (1, 2, or 3).
Calling notify on the return value will animate the figure.
source
Sunny.view_crystal — Function
view_crystal(crystal::Crystal, max_dist::Real; show_axis=true, orthographic=false)
An interactive crystal viewer, with bonds up to max_dist.
source
Optional WriteVTK extensions
The following will be enabled through a package extension if WriteVTK is loaded.
Sunny.export_vtk — Function
export_vtk(filename,params::BinningParameters,data)
Export a VTK-compatible file to filename (do not include file extension when specifying the file name) which contains the data as VTK Cell Data on a grid parameterized by params.
At least one axis of the BinningParameters must be integrated over, since VTK does not support 4D data. See integrate_axes!.
source

+           ghost_radius=0, dims=3

Plot the spin configuration defined by sys. Optional parameters are:

  • arrowscale: Scale all arrows by dimensionless factor.
  • color: Arrow colors. May be symbolic or numeric. If scalar, will be shared among all sites.
  • colorfn: Function that dynamically maps from a site index to a numeric color value. Useful for animations.
  • colormap, colorrange: Used to populate colors from numbers following Makie conventions.
  • show_cell: Show original crystallographic unit cell.
  • orthographic: Use camera with orthographic projection.
  • ghost_radius: Show translucent periodic images up to a given distance (length units).
  • dims: Spatial dimensions of system (1, 2, or 3).

Calling notify on the return value will animate the figure.

source
Sunny.view_crystal — Function
view_crystal(crystal::Crystal, max_dist::Real; show_axis=true, orthographic=false)

An interactive crystal viewer, with bonds up to max_dist.

source

Optional WriteVTK extensions

The following will be enabled through a package extension if WriteVTK is loaded.

Sunny.export_vtk — Function
export_vtk(filename,params::BinningParameters,data)

Export a VTK-compatible file to filename (do not include file extension when specifying the file name) which contains the data as VTK Cell Data on a grid parameterized by params.

At least one axis of the BinningParameters must be integrated over, since VTK does not support 4D data. See integrate_axes!.

source