From 299ec1c3e366bb1a7d5fac245f480603f99a7732 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Wed, 1 Nov 2023 03:44:44 +0000 Subject: [PATCH] build based on ec1a509 --- dev/.documenter-siteinfo.json | 2 +- ..._tutorial.ipynb => 01_LSWT_SU3_FeI2.ipynb} | 24 +- ..._averaging.ipynb => 02_LSWT_CoRh2O4.ipynb} | 27 +- dev/assets/notebooks/03_LLD_CoRh2O4.ipynb | 446 ++++++++++++++++++ ...fei2_classical.ipynb => 04_GSD_FeI2.ipynb} | 11 +- .../{ising2d.ipynb => 05_MC_Ising.ipynb} | 2 +- ...uilibrium.ipynb => 06_CP2_Skyrmions.ipynb} | 6 +- ...Kagome_AFM.ipynb => SW08_Kagome_AFM.ipynb} | 2 +- ...Si2O14.ipynb => SW15_Ba3NbFe3Si2O14.ipynb} | 2 +- .../{fei2_tutorial.jl => 01_LSWT_SU3_FeI2.jl} | 0 ...powder_averaging.jl => 02_LSWT_CoRh2O4.jl} | 5 +- dev/assets/scripts/03_LLD_CoRh2O4.jl | 114 +++++ .../{fei2_classical.jl => 04_GSD_FeI2.jl} | 0 .../scripts/{ising2d.jl => 05_MC_Ising.jl} | 0 ..._of_equilibrium.jl => 06_CP2_Skyrmions.jl} | 2 +- .../{08_Kagome_AFM.jl => SW08_Kagome_AFM.jl} | 0 ...3NbFe3Si2O14.jl => SW15_Ba3NbFe3Si2O14.jl} | 0 ...91bd.png => 01_LSWT_SU3_FeI2-1fdd91bd.png} | Bin ...d398.png => 01_LSWT_SU3_FeI2-69abd398.png} | Bin ...8f85.png => 01_LSWT_SU3_FeI2-8e8e8f85.png} | Bin ...43fa.png => 01_LSWT_SU3_FeI2-c72e43fa.png} | Bin ...0e69.png => 01_LSWT_SU3_FeI2-d4e30e69.png} | Bin dev/examples/01_LSWT_SU3_FeI2.html | 159 +++++++ dev/examples/02_LSWT_CoRh2O4-7eb4b415.png | Bin 0 -> 58907 bytes dev/examples/02_LSWT_CoRh2O4-822521c1.png | Bin 0 -> 96676 bytes ...01496.png => 02_LSWT_CoRh2O4-a4701496.png} | Bin dev/examples/02_LSWT_CoRh2O4-d8c9a147.png | Bin 0 -> 53406 bytes dev/examples/02_LSWT_CoRh2O4.html | 60 +++ dev/examples/03_LLD_CoRh2O4-143cf2d7.png | Bin 0 -> 306060 bytes dev/examples/03_LLD_CoRh2O4-30fb550a.png | Bin 0 -> 22196 bytes dev/examples/03_LLD_CoRh2O4-5d37d1e4.png | Bin 0 -> 67167 bytes dev/examples/03_LLD_CoRh2O4-ce111d6a.png | Bin 0 -> 18395 bytes dev/examples/03_LLD_CoRh2O4-df23408a.png | Bin 0 -> 48727 bytes dev/examples/03_LLD_CoRh2O4.html | 88 ++++ ...-6b435b86.png => 04_GSD_FeI2-6b435b86.png} | Bin ...-9c3ace5d.png => 04_GSD_FeI2-9c3ace5d.png} | Bin ...-9fe52114.png => 04_GSD_FeI2-9fe52114.png} | Bin ...-a20d933e.png => 04_GSD_FeI2-a20d933e.png} | Bin ...-de3c2258.png => 04_GSD_FeI2-de3c2258.png} | Bin ...-ef051221.png => 04_GSD_FeI2-ef051221.png} | Bin ...-f49e7f7e.png => 04_GSD_FeI2-f49e7f7e.png} | Bin ...-ffcf4af4.png => 04_GSD_FeI2-ffcf4af4.png} | Bin .../{fei2_classical.html => 04_GSD_FeI2.html} | 18 +- ...-f39f34dd.png => 05_MC_Ising-f39f34dd.png} | Bin dev/examples/05_MC_Ising.html | 17 + ...e6b4.png => 06_CP2_Skyrmions-c31de6b4.png} | Bin dev/examples/06_CP2_Skyrmions.html | 55 +++ .../contributed/CoRh2O4-tutorial.html | 4 +- .../contributed/MgCr2O4-tutorial.html | 4 +- dev/examples/fei2_tutorial.html | 159 ------- dev/examples/ising2d.html | 17 - dev/examples/out_of_equilibrium.html | 55 --- dev/examples/powder_averaging-07908bf2.png | Bin 96671 -> 0 bytes dev/examples/powder_averaging-efca91b4.png | Bin 96159 -> 0 bytes dev/examples/powder_averaging-f00771bb.png | Bin 54610 -> 0 bytes dev/examples/powder_averaging.html | 61 --- dev/examples/spinw/08_Kagome_AFM.html | 30 -- dev/examples/spinw/15_Ba3NbFe3Si2O14.html | 49 -- ...b7e3d.png => SW08_Kagome_AFM-08bb7e3d.png} | Bin ...d5723.png => SW08_Kagome_AFM-a51d5723.png} | Bin dev/examples/spinw/SW08_Kagome_AFM.html | 30 ++ ...6.png => SW15_Ba3NbFe3Si2O14-0135a936.png} | Bin ...5.png => SW15_Ba3NbFe3Si2O14-7b15c415.png} | Bin ...a.png => SW15_Ba3NbFe3Si2O14-9b66d42a.png} | Bin dev/examples/spinw/SW15_Ba3NbFe3Si2O14.html | 49 ++ dev/index.html | 2 +- dev/library.html | 54 +-- dev/parallelism.html | 4 +- dev/renormalization.html | 4 +- dev/search_index.js | 2 +- dev/structure-factor.html | 4 +- dev/versions.html | 2 +- dev/writevtk.html | 4 +- 73 files changed, 1107 insertions(+), 467 deletions(-) rename dev/assets/notebooks/{fei2_tutorial.ipynb => 01_LSWT_SU3_FeI2.ipynb} (96%) rename dev/assets/notebooks/{powder_averaging.ipynb => 02_LSWT_CoRh2O4.ipynb} (88%) create mode 100644 dev/assets/notebooks/03_LLD_CoRh2O4.ipynb rename dev/assets/notebooks/{fei2_classical.ipynb => 04_GSD_FeI2.ipynb} (98%) rename dev/assets/notebooks/{ising2d.ipynb => 05_MC_Ising.ipynb} (98%) rename dev/assets/notebooks/{out_of_equilibrium.ipynb => 06_CP2_Skyrmions.ipynb} (98%) rename dev/assets/notebooks/{08_Kagome_AFM.ipynb => SW08_Kagome_AFM.ipynb} (98%) rename dev/assets/notebooks/{15_Ba3NbFe3Si2O14.ipynb => SW15_Ba3NbFe3Si2O14.ipynb} (99%) rename dev/assets/scripts/{fei2_tutorial.jl => 01_LSWT_SU3_FeI2.jl} (100%) rename dev/assets/scripts/{powder_averaging.jl => 02_LSWT_CoRh2O4.jl} (93%) create mode 100644 dev/assets/scripts/03_LLD_CoRh2O4.jl rename dev/assets/scripts/{fei2_classical.jl => 04_GSD_FeI2.jl} (100%) rename dev/assets/scripts/{ising2d.jl => 05_MC_Ising.jl} (100%) rename dev/assets/scripts/{out_of_equilibrium.jl => 06_CP2_Skyrmions.jl} (96%) rename dev/assets/scripts/{08_Kagome_AFM.jl => SW08_Kagome_AFM.jl} (100%) rename dev/assets/scripts/{15_Ba3NbFe3Si2O14.jl => SW15_Ba3NbFe3Si2O14.jl} (100%) rename dev/examples/{fei2_tutorial-1fdd91bd.png => 01_LSWT_SU3_FeI2-1fdd91bd.png} (100%) rename dev/examples/{fei2_tutorial-69abd398.png => 01_LSWT_SU3_FeI2-69abd398.png} (100%) rename dev/examples/{fei2_tutorial-8e8e8f85.png => 01_LSWT_SU3_FeI2-8e8e8f85.png} (100%) rename dev/examples/{fei2_tutorial-c72e43fa.png => 01_LSWT_SU3_FeI2-c72e43fa.png} (100%) rename dev/examples/{fei2_tutorial-d4e30e69.png => 01_LSWT_SU3_FeI2-d4e30e69.png} (100%) create mode 100644 dev/examples/01_LSWT_SU3_FeI2.html create mode 100644 dev/examples/02_LSWT_CoRh2O4-7eb4b415.png create mode 100644 dev/examples/02_LSWT_CoRh2O4-822521c1.png rename dev/examples/{powder_averaging-a4701496.png => 02_LSWT_CoRh2O4-a4701496.png} (100%) create mode 100644 dev/examples/02_LSWT_CoRh2O4-d8c9a147.png create mode 100644 dev/examples/02_LSWT_CoRh2O4.html create mode 100644 dev/examples/03_LLD_CoRh2O4-143cf2d7.png create mode 100644 dev/examples/03_LLD_CoRh2O4-30fb550a.png create mode 100644 dev/examples/03_LLD_CoRh2O4-5d37d1e4.png create mode 100644 dev/examples/03_LLD_CoRh2O4-ce111d6a.png create mode 100644 dev/examples/03_LLD_CoRh2O4-df23408a.png create mode 100644 dev/examples/03_LLD_CoRh2O4.html rename dev/examples/{fei2_classical-6b435b86.png => 04_GSD_FeI2-6b435b86.png} (100%) rename dev/examples/{fei2_classical-9c3ace5d.png => 04_GSD_FeI2-9c3ace5d.png} (100%) rename dev/examples/{fei2_classical-9fe52114.png => 04_GSD_FeI2-9fe52114.png} (100%) rename dev/examples/{fei2_classical-a20d933e.png => 04_GSD_FeI2-a20d933e.png} (100%) rename dev/examples/{fei2_classical-de3c2258.png => 04_GSD_FeI2-de3c2258.png} (100%) rename dev/examples/{fei2_classical-ef051221.png => 04_GSD_FeI2-ef051221.png} (100%) rename dev/examples/{fei2_classical-f49e7f7e.png => 04_GSD_FeI2-f49e7f7e.png} (100%) rename dev/examples/{fei2_classical-ffcf4af4.png => 04_GSD_FeI2-ffcf4af4.png} (100%) rename dev/examples/{fei2_classical.html => 04_GSD_FeI2.html} (50%) rename dev/examples/{ising2d-f39f34dd.png => 05_MC_Ising-f39f34dd.png} (100%) create mode 100644 dev/examples/05_MC_Ising.html rename dev/examples/{out_of_equilibrium-c31de6b4.png => 06_CP2_Skyrmions-c31de6b4.png} (100%) create mode 100644 dev/examples/06_CP2_Skyrmions.html delete mode 100644 dev/examples/fei2_tutorial.html delete mode 100644 dev/examples/ising2d.html delete mode 100644 dev/examples/out_of_equilibrium.html delete mode 100644 dev/examples/powder_averaging-07908bf2.png delete mode 100644 dev/examples/powder_averaging-efca91b4.png delete mode 100644 dev/examples/powder_averaging-f00771bb.png delete mode 100644 dev/examples/powder_averaging.html delete mode 100644 dev/examples/spinw/08_Kagome_AFM.html delete mode 100644 dev/examples/spinw/15_Ba3NbFe3Si2O14.html rename dev/examples/spinw/{08_Kagome_AFM-08bb7e3d.png => SW08_Kagome_AFM-08bb7e3d.png} (100%) rename dev/examples/spinw/{08_Kagome_AFM-a51d5723.png => SW08_Kagome_AFM-a51d5723.png} (100%) create mode 100644 dev/examples/spinw/SW08_Kagome_AFM.html rename dev/examples/spinw/{15_Ba3NbFe3Si2O14-0135a936.png => SW15_Ba3NbFe3Si2O14-0135a936.png} (100%) rename dev/examples/spinw/{15_Ba3NbFe3Si2O14-7b15c415.png => SW15_Ba3NbFe3Si2O14-7b15c415.png} (100%) rename dev/examples/spinw/{15_Ba3NbFe3Si2O14-9b66d42a.png => SW15_Ba3NbFe3Si2O14-9b66d42a.png} (100%) create mode 100644 dev/examples/spinw/SW15_Ba3NbFe3Si2O14.html diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 963629129..44e77eb5f 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-10-31T16:49:55","documenter_version":"1.1.2"}} \ No newline at end of file +{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-11-01T03:44:35","documenter_version":"1.1.2"}} \ No newline at end of file diff --git a/dev/assets/notebooks/fei2_tutorial.ipynb b/dev/assets/notebooks/01_LSWT_SU3_FeI2.ipynb similarity index 96% rename from dev/assets/notebooks/fei2_tutorial.ipynb rename to dev/assets/notebooks/01_LSWT_SU3_FeI2.ipynb index c174cc36d..8b7770c2d 100644 --- a/dev/assets/notebooks/fei2_tutorial.ipynb +++ b/dev/assets/notebooks/01_LSWT_SU3_FeI2.ipynb @@ -3,7 +3,7 @@ { "cell_type": "markdown", "source": [ - "# Case Study: FeI₂\n", + "# 1. Multi-flavor spin wave simulations of FeI₂ (Showcase)\n", "\n", "FeI₂ is an effective spin-1 material with strong single-ion anisotropy.\n", "Quadrupolar fluctuations give rise to a single-ion bound state that cannot be\n", @@ -46,8 +46,8 @@ "guide. Sunny requires Julia 1.9 or later.\n", "\n", "From the Julia prompt, load `Sunny`. For plotting, one can choose either\n", - "`GLMakie` (a pop-up window) or `WGLMakie` (inline plots for a Jupyter notebook\n", - "or VSCode)." + "`GLMakie` (a pop-up window) or `WGLMakie` (inline plots for a Jupyter\n", + "notebook)." ], "metadata": {} }, @@ -125,7 +125,7 @@ { "cell_type": "markdown", "source": [ - "Observe that `cryst` retains the spacegroup symmetry of the full FeI₂ crystal.\n", + "Importantly, `cryst` retains the spacegroup symmetry of the full FeI₂ crystal.\n", "This information will be used, for example, to propagate exchange interactions\n", "between symmetry-equivalent bonds.\n", "\n", @@ -733,21 +733,15 @@ "The full SU(_N_) coherent state dynamics, with appropriate quantum correction\n", "factors, can be useful to model finite temperature scattering data. In\n", "particular, it captures certain anharmonic effects due to thermal\n", - "fluctuations. This is the subject of our FeI₂ at Finite Temperature\n", - "tutorial.\n", + "fluctuations. See our [generalized spin dynamics tutorial](@ref \"3.\n", + "Generalized spin dynamics of FeI₂ at finite *T*\").\n", "\n", "The classical dynamics is also a good starting point to study non-equilibrium\n", "phenomena. Empirical noise and damping terms can be used to model [coupling to\n", "a thermal bath](https://arxiv.org/abs/2209.01265). This yields a Langevin\n", - "dynamics of SU(_N_) coherent states. Our CP² Skyrmion Quench\n", - "tutorial shows how this dynamics gives rise to the formation of novel\n", - "topological defects in a temperature quench.\n", - "\n", - "Relative to LSWT calculations, it can take much more time to estimate\n", - "$\\mathcal{S}(𝐪,ω)$ intensities using classical dynamics simulation. See the\n", - "[SunnyTutorials\n", - "notebooks](https://nbviewer.org/github/SunnySuite/SunnyTutorials/tree/main/Tutorials/)\n", - "for examples of \"production-scale\" simulations." + "dynamics of SU(_N_) coherent states. Our [dynamical SU(_N_) quench](@ref \"5.\n", + "Dynamical quench into CP² skyrmion liquid\") tutorial illustrates how a\n", + "temperature quench can give rise to novel liquid phase of CP² skyrmions." ], "metadata": {} } diff --git a/dev/assets/notebooks/powder_averaging.ipynb b/dev/assets/notebooks/02_LSWT_CoRh2O4.ipynb similarity index 88% rename from dev/assets/notebooks/powder_averaging.ipynb rename to dev/assets/notebooks/02_LSWT_CoRh2O4.ipynb index 0f84c42b8..d3f9a33aa 100644 --- a/dev/assets/notebooks/powder_averaging.ipynb +++ b/dev/assets/notebooks/02_LSWT_CoRh2O4.ipynb @@ -3,12 +3,12 @@ { "cell_type": "markdown", "source": [ - "# Powder Averaged CoRh₂O₄\n", + "# 2. Spin wave simulations of CoRh₂O₄\n", "\n", - "This tutorial illustrates the calculation of the powder-averaged structure\n", - "factor by performing an orientational average. We consider a simple model of\n", - "the diamond-cubic crystal CoRh₂O₄, with parameters extracted from [Ge et al.,\n", - "Phys. Rev. B 96, 064413](https://doi.org/10.1103/PhysRevB.96.064413)." + "This tutorial illustrates the conventional spin wave theory of dipoles. We\n", + "consider a simple model of the diamond-cubic crystal CoRh₂O₄, with parameters\n", + "extracted from [Ge et al., Phys. Rev. B 96,\n", + "064413](https://doi.org/10.1103/PhysRevB.96.064413)." ], "metadata": {} }, @@ -64,12 +64,12 @@ { "cell_type": "markdown", "source": [ - "Construct a `System` with an antiferromagnetic nearest neighbor\n", - "interaction `J`. Because the diamond crystal is bipartite, the ground state\n", - "will have unfrustrated Néel order. Selecting `latsize=(1,1,1)` is sufficient\n", - "because the ground state is periodic over each cubic unit cell. By passing an\n", - "explicit `seed`, the system's random number generator will give repeatable\n", - "results." + "Construct a `System` with quantum spin $S=3/2$ constrained to the\n", + "space of dipoles. Including an antiferromagnetic nearest neighbor interaction\n", + "`J` will favor Néel order. To optimize this magnetic structure, it is\n", + "sufficient to employ a magnetic lattice consisting of a single crystal unit\n", + "cell, `latsize=(1,1,1)`. Passing an explicit random number `seed` will ensure\n", + "repeatable results." ], "metadata": {} }, @@ -77,8 +77,7 @@ "outputs": [], "cell_type": "code", "source": [ - "latsize = (2, 2, 2)\n", - "seed = 0\n", + "latsize = (1, 1, 1)\n", "S = 3/2\n", "J = 7.5413*meV_per_K # (~ 0.65 meV)\n", "sys = System(cryst, latsize, [SpinInfo(1; S, g=2)], :dipole; seed=0)\n", @@ -190,7 +189,7 @@ "outputs": [], "cell_type": "code", "source": [ - "qpoints = [[0.0, 0.0, 0.0], [0.5, 0.0, 0.0], [0.5, 0.5, 0.0], [0.0, 0.0, 0.0]]\n", + "qpoints = [[0, 0, 0], [1/2, 0, 0], [1/2, 1/2, 0], [0, 0, 0]]\n", "path, xticks = reciprocal_space_path(cryst, qpoints, 50)\n", "energies = collect(0:0.01:6)\n", "is = intensities_broadened(swt, path, energies, formula)\n", diff --git a/dev/assets/notebooks/03_LLD_CoRh2O4.ipynb b/dev/assets/notebooks/03_LLD_CoRh2O4.ipynb new file mode 100644 index 000000000..cdfe01c27 --- /dev/null +++ b/dev/assets/notebooks/03_LLD_CoRh2O4.ipynb @@ -0,0 +1,446 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "source": [ + "# 3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite *T*" + ], + "metadata": {} + }, + { + "outputs": [], + "cell_type": "code", + "source": [ + "using Sunny, WGLMakie, Statistics" + ], + "metadata": {}, + "execution_count": null + }, + { + "cell_type": "markdown", + "source": [ + "### System construction" + ], + "metadata": {} + }, + { + "cell_type": "markdown", + "source": [ + "Construct the system as in the previous [CoRh₂O₄ tutorial](@ref \"2. Spin wave\n", + "simulations of CoRh₂O₄\"). After optimization, the system will be in an\n", + "unfrustrated antiferromagnetic ground state." + ], + "metadata": {} + }, + { + "outputs": [], + "cell_type": "code", + "source": [ + "a = 8.5031 # (Å)\n", + "latvecs = lattice_vectors(a, a, a, 90, 90, 90)\n", + "cryst = Crystal(latvecs, [[0,0,0]], 227, setting=\"1\")\n", + "latsize = (2, 2, 2)\n", + "S = 3/2\n", + "J = 0.63 # (meV)\n", + "sys = System(cryst, latsize, [SpinInfo(1; S, g=2)], :dipole; seed=0)\n", + "set_exchange!(sys, J, Bond(1, 3, [0,0,0]))\n", + "randomize_spins!(sys)\n", + "minimize_energy!(sys)" + ], + "metadata": {}, + "execution_count": null + }, + { + "cell_type": "markdown", + "source": [ + "Use `resize_supercell` to build a new system with a lattice of\n", + "10×10×10 unit cells. The desired Néel order is retained." + ], + "metadata": {} + }, + { + "outputs": [], + "cell_type": "code", + "source": [ + "sys = resize_supercell(sys, (10, 10, 10))\n", + "@assert energy_per_site(sys) ≈ -2J*S^2" + ], + "metadata": {}, + "execution_count": null + }, + { + "cell_type": "markdown", + "source": [ + "Use the stochastic Landau-Lifshitz dynamics to thermalize system into\n", + "equilibrium at finite temperature. This is a `Langevin` equation,\n", + "which includes damping and noise terms. The strength of the noise term is\n", + "automatically fixed according to the damping time scale `λ` and the target\n", + "temperature, according to a fluctuation-dissipation theorem." + ], + "metadata": {} + }, + { + "outputs": [], + "cell_type": "code", + "source": [ + "Δt = 0.05/abs(J*S) # Time step\n", + "λ = 0.1 # Dimensionless damping time-scale\n", + "kT = 16 * meV_per_K # 16K, a temperature slightly below ordering\n", + "langevin = Langevin(Δt; λ, kT);" + ], + "metadata": {}, + "execution_count": null + }, + { + "cell_type": "markdown", + "source": [ + "Because the magnetic order has been initialized correctly, relatively few\n", + "additional Langevin time-steps are required to reach thermal equilibrium." + ], + "metadata": {} + }, + { + "outputs": [], + "cell_type": "code", + "source": [ + "energies = [energy_per_site(sys)]\n", + "for _ in 1:1000\n", + " step!(sys, langevin)\n", + " push!(energies, energy_per_site(sys))\n", + "end\n", + "plot(energies, color=:blue, figure=(resolution=(600,300),), axis=(xlabel=\"Time steps\", ylabel=\"Energy (meV)\"))" + ], + "metadata": {}, + "execution_count": null + }, + { + "cell_type": "markdown", + "source": [ + "Thermal fluctuations are apparent in the spin configuration." + ], + "metadata": {} + }, + { + "outputs": [], + "cell_type": "code", + "source": [ + "S_ref = sys.dipoles[1,1,1,1]\n", + "plot_spins(sys; color=[s'*S_ref for s in sys.dipoles])" + ], + "metadata": {}, + "execution_count": null + }, + { + "cell_type": "markdown", + "source": [ + "### Instantaneous structure factor" + ], + "metadata": {} + }, + { + "cell_type": "markdown", + "source": [ + "To visualize the instantaneous (equal-time) structure factor, create an object\n", + "`instant_correlations` and use `add_sample!` to accumulated\n", + "data for the equilibrated spin configuration." + ], + "metadata": {} + }, + { + "outputs": [], + "cell_type": "code", + "source": [ + "sc = instant_correlations(sys)\n", + "add_sample!(sc, sys) # Accumulate the newly sampled structure factor into `sf`" + ], + "metadata": {}, + "execution_count": null + }, + { + "cell_type": "markdown", + "source": [ + "Collect 20 additional decorrelated samples. For each sample, about 100\n", + "Langevin time-steps is sufficient to collect approximately uncorrelated\n", + "statistics." + ], + "metadata": {} + }, + { + "outputs": [], + "cell_type": "code", + "source": [ + "for _ in 1:20\n", + " for _ in 1:100\n", + " step!(sys, langevin)\n", + " end\n", + " add_sample!(sc, sys)\n", + "end" + ], + "metadata": {}, + "execution_count": null + }, + { + "cell_type": "markdown", + "source": [ + "Define a slice of momentum space. Wavevectors are specified in reciprocal\n", + "lattice units (RLU). The notation `q1s in -10:0.1:10` indicates that the first\n", + "$q$-component ranges from -10 to 10 in intervals of 0.1. That is, $q$\n", + "spans over 20 Brillouin zones. To convert to absolute momentum units, each\n", + "component of $q$ would need to be scaled by a reciprocal lattice vector." + ], + "metadata": {} + }, + { + "outputs": [], + "cell_type": "code", + "source": [ + "q1s = -10:0.1:10\n", + "q2s = -10:0.1:10\n", + "qs = [[q1, q2, 0.0] for q1 in q1s, q2 in q2s];" + ], + "metadata": {}, + "execution_count": null + }, + { + "cell_type": "markdown", + "source": [ + "Plot the instantaneous structure factor for the given $q$-slice. We employ\n", + "the appropriate `FormFactor` for Co2⁺. An `intensity_formula`\n", + "defines how dynamical correlations correspond to the observable structure\n", + "factor. The function `instant_intensities_interpolated` calculates\n", + "intensities at the target `qs` by interpolating over the data available at\n", + "discrete reciprocal-space lattice points." + ], + "metadata": {} + }, + { + "outputs": [], + "cell_type": "code", + "source": [ + "formfactors = [FormFactor(\"Co2\")]\n", + "instant_formula = intensity_formula(sc, :perp; formfactors)\n", + "iq = instant_intensities_interpolated(sc, qs, instant_formula);" + ], + "metadata": {}, + "execution_count": null + }, + { + "cell_type": "markdown", + "source": [ + "Plot the resulting intensity data $I(𝐪)$. The color scale is clipped to 50%\n", + "of the maximum intensity." + ], + "metadata": {} + }, + { + "outputs": [], + "cell_type": "code", + "source": [ + "heatmap(q1s, q2s, iq;\n", + " colorrange = (0, maximum(iq)/2),\n", + " axis = (\n", + " xlabel=\"Momentum Transfer Qx (r.l.u)\", xlabelsize=16,\n", + " ylabel=\"Momentum Transfer Qy (r.l.u)\", ylabelsize=16,\n", + " aspect=true,\n", + " )\n", + ")" + ], + "metadata": {}, + "execution_count": null + }, + { + "cell_type": "markdown", + "source": [ + "### Dynamical structure factor" + ], + "metadata": {} + }, + { + "cell_type": "markdown", + "source": [ + "To collect statistics for the dynamical structure factor intensities\n", + "$I(𝐪,ω)$ at finite temperature, use `dynamical_correlations`. Now,\n", + "each call to `add_sample!` will run a classical spin dynamics trajectory.\n", + "Longer-time trajectories will be required to achieve greater energy\n", + "resolution, as controlled by `nω`. Here, we pick a moderate number of\n", + "energies, `nω = 50`, which will make the simulation run quickly." + ], + "metadata": {} + }, + { + "outputs": [], + "cell_type": "code", + "source": [ + "ωmax = 6.0 # Maximum energy to resolve (meV)\n", + "nω = 50 # Number of energies to resolve\n", + "sc = dynamical_correlations(sys; Δt, nω, ωmax, process_trajectory=:symmetrize)" + ], + "metadata": {}, + "execution_count": null + }, + { + "cell_type": "markdown", + "source": [ + "Each sample requires running a full dynamical trajectory to measure\n", + "correlations, so we here restrict to 5 samples." + ], + "metadata": {} + }, + { + "outputs": [], + "cell_type": "code", + "source": [ + "for _ in 1:5\n", + " for _ in 1:100\n", + " step!(sys, langevin)\n", + " end\n", + " add_sample!(sc, sys)\n", + "end" + ], + "metadata": {}, + "execution_count": null + }, + { + "cell_type": "markdown", + "source": [ + "Define points that define a piecewise-linear path through reciprocal space,\n", + "and a sampling density." + ], + "metadata": {} + }, + { + "outputs": [], + "cell_type": "code", + "source": [ + "points = [[3/4, 3/4, 0],\n", + " [ 0, 0, 0],\n", + " [ 0, 1/2, 1/2],\n", + " [1/2, 1, 0],\n", + " [ 0, 1, 0],\n", + " [1/4, 1, 1/4],\n", + " [ 0, 1, 0],\n", + " [ 0, -4, 0]]\n", + "density = 50 # (Å)\n", + "path, xticks = reciprocal_space_path(cryst, points, density);" + ], + "metadata": {}, + "execution_count": null + }, + { + "cell_type": "markdown", + "source": [ + "Calculate $I(𝐪, ω)$ intensities along this path with Lorentzian broadening\n", + "on the scale of 0.1 meV." + ], + "metadata": {} + }, + { + "outputs": [], + "cell_type": "code", + "source": [ + "formula = intensity_formula(sc, :perp; formfactors, kT=langevin.kT)\n", + "η = 0.1\n", + "iqw = intensities_interpolated(sc, path, formula)\n", + "iqwc = broaden_energy(sc, iqw, (ω, ω₀) -> lorentzian(ω-ω₀, η));" + ], + "metadata": {}, + "execution_count": null + }, + { + "cell_type": "markdown", + "source": [ + "Plot the intensity data on a clipped color scale" + ], + "metadata": {} + }, + { + "outputs": [], + "cell_type": "code", + "source": [ + "ωs = available_energies(sc)\n", + "heatmap(1:size(iqwc, 1), ωs, iqwc;\n", + " colorrange = (0, maximum(iqwc)/50),\n", + " axis = (;\n", + " xlabel=\"Momentum Transfer (r.l.u)\",\n", + " ylabel=\"Energy Transfer (meV)\",\n", + " xticks,\n", + " xticklabelrotation=π/5,\n", + " aspect = 1.4,\n", + " )\n", + ")" + ], + "metadata": {}, + "execution_count": null + }, + { + "cell_type": "markdown", + "source": [ + "### Powder averaged intensity" + ], + "metadata": {} + }, + { + "cell_type": "markdown", + "source": [ + "Define spherical shells in reciprocal space via their radii, in absolute units\n", + "of 1/Å. For each shell, calculate and average the intensities at 100\n", + "$𝐪$-points, sampled approximately uniformly." + ], + "metadata": {} + }, + { + "outputs": [], + "cell_type": "code", + "source": [ + "radii = 0:0.05:3.5 # (1/Å)\n", + "output = zeros(Float64, length(radii), length(ωs))\n", + "for (i, radius) in enumerate(radii)\n", + " pts = reciprocal_space_shell(sc.crystal, radius, 100)\n", + " is = intensities_interpolated(sc, pts, formula)\n", + " is = broaden_energy(sc, is, (ω,ω₀)->lorentzian(ω-ω₀, η))\n", + " output[i, :] = mean(is , dims=1)[1,:]\n", + "end" + ], + "metadata": {}, + "execution_count": null + }, + { + "cell_type": "markdown", + "source": [ + "Plot resulting powder-averaged structure factor" + ], + "metadata": {} + }, + { + "outputs": [], + "cell_type": "code", + "source": [ + "heatmap(radii, ωs, output;\n", + " axis = (\n", + " xlabel=\"|Q| (Å⁻¹)\",\n", + " ylabel=\"Energy Transfer (meV)\",\n", + " aspect = 1.4,\n", + " ),\n", + " colorrange = (0, 20.0)\n", + ")" + ], + "metadata": {}, + "execution_count": null + } + ], + "nbformat_minor": 3, + "metadata": { + "language_info": { + "file_extension": ".jl", + "mimetype": "application/julia", + "name": "julia", + "version": "1.9.3" + }, + "kernelspec": { + "name": "julia-1.9", + "display_name": "Julia 1.9.3", + "language": "julia" + } + }, + "nbformat": 4 +} diff --git a/dev/assets/notebooks/fei2_classical.ipynb b/dev/assets/notebooks/04_GSD_FeI2.ipynb similarity index 98% rename from dev/assets/notebooks/fei2_classical.ipynb rename to dev/assets/notebooks/04_GSD_FeI2.ipynb index 64457f7ed..5c880a688 100644 --- a/dev/assets/notebooks/fei2_classical.ipynb +++ b/dev/assets/notebooks/04_GSD_FeI2.ipynb @@ -3,7 +3,7 @@ { "cell_type": "markdown", "source": [ - "# FeI₂ at Finite Temperature" + "# 4. Generalized spin dynamics of FeI₂ at finite *T*" ], "metadata": {} }, @@ -19,10 +19,11 @@ { "cell_type": "markdown", "source": [ - "In our previous Case Study: FeI₂, we used linear spin wave theory\n", - "(LSWT) to calculate the dynamical structure factor. Here, we perform a similar\n", - "calculation using classical spin dynamics. Because we are interested in the\n", - "coupled dynamics of spin dipoles and quadrupoles, we employ a [classical\n", + "In the [previous FeI₂ tutorial](@ref \"1. Multi-flavor spin wave simulations of\n", + "FeI₂ (Showcase)\"), we used multi-flavor spin wave theory to calculate the\n", + "dynamical structure factor. Here, we perform a similar calculation using\n", + "classical spin dynamics at finite temperature. Because we are interested in\n", + "the coupled dynamics of spin dipoles and quadrupoles, we employ a [classical\n", "dynamics of SU(3) coherent states](https://arxiv.org/abs/2209.01265) that\n", "generalizes the Landau-Lifshitz equation.\n", "\n", diff --git a/dev/assets/notebooks/ising2d.ipynb b/dev/assets/notebooks/05_MC_Ising.ipynb similarity index 98% rename from dev/assets/notebooks/ising2d.ipynb rename to dev/assets/notebooks/05_MC_Ising.ipynb index 3d9a59ddd..de9851b78 100644 --- a/dev/assets/notebooks/ising2d.ipynb +++ b/dev/assets/notebooks/05_MC_Ising.ipynb @@ -3,7 +3,7 @@ { "cell_type": "markdown", "source": [ - "# Classical Ising model\n", + "# 5. Monte Carlo sampling of the Ising model\n", "\n", "This tutorial illustrates simulation of the classical 2D Ising model." ], diff --git a/dev/assets/notebooks/out_of_equilibrium.ipynb b/dev/assets/notebooks/06_CP2_Skyrmions.ipynb similarity index 98% rename from dev/assets/notebooks/out_of_equilibrium.ipynb rename to dev/assets/notebooks/06_CP2_Skyrmions.ipynb index 9574a45a8..8ce981ed1 100644 --- a/dev/assets/notebooks/out_of_equilibrium.ipynb +++ b/dev/assets/notebooks/06_CP2_Skyrmions.ipynb @@ -3,7 +3,7 @@ { "cell_type": "markdown", "source": [ - "# CP² Skyrmion Quench\n", + "# 6. Dynamical quench into CP² skyrmion liquid\n", "\n", "This example demonstrates Sunny's ability to simulate the out-of-equilibrium\n", "dynamics of generalized spin systems. We will implement the model Hamiltonian\n", @@ -221,7 +221,7 @@ "function `plot_triangular_plaquettes` is not part of the core Sunny package,\n", "but rather something you could define yourself. We are using the definition in\n", "`plotting2d.jl` from the Sunny [`examples/extra`\n", - "directory](https://github.com/SunnySuite/Sunny.jl/tree/main/examples/extra)." + "directory](https://github.com/SunnySuite/Sunny.jl/tree/main/examples/extra/Plotting)." ], "metadata": {} }, @@ -229,7 +229,7 @@ "outputs": [], "cell_type": "code", "source": [ - "include(pkgdir(Sunny, \"examples\", \"extra\", \"plotting2d.jl\"))\n", + "include(pkgdir(Sunny, \"examples\", \"extra\", \"Plotting\", \"plotting2d.jl\"))\n", "\n", "function sun_berry_curvature(z₁, z₂, z₃)\n", " z₁, z₂, z₃ = normalize.((z₁, z₂, z₃))\n", diff --git a/dev/assets/notebooks/08_Kagome_AFM.ipynb b/dev/assets/notebooks/SW08_Kagome_AFM.ipynb similarity index 98% rename from dev/assets/notebooks/08_Kagome_AFM.ipynb rename to dev/assets/notebooks/SW08_Kagome_AFM.ipynb index 94340939e..6da15531d 100644 --- a/dev/assets/notebooks/08_Kagome_AFM.ipynb +++ b/dev/assets/notebooks/SW08_Kagome_AFM.ipynb @@ -3,7 +3,7 @@ { "cell_type": "markdown", "source": [ - "# Tutorial 8 - Kagome Antiferromagnet\n", + "# SW8 - Kagome Antiferromagnet\n", "\n", "This is a Sunny port of [SpinW Tutorial\n", "8](https://spinw.org/tutorials/08tutorial), originally authored by Bjorn Fak\n", diff --git a/dev/assets/notebooks/15_Ba3NbFe3Si2O14.ipynb b/dev/assets/notebooks/SW15_Ba3NbFe3Si2O14.ipynb similarity index 99% rename from dev/assets/notebooks/15_Ba3NbFe3Si2O14.ipynb rename to dev/assets/notebooks/SW15_Ba3NbFe3Si2O14.ipynb index 52bf659f2..b84e400ae 100644 --- a/dev/assets/notebooks/15_Ba3NbFe3Si2O14.ipynb +++ b/dev/assets/notebooks/SW15_Ba3NbFe3Si2O14.ipynb @@ -3,7 +3,7 @@ { "cell_type": "markdown", "source": [ - "# Tutorial 15 - Ba₃NbFe₃Si₂O₁₄\n", + "# SW15 - Ba₃NbFe₃Si₂O₁₄\n", "\n", "This is a Sunny port of [SpinW Tutorial\n", "15](https://spinw.org/tutorials/15tutorial), originally authored by Sandor\n", diff --git a/dev/assets/scripts/fei2_tutorial.jl b/dev/assets/scripts/01_LSWT_SU3_FeI2.jl similarity index 100% rename from dev/assets/scripts/fei2_tutorial.jl rename to dev/assets/scripts/01_LSWT_SU3_FeI2.jl diff --git a/dev/assets/scripts/powder_averaging.jl b/dev/assets/scripts/02_LSWT_CoRh2O4.jl similarity index 93% rename from dev/assets/scripts/powder_averaging.jl rename to dev/assets/scripts/02_LSWT_CoRh2O4.jl index 5e18d9af5..ce57fcb0e 100644 --- a/dev/assets/scripts/powder_averaging.jl +++ b/dev/assets/scripts/02_LSWT_CoRh2O4.jl @@ -6,8 +6,7 @@ cryst = Crystal(latvecs, [[0,0,0]], 227, setting="1") view_crystal(cryst, 8.0) -latsize = (2, 2, 2) -seed = 0 +latsize = (1, 1, 1) S = 3/2 J = 7.5413*meV_per_K # (~ 0.65 meV) sys = System(cryst, latsize, [SpinInfo(1; S, g=2)], :dipole; seed=0) @@ -31,7 +30,7 @@ kernel = lorentzian(η) formfactors = [FormFactor("Co2")] formula = intensity_formula(swt, :perp; kernel, formfactors) -qpoints = [[0.0, 0.0, 0.0], [0.5, 0.0, 0.0], [0.5, 0.5, 0.0], [0.0, 0.0, 0.0]] +qpoints = [[0, 0, 0], [1/2, 0, 0], [1/2, 1/2, 0], [0, 0, 0]] path, xticks = reciprocal_space_path(cryst, qpoints, 50) energies = collect(0:0.01:6) is = intensities_broadened(swt, path, energies, formula) diff --git a/dev/assets/scripts/03_LLD_CoRh2O4.jl b/dev/assets/scripts/03_LLD_CoRh2O4.jl new file mode 100644 index 000000000..2a39df3ef --- /dev/null +++ b/dev/assets/scripts/03_LLD_CoRh2O4.jl @@ -0,0 +1,114 @@ +using Sunny, GLMakie, Statistics + +a = 8.5031 # (Å) +latvecs = lattice_vectors(a, a, a, 90, 90, 90) +cryst = Crystal(latvecs, [[0,0,0]], 227, setting="1") +latsize = (2, 2, 2) +S = 3/2 +J = 0.63 # (meV) +sys = System(cryst, latsize, [SpinInfo(1; S, g=2)], :dipole; seed=0) +set_exchange!(sys, J, Bond(1, 3, [0,0,0])) +randomize_spins!(sys) +minimize_energy!(sys) + +sys = resize_supercell(sys, (10, 10, 10)) +@assert energy_per_site(sys) ≈ -2J*S^2 + +Δt = 0.05/abs(J*S) # Time step +λ = 0.1 # Dimensionless damping time-scale +kT = 16 * meV_per_K # 16K, a temperature slightly below ordering +langevin = Langevin(Δt; λ, kT); + +energies = [energy_per_site(sys)] +for _ in 1:1000 + step!(sys, langevin) + push!(energies, energy_per_site(sys)) +end +plot(energies, color=:blue, figure=(resolution=(600,300),), axis=(xlabel="Time steps", ylabel="Energy (meV)")) + +S_ref = sys.dipoles[1,1,1,1] +plot_spins(sys; color=[s'*S_ref for s in sys.dipoles]) + +sc = instant_correlations(sys) +add_sample!(sc, sys) # Accumulate the newly sampled structure factor into `sf` + +for _ in 1:20 + for _ in 1:100 + step!(sys, langevin) + end + add_sample!(sc, sys) +end + +q1s = -10:0.1:10 +q2s = -10:0.1:10 +qs = [[q1, q2, 0.0] for q1 in q1s, q2 in q2s]; + +formfactors = [FormFactor("Co2")] +instant_formula = intensity_formula(sc, :perp; formfactors) +iq = instant_intensities_interpolated(sc, qs, instant_formula); + +heatmap(q1s, q2s, iq; + colorrange = (0, maximum(iq)/2), + axis = ( + xlabel="Momentum Transfer Qx (r.l.u)", xlabelsize=16, + ylabel="Momentum Transfer Qy (r.l.u)", ylabelsize=16, + aspect=true, + ) +) + +ωmax = 6.0 # Maximum energy to resolve (meV) +nω = 50 # Number of energies to resolve +sc = dynamical_correlations(sys; Δt, nω, ωmax, process_trajectory=:symmetrize) + +for _ in 1:5 + for _ in 1:100 + step!(sys, langevin) + end + add_sample!(sc, sys) +end + +points = [[3/4, 3/4, 0], + [ 0, 0, 0], + [ 0, 1/2, 1/2], + [1/2, 1, 0], + [ 0, 1, 0], + [1/4, 1, 1/4], + [ 0, 1, 0], + [ 0, -4, 0]] +density = 50 # (Å) +path, xticks = reciprocal_space_path(cryst, points, density); + +formula = intensity_formula(sc, :perp; formfactors, kT=langevin.kT) +η = 0.1 +iqw = intensities_interpolated(sc, path, formula) +iqwc = broaden_energy(sc, iqw, (ω, ω₀) -> lorentzian(ω-ω₀, η)); + +ωs = available_energies(sc) +heatmap(1:size(iqwc, 1), ωs, iqwc; + colorrange = (0, maximum(iqwc)/50), + axis = (; + xlabel="Momentum Transfer (r.l.u)", + ylabel="Energy Transfer (meV)", + xticks, + xticklabelrotation=π/5, + aspect = 1.4, + ) +) + +radii = 0:0.05:3.5 # (1/Å) +output = zeros(Float64, length(radii), length(ωs)) +for (i, radius) in enumerate(radii) + pts = reciprocal_space_shell(sc.crystal, radius, 100) + is = intensities_interpolated(sc, pts, formula) + is = broaden_energy(sc, is, (ω,ω₀)->lorentzian(ω-ω₀, η)) + output[i, :] = mean(is , dims=1)[1,:] +end + +heatmap(radii, ωs, output; + axis = ( + xlabel="|Q| (Å⁻¹)", + ylabel="Energy Transfer (meV)", + aspect = 1.4, + ), + colorrange = (0, 20.0) +) diff --git a/dev/assets/scripts/fei2_classical.jl b/dev/assets/scripts/04_GSD_FeI2.jl similarity index 100% rename from dev/assets/scripts/fei2_classical.jl rename to dev/assets/scripts/04_GSD_FeI2.jl diff --git a/dev/assets/scripts/ising2d.jl b/dev/assets/scripts/05_MC_Ising.jl similarity index 100% rename from dev/assets/scripts/ising2d.jl rename to dev/assets/scripts/05_MC_Ising.jl diff --git a/dev/assets/scripts/out_of_equilibrium.jl b/dev/assets/scripts/06_CP2_Skyrmions.jl similarity index 96% rename from dev/assets/scripts/out_of_equilibrium.jl rename to dev/assets/scripts/06_CP2_Skyrmions.jl index a20a0c078..b442e266c 100644 --- a/dev/assets/scripts/out_of_equilibrium.jl +++ b/dev/assets/scripts/06_CP2_Skyrmions.jl @@ -48,7 +48,7 @@ for i in eachindex(τs) push!(frames, copy(sys.coherents)) # Save a snapshot spin configuration end -include(pkgdir(Sunny, "examples", "extra", "plotting2d.jl")) +include(pkgdir(Sunny, "examples", "extra", "Plotting", "plotting2d.jl")) function sun_berry_curvature(z₁, z₂, z₃) z₁, z₂, z₃ = normalize.((z₁, z₂, z₃)) diff --git a/dev/assets/scripts/08_Kagome_AFM.jl b/dev/assets/scripts/SW08_Kagome_AFM.jl similarity index 100% rename from dev/assets/scripts/08_Kagome_AFM.jl rename to dev/assets/scripts/SW08_Kagome_AFM.jl diff --git a/dev/assets/scripts/15_Ba3NbFe3Si2O14.jl b/dev/assets/scripts/SW15_Ba3NbFe3Si2O14.jl similarity index 100% rename from dev/assets/scripts/15_Ba3NbFe3Si2O14.jl rename to dev/assets/scripts/SW15_Ba3NbFe3Si2O14.jl diff --git a/dev/examples/fei2_tutorial-1fdd91bd.png b/dev/examples/01_LSWT_SU3_FeI2-1fdd91bd.png similarity index 100% rename from dev/examples/fei2_tutorial-1fdd91bd.png rename to dev/examples/01_LSWT_SU3_FeI2-1fdd91bd.png diff --git a/dev/examples/fei2_tutorial-69abd398.png b/dev/examples/01_LSWT_SU3_FeI2-69abd398.png similarity index 100% rename from dev/examples/fei2_tutorial-69abd398.png rename to dev/examples/01_LSWT_SU3_FeI2-69abd398.png diff --git a/dev/examples/fei2_tutorial-8e8e8f85.png b/dev/examples/01_LSWT_SU3_FeI2-8e8e8f85.png similarity index 100% rename from dev/examples/fei2_tutorial-8e8e8f85.png rename to dev/examples/01_LSWT_SU3_FeI2-8e8e8f85.png diff --git a/dev/examples/fei2_tutorial-c72e43fa.png b/dev/examples/01_LSWT_SU3_FeI2-c72e43fa.png similarity index 100% rename from dev/examples/fei2_tutorial-c72e43fa.png rename to dev/examples/01_LSWT_SU3_FeI2-c72e43fa.png diff --git a/dev/examples/fei2_tutorial-d4e30e69.png b/dev/examples/01_LSWT_SU3_FeI2-d4e30e69.png similarity index 100% rename from dev/examples/fei2_tutorial-d4e30e69.png rename to dev/examples/01_LSWT_SU3_FeI2-d4e30e69.png diff --git a/dev/examples/01_LSWT_SU3_FeI2.html b/dev/examples/01_LSWT_SU3_FeI2.html new file mode 100644 index 000000000..8977eb4f0 --- /dev/null +++ b/dev/examples/01_LSWT_SU3_FeI2.html @@ -0,0 +1,159 @@ + +1. Multi-flavor spin wave simulations of FeI₂ (Showcase) · Sunny documentation
GitHub

Download this example as Jupyter notebook or Julia script.

1. Multi-flavor spin wave simulations of FeI₂ (Showcase)

FeI₂ is an effective spin-1 material with strong single-ion anisotropy. Quadrupolar fluctuations give rise to a single-ion bound state that cannot be described by a dipole-only model. This tutorial illustrates how to use the linear spin wave theory of SU(3) coherent states (i.e. 2-flavor bosons) to model the magnetic behavior in FeI₂. The original study was performed in Bai et al., Nature Physics 17, 467–472 (2021).

The Fe atoms are arranged in stacked triangular layers. The effective spin Hamiltonian takes the form,

\[\mathcal{H}=\sum_{(i,j)} 𝐒_i ⋅ J_{ij} 𝐒_j - D\sum_i \left(S_i^z\right)^2,\]

where the set of exchange matrices $J_{ij}$ between bonded sites $(i,j)$ includes competing ferromagnetic and antiferromagnetic interactions. This model also includes a strong easy axis anisotropy, $D > 0$.

We will formulate this Hamiltonian in Sunny and then calculate its dynamic structure factor.

Get Julia and Sunny

Sunny is implemented in Julia. This is a relatively new programming language that allows for interactive development (like Python or Matlab) while also providing high numerical efficiency (like C++ or Fortran). New Julia users may wish to take a look at our Getting Started with Julia guide. Sunny requires Julia 1.9 or later.

From the Julia prompt, load Sunny. For plotting, one can choose either GLMakie (a pop-up window) or WGLMakie (inline plots for a Jupyter notebook).

using Sunny, GLMakie

If these packages are not yet installed, Julia should offer to install them using its built-in package management system. If old versions are installed, you may need to update them to run this tutorial.

Crystals

A Crystal describes the crystallographic unit cell and will usually be loaded from a .cif file. Here, we instead build a crystal by listing all atoms and their types.

a = b = 4.05012  # Lattice constants for triangular lattice
+c = 6.75214      # Spacing in the z-direction
+
+latvecs = lattice_vectors(a, b, c, 90, 90, 120) # A 3x3 matrix of lattice vectors that
+                                                # define the conventional unit cell
+positions = [[0, 0, 0], [1/3, 2/3, 1/4], [2/3, 1/3, 3/4]]  # Positions of atoms in fractions
+                                                           # of lattice vectors
+types = ["Fe", "I", "I"]
+FeI2 = Crystal(latvecs, positions; types)
Crystal
+Spacegroup 'P -3 m 1' (164)
+Lattice params a=4.05, b=4.05, c=6.752, α=90°, β=90°, γ=120°
+Cell volume 95.92
+Type 'Fe', Wyckoff 1a (point group '-3m.'):
+   1. [0, 0, 0]
+Type 'I', Wyckoff 2d (point group '3m.'):
+   2. [1/3, 2/3, 1/4]
+   3. [2/3, 1/3, 3/4]
+

Observe that Sunny inferred the space group, 'P -3 m 1' (164) and labeled the atoms according to their point group symmetries.

Only the Fe atoms are magnetic, so we discard the I ions using subcrystal.

cryst = subcrystal(FeI2, "Fe")
Crystal
+Spacegroup 'P -3 m 1' (164)
+Lattice params a=4.05, b=4.05, c=6.752, α=90°, β=90°, γ=120°
+Cell volume 95.92
+Type 'Fe', Wyckoff 1a (point group '-3m.'):
+   1. [0, 0, 0]
+

Importantly, cryst retains the spacegroup symmetry of the full FeI₂ crystal. This information will be used, for example, to propagate exchange interactions between symmetry-equivalent bonds.

In a running Julia environment, the crystal can be viewed interactively using view_crystal.

view_crystal(cryst, 8.0)
Example block output

Symmetry analysis

The command print_symmetry_table provides a list of all the symmetry-allowed interactions up to a cutoff distance.

print_symmetry_table(cryst, 8.0)
Atom 1
+Type 'Fe', position [0, 0, 0], multiplicity 1
+Allowed g-tensor: [A 0 0
+                   0 A 0
+                   0 0 B]
+Allowed anisotropy in Stevens operators:
+    c₁*𝒪[2,0] +
+    c₂*𝒪[4,-3] + c₃*𝒪[4,0] +
+    c₄*𝒪[6,-3] + c₅*𝒪[6,0] + c₆*𝒪[6,6]
+
+Bond(1, 1, [1, 0, 0])
+Distance 4.05012, coordination 6
+Connects 'Fe' at [0, 0, 0] to 'Fe' at [1, 0, 0]
+Allowed exchange matrix:[A 0 0
+                         0 B D
+                         0 D C]
+
+Bond(1, 1, [0, 0, 1])
+Distance 6.75214, coordination 2
+Connects 'Fe' at [0, 0, 0] to 'Fe' at [0, 0, 1]
+Allowed exchange matrix:[A 0 0
+                         0 A 0
+                         0 0 B]
+
+Bond(1, 1, [1, 2, 0])
+Distance 7.0150136167509, coordination 6
+Connects 'Fe' at [0, 0, 0] to 'Fe' at [1, 2, 0]
+Allowed exchange matrix:[A 0 0
+                         0 B D
+                         0 D C]
+
+Bond(1, 1, [1, 0, 1])
+Distance 7.8736818956572, coordination 12
+Connects 'Fe' at [0, 0, 0] to 'Fe' at [1, 0, 1]
+Allowed exchange matrix:[A F E
+                         F B D
+                         E D C]

The allowed $g$-tensor is expressed as a 3×3 matrix in the free coefficients A, B, ... The allowed single-ion anisotropy is expressed as a linear combination of Stevens operators. The latter correspond to polynomials of the spin operators, as we will describe below.

The allowed exchange interactions are given as a 3×3 matrix for representative bonds. The notation Bond(i, j, n) indicates a bond between atom indices i and j, with cell offset n. In the general case, it will be necessary to associate atom indices with their positions in the unit cell; these can be viewed with display(cryst). Note that the order of the pair $(i, j)$ is significant if the exchange tensor contains antisymmetric Dzyaloshinskii–Moriya (DM) interactions.

In the case of FeI₂, Bond(1, 1, [1,0,0]) is one of the 6 nearest-neighbor Fe-Fe bonds on a triangular lattice layer, and Bond(1, 1, [0,0,1]) is an Fe-Fe bond between layers.

Building a spin System

In constructing a spin System, we must provide several additional details about the spins.

sys = System(cryst, (4, 4, 4), [SpinInfo(1, S=1, g=2)], :SUN, seed=2)
System [SU(3)]
+Lattice (4×4×4)×1
+Energy per site 0
+

This system includes $4×4×4$ unit cells, i.e. 64 Fe atoms, each with spin $S=1$ and a $g$-factor of 2. Quantum mechanically, spin $S=1$ involves a superposition of $2S+1=3$ distinct angular momentum states. In :SUN mode, this superposition will be modeled explicitly using the formalism of SU(3) coherent states, which captures both dipolar and quadrupolar fluctuations. For the more traditional dipole dynamics, use :dipole mode instead.

Next we will use set_exchange! to assign interaction to bonds. Sunny will automatically propagate each interaction to all symmetry-equivalent bonds in the unit cell. The FeI₂ interactions below follow Bai et al.

J1pm   = -0.236
+J1pmpm = -0.161
+J1zpm  = -0.261
+J2pm   = 0.026
+J3pm   = 0.166
+J′0pm  = 0.037
+J′1pm  = 0.013
+J′2apm = 0.068
+
+J1zz   = -0.236
+J2zz   = 0.113
+J3zz   = 0.211
+J′0zz  = -0.036
+J′1zz  = 0.051
+J′2azz = 0.073
+
+J1xx = J1pm + J1pmpm
+J1yy = J1pm - J1pmpm
+J1yz = J1zpm
+
+set_exchange!(sys, [J1xx   0.0    0.0;
+                    0.0    J1yy   J1yz;
+                    0.0    J1yz   J1zz], Bond(1,1,[1,0,0]))
+set_exchange!(sys, [J2pm   0.0    0.0;
+                    0.0    J2pm   0.0;
+                    0.0    0.0    J2zz], Bond(1,1,[1,2,0]))
+set_exchange!(sys, [J3pm   0.0    0.0;
+                    0.0    J3pm   0.0;
+                    0.0    0.0    J3zz], Bond(1,1,[2,0,0]))
+set_exchange!(sys, [J′0pm  0.0    0.0;
+                    0.0    J′0pm  0.0;
+                    0.0    0.0    J′0zz], Bond(1,1,[0,0,1]))
+set_exchange!(sys, [J′1pm  0.0    0.0;
+                    0.0    J′1pm  0.0;
+                    0.0    0.0    J′1zz], Bond(1,1,[1,0,1]))
+set_exchange!(sys, [J′2apm 0.0    0.0;
+                    0.0    J′2apm 0.0;
+                    0.0    0.0    J′2azz], Bond(1,1,[1,2,1]))

The function set_onsite_coupling! assigns a single-ion anisotropy. The argument can be constructed using spin_matrices or stevens_matrices. Here we use Julia's anonymous function syntax to assign an easy-axis anisotropy along the direction $\hat{z}$.

D = 2.165
+set_onsite_coupling!(sys, S -> -D*S[3]^2, 1)

Calculating structure factor intensities

In the remainder of this tutorial, we will examine Sunny's tools for calculating the dynamical structure factor using a multi-boson generalization of linear spin wave theory (LSWT). This theory describes non-interacting quasi-particle excitations that hybridize dipolar and quadrupolar modes.

Finding the ground state

Begin with a random configuration and use minimize_energy! to find a configuration of the SU(3) coherent states (i.e. spin dipoles and quadrupoles) that locally minimizes energy.

randomize_spins!(sys)
+minimize_energy!(sys)
49

A positive number above indicates that the procedure has converged to a local energy minimum. The configuration, however, may still have defects. This can be checked by visualizing the spins, colored according to their $z$-components.

plot_spins(sys; color=[s[3] for s in sys.dipoles])
Example block output

A different understanding of the magnetic ordering can be obtained by moving to Fourier space. The 'instant' structure factor $𝒮(𝐪)$ is an experimental observable. To investigate $𝒮(𝐪)$ as true 3D data, Sunny provides instant_correlations and related functions. Here, however, we will use print_wrapped_intensities, which gives average intensities for the individual Bravais sublattices (in effect, all wavevectors are wrapped to the first Brillouin zone).

print_wrapped_intensities(sys)
Dominant wavevectors for spin sublattices:
+
+    [-1/4, 1/4, 1/4]       37.33% weight
+    [1/4, -1/4, -1/4]      37.33%
+    [-1/4, 1/4, 0]          1.60%
+    [1/4, -1/4, 0]          1.60%
+    [-1/4, 1/4, 1/2]        1.60%
+    [1/4, -1/4, 1/2]        1.60%
+    [1/4, -1/4, 1/4]        1.59%
+    [-1/4, 1/4, -1/4]       1.59%
+    [0, -1/4, 1/4]          0.77%
+    [0, 1/4, -1/4]          0.77%
+    [1/4, 0, 1/4]           0.77%
+    ...                     ...

The result will likely be approximately consistent with the known zero-field energy-minimizing magnetic structure of FeI₂, which is single-$Q$ (two-up, two-down antiferromagnetic order). Mathematically, spontaneous symmetry breaking should select one of $±Q = [0, -1/4, 1/4]$, $[1/4, 0, 1/4]$, or $[-1/4,1/4,1/4]$, associated with the three-fold rotational symmetry of the crystal spacegroup. In nature, however, one will frequently encounter competing "domains" associated with the three possible orientations of the ground state.

If the desired ground state is already known, as with FeI₂, it could be entered by hand using set_dipole!. Alternatively, in the case of FeI₂, we could repeatedly employ the above randomization and minimization procedure until a defect-free configuration is found. Some systems will have more complicated ground states, which can be much more challenging to find. For this, Sunny provides experimental support for powerful simulated annealing via parallel tempering, but that is outside the scope of this tutorial.

Here, let's break the three-fold symmetry of FeI₂ by hand. Given one or more desired $Q$ modes, Sunny can suggest a magnetic supercell with appropriate periodicity. Let's arbitrarily select one of the three possible ordering wavevectors, $Q = [0, -1/4, 1/4]$. Sunny suggests a corresponding magnetic supercell in units of the crystal lattice vectors.

suggest_magnetic_supercell([[0, -1/4, 1/4]])
Suggested magnetic supercell in multiples of lattice vectors:
+
+    [1 0 0; 0 2 1; 0 -2 1]
+
+for wavevectors [[0, -1/4, 1/4]].

The system returned by reshape_supercell is smaller, and is sheared relative to the original system. This makes it much easier to find the global energy minimum.

sys_min = reshape_supercell(sys, [1 0 0; 0 2 1; 0 -2 1])
+randomize_spins!(sys_min)
+minimize_energy!(sys_min);

Plot the system again, now including "ghost" spins out to 12Å

plot_spins(sys_min; color=[s[3] for s in sys_min.dipoles], ghost_radius=12)
Example block output

Linear spin wave theory

Now that we have found the ground state for a magnetic supercell, we can immediately proceed to perform zero-temperature calculations using linear spin wave theory. We begin by instantiating a SpinWaveTheory type using the supercell.

swt = SpinWaveTheory(sys_min)
SpinWaveTheory [Dipole correlations]
+Atoms in magnetic supercell: 4
+

Select a sequence of wavevectors that will define a piecewise linear interpolation in reciprocal lattice units (RLU).

q_points = [[0,0,0], [1,0,0], [0,1,0], [1/2,0,0], [0,1,0], [0,0,0]];

The function reciprocal_space_path will linearly sample a path between the provided $q$-points with a given density. The xticks return value provides labels for use in plotting.

density = 50
+path, xticks = reciprocal_space_path(cryst, q_points, density);

The dispersion function defines the quasiparticle excitation energies $ω_i(𝐪)$ for each point $𝐪$ along the reciprocal space path.

disp = dispersion(swt, path);

In addition to the band energies $ω_i(𝐪)$, Sunny can calculate the inelastic neutron scattering intensity $I_i(𝐪)$ for each band $i$ according to an intensity_formula. We choose to apply a polarization correction $(1 - 𝐪⊗𝐪)$ by setting the mode argument to :perp. Selecting delta_function_kernel specifies that we want the energy and intensity of each band individually.

formula = intensity_formula(swt, :perp; kernel=delta_function_kernel)
Quantum Scattering Intensity Formula
+At any Q and for each band ωᵢ = εᵢ(Q), with S = S(Q,ωᵢ):
+
+  Intensity(Q,ω) = ∑ᵢ δ(ω-ωᵢ) ∑_ij (I - Q⊗Q){i,j} S{i,j}
+                              
+                              (i,j = Sx,Sy,Sz)
+
+BandStructure information (ωᵢ and intensity) reported for each band
+

The function intensities_bands uses linear spin wave theory to calculate both the dispersion and intensity data for the provided path.

disp, intensity = intensities_bands(swt, path, formula);

These can be plotted in GLMakie.

fig = Figure()
+ax = Axis(fig[1,1]; xlabel="Momentum (r.l.u.)", ylabel="Energy (meV)", xticks, xticklabelrotation=π/6)
+ylims!(ax, 0.0, 7.5)
+xlims!(ax, 1, size(disp, 1))
+colorrange = extrema(intensity)
+for i in axes(disp, 2)
+    lines!(ax, 1:length(disp[:,i]), disp[:,i]; color=intensity[:,i], colorrange)
+end
+fig
Example block output

To make comparisons with inelastic neutron scattering (INS) data, it is helpful to employ an empirical broadening kernel, e.g., a lorentzian.

γ = 0.15 # width in meV
+broadened_formula = intensity_formula(swt, :perp; kernel=lorentzian(γ))
Quantum Scattering Intensity Formula
+At any (Q,ω), with S = S(Q,ωᵢ):
+
+  Intensity(Q,ω) = ∑ᵢ Kernel(ω-ωᵢ) ∑_ij (I - Q⊗Q){i,j} S{i,j}
+                                   
+                                   (i,j = Sx,Sy,Sz)
+
+Intensity(ω) reported
+

The intensities_broadened function requires an energy range in addition to the $𝐪$-space path.

energies = collect(0:0.01:10)  # 0 < ω < 10 (meV).
+is1 = intensities_broadened(swt, path, energies, broadened_formula);

A real FeI₂ sample will exhibit competing magnetic domains associated with spontaneous symmetry breaking of the 6-fold rotational symmetry of the triangular lattice. Note that the wavevectors $𝐪$ and $-𝐪$ are equivalent in the structure factor, which leaves three distinct domain orientations, which are related by 120° rotations about the $ẑ$-axis. Rather than rotating the spin configuration directly, on can rotate the $𝐪$-space path. Below, we use rotation_in_rlu to average the intensities over all three possible orientations.

R = rotation_in_rlu(cryst, [0, 0, 1], 2π/3)
+is2 = intensities_broadened(swt, [R*q for q in path], energies, broadened_formula)
+is3 = intensities_broadened(swt, [R*R*q for q in path], energies, broadened_formula)
+is_averaged = (is1 + is2 + is3) / 3
+
+fig = Figure()
+ax = Axis(fig[1,1]; xlabel="Momentum (r.l.u.)", ylabel="Energy (meV)", xticks, xticklabelrotation=π/6)
+heatmap!(ax, 1:size(is_averaged, 1), energies, is_averaged)
+fig
Example block output

This result can be directly compared to experimental neutron scattering data from Bai et al.

(The publication figure accidentally used a non-standard coordinate system to label the wave vectors.)

To get this agreement, the use of SU(3) coherent states is essential. In other words, we needed a theory of multi-flavored bosons. The lower band has large quadrupolar character, and arises from the strong easy-axis anisotropy of FeI₂. By setting mode = :SUN, the calculation captures this coupled dipole-quadrupole dynamics.

An interesting exercise is to repeat the same study, but using mode = :dipole instead of :SUN. That alternative choice would constrain the coherent state dynamics to the space of dipoles only.

The full dynamical spin structure factor (DSSF) can be retrieved as a $3×3$ matrix with the dssf function, for a given path of $𝐪$-vectors.

disp, is = dssf(swt, path);

The first output disp is identical to that obtained from dispersion. The second output is contains a list of $3×3$ matrix of intensities. For example, is[q,n][2,3] yields the $(ŷ,ẑ)$ component of the structure factor intensity for nth mode at the qth wavevector in the path.

What's next?

The multi-boson linear spin wave theory, applied above, can be understood as the quantization of a certain generalization of the Landau-Lifshitz spin dynamics. Rather than dipoles, this dynamics takes places on the space of SU(N) coherent states.

The full SU(N) coherent state dynamics, with appropriate quantum correction factors, can be useful to model finite temperature scattering data. In particular, it captures certain anharmonic effects due to thermal fluctuations. See our generalized spin dynamics tutorial.

The classical dynamics is also a good starting point to study non-equilibrium phenomena. Empirical noise and damping terms can be used to model coupling to a thermal bath. This yields a Langevin dynamics of SU(N) coherent states. Our dynamical SU(N) quench tutorial illustrates how a temperature quench can give rise to novel liquid phase of CP² skyrmions.

diff --git a/dev/examples/02_LSWT_CoRh2O4-7eb4b415.png b/dev/examples/02_LSWT_CoRh2O4-7eb4b415.png new file mode 100644 index 0000000000000000000000000000000000000000..862569f3e68924b21fe36ccecac1d4e17fe0b0fb GIT binary patch literal 58907 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%0D5<goyr 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 A&6JYX61JKZWdIBMg0Ik}ffTAp= zh`-C5rqmJ*6FkA2L8i#F#|+LE_6HfG4R4Yf>1(BB!=ZPHA-4@*GR{Op z36>(d6$*S@{m5F8;v3*w!?HOIy*uD)qdIP2-sSNL2+*U)B?OhpYj}WLh8~$8;Wq)a z`I=bAfwdgK5Za-rfF$$K-2WZ&U<@&UYr4D2up17o;PQ zdn#_lZ+Wb{?R3Tb8{6^{+fo@t#esA2#!hvoPMz9gR{RVuF7|T6Bl3vL`h*J{$ zFxYw>t8gH+0s#R)vQXdkX6g9nA6Mrxx>q*))s_gM0NPAwsZ4%mQT4$2M_byw{*Qx< zn~}-Sj0N%)mr93>Yf&983OzE70^9Tw%dj>Cw9T+u`6m3cWvBJp< z15Dn-CvGOJb4-}?g=slgu6&w7GK_o?&m^Ewy~lsDNkwcz^WU1Z1gsJFc?rzCGlI(_ z}N3IE`uWS##ZhV8Yt21jaC zP5)F^dim0Qsi;xE`P@do;eaw%v8wuO@>tUH>fArh51eZ?{lHViOW~@50cz-tbQI|z zC+-fiT$i}59khuUBib$w{0Luv(}uE%l42 z-DT?~+Z?Rn_4y4p(5Z2O`61O7dWi}=mPjCm({N*m4k)57+aNHO6*KVPE6>wDI51-`}3o(5kcLZ0`AruN3MA!vZ!#f`{? zh0@7bBGcD0sb~!0n87~4kJAWO3?*9?l}&H~k!r+CY(C$C1Fowj>=P(Jk*uj(R?ok` zez2>CE`^98-Wo*awv((=5#yuVEqDXEI$>-hk-(tRCp z{F;UlM*!$0uTG~YAjTgAVa`3H%UeaX9sTU)C|a;Ga{Kbzr~#w>&sUm%{D^t7L41A9 zV558T;+T8+$hrBTFr80Z{SLuJsS3!9b-xZ$QMlT#JyNP`esxDRI%1v|PPRVp7&ufU>tCx7 znGu7<19g$gH(`YBuR;g7qXzJ*V>Y2hH_>yW--5QOXBN+2JWqRWb|x&-zxVFLM50I7 zT5bm@f*#raDPAU8Yex-|Rldw<*F zk@128*vu=V@=vGv>s2R=&OajiAoU>*n^T_=xF=pGix^+T5%fdxQ1GuRO1)%W1mL5*lIaBu5nVcREQ#F%a8)RQ(3xv`!iI zZT2%OeX-R*-LbDdxzN|=-1NgBl|^?gE!6}F?#QtKUVvknFNYd)C2Zhc;7|ATpYy2o zVR46V!&-12YVwxhbY{2W8m=38b*%m@-bxyq|Itv8k#kVO{&HZ~OK)0jde^S3o|yNk zSvd!3y=;ECz8ycpvUaIb@~PuCKsINZh&GfQ^qw_)apkQ7wM;CfsY#F835`(!=I+8n z=utWjOxjVII$M5P1a3bRP9GG9I>lTIc5>+-kQkZ+bsmqWN5E#}0`lZbkH6}W-@7QicvDk=j0zH3HmeUW zhd&;U+B*uu5*Q9Ym?8W_NiEzU_=hnW$RK3M@!sM8U;p#6<7KvyhCe#5v!dXCM>I|l JpAybq`+uAM!@d9j literal 0 HcmV?d00001 diff --git a/dev/examples/02_LSWT_CoRh2O4-822521c1.png b/dev/examples/02_LSWT_CoRh2O4-822521c1.png new file mode 100644 index 0000000000000000000000000000000000000000..1928a2877ffd0ec77e37049ee7e900866b4cc290 GIT binary patch literal 96676 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ⅇ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�X-SZPrwrJuMC`o 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 Z7Jg^^>P}0 literal 0 HcmV?d00001 diff --git a/dev/examples/02_LSWT_CoRh2O4.html b/dev/examples/02_LSWT_CoRh2O4.html new file mode 100644 index 000000000..1330740eb --- /dev/null +++ b/dev/examples/02_LSWT_CoRh2O4.html @@ -0,0 +1,60 @@ + +2. Spin wave simulations of CoRh₂O₄ · Sunny documentation
GitHub

Download this example as Jupyter notebook or Julia script.

2. Spin wave simulations of CoRh₂O₄

This tutorial illustrates the conventional spin wave theory of dipoles. We consider a simple model of the diamond-cubic crystal CoRh₂O₄, with parameters extracted from Ge et al., Phys. Rev. B 96, 064413.

using Sunny, GLMakie

Construct a diamond Crystal in the conventional (non-primitive) cubic unit cell. Sunny will populate all eight symmetry-equivalent sites when given the international spacegroup number 227 ("Fd-3m") and the appropriate setting. For this spacegroup, there are two conventional translations of the unit cell, and it is necessary to disambiguate through the setting keyword argument. (On your own: what happens if setting is omitted?)

a = 8.5031 # (Å)
+latvecs = lattice_vectors(a, a, a, 90, 90, 90)
+cryst = Crystal(latvecs, [[0,0,0]], 227, setting="1")
Crystal
+Spacegroup 'F d -3 m' (227)
+Lattice params a=8.503, b=8.503, c=8.503, α=90°, β=90°, γ=90°
+Cell volume 614.8
+Wyckoff 8a (point group '-43m'):
+   1. [0, 0, 0]
+   2. [1/2, 1/2, 0]
+   3. [1/4, 1/4, 1/4]
+   4. [3/4, 3/4, 1/4]
+   5. [1/2, 0, 1/2]
+   6. [0, 1/2, 1/2]
+   7. [3/4, 1/4, 3/4]
+   8. [1/4, 3/4, 3/4]
+

In a running Julia environment, the crystal can be viewed interactively using view_crystal.

view_crystal(cryst, 8.0)
Example block output

Construct a System with quantum spin $S=3/2$ constrained to the space of dipoles. Including an antiferromagnetic nearest neighbor interaction J will favor Néel order. To optimize this magnetic structure, it is sufficient to employ a magnetic lattice consisting of a single crystal unit cell, latsize=(1,1,1). Passing an explicit random number seed will ensure repeatable results.

latsize = (1, 1, 1)
+S = 3/2
+J = 7.5413*meV_per_K # (~ 0.65 meV)
+sys = System(cryst, latsize, [SpinInfo(1; S, g=2)], :dipole; seed=0)
+set_exchange!(sys, J, Bond(1, 3, [0,0,0]))

In the ground state, each spin is exactly anti-aligned with its 4 nearest-neighbors. Because every bond contributes an energy of $-JS^2$, the energy per site is $-2JS^2$. In this calculation, a factor of 1/2 avoids double-counting the bonds. Due to lack of frustration, direct energy minimization is successful in finding the ground state.

randomize_spins!(sys)
+minimize_energy!(sys)
+
+@assert energy_per_site(sys) ≈ -2J*S^2

Plotting the spins confirms the expected Néel order. Note that the overall, global rotation of dipoles is arbitrary.

s0 = sys.dipoles[1,1,1,1]
+plot_spins(sys; color=[s'*s0 for s in sys.dipoles])
Example block output

For numerical efficiency, it will be helpful to work with the smallest possible magnetic supercell. Here, it is the primitive unit cell, which contains just two sites. The variable shape below defines the primitive lattice vectors cryst.prim_latvecs in units of the conventional lattice vectors. This result is used as input to reshape_supercell. The energy per site remains the same, which verifies that the magnetic supercell is valid.

shape = cryst.latvecs \ cryst.prim_latvecs
+sys_prim = reshape_supercell(sys, shape)
+@assert energy_per_site(sys_prim) ≈ -2J*S^2

Now estimate $𝒮(𝐪,ω)$ with SpinWaveTheory and an intensity_formula. The mode :perp contracts with a dipole factor to return the unpolarized intensity. The formula also employs lorentzian broadening. The isotropic FormFactor for Cobalt(2+) dampens intensities at large $𝐪$.

swt = SpinWaveTheory(sys_prim)
+η = 0.4 # (meV)
+kernel = lorentzian(η)
+formfactors = [FormFactor("Co2")]
+formula = intensity_formula(swt, :perp; kernel, formfactors)
Quantum Scattering Intensity Formula
+At any (Q,ω), with S = S(Q,ωᵢ):
+
+  Intensity(Q,ω) = ∑ᵢ Kernel(ω-ωᵢ) ∑_ij (I - Q⊗Q){i,j} S{i,j}
+                                   
+                                   (i,j = Sx,Sy,Sz)
+
+Intensity(ω) reported
+

For the "single crystal" result, we may use reciprocal_space_path to construct a path that connects high-symmetry points in reciprocal space. The intensities_broadened function collects intensities along this path for the given set of energy values.

qpoints = [[0, 0, 0], [1/2, 0, 0], [1/2, 1/2, 0], [0, 0, 0]]
+path, xticks = reciprocal_space_path(cryst, qpoints, 50)
+energies = collect(0:0.01:6)
+is = intensities_broadened(swt, path, energies, formula)
+
+fig = Figure()
+ax = Axis(fig[1,1]; aspect=1.4, ylabel="ω (meV)", xlabel="𝐪 (r.l.u.)",
+          xticks, xticklabelrotation=π/10)
+heatmap!(ax, 1:size(is, 1), energies, is, colormap=:gnuplot2)
+fig
Example block output

A powder measurement effectively involves an average over all possible crystal orientations. We use the function reciprocal_space_shell to sample n wavevectors on a sphere of a given radius (inverse angstroms), and then calculate the spherically-averaged intensity.

radii = 0.01:0.02:3 # (1/Å)
+output = zeros(Float64, length(radii), length(energies))
+for (i, radius) in enumerate(radii)
+    n = 300
+    qs = reciprocal_space_shell(cryst, radius, n)
+    is = intensities_broadened(swt, qs, energies, formula)
+    output[i, :] = sum(is, dims=1) / size(is, 1)
+end
+
+fig = Figure()
+ax = Axis(fig[1,1]; xlabel="Q (Å⁻¹)", ylabel="ω (meV)")
+heatmap!(ax, radii, energies, output, colormap=:gnuplot2)
+fig
Example block output

This result can be compared to experimental neutron scattering data from Fig. 5 of Ge et al.

diff --git a/dev/examples/03_LLD_CoRh2O4-143cf2d7.png b/dev/examples/03_LLD_CoRh2O4-143cf2d7.png new file mode 100644 index 0000000000000000000000000000000000000000..bc70c07d6e552fea26b8f989ff19fbd6d552d2a6 GIT binary patch literal 306060 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 TuF6M}c{(=rjA6>+*&&)- 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%0D-~C2W%JP<9y8LkN14=uv2M~AcV2;g!PDQg zS*Q>yH_LoePlO;UQGq#TDgS-UlV^)W4W_(y|3;H@OkXeSF6==+%JDE|A=+k zFDKUROXCE0tN-V=?p^Z|P(UmxEd|G!j)B1#+SuisJL>k1v~ziR4E&vS99fSAQ%<1mIR3h`Te`{+JOK!wp-|jM^<9n#R@whwnf`rmcLeSW5Osh@orUGk z!U8@boQf&{QX?ZH6B85vXDoX$3PcrCJalK@YAD)tGvkg?!4-o6J&!> z#xuRI{NdjM+6+)Bph_@o&=g)3oNM^Xht==zhXaEHD^_B^`D>w*y(;b|6f1n|!7Q@} z6-LjX`;c2}aScLU>aLc<(7VU+PE=EOdpw+5RTVclR6HLmT&!vqwtIJX7d#Wd>2Is$ za)^i!2otTPBEB*420B0SX-8t#qJ#f)UFu3-P^g!H7XSF(&B-N}X|&Vkk&Bt_i45V< zLKC0kzZh4fh&v(+UVqc-TMjuZ zTia~loFk>c8^Vnw%KD_qs3u&Dj~7;#L54jSWIt`&MT5$`yWjH)NPd*#T2c$>MWBIf(s`iTruBik6l(H6uf|cnV|^fZ-UJ8oYZ4 zIKqN!0s|5}Inu!E<0X12^x-8_wxt5P11*=YfAE$UYOMHWDa8=d-u3B=XEo{P`-7MH(}^< z5b=gq0kQ|DGrjsr%D$g>sX}Xh0QQ^KZ?6U!E2eWzE8L$fJTQ=mEN#z)xifQ*30ko` zFBGop06ALL1zf#jf zW{X#W9^5LW__Fu8ieka7!qEpSY4ra7{^XB1Nh2lC7fUB=2w4*cA){wXdIxd?c*Rqs z8jRUTHU#5E@bX%}kM!ggW$Inh@H-&NABM$C+C(iTL;(OADOvR5ZI+mkC=1f0uMUe+0 z`lE*T8$(T@YE$)KWc=rk9Re&qwFD!NcbFwrH)qsaihub!5;51mdOfdw%KEI>QUMRU zWYd&lwZD)4-*-*3LM8ufNQWvw3P>l)T{mUJtb-k=2cIGg)OqmR4BghRELZq1v?3;F zobFvEqKUp*^PzPfp04!*q_#Kso%mIiu?z@NGW36 z;^Az7ZfDb>#fhiG=gC7D6+B0O|0bNCXoUAymeP^-8MCF1diZ~{3)z6IR!mHgRoyfK z*@|uD{A7vj z(z>)l%|X)lN({JHodbXVpcY<&|3?t+W(1vCvwxxe&@4Gp2QSabPtx{}eY|9@GnX1o zrk53Y04uZF>+U=$DJeJ@K~>d6N=kI9t%*qUABUOo_j0iVF}4!%sg zwSK}}mID3VyLTX)p{>m`$k4@|&WT5d1CNo3iHP8kNcHqBzCej{!@Jk-U1i&qjWwMH z)`>ARtXK^pek^_aEM#!C4ABarmpq!=szDlt*n=pjmj|KUH^wckt!X&8kS{6~O}-)e z846pKe;sU{#~xmX$2p|9)hA_`oMSjSZcOK?>{Q*8XF_X9>0{lrH{- z-PzPp(DZag$VK_KpHZuqkM3O5GAK)b7z(V3iA14-lQ(18`?@8f&rp3TYs*JOe5=yb z)ga2G9H%_XezEg9phxbpt&DK6H+gz?*7vmMwZFdCYUeC6f-+TlY(aa`5Eu!5ENi&m zoG?xh2gmQf%-q13!3|*$oRIg!^?7ycTjv+f0Ng{#zW%ENLGU|tAtxTQs->`R&!LH{ z_h2b;)6&!&YRM5k@AgWowf;4@vl^TEbeK;uJQ*x zW|tnNrG3VlTUA`cdwkUKL!fAEaonk8(1Jqe78f5mrQSQ~YLiA7D|GMN-1rbvOXG>8L zO$70oJ`lBP)~Z1>{r|OB+W?A;m**L>=Io8Y^`-t#in}r5Oec?(ba!{>OwY{70BRIj z;O>=2+4MdTTIGv-*QytesNzF+?&8P!JImWQ2d#(`*`yB|Z88f5t#G?eIv;2X&GEdT z78Vwso^85SK)0)^sv7?tC*F`9Nu;??qe9z{DE)Zc>b@UM)SO{}=!GU+l=k!Q#93}` zZiQ{*I~Vy3@FxGeMa=i*$ePx=lFR&h(GK5`hJXVL`YD=1L;&63Bqt@obpQGDCoX81 zxMk-iT!9u-ZeF4%(>~q2`X6po$xPSc!g-X%mKK3+fQ5Jm3(ygSQC)!7dv2};%w)wB zLGw~KR}LBvyvP!j(jPx|J@8m&nTaBUq7i1<83GdneE;3a728~Yq<#$5S5ur;5s&~` z!l{&J4J#?$1)sq`<3h!uk`+-U&PY34sK0uaVg8A@MFHKq@@+jrVvTFwzR&))ycipo z^DBbtr?m9gHXA~IiM2Z}y+?$&5l?1TT3Q%h?a9H77#uGdvPj@g^{+EhsIDLvXBsFx zhM*&yCgyq6$BcE+67`=1xq@cxtrXaIo!UlC>xPVB`~bV}(&nu8)&QqlRL-Qj8+O1i zHgv6$$81bb>1ktVsO=NqTsz{#1|6*!ulQn1nvWqm#)_g%vw zWX3_|+@!?T$3Xf1A+!$!%UZMG7}jVol`VVkOo?^+b65rPOt|j}VdQ33EyNmr}i%^@UB1V$QD(c5{IyOENBvB@)a47hF(CHm zJfTzNKZ@M)Tdp zjJ)P6V(^z}T%ER39+{Irn0dnrfmJIB3zN%8XUKTKH$)`CX;__O0 zGsq6-TUk=F*ZmC^e9B?Tm%t@nI@7fs=Z1|)pW2J`$k)wGD`)&&mpYWR-4IFLHE7QO z(T^xAE4#RBpFLn?U?9N7HNX+a=%1KS1fm1?g6;wqK1H^kG zOi8=LN_C&xBvj@28@w6`bC->|=BJ}sXE@}Fr!3NtAvpRa{VZ6B1yg&H6b^f5Z@<#v zAySyKRgL~%7C;44Db#Ohy%$F~R|X$t(PgnU7B)*}cYl^P6K#Zzyf8VAj%_O0(f z1S|c%ATWiJA#QMcI9oW2j&^)4jV z;?8Bg>-yG*((BIo#uPfFL{?P)H=V5>*QmI{5WK<%SMM2R&Oe^UyLb6*Q3a00%(}Om zh1lI35itwq2-3XbO^?@C3K6EChEJ*LQkCwX0Wuc)ExmLcRV+4j+m7qyaqT;GhUT7& zyO`nvz)NdQhLJ|5YZiZ^^7y@}ZFaYhLDKy+z(o{3%}eN#W8&j$W@g4kFvIbVw1DP! znC;lY<$`z3qKX{{Um{L6uWRL;wXRK@+0fFm-aDd5g_Z>}yd={-L+^lGpA>Q0rK^c& z-VcOW!Xeui2#z)6Ll+3kLL0F|7n)Bzu&{*1@N-jhqGcfK!K z;d0`2<&qv9&*|z}jYejU3`8m)o#_g|sRw)(;STwQc6oo^#l2aJTsfor?61?1{66qu zhKNnube=G`I9*P@O~y6%0it}YB;PbK1M0tK6jDEZmS2ee6I;^ZmlFr$j=Na9a#x6~ zkZQyJ-ZVOgcK9MWd3n=1sN9rW)-1A zSqT$zb9osug%kV=A{D1pq5`shzW1JVOlw1T-h}E*CdetP3R9=ZQh`Z=y7~@4*-*Yu zTNWnNGK8aAe*OB@+}sb$1>|wSh=3T(UWV%@CzVpDhQS~_3dF1eb2o|vSu8+U8yh*L z;*#`qr#eaX4b~(FV?}v%6%})7e(&y@16Kp^se_+nq>)rnRVC=K8PadK$NTp>0JC_M znc;5wwQW@4dLn1ll5tTQh`={`UTj^PYkbdvLW)(KcczpYNtF+ZRnV6%D=aUc9({kl z?N}=zM)D^KTW=)%_r-i7P1GcU$)^ zy9&b~Z_k`nEjY=S3}A>SX3uCkzb?9e%Sx42N;SFn`EJ*S^*79zS=|_{muc$7z1Q>S zKQxe6&3*dlVzCA(k`$95s;1dO*-~)d=BSC14I=dJTSHT3^WkM7KYwQWi^FbT9Ugm- z|ES1&YHB+@F0AlTF!TSp!PKxIfhk=w;NTUT^&VDR-$Vzix2O{W9w23IpU0^W=cQwN z=P8U>n5k1k8ne6Rii#5%+>YQFn9)dX{r#i;GE`SO=4CNB!xe}Td4@?XAnyxD2QMQ0 zIX5>Cf95g0)VxR9@L&wiMcx8C>+KW`rd2tigm{((aY1aK6pS7TVyiJ5=`gy;{JuHi z01m`0>$RT~kE%-E_?9#IM(&Lsul5&F9v&VzVU5PaxX~T~YiTmGF22ecH6;)9x}G!3?fm<@E?UdEHUF#fi`~ubwe!Q+)AN4s_xIRI_6%38Z|8h3 zD)(`5vn&PAc@v$_-_2Ha;({c3@2g6BYSX9OE^LScc2Z7q?~u7tf)Q-MZ`EX5+c~I; z-t;j?!7--IjqH`~p$3wqfJcFE4!zeDWi*yLwDNH|6f|mWt|!OV?_KH#WK9naRSyS> zKN0zQDHg0VLVmq6%eYSx(g}52FRvS;qo?o1f%T)H?a`-+4bmd=+W$R;_qF{vGCIJ$ zi?6ceO`-_h+5SYn(cUFr)y;i46W!UrSBG}U1KR59U;^9AS`KdDx+zvCOLa~;p>b{Nh)QaZ;aYzj2RkA|68t<@*q9SP+*}%V@i|N0Azes;a zIYEBsBB>ZoAq7MSpDsZH6a`t?A9Si1jF|<>-(E8}ufjyMcnL6vkrmbhK?-Q3y=xi_ zNn;dZ+=FQp@%;^+hhpi1O*eBbHdS}n3d?Hy%!W`b(7p~Dflk&JDaoW_3WS)-eh_0# zl3ofuggfS%ta>-LgjrOo+8tmI^CA%%1}jE-pR3#(mk!c zW?nkf3%>ZR@ZJ^!@#5F^+>R$x8ND;zE$mjDYsdT?(8C^I(Zo@Ax_QxC_Y zuXV0E8iImsfN^kk_D0)^e!P}}3TqXY{MhNlp;hO&ZqkTY9|j@fkBM&CoR+bulfFJl zjQlh%&+Gn{5+|NAoQ|L%WYRMYhD>RGXO6So_X=$3qaC6?uOxgiN^G>B|4zbGb>o^n zNFOg56UenJjNl|Nr^Lo9WkSS(5nl^mQbJ1ZYn5w}$PrZC3 zB)A*>JfV&H<~tq3oK+Fx6Kq-9#s1W+t`XJ1jUg%iXuw1uD(GQ z(b;a@PDZt(wNQo@J~pkE_Ik6r=VAQ66P40ee!WKfCmAB$D8zE@r^9kqU3Iku^)?$Q zJgLMk38_Ag=6YhkR+fu0cc1OMZ||+2$@=W`Xh7^W;6_-3UqnC3Nm@eWEBhh}Y#X zhGNK^1H|*LPv!}HRY18ZWiWuNAo+QCD^?Ll9a5Vv_|JFa$mG8{Bm94QuJW(2`HAHu z=|V8I`LF#{aOBAZg$c-C0#RBZ{{>izz-W{iJiT6KP8Nx zjbT<-pDcM>&6Mv+@fA!Nxt{iHBz634tLO)jEJxQG3`K87T$jD}zj(wsL#K_^Fbmu% z>5Cd?BIQYX4k0YuQt;t#gYWHF`0-w)a93i0rN!IR}UvGn${#QJ_0 zQFuWl9J0n`11N$24^8W&vsvVH@rHkDbnY)+Z-u@m6uisPeK7|;y#3M?j+wv_Pfy>tpheFDPTke= zI%SeSzY?;AodB=x&EJ3ich9kzMvhEXHXNzcZ(Lx3J%nL+`C<9Hpbm#1UL-JDVML1C zXuG+`7@=WD1wx~o@fS@Tu@=vEMjddA#4WPQ3ZXPZR3`i9{R`icnZ_taC8Bf?a%b(#^`UgvKh?c0CJT1F~L z#`hgJhQ~WJC;ra1y}$^8-9?C~Um}&{dSS#NDYNFfMyRhLGHT;y+z3U5%5!8k)44a% zWMau!gBW53D$1&%mZeKfUl`3A=iZR+?{J7EoyJFd;T0h<1CNpV6Z-2xD@sbrJ*U?8 zb}t8|*_f)jv(G7`E<*2AFj22M8 zVe44=^d<#0AFYPLBqh}8KJ@Cq*M1MgCiSvFVt!A2TK0-YoVnZ!GUeZv81#bewJ+XC z{FYVoH)oTj2Fd&QQU>393whu_*Np^`Cnl*6+Xym>#28n_j4@kJeL{v?{=;49YD$XI zapx(i_y(w9{@18Vn=!wY%WZ{LK0iNudoS@OV$`J2Rjbt)?&TSF4clPD39I#)&3v7} zBnkYH5Wug{mXKh#@BXfTdVpPC=N-7Cb^kH#g1UUE-sfARL~O#e6@VJ>=s3lUqX4vj zNvX$g+TvZOR%=cf#L#|2pvQ|M5^~w;J6L_G4ev12Q}C^lahdy(PwxWMNQ4jZ!@(W` zbD))8KWo;llHfVM^TtQn_SYEnFDlu~;DV1PUcB5PeBIeme*JeNnRiqi;4!6^APA&* z%BCsZ1iEbP{uB@?kZi<3Z4oxft%@9s-oc3*(Q!Y}Q$$wQGy9L zofKIQx}VCQIg9)K|I_1tuAl$fwJvW-4Ko$Of#Aqia(jA4?J9*baCZQus~Ds46JE!KBs<{Z`K zpEX6}-rDLL3tfXPI&-5SO`}XyXJ3&?oOhhlMuAN3U4jhLpLe~_DY_$cAH#LSzL&~1 z=FstqzfLe#usLhD3Qa0XsI0-$!}N4ao5#&UE-cyeD@845h9Bwau3>eWu|2I%*^8q#54TW_2!w!FX8q{li9I+)p?UunhzW4y4Mx7m z9UaQ+IORfBr@jLB6G#{Nb{Z%QOYRQgGi`8z)V8RIh`tSbsW=dR-L|z6Ezjtb zrK+S)&v3u=Kujn*kiW)-b^*&eb^VWcL_B=XoF|+c3g*;&v2lZnoh-=|;p5rfn*eAO z&h58M-kQATJRi8{7Yje^5^IuR-$GJ7m+t(XQyn_gPsQzSO0NY%RBhI-Cq(F5nRG6a_=1Xx>o7ph}7$eUB4@k@EZVnRP(LXanUq z&O|1ue0f1~io+XB+WFgbqGk;%%AGq;76p?R1wFE`Ol{5@dCcqb$BGm8$|;I|w#N*a z)Za-st=;tz&}ZQO-dn!t_?%lev`(naLjQRe3$Xl z2t5oY!Z37eC41^&`tOC(MSNI%czm2&~dAuP+_Xu>Pue@|_*@m`PD z)Ri}Gd>$PFILJtRzG4|)wXF#=Sg!7SeQ=G~C%;Ynpr3!K!=&dHu;ffng^w8W(&DLb zSmd?2L14JWZ_?>!Rgz3u(RA1I$Cq8mZn0bYnFYJ1qFJ93I`r+EzduafTzj!z-W;0wg#~&<5ugZGkHqHcj+jP>&uNMjideNv-cPZ{NQx3#gR6RDjmz2~zk~o3+7MxRmzR5NL9V#r zt>X@_CymYf8{Kr@xiI`F>XjlHT1?nkt15?ogmA*zjh3J9M4x000i~w=!@VDAd{8gL zAw{Kal*fcaEvX&8V-6L!v- zt^7)eq~7A=>I(AZ4RbX+0=i*oece>oK#Ca~{->3?(+$CFQIm{ru=X)oM;Q?Da#H~3 z0w&ecG+@|)c65x<4LR^7g-EzLoQK}*MveLYz__28N_%Lkj zs^j!|Fz#vpld&omMNTPRMoa$fK5%mdU0`QF>yvQc+VXNmDB4XG$*sl#)WzsZtAd%Y z@t{jG4z-^PsfJSP;5A?B*PC+pUe`-9%6((fK`laRrLx{IL8-{L~x3Tt44k?NKtg zW|xCgfcs;*Aug#>q>b^zEq~#(^dzzg$3ezi;K_aR*jM>NMvTzE2^Y$*Cig(^u`yp# z;_6(_^(Sl8gaX;~!Tdm<@!nIpA-7=F_1X%ZJ@y?wr#=n>aPnUE=y?-EVn)xwnV^so zh||06xzklt`)-Jh7EYX*Z1fg$lYp0VnI+NMJFk4!Yk1t z%iFnZof)t^6GKKRHW)39cfVB7YDng+JS9uTdEygfxLd zN=y~AR0!Ts4aFFyf!@j<L3v#UBjF;$otCAhZUOuL{wVQE6Cm5 z9c59=LtC4}29}|t5?(Qul{!ZCkgD1iS z+d`-U*^2nvB@H}m3e^gfX!9o!nMkD`=jFn&XVecGM*8kz&4}Gd^I#BB5g}o@GL;#E zd+9MIcj9RwCM{Kxc!OuzoPUQyMGJ-BL%vLFlPw=zA%um8gGW(7K=8Krpi*SrM=H*a zugE?(bOf*#f2C4JboYd%{sY%4*OA5x5N^Y8u=GH2zP9ATj zaqGFV*W$h8iyxJHzsXQYEjQ=$jBhXAp*$+R^pia-a_W5w&cnBs0l}+lx0ekl3so;Z zE8y|;?H&qJt3aV=hcAsFva~njc>$1(r{A-RM*m7HAGw|hX>3Qh_f0u%d(|D zlC}M&kQ=>0Hk0U=B#^B2gTeTP`id)Z-;Mw8+$dty{L!@}1zEVhfV*q`@Ad`@Q!30oj?V`rMUlGHpY{+x3i=gP z$Dd$JA}XA_uWfYyendZ6iLq=fB~(?>@4|t~tVxYKQ=xC;yQ5KYZ@jP9$(0noZqEmQ zMup5QGNkhLK;m3;xL#6G9>ev|k&(3wM*q5VV?~+BrJ$)HRwqU&pRDbRrB00lLR_$kL-cXs)vUhc#+YI?ss*z1UQ*#bItYJl?Q4DG%!p< z(v!KzOvGW^?tFqrdyjc8U=ts37l36k0`}{Dz(Zt_7K~ci<}q}fjN8G`#TcA#NnK8-W=F@;%zwc8ROX z&_|3cHf5!HvzYgp?IY_34XM_GrWKu)g1Z7(P`mNToPE%~r=Y!K{j4f@+2+q;G);}G z_jm~vHz5To@^?hT^TfgMfsNWre_zv}p=zlQ&;sc;j)2hSkT{Q!qL(E8OB2T%`gETl zQW^;4^91o?HRgZ7$%vy0V>!s=<)0{lgG2pM%Dz%*SW5vIK2CEQUYE?kP`JNLIT!H((Z(0>n4IjkOkK7H%l4=-e(9@)S{{e^L^xIH!x5va4Wo75SNN#Nv8|1ok}AW{ndQc7$P6F<^W*%H@55o!PPFUsWBnfXjh=8^ z!QcjfgT=kei|f?YFoI289<47XqUF^q7(>pz6&3%Qa{#&mPB;leJF%Xrb^o`c9)F$q zPtpVvxEyFq-bZ6Oi~j9{8SQ2_-K4Gh>3eyJo%wY#WQmV|y9pMhV>TNu=#MzH+@WfU z3F|-Es-jxVl-N(>S zMAO~?^BSz3})RDq_pH_2I-2-8r$hxn0I4<5)IulQ~ystdHc^(L+Fue86k zA|m_FyRgILGNS^T1}uzGD(UU0s=RuH8$4CE&6+?dqKSpj+zy=9z%Sk$??U;Mb-Mp> zc&po6@Wt00ICBP&#(Y8Fcmqw+^E^QmwYXjBZhrr#H4i)yVCT?Tsy0W4$QO;a?s-q^ zA4f->#tftT7I0#DYi=9!t$TzYiuk6mZoKt;xeZzAwSG%X(K<&rD~f>Em`o-?ow~&j zW{nSK%ACU^o^`?fxE4g`;b**SKyDY|s%b?#$Dg27CAGphJl3Mte;K!5|dcF~aU`KIfo1FpB7 ziu_bURNxiK<=7T#=;E4%h8UX;Hm~i9i_Qr4Qr*qtpVd{lPvx~53>*|<$ak-?WzMBS zqvK2O>Rm50Yz+&`HZQBYIz0I@$JV*z|Fhy|o^&3cHJrRWL$bFoH8*Otz^3_DLIz(} zuwOOkEz;XS_dB6tRNwSjH8zUV$71I&$wRpMoNWFsj*M8*UPms541; z?)Na37A_+s2Z-We!;CQMsV#=;bNNQ3WMdu)sc#1U=PQOH18Wq|w2cJoN`Kr=+hKSm z8I%EPtn{8w6jINFdM<=>3+%qoZ!77I3zTAj{w1doW)U zy&;^2{{(?hK;3ujE+!f~>6%hsr}XImv20L6@KT-G^5~v#q7LNMLG49_G;&{PBmwKo z0q57to2Kp(>#PMiIp6}mGFIk=>1iyC%x-d`gNa^+^OO7{I-~1MDEWljo0g||^gfB7 zYqrBr#`MyoBaa5S{zgWC+^^egw`Psa(`tc}sH&wfAQM4?_|ufWqmy~^O%JUt%Ow1& zZ(-?vUti$VUPf9PSgH44wT+Ab3h%L1E?s5isl~;N;jQ2Y=Kp~d%B7{>P~lf551d(5 z-`zhsFzDud5;Y5lWkZCFD@qW8U*6p?hNVU^_&l-Ij~+`ey!U2F$Hb^tFF& zt6;)WPv?obe@`FJp^N)f07sHT!^XcpyKq?|xnFqQGwq^dfX0Doi5c^md0z;DE|26* zJ5I>vN%peSu!Dk6E(sz}m}XuTANl3m7)ginm|lX-Tiffd6opX|)DruT+D(@;B1X7j zIjiXD3+FZ$W#CAwPsKXUK3*cd38CgGw$i7-K{jPe1sY92kA8!u84NG~m}ycjWJLNr zWNveE_Y#EU2s&;fi=&Dhe6ArUT*n%+8Lw>qNE72yRye!}cqie6 zSGjCP(>{XsNahOfIDUB(*~dXy)0P%t@6yokEOaF~k$=(o`nHW%s}`=uY|kmJPGcmG z2Au0nr?AprG{G}PLQV3E&ZforYn9~Gt+Q3-q15ak)&vqGUyLc{+)8k8qT#f^@wRQ5 z`|RSSbq;^uNX}!hKl}|rJf+m{FfqF@bfq3#R=V`0v>%BJ+nN97WMZ28^9?kL3L9wA zL(Sg>Q!8YkOa8`IxTmc7@dI(3=L3-F(P`=F4~~v>>KnJ~e6ud)?(UM@hpP^7Z$4^F zH7RmLlDVp>D7J)Mm(=R;+NUJ0$EUOe+1RIXF0j?J~*E1o0UF<5wT#eu69ja zL9E1!ii=4D2?oEGsUVwV7q0&nt!Ktb<6fSDg|MLQf7uDz-`|g_S-$YdmZin{mZ&pk z$(-l72#-B5SkIHmFpMF_UD2p@nS3-PTgy>5`W}t((xflDRmVN+=XI#Qm=q~9ZDLkC zJlNBFGGRS~i9E(~8LM<8MKsBngn(AVl1uMLvTI ztnW<^;Z_REi9b?$;+=dJbj^*f&`_7w6^w0c=OAZ2~8$T1OH6 zzpkv3M@B{f{P^wLs}+5r3a4g6R0Rw`_ zk+=h7U7mlqxD;d18EU(k&knEt!RqKGDIi^Y+h$q|PBc9~yhHA_X40Km;NeW=MEddy z0vGsGu5@=jT3&hBb85%ewYlLR+s;|TxB(&xQ?BgcHX%N9n?ZkP!7Ml4L3)VF{<*x* zTyhYAaUe2^C!w})X~IW zxP>wLK?Q(|pgv9Dzkwc1$^KcbNql;n9I?D&gx8_= zA&njjEMZO_#tiQ-N_EZbA*4z#skRfNz;eOyZ)i4#eI6;33f#3Wa7WWU8dH%&)sE+5*0;y1Q>q=(oX{h8ss&BGazWg4Xokw z@#&mB&}kD1*x>4A0f>SV8f)XKllveZ!CK zz^W=q;nL;sW$as*nF3n=Qv5H1h?G@4Zv^yxMF zl%I@$Pxm$c4)upr4KD=9YU5uv*hc!=#kXGa#TihEtP9~QSV`!rW4+aA9jcQ z0_m|PbLJenbvc_Yut%AlqMtkD6cc_=UqodQtH2|ZBf|YGOaAL&-j+ubBAksfny{r# zTg$_`uYUa?ej2*h@{U~xJA0|75O_<+-VpOY(a51gLb<{D z2)*cVtp2vNc=wDPf0@foE<^*m+-@YQo=@+Wr`25mxeF(313l#lM1)a1eL)b>P*k)B zOW+$D8^vU>P~k#Jx&AAx{r)Sgjc|fLa&U;Y&Ursq+j!jPfPJ$Sm2Qn!H zyR3C0d%uw)-hSe48Ps)EC-F;>n{W3zn7{lGMn+7OrrVVB{O#)jgE)V)Xq-t74Dx4H z)ua9WutBhXro37pr>H&@j$yDV>L!p7Ww52O4*bmYN*z|+Ym3rRKP72Rl0m{C*R;lG zlilvQ3jwm+1axg@=a1tTW$IN)6c$IV!=9czmmWHFiAdjj!6!}+055+Ns!nppKYG|& z|NcQk2l3M?F;nOx31k(BlckoWidQRJ%AI(u&?66=m=$E6uP4#4-iOw@(0qv4GC|N=u=)+^2)ul!ug~3z8Uer0CQ{zFjplI+1I^!bLj1^Q-$xWYRrXR^dE=A1Y?wNW zIJA{F;gY=;9rj0iu4z;xJ7(rEu*6uIipTU|N$7+b+^cp&#PfrW2Tgy*6k!Hqu||-@ zM8iFEhNbRAeq^rT;>*d;(YH&&QMM1tQw>#8fj5w=xxRLZ+OXzKr;s7OAf(K0R98^} zYDlmF(%ZM(QGmDs;mSpOTBte9B~f6j9izxp%=q)|e8r^3!DxQaFLvyKZ0&qkcch-a zTM*8nsx6V7@08abk>ZX|um>7R&Mg@@!Ey=;g7%l;7@x_3 zfGp%!OIEc((^Vu=_Mb@mmuCgKOptEj@Ps;cFrP!;Zsa$D_o!yXKZ$Y0IJCVEp! zd3<`dJ*XJkN_u*}+aq9<1X4dh-TgTi71ABM^JmXVV3hlF)2mP4>l_yMd(wGtmg?8< z%>R-|h2=@s{_ydBq=9tn4hcb`iTE{DRQlGtaz{LZ(E{DNrmI)Kv*#(?ZC$JuIdQ%W zm_&2GbHvP8(G zyzl$}bP@5l9~T8VV!5y5>K3Nxn2p(%&>oze0Eql}bF(0;(4OEmU0Sk*qWDRd5^eUiBEWO1i5g5Ll)8CcNS*G>>yl3g-@c##a(D(<) zsHg^^`oCa?<$>nediG^aPw+gU?O5}Q;{RP;Pegw=ShGosZw7W9irj9eISWV2ATKe> zpi8G6!~X@g!nCr~CRF^|ey@HgAyk|kOn0ElDs}p-L4HPr8yO^VUhAWo5{S|dlT)s= z4pDhD@k4Nskl;L69*MX=!PY?(Py05RmTvU-$1>-}TH3-mn&ny5>C2eeC_&TUl$Wnj$XvWTABz zb1F5b{`IoJBh zNYGG(pu%SJT_!*QhG5sO9{+bEtZ`eS9~mip0f`8ce1VjyPxQRnu3rBw^Qo)5_#KqW zpQ@|#w_Azv58PMDK})TaQ4Z~qKr(vgg>S`D51Bx6OF{`PO!W9|N%{R+&4%WZKWk*6 zI5Pn}=zBRY4~v)C^0wY|(>^0#92_!;H7l|5MtA5n`QU(N6t&{luyF1yPICQzt2Z_h zz_SuY0{(w~%>MvQin7p9X|J31e4$0`dIO?H5q0=Iwov{KCT-KWp}Oe+9Og0_{GRa_ zy3ciC1i`@$Mg*J=8|^!T@nWE^AR|pczH?bx{`#s^XJg1rSI~+fg)nxGWR2F?+`Q?1 z1bC5}8XDvpil|ElD^nm*RAAA<>A$y+gvzR_u%wR+e(?pgCMGYjI-43#)@tGQd>kEC zV#mTBugl5%?rT0d2{`{H2sEqI{}T(-Ah5z|TG$H`9~wv))b72bR`Ds;$33qp!?SQ; zHnCMxPe&HZ)5nJ|8+rYuV?6$Iz_aSz_GJBpg&@(_>4KO5M7^Yz>DqpH4kxtH$w?rP zaGAEyOnSU|c@e2cE^O6;95xiS%^w{e+i%=s$c&3Z7X<(qsFj(>c(za!5+HO)qP^jx zqcQW6y>LiaB4D7m?c$2<9V#k}lJCXSZ|73#mNx2*1WWc*d)>YT6O=AZe3|R8`R5oY zaG~(H@Pi50>yK3mWGAngj_Y{QBT9=wWFPv8LmQ)Ho zJbat4?6Fwi+XBV0xWvXw@kfd*Su=1Y63qyEe|Yli_ni~Gk@!~ah@zo{foKL-S0_5^vD%qaD?2V5adWEyf;ey4YA z`I?P;ii5{_t3YL&ILL`7LmP;M=m?+hMvxX^k;0xvSf4RE!PPh^XAY>Wi5x!)^`5;L z?2v*39cs}Y`x(Z)K5|;1o3Lh>YT-*b>2L0nwkt7HOCyUoMPPwxmx4zxlyKG5@IZ=9 zV^rv&=G4ml9E_=Ez*7puIv`dC8jc8giE`yp1(qTrL9=y-^y~o8t4}_ntL6Bh{)@I7 zf*eugTh;N&$wf#|v0*Werz!B$;2TQ2Wp?}Fz0Z)#A(nK zG>6454@^K5NO$A|gEXvGLDM?~ktMxWAd3GTtuG%O<(kc>+3KFe+5KAiJlNS6{yMh+ zE4K#i;{u6jq+rD$lsE9N16z(mb-q9=*!DJpY%0`|yJ>{=qURks#HJF<}YP4PemOvqMO2QopHqFU^2mM?>+1SwU(61@fLp?jvQ>#XBTIl?K zcCsF?f(U(w)HwBkHKNbSzcx2Q+@Oe?Ro!u;oj3Uo1hk6QEJ{&ffrO#>m)^6Z$G09f zukaLxv3H>lQkmsOW9SVFE9+|l(|NQ`-$L>&QMMj%5YrN>zs<|werkH*PK;2&O{wwv z_N&gzc)v}+PjKAhR;#&eD#XTMLVYN zMg#tNAJy{Z7c^uG6joD!K|G9~q;?`8qG$-4fr=?+YG2iq>@Oyt{I=p{%27GKHnJu7 z?aR>=vt~moKqTPCOZd~^STlow>26OF(AL|VmjpxSzbhIDR9^0``)^1`TKy}ZvoS_LbIqcT#6XrB5RU-~Z(Nj&@jW@}%Xtk07KLU)AG8@oC0vq0 zp~rvq(va;_bc3Z?E;c*~u;(sm)^Tx(CUjwjv%}WuUTW|i@6t2}XVnJ&K5Mq|N89iI zJX%^1tqWY7@ci81;8OoKn4)5?58N9urnMAT4s|GlyX%Y z$*Qbpt0b^;+7g&t-hkL;^_*4@0hOfvA!r`P@s*iygZy6@_$)(?HBs7>_0vw_gY%*E zWVfk$EpaTNfuRFL4ExV@G|}OO9w@M&;AFl>5XeR7k04#Vf7aW)eVHkTI>IwpOWTQ4Fc4YkBTRuZQ6X4f__Z zwrO?05*!EvIC)<=(14G5!NRyb?C!nPN52}CLwLElX``q{>jvXUE2^s2`7Zi7E~`0g z#y}v66jL5znESpnPcQ`t1dyjBoNy6F7YxqVq%79U%{LD)ayFo&&iweX6*5}8h{?l{ z;Z4QugRv8wDnbNZBMl(N`v#N*xxTs*Mgs0SYHC0PO5Z|4UE@@kj2e)*c+E|YT-{V!sc z5J2pDiV^n5eOQ^R=d!&&BHz%M*(U9x-9oUpwDfkS*!WRt3_L*X@Ls0NJx!cHe0Nv* zKNB)$#*5!d-VD`tqSfo2a`h=8MN5x6=X^@K%$2}=L+HqY+8x+!VUn?i-sQcuuTlMp z))DA91vT3IwMnXBVV3Z^fLd#1hwf1BvbJDX#=TbF99M~v>fROL-2Z>(G|>aECS|M@S; zls--#LD6!AW;6Z%4CT~Ut(UQyW5ifH2?7!p5fM?qmVquxB#9XKrWbtw(f#~srPxSQ zEfpQHclF&%yHRKQ?!2iePe7CJ**9up5lhuC-wb`7CTy4rkVVj^HY2FMIi1ps!2$J1GFnk7mU4O~CLzjIj=p)fw~aoU6@l8FGdf(MP= z74jLZ`y5KIrtc^#;Khcxn*f^Me6rj{jCzJPiB2 z1f3S7zBe-%?g;Z_MPEyUt=_Vh|YbA?6K~gg}mWs9q&_vmZ6zndPO$A!nG1VKuh=?EE)(?qo>r+ zti>?UIa=b0yWi+N+S3{UGs^tW3&3)JIVofiZdB@s2`V=QD`kfwsY)#Gx_Y6!-0UT8 z+wUlv{Zflm(i4zknKNPqpxN`5>`Al|#nLF@BwuUSR1}hm^lJi+pM22Nh-=?(sO*m* zloDi)ptR%}G#c5t5u!&<^1Y|Vp$-2Mi}+#uH{|2qxj??=b>5>s(_&?;%yuqEMbF11 zXy@HQ@5`SEG-s5|k7zUb8|@86$<7f;K$Qruir5WY_6Mpup#)l;ilo%B`}hC(uPNkJ z)T3kPnW3X4%5+ugN4Jl_=qr(Ep6gYlbmwjR;M0o7-_=BSsU7#(nNDQU#zDwH;f$ax z2;A*(W~8+T4(X+UB>^!vh?S|SxSE>Mgow;Ip>ohm;1==oO1)GC|}- z^H^hw8eS{IkCupn2~s=5chqZj(vC1M8_E2#kL+84|g3XQyUkFixgCLx6Ooh!bVQ#ivM_g}DD^i%(hTljcC4jyK6MrYk?1f6oNR(CqDDo0T{w~+j2@433YU0huJ zfD~+`IsYrlLg;aQw99{|r|W6SaM6lA6X0q6w-%y}awaJ)FIOmiyD1885H?7usR;!I z|7YnS0LJZC%q>TP!E@l=dda`JyiCY`H#wf&&uz=iUzFmi^+(o*3>zo*xJRe}G*a$b z^q99hFb^$eY9Lmh_ll#V2YpKvFUaIcQ`==@S4wxVIVRfl`%9%@^GL1Y;ZQNd#+*F- z*A>W;d&2y0LMBgiHWJQ1*JwAQ0QRTf&IRI1PU;ebBFR)N2r85|4zgbw=RSNAkm&E< zjFtp|lWuN}v{8UX3@B+}muD!iG?QB#&sZ=8hjDTrpVzHa#QD#l1rF6ggDJqjqP&_; zZnkn=1XbSy_I!1fd#Tg*#{mX|JVCYE-6*h3Xysm_Ou?g32a+RVd}a=tYBp;32GKkuR|C zEKiklb!!|atc)b2=`vs3>W1DVa1vZ`wtd9TROU{Rb!n}+h*L-ZP3vy{%|KlZ_g8k2 z?{ujSyHNiW1>Oi99Cn;B66LPtvUz=EfhL!WNAoiWQhrYaMU3l4vl{fEbPyg_BJ1Yn zDmUln(}V=P2*B{Rt* z^04k%YK1xm4`1s6D#aHHN~__A;sevY^MFnnb47k6%#KZVU%Rb5qW1~#vuivhnRs-R z6a{Aay504mEUB@lC2+}I&2msei@;MGep6?0RsZW zPjT9Y{({K1&3)qnNcq4NDTa4X+bj3k{c0&H;jQ7|AK@>e`XVop0{#MxM4&*U^xm!C z+!!KYHMJgKm#a(C`Qz{%Y9l_-@c9-5oVq5pOWobwfGprh^6r%eEc`!<vnx38^85^(6K0{6j# z++jsss}GBn#(YxYx`a_dTlb`=Ufwh(PB2*#RKQiYN@nZn&lVtH>D=6V{Hhp)5!BWoRVS@49COrgiB$kv8S#%t!G?c_abp3JcQBMOhrch{#J;! zfecbyQ($Kp3%XMb&{Y4UNSmfmiV|J*@q2W)lS~CEAz?nPwO`3afN^Z>&d z=>ba~)2b`R1`ufC8Om2_-*Qz_%ncXjNK!JM?*-A>vmrfO=wntx^Y`_bG@ z%jj5?vh!jcxa97dr2Yo{W$QgBgeAgoeNIyZ9NN!Vs%Ns?*;k@Ddi7pVon8rynSWD6 zZgYp{BgrT?K+X80<34{*yE8dBqNdLI8Q_eFkJNYKnvn3`moe&$X%Z{6O(%IX|QB1#uEH!mK$x9KvP>@xHSCqS~qkrm`$II@U4tS=o5 z{P)%o($c2cNm1)K%Y!Wj5&trc8%ixbj&N{oaPj|n_VuV4A*2p`n!B`fKc7PF@-n&G z4yA?F2(*m0`}O;+zIPn{xoo@Vl{I3(3TQWca`dnE#LnN+Js0Mq){zmZhP&_~QkoY=?UX7EL%aM< zfZ{FMA*(05;u^PQ72ss&=SwX*s#8<8!scDeUSV8bITYE4rrqwu;POve7}pFIUa^pB z$)4%S&p683%bXwz?8c8(bJH&U(qFLSe)t&B;wD3>$_c9Nmy`xCGk~Tkg?q-=-*XR{ zoUl)rrN4wYp8g!)<%^8cDiRv9i&HoY;&&oTH1PrWx#!=ZoOJdL~_#^0j_ZDp#mJN@bHak6(j zc4H95*_t)THaq#~gu<2?OArP05QrzJ;KIRmdk>N=KeVLyYK=U%ez&~eq+WIOW2qL! z`(9oS0{v7=*?l3bAN~2XfQYB&Q_sXuHYBoH*Dx2L6S!eF3I|GUk&(uI2l|U<%b11` zNTDS@dN_jr*V+(k(nNGXOjY{e%Y8kmOyS<2Ijt{Hor(9`-{Kx88aPy^og) zc$!)OqF;+g^+{AEGe6at=tf$N8RY)+6X`PUJ8~=HqKAnB`04?(S6f1V4~hPD?G^pK zu^e7EnN+hMzm;5K8Q1gz3q#lUC^Ub6Mw3zI2sZ)&$`C-p(yxi{H*S!`*_}z076+U_OjzX{#_KnI^V;5*m1j_w{di}5tQ*JJT5RWf;PDJ+kk>`YzblVca~|c zX>lBr$aPI{EJ`qL;zmXgVL06w+U(J+Ps^hq*}_QkMfK?u|K6hR;+#g$Rv65)xz`DR zlC-zCFV|ZDQdxu5s{|yS^SBG(QK{1JI=5)1N+88z#HW5_D37YZ`fORjfsh)^7+}$9 z@>%-%Pp0JQ*5&I6l~AZ6Y_Z(qj%{6A#MoT6wXQDO8Z$WTew}+^Ld(z4NS4;2i&S z%$afR;CJck@Yub=t1KK&ld=K1F`?AXQ6mU~WLQ{m^)~ue2maoLel1JX?HQg~3v3Zo z;4q}5ggRxNf{v0B_d=5eKIH*|1l+=H^6I9^7s}06QeixronlH<8)};)dccV2VSm)V zb288VK_;p1vb}dp8iKt#V}aj~f@QeFEKC1%&^75|NFSE;HBR5LFs*1vm_iYFAx*Eo zpVu3=S3hooKinn$?bl_SIq$HHo$2ee^C`J%pAHEf+HBOD<)5dnB%X!0KUul#xeN6u zbE$Yp9U#H?3Q;eO3@do6QaM^c#(z?;&Bj)NmUm+B^nQ?wu>yirkVyfQh{cw4bO^9> z&ev?c^BFis4Bq+5f$l}f5~jxQU?-4=uRizFq$qX18l&X?L{T?8rmAI&$}D(w1=4ATfXj%`Z2Z(%1{(mCUe5K{ zH>sfvmWcQdNd`l#@^q{oHwpm*l6mp#Mp=TbI*l>KV;lqEnpE7zaZyhOP8lWX2T;(v*Cs&i2vEE zAfJi?fVl4v5lJux&(6*|=8GMCy};VCNyDD3884On0gKkn<+SxK>W12kP77$)pY<$B zWiNxI6G}C;<})FI323k}=1P0X&a8c}BnXfQ7DX~4!T9p*9{|X27ny?u%BVolsnuR# zXF-q5t&DtbE|$Hal_6)?5| z<=BsW3L|w?vM7O3UsJ3^O%9^03BCqgl4+3TD9|@E2GF6Sy3W*@j7yOUM^Stlp!m95 zZ0b9d&<%$Onl-dmw^zBmD_Z`}wTrX3)^e6(=$^&YDG3H*7@zP*G0o>cn=9i=^ot>* zuzbJ~gGWCivQ{~Fg)Ea^VVy@57*il|r@*=F#pQ9+U0YzteS91%hJ#VW1nGFs*!zf- zo=>Z~P`Fy#RED-;OZ!?<@tCt}Btn$d71ad`HL=CT6ZzsA{cDdc6BWvsn1;v4@qm0K zWY;sXh;YjK$V@9voT^84t#V!^0+g1BG=8xss8xG7%GJ3s<4MhBu21e=UiYBPY|O;S zsE%7)?}vsDju4LsMWO_>BN27e#^x%E@QM?}-U88)>B(js z`W}LlrOM%&k=5g0S$dxN|h7=d(lJnnj@U0$}LX znMTqvJ&#DeV;-1pXf^MYP1q*b!OVSRB~zHt<6xtD1omz2eP1x|c<)>}Pa8(<+njdX zVyD->K}Ru~ZC<~8saSl^nMiShCGdeI_!|}#a`0VGrgvcm(B&3YFvWg+?TrUioa8JS6~jR$%dSq$$kTsHftcTd zu*;ybDhv+UuJIN$X`>a=4`W_-rPsJ?VzXM~XWjJ!O&4y?5+zQy^C$PMmS^O8e*MI6L6LY+H|G0eW+Pvr6=|Q#hl+z~Y>RchvPb zr(=gR*`2SHHo!OR1-o9XaiiHG6c-LJ9Kp8=5^Vs=9c0GJ$FEb^gk*}9Tk6^K%eJKZ zqMaruxtv5_uQ)FlK>j$PFQ8)sP)2xj!3_-YGRm^aS)&d33sc;@t5T@b}fFj5JoycNUjl3RZ%f%UVQ`F zpU8QnU7AfpI;4wMaF{y;3LGXZ$*;yvq9yl<(ZaJI?i~c0KjoxKqsZ1V8`Jnd?kWUt zQNRwW7^95Lv}CAp9>vE6qElJW-ZFkbqT=H6cztQ7Eou!qqy18>$ zeQ#iwD~*f7Ak>ldSUt~NS?Y!yR+l$au#8ny#o-_hQpNr3;`&= z?>SO{b)nt17?(rcbNvSl#^h3Lf}X{JPXDI|z9I#3)IbQ#OWmb&91b*fbX}^D1GH{t z4L@}iiIJC08}QKv13~$4BU(YR5;h}?Qb_mVbo6^_Gp4`;2-6h%b44t9oCG7;h8v?C zY1A*Wj1Mbq)E3%B^ifF%#+e_$5)^RZcSG?T{-)}?v6K2fqf>upU#8A&CFS2ejL$ty ze>b7(^SfIKlh3mFgOB@DLhh*5p6$xW-%(leB`)=;1d2(qG^y!>xD*WEu5zxuA)&J`F*k|4dzKop$K z+5*5y1z_tyQ-jY-{VztPn*6lMZc&+}WROi_z9GjI)26a($K*#&-PrNff1pPk76=e< zKPI(l;F|i)8e(Kdt&%R&Bw<2V-|23xxVggNSUu}dO9bDR+bWbZM?IrDlXxvB7yDh6 zX8^0JhhCcgjgfXJH97%cHmR%}GiBATy7By*|KNr_j%DO|{?vv4CD{n1`WlP3kbLo4 zS<}1esvjxw^R_`^s1yZ%ifpYIS*u z2>aka$t z^|sDp8uR9ZEAn|$jd&9upvcS>-;M%IOHXg@;6ScX|2+I7%E>N>0b*L=c2GeipL3AR zfJ#ngD{uMlWYbP4reX|Jk8Ra5{JqcW>%}#pXoVE+TMAq=LTqJLEES2Kp(KKeO~6bB zF9N`00hopa6;^1%;*p>EW*Q}8YqJ#IMzgh1hTK+Bf@%BT=tpu3IwD>7emsr;o@5XR zDL;3||A*)K%Z5H(@_1wVslJbVJ}rhRPR*Bh_SIHTyTNK`FuHQf5kkV?E{?x*!{AR9 zaIwOxAvr@FEX4rb3dLdp#a044PH?z)JUCGs(~r>BRt>1)Es_@mpP~*vj?% zQ;@7aD3CsS@?}de&Q0-aQF%fCP{t?fP@s6m)V?a5J0>nbkk^Bw%*7;m*!4NSdgZbw ze;}-$2VF{8Tukh3ClqkXRPIgXi=BIB@8gnUwJpSK*J63yX8y|Bs|z`sYTCJ6(1^kR zF>LA#q*B46F)X186cN%8R#sNPUH>{7#RGg5gblAi0+YrV{s(QU3uL*m`c)BNvM2k* zk%F$6?(MNiQ(+xVBB|0@Wq$9R%%sgvNP>dWv3K?5gH^h8iEB(Im1RUi`F9X#tUE;J z-)v9Z{XmV&I5lO)rwVtj_=K%lWJAXim6?gpkDP1zZM>5ww_M-EsmS7I8#I(Q+<29! zlX-ma&V>G&)DLudx9k*pUFJ3myDLx7g9yrmDo~n_DlXUYdI-Kq;4PC zzswotaf3KEJB-OxQ3f8E7F>J zw0bn&zgKGkDklsK$YDt&gNcx3w^}x$SW%?jhVw}rboekNz-t-4 zv!uzLdSzyc{1)ggtvJzCZY*HVkO>~8fLKhHyq=xSoM3RKOo0+=3OSH|*~*Edy>I!$ z0Hyog%fI{aFy}hLuvg1~npf`@z4{Dik99oH`)#=QZ z0Pa{UVcG!-M`s_v*8*N&!o$Ut`V#IAWOd>(;x+nrRFZpIV)y#5+2BQhgbD=4dVfE8 zdM`O=`MD@{jNU7P0x8vuE_m1X_KFmPy^0a#Y{1*+`OhCy>Q-GK`bYtSiHoQj@@s1B z-#k7G<}pF2g`>XUA0sc>aacO*A!w&~{f%-ESNfN7gRL1HgxZTnEMHEoW5k_O9OEuM zLtvQl`9qTQ;Eb*Y*wAdg(QD^fpwkGLs_LK>)0PC`Wx&n1yj&Do$m5h=KYJ!4@Mt}m zAJ1gGq^4-$_k_8s8HMzU$_1A#`AWGLLCd$DOHbrivp0xc;v& z`b`O*^N+qs3Wa=-3;m4Cs}XE9+ZphmzUA|dE)&b_8`gN4XM%bVIPMd*9n<;^b0m^l zN}Q`eF9Td@zN#?1ulXlg#rsL8O)1Qmx~jM-+jO@b0pC zZBv@k`nIz$Qg!=J%MM!aSevmHEiP+@oPdA;t^|NmJ@IPCH{l;aLl_x^S?qie3`}Tnbe~-a|bCb$kPX{f>U0y4d(|@mOfj>ADU$)pwUQ{oZ zh0HMA%ZMoy1T-J$!l?I+y4@ZKJs8r@6v&ELbzvGoE7 zhnxC${QT5aBQ1rAZV0_^0$Df@^T_RqGbF0Uov7gw#i^9k)IKtd7%-kpeK&2~rzrhM z{X9^P_N)bHFh}*WHB)Q0Cu{kfQzWv=s=O(wtV!VaJs&Q2H?z&~oavbfBRy5s5YmjY zVRuXN9*E?tx_eG@ruQ*}!yl9BfL1b=`lR-4>HV%sF_0r%d;m`IkX{vUs-HF&kA&>Z?rO(hTmTWGYHry*N$ie?S1L5X_RhIAQoK{$HIB?%sp@fP((yUMFH>b z+*thXMv7xaj0#16G#e-!Y5|Occ|CP9UHP_9Ku0tUT_`wpmkWa=UBKpCjN!cmqdqMo zV;maNo^SQ9mL==P%;+c{2|?Gtih6pap=W2^U#ZfA=!Hq&rK)WDra`fS(z;Xdpax}fjofF=SeUOg7n`(9P@t% z@kGOQWD*=$1Y9I&ee+r2*``;l@rDEr>o*@b(u(>6Lj>?+sP5s8L2I#*g#WxldAZ6n zm`qpOxzU6rfzphC8bW=4oAdKaQa`STH!u}3mXl;Q;((^|>t9;H-aaeq@nkA-*wj;h z%95FYh?rPPYA2Wi?KAJ6%5Ep$-d`VI5}3&1A0I@CxoU2`JAf%W;O_475q}a{pE`;P zmIN;XIKOiD{RGLw&tiub7b$;@NRQ0Ttu)#I-B|?TKwk~J{HE9u&~;=>#W|!L!2k2K zvm{K2#q)WxgDC%afKm!d!##GErQ!I6K-74huOJl4TTfEjT3IF$%DPJMF17npqGOLZ`zwD-vSPwzvSvnG%Tm84~?B&71E zr`RM~OKEgGbYt|kYYe*H=nhyg%ExixgkId$t4u!g79!b)Y?yLpS!PnwQI$@$BHIt} z2=53rN!*1tD941)TXN**Q`FA6)SJ>(Kq&*MVuWa+Yl2q(g9HNMV1S}GyOnW2*)IQr z3xa>+T1$do)MAsyU;8W}Uymaupspr?rTR%F%OsD_0&#$KG8+7gGC-46bpfXrzhipW zosTq5{6T*?C%_8+^(OsgzI|#;mkA`S{?(x4;--0@X@=TnFbp-?Vgj1#%+Hg1a$;{L z?WBtDN8$SMM|%H7s^cTu9tZ!VOZI?JqVG#&{14>WYz!nU^rNSTisa(mMc}eAJUpy1 zX%Ha_r;G~%y$y6-(CWW0#<0<(2bL>wI-~%$3m2tpaoL9voV(>Tu2Gk-IAqCgPyflE zFdnfE#gMizrbrQ5nIfIk2kL82F*CP*QCrMyd3ETV-xJ{>n*6aiR`oKtVJ?zdDTpXr zo>{=Gx(}tF{N#v>uPG%ZiJ$KC^n)_Qh zJqZ2|lVAr3gaNJ8@NhwwU&5ZSb&SF&b93QAOQhr4q`Xenu?lUTFYR2kBfnVoh*Jan z7i$dkI=4S%MX&nQxvXE5wAS(e{|~bFBce;CrIX6X0nZt7zrzI|G_-dw=px4JPiY<` zuWC@Iud~53%K;yI<3|g!ZA=Cbv8S=lma3Ri)OQ8%FFH8W0K6(Q0nkY^ZohhaHwq8C zK^$z|6uJ#5tx3)YTsuQfYrvj-CDdL>fys$cgy0QGIw{7FCNe5oR;5f_2@4g(eRsGF z!8%WEK}19pJSIsWi^`_bW2>jfMFE%?Hnz4<5)43VC?LGX?5Hi?%n2_0waDx2T6xo= zLkuhnAh0OOLXtr&_$|gEa*}@tX^m*dT6vcyS)^H2)772t;QV(D#^WE9lLic11>-Y( zYH!Y@14-+5cYo|QH_?xro@%_L#+B;FlaBt~I`!zd9#ct?3ylCV2XaYr0fSh_iVxfp!9p1V zh$NQ>2rkYq5riNu|9+Exw_fu;7`;3%{`Gl=3@I?GtMID4$9jC^LnK$Mf_+gHZr!&L z?=R3%*@2o>i$~R=C{`vZfI;2XITP_@h;NF=+qoTtk-auX1Ql4XL%1*@)nMQH5x{79gbbCadUg4OT0DPOOZ z!}?U;<$)ZvinjL1)YQxmaTqbw3 zJ%wcAlE`lf}JWP;b__ULZ^APNAAfQXe)qYI{zzjgeNvvsD zS01-XTai)2K{VZ(k#Im+cS1CJ+opbA{B@_#E2n2A{H{#FkS1U#bR=oMk6Jz@wRvp1 z6rF7Bzq#ehkzS|1iG3;h8!^`!=;iIe zl5wqg;q>I`(=_54=7q8IuHCgZv65iDwc)qTo%1Pn0Tvb|Rn<_ivRX>X!N|zS%uJnM zo}aYg@iNX^?6}HK_fA@4wSH(J{YY)?`E4```CE`?Olyl;3)y{qYGu{bv~TORsGb(t ze*?DUf3vp5?M9RP>;T?l*E8_L0-L;dl<+TH;q3Oh56;~4F6EE0xISM?tO}>^e$S&% zK3@qS^t8)-Ft1w`;`g1Lta%F(M*4)0DoV@D4TR5B4c)4q@+1L4zT1@5ZoO4abVH3`6oywU1T-G!#)g(`rqdOcnlB&_J2?+3<ae7*axqm8r0Os&Wvu*x z1I(ycq4^BUWCYo`x-GGerOJ;%qHskZIUYG@Xq90$t9Q4Vau9};Sc61`VagP%biXs} zT_-LLL22lA^K&ey_WFs@JAZ_>a8)S@}p(rB&;d zJ8mxM^khk${05ZGv+4~YJlomUrBgbI;H8hOy(ucE=gb)}+{+9b_U?kGY*;Wwa)u zVk>JqC>!u3&x=={yEVdAj`8I!2rNwvz=K&cfGD(?_Jd5Rmz3>oB;8-dK;V8wCjAG)+g%rSjF|FQ(Fu=&a-nH~H*yKP>v`E#qP6j0FB_)CH z8XbLoeH{p%l$TFra>%Bd34XA;5{Hn~>#XO4TaGSWVxv14s&AC$3NqOI3l|rIMx}#) z`mJvR??hJIHz}p$3(ipB`F)i7zvmYyf4o{jK*a|v-H*@y&8z4yA?4*3letwD6)r>; zl{Vfy;L}6i_vKYp#V~Yv74LWSwo?E`KLalXj)@f-3kEO&bx4nAe76 z>moc32e~)Jp8;^N%GWXdC&_E1tE8ay{y9%9M zp3jtY2Kg%`ZZ+jR7fW=F9p;f9shGcCuc49M=iEa~o=CfWLMH+^m^B^SAQ4e1gI3#t z8q4*G#6+z6WvDmV7yce6v~e(e8OR&bFBqs&#PCH)CmD65V)AkDU&9Szf{;~k9wH;? zi4+d>`(wIKRh!^nu6Wgn@M+YBbr7S97i`z@_a*%Zo=er$WZ9Tgi|&i(9y!fJa#=%e zH|k~bq8DfFb@+6CK5e4!QO4)YRCaIrPf1FE3Oi}a3JP@j^y{hB=Xy83^&2=^33I*i z^*Vs@tH}!a+NLQh@o8BW6AjyHlU+qw*?sm#lci^;aRPEUeN_p9$f&{Ix#z<{7tIG& zq~{6YmcigWEA-8ke?#AB9O_AWSB~^?-)c#0_?ORa=2kdJXY+dfC@9!g_Gkl^;c6WC z(UhS;n?_$>-@&ZqIxl8u!VdSxkMG!!C6vtP7xW%OY)000A)*e)>weBQ2J|`FK7+=} z5a5$m-F1Dx%v#w7y^=HZo3D~R?mI7?mCA(?)AZ^cCZ92H88qFs+|u}Asmy^}6lKZ; z6)5>&dUINptqI#fUVBGJ#lq>a96m0`TEG+gEc0}xLT+mkI}yH8M~u(C$+HG$nM}_B zqJ{7I>1rQ1qh1jUfgw>2I%y>~9P)E&DyfF5A-wLEHKR*Dug9+m&q$LV0(~>QCgNMP zslwq&BHZs*-h9tEKHnn-4lfHuUY$Xj@a-EC)X_S2*=D!q5}g^KFHpMyNt6{UWz+Xr zCHnriY>i;1&er_vk8SG5u|pmNAYlZs{1c_;=I3hx6g&Yb>G8=))3UA0{)8DpdvqsVXMNW8l4qSP$ zM1OBmgw{dHd0oHP)=uA$>H%wxA^T>AsFfc-W(;Ri({z&lA5CY$RaM(|?F}MqknZl5 zZjcs~?(XjH?gr_QmX_{rknZm8l9Gnax9;Z~ufG7tUTa-(&UqZ^%Q)?V{7<$MaXBr4 zr0~sazJJ$wYfN4i|FUvhX_x@xvC1Lk>xN$@Rr9LdmS47&6Pw3WfeHyg5@~TD!;j?m zcn9tRhNdw=eB}#XuaAyEYTmK-b|-znKT>{U+bxRTPIhE$eNc@4Zt~i>fUV)oH8XV_ z4m6Ls&rr?4rfKV__zgy6wex^U9Z<4Pm}z&r_|@D2OERFaGOEQqdQ(hB4WVTxL;hDD zZPuMEN0yrOnm4klN{lrOm?Dpq1BF4xSu*h#wkx?ddY)OhpYckl7+HDyGD{;hJTWy;E*u_=XNyS{Ak{daU{s^)iJizWI3 z0s-zTYin!iIDx}p?5KRFip*Tdz)9`DFNu_Zx8>mQ(9PYQn}Z|f$BzS-cK7jB#y_4z z-`P_u%O|5G0j1a631HkMZf>0wE91nRx(!(VH~4q;C|5^#fCwvPEJbGJ?Dy;P4n=NB z4IqUhY2wN>R@06kmkjTpnVZ9iq*YbjRH1i0HDO5@|3>}?2r*aR_Ncb$hxOY6?f3K< zp0Co@y{1c*8`HH92VM6GaXDKQlKH*5h#-rf*6yv14+6(3s#)k!Rct8#%o$<9R-C;? zTvmFxd|d+S$=BKb%kgc>~=@@rthus*;0;qU6dka zae@u^r{%I>g-o1xu|2ACyOEC|Ko~B9Dwoao2FZl`4vStFW88bZR(;ue8OWLYx_<-) zNaK!<*O0dtAoSGJ6R=>#$jodHsE9Ne0Pis&ay>)4(E%3DT35`VaS>Hfvw%lu^EP&Q zBkZd`;Kl;R)XK`rz+Yvs+HgtoUpS;15Lp2k4-hDZ^$`WN@A>%|7^ag5`K?=UOy*GF zBYvdkN}{}-|NLO4{7RGSTd`mzV0WqEtbu8wy4{WY#HviM?UAH5<)X_+>7wR)>uTK> zr&=*w*3&!RdAX^#U4!D{0wCjngcxvK*vy#(0_6^Pq82mx;=p(5zd?M7e~9CX^X-iR z*8(SBm1r}MO@=TI(R zFsom2;j5&L8tOf9Md(*RH7U_b9wL5iXBeX@;yrNvukE>Y87D@*k-gH@6+ugjz;4%m zYBH@ZiWEzdd{U4X7^4|Si*JBPh8aVxpi1X{r$m0tSKoZSc>bqFK|x~0W>JH~nC-Ll zsLS`RS^C6=%YNkY?=L60S{kvi^#fRq1LbE{5-RSOx&EdI_7c>I`I?)y_D~=_ECmie z1_IWe07_apia5`65&hIuB9}|j2CcEt(fk<;T0*ZOce#(aB99J}*~-3#)}5-!?t<4# z_Ij@eiElvS$qN?2eTGW_rYD1#S2v|R7eU+G^+)tXZllhA4XuI7aa~2ZTXCW!U7p|T z(M4V!r2+sW3Zmq)(_?q`Ly}Bn020j-iT^zKPbA7=7=6lQjYBO1Z(d3)GTe9wY2u10wnr66znMsU=zzR{s zZUt3@j2zO~rUYP^@;J8N1LzIJqqWs%l9xKFF?1GJ(MK5#U_=x!2XdKeu8trIlqd1O zzC-^yZBWJe@IgO|cN3BH{*)|Q!7b$_Qu8dw+8WB?)%anWVZ~(;|2xP|qLucOX|0A{ zMX4q4;zUjIczYX zIt$PD5XWEknoY%06$1pDMD6PIlAAj3E<=xs(Lg^^ z2Z7Grym<)y_J6bsdD|^*G;bBKIssJJ84H)85??eD+i6}EEMr=I3j!Vwi>>jL9R3Lg z=vf#M;KX`VKP3o2gM|DcuRsIJY%Lc{ zt2F>BT3f*UQBDrIp9SCq0Pzofk^c>z>KIUvk%1Vq1qT9znQ(|vyXkzsRN1T3&*gPc zOw=fyz^V))HrKFO*!l9ey}6@n%!p#tu3mg^hvIuIOnMC(8g-H)rg#(?`xcsUR2dnn zIGT>1>JWyu&_umfu0{)KBm@eVsTx`iY5x*Pb5E=uP|gAwl@MOfRw2maM!cjsI{`av zCErf-(@GrmDgdZdim!+QQ?jK4!*f+NHH5sO(BzDK|LgV4-0##%8$>$`?zp^j+%dM* z!+Sqr-uxn+7gEh%^FfmMQf!9xUKBgDA!3@1T@4)OfJ~ioB#FcY*+>8c61Ax}wX^gJ zxFY!NWxkd`1Vlr`ifLex>L^E|Zf;U5)%J_W#ugxklH+o+qjlqDqb8D;a&|fFm_J>{ zE8886B*1gHd($Qe2ETrv-a2#JbsR}00?38WGXAeMo=fu*KG$tg%ZiL*+dS(kI&WPQ zU-4z955qL<`BCpJ(E?G8cw>R>T3&wH`{;di6e3806?xS&n>ITC*g>ay&iCa^NZzUY z(+f>Q_ET0F8u8Vk`T^s1e|lxDy;a&uu;Eq|+sh-a{m5sB)+~jHxEMG&-{rkHYP24J z`1%V?>xqE`3}ZI_6N-sFed2|A^Gudw4l_L_vO2dMQe3`nc-&fBDqJw5QMvdDhlz&} zId&n)J}Ktdz-_;lAu|$PYw^#m4+C~TE{THsOA(#7+kHas$PvzBJ)-V>bB=Zv`*NIR z#-aF0{hY66MdKWY)jc1cHEXmn*naDE=+8 z2W--bU^19ADvWgIW*_G}Bz0J|xH*^)Pz>oQ&Nn7KB$rCth>*7k zFrzE)w1JBRQ=JtBuTtllKf1N=^PA-1clZ)sR8K3fyF>kZ2vsXWQfdal2Bw)2V z>FO~MHS$aVMP(pK5{(`7a_L1zM~zT*!g^qCfi%b_(y z&~gs)`G2tvpvMS^lbhEB1O=;>&d5Tx-+^yFKwMaHqYzgNiob&s%plZ<5XAxj%NEbu zh3|1hmNqtkd)1YPFhjat`8+*_;_FOuR`GfL*C~#3@7>r1%)WtJjz^s$hiGUfYza8;=98a}+o`JNuHG&P+?RQfmk&7V*{^n3 zxN)RF_H~w0iQ03!Onu#7%$+~;Nl-l=J40IdKX+HD9E}rAU&!=}mm|_h5{wtCR>n@_ ze^8E6B#!%yD^_r7u6?75MIQ3R02E;vPVflMH2k+t)pLD^48Y7@ELIIL-(H&H{`mVK z>dtbs-NgXPMqBzSP*6>YJ-0XyOQJ26A;}Fx`$1FYl1>t~wmV6eCh9jLx{Pf6=sn^kL6)z`x3kof3S8 z^0wtu7^gQQJ-&bXHtY1LsGT!+HWRPHflq{w&$rJuS&vzTc|O$i7$D{rpTzOCY8?O~ zkeIM(Dq3}457BOaO@inndNq61Ba+bzgxVuA{4&x`w!W-9;9(LH5=uvuR=lcpaqPi` zLYaOp6r3aY(2jV%PY82a%YOp*O@;mBxO@oF1l#2-WiNfapo z=ay;!v49sXe{gUZR?HTaUpVV%$@aNCsOgFfzu&jO&R+)wggZ`j^Jw+r<-Km_?rM7x z9qt|#)ghvdJ2|RMCuw{DPAtR?+jsebLfGj$a1P9WeteW&e##_RbmM9^XTwuOe-nHk z-OV(}ShPSDPrwup8k-$C53lw)sG7cybz8P+iit1PRjF98tm;~vPP2(F)uvHK$Zd$H zga`f3ZkJ8G`hI!&Dcp#N5mNT#agT%*4Cw+e(K?CoA4Gs`x?&l@TwL*7Edu9}Qdy}m z!!o1~paC_A$Aon)lz++{xE7WfJd08p5xBchAfwnt~470ZV5@L`03X zuILgkjT2dl*-`iH3{Pccr+3ezqf&80|J~whGGK#xE_1sd{Bt0rC3#8tJaS`+FnF2h z(Z0>%C&#k(Zx|qlV6}4EsHQqEpFjRxo(2{MF2AST&vgA`2b?NW8y2L#W5i8mwH^#7 zP@swi_ktiu#)$uess*WD`O`)PvC92de?%jL0rtnl@&9d=lYpAOT((oIj$gO`VudFE z6h#ONEWpl$A!A_tbcce#*J;&s>>-#Svk5dJ$_cn^NWnpc5vF6QP#^>Z1mIYuW~Hg2 z)_(YJd8mQYI4@gz)b0}a-EQu5*)x11I#P?xJ3aUQ`U;4Lv@9nXD`KWliqH=r-%aHyX&B1AQbr`l`!TSL?xW5%}_bN6-F^)~zRy@edSv2y9 zr=jN%c5<65+d;;of`mm!>o=JS#b)QDRAtZsxhtbCPfIiT;b+Hv>qcrWbbNsQNWTfu zjGnWN7z!cTTte;d%_PycX7EENS55pCl_2nzvFV(&Vir5J%QK#4^=ET3r#K7w?JIsp zQs-fY=i!!$+F=rpm^bwdS@qd2iV}9qFZhI zxyt3uju)Q>IO|_Uy%Se4B*ypQ*n^*qyy5Ru<9hWbRyW~69(((R&nxqH+&n8(SLPL= zA3>-AIts-6^1aN0dpL{}K=XntU8W}={-q9>=2PBz&20CcMGW|?O108_z`z+|V(5?V zG1Zv35@ZkdrIfZluOKpqbhREx9O3ty0%_s{CxD!jlr-nHU>(*X#+jx*adF;VV>!xQ zm9%I*G9aFm^ie~=;8m*xsdz)9INT2AkCj?$p7?pC2g)XGe zk`)^PFt&8+>07gy^wWWQwEKg`{*~-P%Xj&ZSepPDD?lC=0))A5zU#kUzOk#i-?*_gRIezP9}J;v$=euo!*yfAtf<{7Ie z6EU0kM6wWJUI-8#(?Zv`|W zW&m9V@bH^UN=gE-_oLG_EomGW7+3@lXy)|Gi{JHn*5lp0zk+_CO1 z@Bwd*=~th#ku#8V8C?B|H{hYSXv| zj99^j($dm=*@L)8M@Q`&c0r^)Kta*}e_`qmK+F-<*ysKn2x)M0ad80%`+GJ?wH)8G zZ4|Y|WE>uN=s^Fu6KvrcQbIl>wo-gX0l_K{ft-5tDYbbv*eYyMXpli?MOBqt$=rZg zlhBh~o=>*s9wVLS)MdA>5<#E`ead5KS=oXP0K7-YkC(e9%qVDF_ZNG{pnq)I`)4Q| z&{Uzk4~{kE{Xv}|V%4>xw~ld)B#duzxs8h?}HkUtWIL5`YH%0b#&UqVC-POpF}q zWX>wDfRvVJrmX-Xfkg2Rx+}W z&>=9;@SWkv#jChDJ>pF^WB-X*Exu)JPG)tHOxYh)daFYYo!*aM>|l{*#P&VcXaNR{ z;GE9%O>5gR}h^g`fsGC+;j!7!RR}mchmcvhi|ccuk+V?(zuo@d1?r=T^f1 zlHe8Yo95~6D9wiw7Wjx-g2$67OwC&W0Ejj!DYRc99P|McRm!mWM993npaIx_e=(hN{ViMbf{*@Q(){j6SM)~V)MfF*wqUp!H6WvgE?M108!7laCeaa{j1 z=PuxsT{0Y)8O?G*OD+rQ2Z?HaboyJSLO-*}3ZAjEpQ>jmcoIrJBoojB+A| zoJ;5HXH;fzETbGUhzMobQCo;0W0F~jCAs??Or;JHpP3jNtModb_eYX|9sYr;YO~Ot z4hp%C;nNA+mP8n3(k~)@kD7)Czzx~FrmLmJ$I6;_*0y#5AOHcyj6XLt00+A)K6&0_ z?(B3vEB4`I8gpX62B=Gb&1suZc8*oR`Sz`v8`B77{YAHA1A3CoL77kYD|%PQ&!FYa zIyMfp*EYA2zeyj+V5{sZ9)t5(fjcl@$d*y8S-F_Cxl_l+=JsjI8=;3o!zYda3u2y$ACneS^`4db8o#D(NQbful>y6lGA zVSz&Y?sOv*six9WoxZhD048+3uChn_4}y^*-tXFpFKw4%+UD=OUr;5X!DJ$$(MbB- z_e;&o*}`m9wwqRT{hKpWOe}rDP9vEmo0^JEsPWqbb!D=H7|AAKimyqF^_g7Ofx_EC z*4Ri7Vc*ZTNt3kl2pB}-DK)`aywWD-UIX7h(r^}@B&KG|K<|GW76x0ju@Oz2gaDsB z25&A!UvQQlSCttieHA0Xz+0h7ZG}iA*Z{JqIV(fnJz9n3+ivpG>aPrTBGSrljkh{E z@Dp4mwW5m204Oi2=c#0Y28Q5sAze_Z1H2~x|aNz=Q-H0N3ojV6cs82QS4}$Xp%rkGB@J2Xay%-%7rAJ z=_kchh28P>0Dj%6LHmTBGsyljA4j){e3h?_cfq|QX$ z7H40r@AT8`Sc74gNs)IFGkO5A-vO(J8l$=lfx+)0J&yTu#Ed0TEaQ-CIyNYu5y$3- zSpQQ8`j27`qzKP~YJF!Oy@8Vk`~ehVJODC@N|o>aXLufo{&tQ#NSr^rFY5jN!9q5K zj%scZtiZ_dupC<+M*Ymd)KxcMPDd`vBR7lMzoEv5ajIyMvDYG1A*kzh5}1Q?Sl|t4 z&Nh3mi8A$gHlF5~AAEPOTHxU~A@?MyF!+}n4tpyY<{*$+J#UH>qh{S7#tl}HxQfbF zgkT;}0Ci-*9BaA^5q_dAn=HN~QeKR6qGs-g`+vP??-{#{KgP}&Tl%dUcX^Nji0$Oj zZ7Tr4y^^u!4_4kce&|Br$Rgt%C&l4pmZRJQ;C6`|=95{%qydJw|5Ggs1%T?!-rDKP z+&bJ}L*G!goFMBdpH4s1(*sdi(vWS!km*`wU0iZ`B)X-|yXDVuZ_B3KA3&skmMWf8 zs-#h&!FLvi5(t|Jzvd|8^R{!Q?$4BVI{-Awe-EN(N*(naOs7FFv;*>xBLMvZs)C(* zv3qT8ZT!Sj|NgmfiML(}q&6Sl7AGw&$^=)j2yFSimfg+3nF$08WB|rIZeHJs>*JxY(~joB1+5k{0bLMTlzWJ zANI-EX;%2EHBM;tzThKgigR^~-IMfSeByv0kq63zu-^WBfMXbe*X|Tb9si5?&{$ov zx(N)KintIQlj4j8(P6pitJsCRU6Ke}B--`0B=f#&b6Y-BnGBP0*RLq>@1c;`97IXe;&1&s zSF^X=K&_p6EY*`31`6f~75DyMqdFl8ap%#@1FOuYlWM^TC82BQhsns7LF5oYnSYEO zehZA-xuhY1!Uk+Puh-G`@eJkrb-v}Lqi=P^mUi8Z6@@{iH2>LGjd1^y#N~1{%=A%F=31(<58N&_*M4>8&d zs=B(mdez)%W58+6L$|B+L+$b~zAlwQ&0dqY|2g-_ij3K({4XXcJ7NMK+0h@3Uq69B zVPFuekR{~2eu}AO8ybD-LbL>yBuSYdac=7H*3)z-}75+#ICpe z{qtD<(qa9!=sP7CtV%-9#NsS5pWzqPVO_j{X3s$Wdr^ioVpw^fXC zD4Y089;(|c8L)_-D%Hf~2fl;HhQ8-^?{>703J?>Knc&jmmmibP_9g!w1oo8uEY0HN zZtWX3jk~DS=QCR%Yz&(cY;V!ilLv*`M1J;bA~+99F)hFI4n+t!sE71APTei(Ta@7^*2Vo=UIJ+aUscvHLxwSG^d}#`*@IDRFKJcPiAcwx zVWnmTLH5K`Nvva$^^gj64mI`+fSwtu8XRoCQp%JxV3UUhE4w>rA?N%nVC4tm9@P6` zx5Uspq&Y5HT1Q>4l?`ckOTT-*s@VO4Q7Lq(YjSrjnIoj8yIY75SzbmaIYYKTfQ4^p zq7E)*@Lu@pDNx#aG-%1zpEO1PuR{g8_{`DmkGMGN3@)ywi)?+8=|5kwh1~B@m<2W* z0j3^m9}6(g-}7*He_+z(WI-RgMxW%!lH&^koR(-r+3|Jymo1P#pW^&m9Q=AsTx=GK zZiOIYhC~4pEG6zF!*@T`ba+d~<&RGlQuX`jpv4vYF9t$G`%+d1Y_P2BS2R+wV92ne zulY%$2bwBff1V4*&fDfF;qPOK1C0V2xvXgpq#?)hg{VCb)4h$E-;u@Q8L(-0ZwJ@I zw$j~{+!fW0yZ;m(hI8xS4+h?zDsQ{21tD{vm`NQ8p}~+((EZqOQR8!Bfnub_+ zZsQl0CkoqVmwwAKJKm=}#A}G>;?so4utYH$y41 zy`3xP-pR%P%j;7@vw}R`+lGSNAgP%i}j)e%1sz zJc+h^fGJ9d?9HD81bqMIp3Ryk)_jMX>#g^{I;U)`0^LvW7z< zOK)klE*w*a6JLAWVB1w+QerOhCO`V&UM!yxOF-?^2yqvVq_XuW+kI2=X`(CSdaUWI ziL@h-Rr@(BauLZoyRJ#p|%q3=Levs|vA>=!!L zY&c;?q-&SZ4I3_YL?~2Y&=qw*rNPJaYo|-teijz6np!FmkI%ljy3Wq3guwNcw7Hxs zqYghDsK)cwOfnI$uZtEuGdmy+r>*6z zP>hB`+T&pJ;;wefr8CEoQ4C1WrKwgn@9TpKDL0uR1F191V&s{L80=bDEye-eUvK%S z@0kHV4VWx;56Hm}?t<__xiH2?%GI$@&@N29kN!GL`f_+iOdC4y%y_Qqnk8o9%U+}} z%PY5R>5C>}O4fix9gst&k8Vq)j)=GcfB~|;m#wm?ZRm;(wIqF-Bnx8no`&4G`7P`e zg?MD7=g1#;Ihun{UBn^sg0hIij!6Sy{P58rqyT^i_-*K&0^4#-8V{IJcSIWVYI~Qt z>p3xCT(^EsIkAkI#am=LFx8w?jYlfBftmdm*VWGS(`9JLX+!XoJnnP0+|v9!t=p2t z6mE2F&^Z*y0E7$1<(m=Gib%SbQkUlHp!@k$ZitK6FC!yE=v}HmMFFl=#bM^#@C4Rd zAHhop9*Ybhpy1Zt+0=Bu5bK8AZ^u;myJ-b};%UfTzh8r(e^#jD=;rHC8%=O+PS^Ae zmG}==HES%qi$#l!U$pqNVX>t@CQ#~L-Gi@n73rk@OZ)(hj2#D{`vb`WuweJkTV8u9 zr>9o!8#xl=+x+s>sgm118T#=utMv51!6bxI5(YR}Nh%hu?bK+yQacikJiTM5SuXAYW96IeC+Gm9 z8dHKXtu9mhD{>^SGmG-@x^&MgMy{9#94kW>6d+%3|S-y-9D60C8tjZQd~qt@~urR zX5{QcaU|-hjlX`8CXLWW?cP4+&(P}fT&Lye+cf*>16{cIV#_)Pf-uJ&Q!HkN*n`{{ z;ebHrKNVown7x+8#YI4BE#5vfm2r!)!tte&$h*DVE0iK>np$4-Yw!K4=tz9>hW>aK z|3)3qz$C{L675GuCE_0_EXviiBJXg+4-U zYLm%1m#WO#G#SJPgMyq-l+XOGe=HKyu^fr98>}_FEv64P5%R);ThTVl*~3 zdMXM6yU;-K_&LO$8(a{98V-7h+qQzqQxI9XCVM(K?3>(CTo74f;SCNJmi3W3L#y=> zbHYf+`&)lU+||olR6ZgK%30fA2ObB)BTvY;R0?ok6~VQK&)m~k8NpkDZvu%>i>v$t z9`_KXvSvg=xR+55ba7j$4abbMVS{)PbL%bt{`B6?mh<^rG{QsY>%SaE^_Gvon`n6u zwNOS)5rRy_$HB?zdS&wSNS0rSmy>fK0Y%|NCbWF2RQ*_Mc{JcYn!} zM*OCx+=854Hh5M@Vj_+csZg?U-!%DoG2mA&Ok?l3&mH)(7LZgi#fz0KbB?sNwXww0 zGcte~T7`Mofdd!{wTIi}1ULog>bYuLk0}ZtjzQbE(96WOjPy~-FifyEP#(}lC7OBy zbQLNps#29x6aTnCM8s{Mn3vrNrga;8t1=|@EEo_Sy@WZqYrD0$xRsjde|+b5my_A% zEx)z%LM1fQg`!Ywg4%<@sIMe47oN^neby19rvp-wKQDAo2wk3`^)i|p8XAPbz<2huu>CDyZ%za-*#}z;>sb zR{#0~Od(4lE(r7$&R)>3#>{VI@hq)*g@zu!qp)y)73u&SsoQYcVe*fb!rYP==L6Zw ziw?v7=n#ph7PCF0XgnP8>nC>Gq@uy)rIji9hU8>yl~o$x&H^T! zg`GWkLDob<+6>9CgN{1MG0gDX4GuU2D;~IIo*0Fa6J#ox%fY^QM?Vn#O+>`rMzm*J zo4BcS$(DWyqFf4mfWU3Q_SiQ?_~DL}nsP2yT(l+|IGVrXb@r+0O9Ur$?LTUli| zaP&RDJR6b`8CeeGWDHq(-|vsL)z@3_Xzr9tc1ipn?-nnlr9UI!sXe`J58FMJmu*ZN zYIgYSSWIMjTM`|&$tCUsZ9i}jZtgQ1U%_b@^%yO46s}gC&&=)A>s_3eB|2g_D-3)@ z$_u>@A|o|A|5ProGj-+!ux5oQ00A^gbl{4(jv*~MnNY}&-|hrCIR$I2{9EkM*~O<^o%`n7R zCH^TUJveQYAf@*#Y4-}~cT8C`tbm6w3i$hKF63ISvO1BFr9<8w=Jct{at%$&s9m7x z`2YC#GbH5szQ7#5dV`~14MXL`W} zlHVpl2~GA7XMWTFvfh|0K8vMVQ#XF>U= zTDfy4eIeU__BsZ{3WiFJC~~Dj06Fjwy0yO@&lCVr_C!i?@`Pee*BO<47f3l}*3(*= zf5&gja03s1XXx@(d^tV-9i8ngkMo$Vv)DN4u)smM;&AVv?>jyC+P~Hh%Sub(Yg*Ec zq)xii<_GmQ9`ND4Wn!eW5TH8|3|V;7N|Io|Fp-H95TLYXhft1Dthk5_1D!w@8`mGMh@A>L|>-~ zp2NVz9^HOvPPt<69_xG7KbP))Qk|)0&b|Jb|MKn5T$EeG10(jt$tj}d6V?C@Vb4{i z6XwwMXYv2#J z`m)gd9_=Q8BSs&NcD0*5(S@FR@nl{66azWRYsE(PY+_#TG=Yc!q$llTw z=k1{;aG6FXO3R@bc{3$g^G@p6l$Q4|_w~4`Kl}@)Y{{p$oW8n9j3GSzXNA*4-u)dN zrnC_g7Q|bxPQbl^9{FeQdS*ru&?De}10G}G7AQbn81XCLbg`BtkPEWe);|urc}j>j z4`b4=F#tpalV$8Ecg|=$-?n)kalm;1iLI=R9nrwlL!{uK5GDCozUjALj*73L=q!ma_8P+#E#| zx$GQ}AqU==|LFK!8O8Q(<}VqtxBAa#C0B%!SR2Sz)WwKD#D=JM2~v%nl(Zzd)~we{ zRmv>#nzO3?PD*_lKh?F&jjBG9ghpO%3ECImr7%Go4I7Dbd_ZkmVgZSQuKD)Iijj8< zDseHZ?qlts8X8i8p~nkFuj>yYmZf3oAAyNsx4l%Ebn#I1!&3D^h6ADn|f_zSoB*8 z_enAQY=S>=qKNf;9nTV`UZrNlJ*CZz9eW`t-H?siM-=tS2HJoa3lKUkOgVmQdb(x% zM(RXl$zJyiXQ4H%Rx^h_8E})85S5P(_q=vFzyvySNX?FODLVrRRzvik~(R4A-CY=@_+Y%`@r^vDXh239L zRghWV@!+*TJg8*#nO&ezp_~q0W{M3a5v& zzecMQRhZ%Sd%v)+?;BtuWf&tI3IvWafRN|N^XpQPO;P7f*UvgBG`Sz&m~0zfiU05Y z^wmb}2kPCxeb`SSe?b8E0SYsO4h$GOc)s1@{t=7xtzZW5ZD$mp5gZ~S|MRSPU5Li_ zgpdX(DBr0lNe%os44pt60)ZB*bP2L}opvo?$O6+K(3o*H(-?*|7d>Uf5OkE(xf zj{|u}PexbZ%nMySasJVoYZ5-ZKP&~GqeQ45S#N|P-x41rjOy{r>F~v!pLR6O<-rQK z$waR*bu6ipC@lZjc0B0EpEe$@xhVvot zS8zqm!Y5LK$+Ht3pno9Iyp!3cORU)Ib(9!Q?4;XyGuhdChjUW!BA@o*S=vSlWMkwC z&g$;gor1;+=d$qy1<=|$hP4@)GDPNty06@!%&B5`2!|^5yCFXWN}iSTUdr80+w?4( zvNpVnZ})$}^M$pSya!TMNkR3RI?LXg*Y^s=bk!8ORZzN=^lK_;S;@#jWVi(cG&+Vy z9AQQ6|26JyRa4XMuB@A&f#ZWf0Z|~~7D<&FAwlX>1rAPyEGu=? zGlmiM&%QI3SMrXE1w2|3Y{M<1PIHI_dCu@lx9Ez7ER&Z zAu(FOk03keCwH9UB%ykAvk2^&wRq7*@kJw00qbWFDjSEia#qV_gvi1s1JBfHZB{8R@Z`2{XF!CWO&>zP?~kTJV!p_sF8eG ztjpTE>G{G8{Z$m~(^is6&Kj|!@8^5JT0RMkLqh=4w23C<0uGKVZNjl-R#WjCA4`0o z_T$$3&S~9lP`$af>jgycAi=_^qb(lTb3OTVwYPskkF3z^^s=z9n9SlO91;Qd`WxbY zv$ifDJK%FW*RZv%9NH5BySlprzKAeGDQW3wLiLI9ilcSAfcJv7M>*gc6!Am7neQ1G z@X9oQ{Gam)F1Q!yBrs~!0O%gXeqdGw&*pI~6WUrkPrP{%1X(ErP>& z|2o2jX%KCjl`(LH%!|LcaH+I-qzK5Ue}t z8log6rnN_3I%`|`r{@hO{g)X>T@pjw;+B?{nwshV1g;(JCDJ>ZAVZ&Enr{XpHh(V4 zXC>pI1ICRcM<16rm2laSsDf$!SVm8sAk8h90$0z#i%uGX*sQQH#Xj%eQN@cfCq0gZ z-EHI68W|@@67^^Qnhu^uoHrMr=}YOKlR-5|Y}EjwPmRkb#N`r2%ms@lQlP0))SAtvZAM9-U?TRc#NP*3d{V8OwWw(T*h-u0WFXoex z-1xn!lbS$2!(PjyrJ3H|j=&%kpMlCf;i=T?_;aiGU0&~FkU_6g3*pF_ zA5`#F7^45!;tMIP|IMFDzwV2)@Z8B;N@^ed-ydo6~zghN<3I8)=}g-WI3(SEiDI_m1`w!Q*^hCsB+ z9_POUEA|XW_S6xuS2Z^`2QZV8i9E4ivgN>eRcFA)vW_8_4`}$Yh@i3{Y6ENd)UD>l zU1y~b4W{o#;+Jq(8UW}5AM{g_I9o!9vw|Oa-iX05dcrJPBs=XUjY$`6wD39cy0FT! zhlegFdn65`BhrZBWIxd}8WNn7^UD%nR3dR7035pNzF+mD04}D|!vyO57EYz`S{vR$ zQ7~Q@nS;?24%SA065rTw?d3G(aJul36XqTlmZT`F4B+1N@XiZp&652oKPB-$nU)iD zvC93coMhFnl09Ow+P2wX?S55`J$LlteZdrMP*%#e_T3ohVIJdf-WE_Esvv<7#TDyT z&I8ApnMuDU{x+>26t4FA_l6Ya_MGpv_2P`4D2I$xQ0u6gK(m%KA)zm}9aXGcorMn# zyy`o+ISPo0`B`nJpBcFj3tCz<5(`V@yIT4dn~HZnhSfoX#yR}=MxzfpZgxqwgm?tI zjGYHo=0fMP>vW(h~nwpDG-Xnf)0du}3) zhzuc?6Y2hVl0jC!@~>ucr6Mtf%_0C47N|s`uSThobeBkx(ws#lp`)G<_%BvjuAEQl zurU|*J&hD>*Zkr%Kku`Ko|Mu~iH73d`0nQ+!K%z53*=vdNW*@o0*v*>e7G^sg%ZU(t|v2F^M`o0AwUyAJlDd@hsRVX6NtcR0c(jy#txgv;UIm zg*ct}*_4$d`*$+ZJF2`k$5npQU}vh|98N*zJ?3H;fX*v!7!=3^Ei{OS=jd@0lA``X z7ljVfdvvQCqriYY=la%hJ84~*gMfUZyTMpOeUHZyRL=k}TRVV1sMN2NN;Fj##wIlV z(1-C!YV5}?7yM{MdYu|M?12++qM~;!?hEnTC-X7nCYql{%~rEGYIPi;@7udS@-(Jm zGr1vq^10S+W?bp4QK*+XPAe*qbn^#`sBcP-okE^gM_6}Pi$B)I2;C7t!P8>ZT2$tAAk??`1r=wh)7T-FCxZf*P{tf3_-sHIB z%(`3;f4!OQ?1fm_*#VF|Dfqu?0}!J|OFy@0x+YY_WKWj?o@;x1dtcwqva%0Khi~=Y zo6(!Lh}ZmwUa`2sJ_74)^#9gdu&9QHhR6OeTJF@+$_g(arv>i-ne5q<^|@-F&XbPT z6w@4_TGHFw+t=3z2qXZk3J4rJJ~o!yH<<@xd%4*ejm?-}!xuI{iw|P4)9_0j>ao4l z>1=6mVmx?#I=px?q2~d(1CWhJ$~D2|EQNmrF$5(s4Z_-vRK+SlY2XZ|` z0=Six7wRdIxS5e>F0Q5}sC+}lbhj<7t)2O@KXJ9yUz&omZY~bKcO~r*K@VN$MgEcv zwUpva1d6liGQjsL3%ta+?!Gn6P8UCo^k#iOTwM1q?r#8I_~ z%6m5{&-h($Ev+MHXQ)S5Sj4Y13$HkHwa+p^WK!aa<7V})M;FbsL^}q%7a!J`b)KN) z9VjJ@aDmtaTl(J%f($(+pWXv&J>u1Vmk*pEs&ZIV5U8)BZCvZp_}rMrjuT%de0f4ge!ocnBO5d!zHgLtVzKTzX@83J^b z#4kQ-uK_s>42wAI0|RAcMiEb^NvPdD?l0@&R6){dMe$V-$OSjMACBC0SYEel*GK=a+0bnviLhnBD(J(>X>}{{3zEWK5oHYqD)mwr$(y zgvsVqlTNm+$*!rUnmpOo^ZotTdfxS}wNCA`_x|krzAoO7kkiL9c1Bh^OJ4!`31@y6 zAo2qE2Q5~C=2&*A0aHff(8q#!0b{hxXz|;7a?uCR>uSoOfxPj5gX48EAZ5{m1yA-L z7|XU9XySy6kyS1M7Gyz~b2IVIx7$!}fxv~08D?we_uJ__0DaZKa3g>^O~=Rxb10L% zxVn1e+U}h{GbWR6p)ky$q1G5#kml6zan^l)!JRf;I5M(QW6TnZ>BbkW!yNm=q;TI!VRW0V^NZ;g4NWv`|K3i{06_ ztII8^_JtWiTYfs}>OGWV`VME(Ps)jtZpbS}bILuTo?#vEna$0aaOJ>=0+)8XZCg-3 z(=G*R@XY9g7_$9(53-m9yFf^e?!fH`+%$*sFit!$=vOX;< z_PxM3H-sxV@&C|qK=hHKp)5cz7|{K2=>b!ceCu(I-n94%!3XZu+&EL*zXd#-?)0?G zw9rBY2}R|=s3OvYsZ!t7xM9Ma)oOoFd#RI4Tr}*UnR(K@mdfm}HJyKzHK;MBc$*Vr4}aF8m$bdH2rJ%|=sRWRd!h@6ocI zD<^sKA0-X$rzy35txPtTzdt3k5`~Z}V-bOr^$#TwTb{Bd;o>t`ehZ?uz8*v^3D?52 zY=XHItcd;gkRewrc*8{FO>~e3LsvCxw#d^)SraN6bw^}<(Z_S;T=+mGVrR}Q9le6j z#h)_B`Mu&JV2Ng3 z-m$($MoFXeE?{NJ%MxcDGAd)%C(;J|7F=d%hcgj{{WR%ouMbO6f-T1BX39dlsY;8f%IY8}9j1QoAy8gBgC4~+XEn5IW+Nm>#qa#HZJs%o& zCr4jA83Jp9wu0&0?zOzR@;KEY(Jp5_JOlV5w;jtG`|PjG$*aN5 z?hE;|eSJtMop1fNYIxC~fy6QJ;tzP=ySnrt;2|%=`MSYNjpkgU=1&GZ+b(K4ZUdm9EHQMBv-RO+a*pxPALAO|oSE^oB{<^>$HJCg3n-E2wEVyL28UMOL3laoyg`89hsmBCn#Q!7p zarB$G49SpQA`{}_J|YEl%r?#vHzC7py!Bk=&&_e#f>y*6(zzge-}CG?`MiH$xf`{h z43ffvAb+u7stnToNd$fl$3>xK%YEM4C_ZV?I2j(rLh#?vgmD4pS4c-|s>C9FSNa0j zK`~h-p=%q{oMmf+lAqk6RTq-I#4s5oykv*$JhMheM~wvEEb^C37){6taTUl{GkK>> zl4H;sNDh7i;JQp@)?g$V6?b~9-o5M*rLD8h*Xu)y!sM)@6JV(WYN~=Sf!4l!SP2Af zXD8&lDbSH;x!eyhKDqML9?060)An3;xUi!x*s&4gY6}Q=8=v)<^#&)qK9-PkYPC6Q zpY!@XLBZgoBniIRuDE(M%f?;viNiDxhOY}atozjIu@bI{VSOTzA#4i`75Yi4$%EUO znVG+v&advbyO!iA=SOPlb6hnccC}@IGeWrX``~;z5UTGq7#H|j!a@%vCW}XDs9Zoo^8JH%D8EN zw3nH6?rKMR9jQK6gTv1FJO8E=_;Ba`fn$o%XRIZOzv`Z>mMnP5IL;vvJd_;DHPwPp zeD1+L_5{xupbZhL9^5sb379CC@dtnM_{&>S+Z>{=kAVRt5AAq>;^vzv3=BA~pkN zpg*&VgI3gK6kh^;@3c4++;ZpDtCI{^s%d}LAb9eBUC1tlfei5%nsFhNRAHFt;rATd zW>+wqs)(AW`y(M+XwFb;<72!dj~(CL)XSl`LbMxI<=JjSriiw;hx@xOkYXwkY0$o) z^~w0sTYgf75(cZz_uZ9n5P2~8zhG=Q+8_&VBM23N+ga zeJaT_bKthu+pf#*3ldE>|N3=eFh#tkjVKr(9VFl66B#NS;9F$Yg~)$bP)eqRnXb6Q zQ8=`aP~AT2i6VyzrX-UkQ$Y5#NExJ;ti*BDW8qTJi&3ALT}n$!D*`wIH|cDSj%p?= zSsd}79Y)Je@XvTq;1Z%+{$PehJWV`e{Tf8cp2CtM_3|Z$(`4l7=*vMn<|IY#tvY&U~&mXLf z6BWE7fJnc(a^)qNk7duA8plCDjiKKy{7U|z8aziS$)T^h7rtFiDNcLNso~CT>VPqh9L!lspexu{fL%0Rw}aCUVC`qb6oKMkwnX}7o2S{wru4p2%I@$eVh%_4DRsM4Pt3o-)?Dr9ixj^t zTzRHjup-&v`Hiez&ev#Rq)o&)6JDIe=h{p-bazc|JBO=0=!`NMu(~h(qSDA9pEe^Y zSp2~MF6F?L;~4bOth9CTT%VIM)$15d#l~^X&B|nwC_XHq3Et zIgOah-Au5V)*k5;Z%wlDS@B_ky6SQP$7}WP>;eA)0D(FmKd|Rp;rF2MejAC%m{d6- z;dEya#NXoqWPFZG9wd>tE!!J3Q4aym4}C|4{z*j1<`YRmNFebU{6ubT5fG9LeUodS z2>7Q=2N(}ttegNIB=T4LMq>gbI>D-;l{BI0x9RomHI4jv1PU=*1C5(1jBwb!AifLw6i+hpG;|3df!L3HNMz$D7X*;AfYmINm zahdSPFKeUF?{;Fb}zvzn33^2$0>F9WOy()%Ws3>duH`? zIIHPc4?cWvBI_I28CReDjs!(uv##QL%9=cW*V-U5sUx@M-{pIjjQ*Sb9w6D?&o2#lUJJ4(>s$-cZ7Fezx0q%q0gvNw!WIYe0mSYQ> zr>W+()!1$lU#f@C0L10~lXczqqB@M?bE&m&j|&C{$0>*uc(@6CRL%$~F8y0|ORA^o z(Y@;vs9dtG&!S-`QF`8}jzLsb*HHgc9YmKDx^9e?;G#?~aK#MtVgE3-Xgj6uRTnqAzTedjf^0z5M zfZnP$!?N$9>%eLk!qfT97-Sa$)loE|<2Ep&;!y;tZVTGpv| zJKwT%E z{^Hm;ljVsn!DU_haai;8vmE}F;gU9cF2AK__T-Ah1q)yy*)SQD=PWzLD^91feACq6 z#6>Dq1*{(csiDizNp2h;p*wb=x6QevoF0i>HWUP+1^bQ&zYayBCg!gYx){&FW#n@6!jjh#T@9e-e z<^5?^34;d>_Y81EoC03+K2iIG3L+uLII21BG32h$mJjz?S zxh1;nKWRFw--pZ``dyFFkcpo1ZOUcI3(VkMUlC+m<)Ogz9G$=>yZ4)Jniu-N@6~8= zJVcllejY33=HEFMIO^`ncT5=zM*~+ggTYKOG(~0P0#h0kz5v}&wt^OBP+v)Q^=L{pH)riKbwI-nE#!awiCvO{3n+{*(_Aij9N z`i9D5JyJfqUqbqdOme$nihUiep!PWh903`mP$n$d6cCxJ+B>)+1s1agT+iMob;8m(J_V* zaeMpZ!JOA&mX5w>Q+*hIKb6nxc5LKi{cFZ*v)64xgMJ*X>->xa)dqJ3yDeAIign_B zH&=bDX};C_@Wn&Wi%&wAvM5@=n353hH`>Ub(aw{t!in+_Lv#8bAHJ(KHyu2Xw_QkGDr!{aj z>yf(Wd0Ce%Z~q!U9rK%VDTj>`edR?a)3?=~onskF(+mMS!B!ZTd%w{u$vmIf;RfHc zTX#O@Jq`s8BE0kY_hZIun^4l4P9L(6Jq0*lHu8~dScK|7cINOY@yhVuFV3!4II&5D z>k4+;fV;vH&uAyN!}$wH_;Q3QNM;BlS$_2tTXANS-|Q|k*W1MW#G1S=;XJc!seyxH zLl-)Jpb2Ti(ThCk2d(XJ43=dh9vO5XB>KO1s@Cd@)jG#9tZyPo+To<|hl>qSo;@6# z#uHin{Q=#ukwM1&ca$MAp|FRN4M*#n-aVWLqm(+ZM4=2PKw?h*aW(P3g^ee!c4NhX z44pD(K5fgLFR-zxts{X}KBVjQv6G>c@Nv0Xv4yjIq_*%mXNY-9^k8nal|-;jD@h^^ z%|h1r_COgH3h7-^Wr=??uv!{RK~~Q4D2P~i4c?Lssk;i|dQn(EPJoLK|MdGO6Y>JA z4%4}dmq>Td7fK!dRh~i9#(?<+2+%C0&%-h%NHzt=SiT1AF9}bBE*5p)-1ah z%@1T_?qA)=!tiI`BmadvBHuvC2E4tKSyE`Ti}3p)z6(_f}amtDQ;>ooN> zV(0*OVW>_lUF}gV>;?Um1Q}OB#BnYbkpi;9U@sTG0g!JfJd-PP|0 zN!CVk3tzJFk)T5&u_TwTeG1Lu}W$G3A|EP3 z8OmTdb?#>Wj2ZX@Jw#pI(<4IC#w63r$dTU+=I=_S^w>y=kA`I2!Pv7r(r6&VhI!0g zeuoVsvtMqk>M1|^k+5vx!W^)hP+l8D|8`bC&``m z81N-x$4b_<Ho;wqnFcEoCT&?PkUCRE+Ctn0fIK4h{}-a&iKl0{r+Y2c6gHkSROC z@B0ccnw64iML=UF0?qMH8_=Y8OqU9!dVbl>m#mCQIFrf#y`yb<>FT%J{(h!BYHn%U ztJA`t)iH0q^YZ+RB=simYoleQb)aqOG1i5eH;z@`v~qHG#JlLp^Jjrm4rI8%qFFy` z$3({sJRLV{)gBR`1oS?nX2iDXGr^k->Nj{8{rxSpQB=aX3(-4s_>#Cr{S5{sS&5R) zrEI@8>U~ThFTSL|7afhWBf~$*&S9lP2E@`Q0lQnS zuB)qSL~vhrIk4)nyZzhAvHKe(I!Hu$@7`Q~pBIu$sw~#h&Fc@}lBBNC>y{Tq&k$Cx z4mG^kMwKjQ$z9OzCTd1WE9{L{$GO+j%O6Fw#p2>C8PiTTNJHEu9I!Z8>kxezf0j=P zoB)()nnim{NpA2ED+B^*3(eyz(Zq*6x319IGv?R<*-v=rNlzZDVH&(ul1T@$V{@|m z91{bum4r=4Q`Ba9Xj2y4;lN>>J1@e1r3Xsqawjgf@S@V&@&Z zk4U234jC+Oh;)uO+)pbOX!0$DX`2nS3~SPYaE@wQAR<7xknr?(!(A%1-`M`6k2?5- z6xaETmlp-JeXt~6Z+YIG$_v0jr2dqYBbQvAh*0SjAkOa!BS?$L%bCW`A@h>6n7$a=Md*v;mHi!HqZ6v)ip=(stojgf>Kz3zomu6v? zPmq04aFeZZdbv+aQ`1*~I3^oxBU83O7egLnN}iu3wDCi!$i@w>4lyk*;CFBL@^j=- zSABiGvCJ}uq^2`hrEFHCq5?@DAE5lgtprokWs{0R+Z_x;M$wZ|3I!exC2OF-lg->D z$w&Yig;7R#dUrchy)MKn%XYx>g~L6gb7h-I7kTn@TI6|YB|y`VhN1$Od*SSF{YVkCtH-xO9%L?G>$ zOoI7yM~`gFw4;qo?&?Ez=FkIoa2VKQ)BNmurYl4V=ncz~-4@$TDpp6r4b`W&=W z%FbM!XE0ORq$`8=C~>T{#NpC$cPnd|z^=nH;gV!nTSkj$-8OtYyH7D@K7Zu;9dNM6 zC_(`>W3x#ugVxXrGI2(rHLD#!&JbL56?xL-V= zP&|MPdAIhVnNyK|o&y<(Btkz%r)K(_eN-kHn`?|sT?Bd8m0RDRI0e#7PlcJq)Y)~-n6R0#m<-IsLVu=yeU*{;=Mg8D^53h~BZ354g28KS zC$})xoGUanv93qPVn!~9&AeLz2L}8;j73}TS8TSvA5fq=%I3Pj>&+h|q@g1J1|mnY zN-QWth#wb-g8cTTilq~L1@hqr4-V=bU%VztAl=1DctAluQ{-{c?nyE?O(QTkn|(lLVJ5SdFtZogvj2P~%8 zQleGPMEEI_n1-Ri2LDH=gTuq0Ka@OvO|w7oIlFiz4otI4AvEUTq4!fg9TxI9U_6%L zs#4xT15DyfW)s@YPs*+s6+@gFsSQ~fU(AG)3Qa|E;Q zXM~9wXCv$}K}c<)Aq>A%n4Xty+}hOd+0#^hK(dtT#^_fBk!O1!t*20TGoqTpE|}7# zr<%GvNYn8tAt>v&b+r2ghRs>SOF@D_-G(FyqiPlZW@l$RJWc@0aqy`aJSH|P?%%)O zRbK9kTaGXFy=MmmwjO*$k}5rq1d@_xEH9A^7#heO4HB06fMmuPsjkYJS7ib*Q7VoT zg-nx^7X#f5uag0c$19#!2Jv{GE?z8q)uKaX*{D+(7LEkg-w1K000qybhK53BmrANE zy5vebN#Q~K1C6?%2Wc?55Wh@1%j;KZdc4S|mhynz%bFs_O^cPOSF;P$K`9k0_QonlB&wOC zk@WpZ*p&WaodMI4zDqt;8d^x$zar)cn92e4N=i5*Q!nwajOF=b29W+gj2=OuY z##X2xh~D$}K(ainVvdf$BFPT&ZD~@OfaQ%w%f~S2y%`4>H5d9sC%+71>vn|BlU{|GN)= z4A0I2Ri_Nf3P3bL3V-<-d-}Go$s?h_7yV0i8Yi|w0mpx#Gcid?m{D4yECAmMG|kb( zFbZ`vIEjuZ3wOPdm~#I}V8Da^($)#SKZgmQZU_RAr5SFnnRa(D>ApK(Q}@j~_5p;f zCbxqFHv#gP`g5nC1CO9F5Sq>h&Pfpw5e*D8j$Qt{YJ=O}@CF^#?(HMwJuOE{=N)HP}_1TC2|+9VTF=RxlVW0lqkwczNgLw_)g z*zGb%e|3VXGohqhFVN@eGiqM*Yy>n!j#g?6Uh~WEM@e3*g{or;l?CC1(;jzA@#vNN zWou}P0Vf}Css43L@w#V$_#gY1L+4r!o9Hsul+eNArD0nI`CP3+G?o@R@lwTLaCTM8 zA<8YLOg)~}GyoFoPQrp=#s2ye!!@Xthr>H6lc90_>OIUxtxySuyag=J=Cygd1>PAPJrQ@?DJEVkiJ ziiNEx^6%k9P}Sd@d)&{M6)-z{t=ej9nGYDEf3iVcxl>7}^A&uSVliTqrQ}5dg^40I z7Cbq?=_4o7+O(}Q}YYvsj7xn_2VbNfh9hmPk#o0#>vWjXp4VV+Vq(}`CX)qSEzj7ZO{ARK@s52$huyB#U56o_@$e)!(RW8 zU%X&Zol_>xiRUoWHsJmp%ZLWfEt&GWEuKtaT%=A}9>z~Gl9)9%c?m5;i^@DxQuw0Y zA&Q;X7ycQ;<{vG~r2$@hw<~_@j<#F`$Ri>~JB+);&oZtTebIJ7-E5T5!~u`b)(kI0 zS7nE7`{`F{8V3zmS1w`we;-~v_<*nnzsIpU0OZus!IMpfkJl|PbL^R_KK$a=PO)ni z&GuHS1ReRzZ?@{a$j3IHCCrkIAPUc^uzt1%7E9a9OcA#LW;my)d;b__Zm>I);a&C> z?`tPW$Ps|Mvl(IRF#VS=;)S!^C&a970eXnkKR@V(GFC|7a*#dakG_FHo(v_WtQb5i5<8IGz4Df){tWtieNAuRwWY11Vn)tC zbpUy25~rsGq%)r%GdAG9dibF}RBNa9<1UW1n!t8H^`jWEII-}$V_&Zg55og}WXg$# znZrii>izwF#A*YNnZ1>QN1%8=Py0EIN~I=gc^E4p<}wDsm@uKXeAK%S7bk^Wg`}}-$txO7( zQ~~-#iqw#hkSunq1K0K{23nMsYyC&a@2_y=((^Sl(whXRf~aG{0`8*)3|)Z>2jVxD ze2mz!{l-= zoMp#cdy~4q~8U$MJTb*&&$At)n=)>t~#Hw%3j~ z6M1ly3X++gmymNG{^VJ8tM;)TZa8MI`tLl2q14n*BSg$OJQN_~?STm3_F7a0h-UI) z%h&@9Wb789I|oLA<`76k1i-)*W2I=NA2GA)ri;oL-ko|p^xllACwBfEc*_1mUuYY@ z3y5f3TEE~=}mbMWi@8Ro3r+77jv zJc-&(HYN3fc#sfNTa4EkCzx?0>od^(Hup!GMZQLq^fa74DpMcD5^c@nk&Ks^>1-(e zjJV#_)Io1L?ET0YRk_TG4SXwn7+zl1R4YFEU2i5;4A^q5vtdEN!-%ev)5Wh}0Jd|(+lfR@3>j^|(Dzm2;wf(`lsrn5TbcT0E~ z(lEn|I(~PCyBz7-%Bri`Z;&5!K88XCMqS>llK^g(rsqQ6@@-20;XaV%jP`lrnsX9r;(C zIHUJV;`N!N(S`~kuGu;<6Gq`G>dE^J^696Wob#gA&_;8k)9l;!vhs579SnPw#wVa9 zKp=%dIIcYQw!+SVw9o8-K<~i%cA|=t4C@8!K6MEaA{cy#G0Lw;;kDnWN>6z=<<4H| z!-0}VkoJwaLgug0eDoA1IAbAK%Q3o*+kuLL?#L(w5ZmOn_7d{}e~?%Wu3m{0c;b$)SQmW}^I z9>C13;F_A3clG=J9A$1|v%A}S0>&Dm@Uv9(aFp~&de&RlPq z`d~i%xHG@;}JFx7KBR%*+QN8qIJ{{To9`hNhzxlVzgy;GUey;W&3M5k2g4ucyok%2#AWsiE1aMR5zo}(2vJH zwHyZ=E%=nqXUZq?C2HOg*RNK&f0{@qZEPRdWt|6>FoK!?^`2}pWtma|@SAv)hQUQZ z(+xf(lnU5}g9!dx(Y!XUhdA6dKBGSX zI(Lib*_v>7YtUHkaZ|bZo`}yzsw`EyKlR&fXU=oc07mPhjX5pfC^Uz|T?wNif#3L} z?+@lQ4WWki=V=dI1=xv5Clo!KusQn_pkfkjPb03c0n#l@MQ^V2cX%qf@)jtV5yuyk zpjC}GdGw<{8M-tiI@?T;HnlZ=>kIR7bMd3uQZ`DGEAc$X>%7V5JX9nBt`kvb4qa}( z)rI4{`1Y=ozRY(})N`~1dM>~`_+4Z@Aur}<=*>0W(VvjELpdcDOpYvhVDMuXw^mj$ zbY7S^Wh;vIN6Yl$voMw$I8oK9^Y2qmMW|ovdviy}za6+^^7=X_+PeJ|5(FI@^PdJz z#5y;>8bnAF$IJn=OY@4ssVh+b`$|)>c;m`Nycm?K1h)EECY^|W>s;5Y%1Xg;<;oeu z=}<}Q;k>Me*s?gspov}rl4VEBJ7`u=Aj}*~W~M-0O^K`z2s6|4?^B1wmFbmSebrk3 zm~aC|a&qc7r(IIH~*bkg)l3@N?C&d8W6HK4aqk_O={+eDlPUvEtZj z76;Iws~7)7$J@|rLTkv#<|msX&H>wi3waW*9MyuYI@~Q>>0eI2)dT)+>4qM`_FnQAvml{gzH^g)Z1~9Fm7ViJgz;6~j_tTU2d1 z5r{|}kUH#uvpfZ@l=yENam3>cpY3zjxRBw`@mp=; zQnM2HEAXWuq^G6^r^Lpu3e%tJ4~RIw<-x%$?6MzEOy}~*qYWW>?VJ0_zPO1zoIr4v zF?PD#qh;tO=GZi@o~AMqA{Ahn6$IC>|2wwlB0z%GNpIGz#*~Brsrqc^(-Hr6+|3@RGp?=llMB8Y+@Y|4AxJn*L%w zQG=*$J493SVth||Io!eo3SRAd{`}6}^J1%E@WlCv#)+T6+s2rt2_H?8{^-;at-G^ot!CJA zQA#|EK$l+w=VLxL=t&!5#9i)J3WaLL*FpL?yHhccjRLxPqAD(21d!+dZNVs&+?4nf zaOVCqh{oz)^3UlAa+K%P1qltV^5?N|@GoF>UU?rzL#+e%6WQcFgc@WLTQgK!UKR^$ zVk@c;`M~Qx_oMGThe^U)X>lb9XS|K?gBeT4Hk%?6u#vkVMNX{E!Q5FR(jF+>w46n( zNT9YqVtL=C5y>@fHrz&#XsB@vgCR1l$~T#B^JMSvpC@)RJM5=+Hb{ulu~>0tM#!(! z=saZGKZ|+WQ>u@lv$9o)BERgft?4qkKfG5%Vc@~?`a4^#$QZe=c`Tgp7@Fgd3Wyhr z0aJ+u#;8e)Qw^qzP?%4BKCodBWU0z;hoS7Ygf!N=6tX;m8~pU`19`iX`Xf8+hT1`L z{}PVR?h}JJKErS|>aOMCWjjLRV&b<0V)Jg5-W(qNv|ERDWgIBTJ_cBxJgS%H4&WmR z6LanpzC7ENJ}}fdyi_&n@dGzDc7m64v|fq&_p}CeY<_->i#343#Nv&)&OPPvnh=jLlwLVOOJ*I*DLJaxYC(=(tzQvCoDu#_Ox( zAseks=ghFRzP?+JlYkl}9#FyUb;=RF><&oias@`q=C8oI;y<}zSW+qP&%7Rl-X>d- zdCX957^h|$oeKjWyUe z>jH&Nx2rb8p`?13jENFjIRLLoHnzxPrYVHh_8cvoAgzXJCnNiqal!Dmk(Pt>ybf_g zJjn7D+sJz-Y6Z#$?ytKX+Yx6rvA)l0ob5?}lAza#QQ&KeQ*@PIL`I{C#ph*>14Qa| zM6-AF?9u=sBM%QwG5FW;Ico+cCMG(%5a55AWdvxQ^eIn!OT_$i&GPs2<@a{*-4^?A z3rGLo7A{$=5?9YK0dz5oX!8`MfpIxPvPf_5Bldc~Q_qU1g)4%&BU|=}<}o zrv3X*Md{@sgLup{S*Hxa45^|{JnqUYceCGW02j^G@Z`eM!mPg>wn82jIH~1d%i9tY z5v4Wiz-|unpKtend}qg>E3XkJwJ;E(0b6Ffx9bC1+cY^1jts+s&b^7G1PBm0c2H9w zs(M0~^cm6F$Lnt`q~QjnFB%riz7Q-O`8b<4NP3?-7mj?CLk~?6M-j%LLqXmOie{Cv zHgkFWONy0;=HpaXhpH`Vg%@W61{7%twOgvrD6W_}*QfC6wF9^JF zgs$zgsVnQ4;y?D-zjFO8WKHPP#w{E7-_A4qENwM0>d|P~Bv{(LR}d2DRMH;JKWIYk zMMQCf-v2y;J-&9#T zbqTpJT0{l%{;s8!1K@+=;?By5_5U(w^N5Dn*NQjP>6ElDMbA0Mdz>^N?9QAA3M6+B<{Y%Bi^q}i7`>oyyl9O$+F!W^WSJJcju~Ybe9Z%z?elo zj}PlV>(s}X4U4ebHuA${&))CtbF0nY&U_6|OIw@Xr@ulBjEKJVrm?kqcdq*npJm7< z4~f*3RVod7Q%o54dI#>w2sh8ORI(E=l-1%$Bvy8T8H zE9L@yo%8GLO7HY)du#uH!>ua&sV_z^m)S5+gjtQN_JDrVohq`WzhBMjz6>MKb_UE) z6@nYGIarOG1PXT6gg;`?&ri-Gj0`Ut7g-p&DbiHOAn;Xl3Nlu8$nG!eee;7TV?Xi{ z1oh=+07NC<>L6pC=o}vG4Feu(Hbn^)<^q95$V|MHQh6_3bTO_R1s4ns<7<#Hk~sp2 zz`T1$_t+jZX!qWYB87&xVYO=J(2a+XXlSe?ZK6IDAzN8eW9-Yh$ldBd?kdUGSLc8$ zEF;ybq2##4l;3;oQiCW1*3clrfm`}c(GuE!Bvha>FGB~}^Sux|1%~MY%QQf4N zh-|)!#nw`z=$LPT>%Tmf@V?TGKD1HeOjb0lKqBX!;08SRdnKcbqMOJpp^aYoz6B8C zaDVzha*8!&$C;Gg{kK@*>~eJrTrfT(@eA=tCGR<)8oo?4_ZDM8iJ$OHld8<)#(!3( z&NAO+AgaLpu}g%h6|U`iXQ9DF^F_9K`)^JEyHCg!Oho=&z&x`pbw#9T){l=#c48;< z0DJeBu2ldYHD?X@j$q|=027U0YQPv-oJmmS$6sFenG!OUJ`QAb4Ab{^vF&uYUT>N* zx|Ov`fw-*HB)P%k2K?AnBr*>C?*QmWI)PZQ>*`eG;__PWplcov1QO6RD7MjwDIyK` zP1j|0!;l`Fl8z$LX&pbHhX7?Vp01{_Mk1u~S7YJ0Oq6;0cXKYfnA<5P;?sX}>bws1 z)0+H6v3bX0kWLQ54heNJ3l|?bvqCNup$d*V@4O10|X}C>X1?!pkjmeT963sdcsK1 zdM;h%Lz>CweEJim(48+#gYb@~=zZvg+5i1^H{<^9p<5WY#jHI(zy(vW#5#r>m;ISmdORM9?Gvnk2%LSwjDT{-O2S7*I;h4>->AhCj7uUE zcwV2w%*26*8Wq6&kPi*^h52<-yuB%6?A(~Pt+B>Ap~k_(hp(Z5XV&ND+cI)Jo;x8z z4T!|{7c1`cb*bU2%uu7qiToZ;@aex!$n{Q~%_PX+?o50NNz{V#OD&?_8snlI-^ZM~ zk2Jn9@6Ia}k|R`nRMh8Hz0iVE5WHE-L4gRqaVez93j_V}y>ZW(V($wornluIYioX* z;?%e}6^2Ap<%olLkAfR@0mW!>b$@4nn*oE2;TMPi!K`tQw2K zglLm5{uh{+RNTuSYO8JTO(}x~VL|ba!_@^!hL9^=^i1bc;I8x^$cb)%W4xD^RBZRE7$t z_&QB1#rW#>^87+}cvkFB3md$}g@tTr-eiaVnK)>apykU4p^EssUjO?l4kCu8HlXq2 zr{k^|zVJHssUlKI>V>p6nWK32)tmaG6`9>BxAXh*M@do9PQ<;|S_%nm_Bh!wqFZ|y zYlVv>Mf+A+WC8RKpKbq?&3`vf90~;gh@+7$g#28i`p3;__#bYG^j+P69m&v5<*5F? z=h-xN=I}-xM?KBA&j;FEXD7zxqqW^$KN*rxdU+*q{J?3JBfD_7-a7p7>Cnj#3kmu) zP*@Bg--h1Y`U;BC7R*$F<&r6d5=h}eppmx9$}hwT;_%{yi9k7(--}6M!Ar*|B=MV+ z>3_?a>%ZlEqs(!46+rT&oPMQ!0~g;Tc!3f-4SMfA<99j#)AnQcJEd&TyT^L0S5;K zTBXG7TZ9a!yzO<*?Ym01JQ$bTljpMs+X$}YO}v=j+C^hVMu>P+IterO^)a22D?}u; zmGIP-+o-=Dbw<|JW1RRpKkCIP<^qp;et`c)q_p6aMzcpYc$qQt0TGrZM|hVcK;cZL zaIa=&M)#@w0t~+g3T9!U4k*ai+{4VSx(0g?ZFO77q7TWgAEiIeBUKFjjEiYTXIiI> z0dg;L#?NF=QH6gcbs0jFuYRYFDMkG~9jVwok|)NHS#TzwUL(XcmRwL5 zNrcv?qKZ%Oe6LpO?iklsQJLFvoW8VrjZQHTq;b^mY#umkv$)EYp{(NbAWAi1WX4B^ z1w6>Qx^neD2e-8)T5rRWQgac;lMqWEM~;`Q)@Kk;v8^nWd>_3GYgdd}UX{+~ah@L# zuP^N%{>Ysjp(M>M1lE`Lrq<77z_=4jmNNR( z#l^0^XXiQV;i#d-Z{?LMUjljx1sU~rTD_kG`N!m$lo^(+1@ZyWSxoNkza%u|Gw2Xd zB#D3BVI)CmOX)gu^voDf1MtL>DDg?N)&A*nG&Q;7pr$<%(k!nV1;mo5Nj98qsilha zcK7eM)5^5EnuMjBmrhyD4l1MoaCzh^||K3bHK4;BAt&YX^W8RoxoW{el7+R!iBlLUMw1_}H zA;YG?{o3^x0DSyiiUQ?i)BBm?2PpB|Qe5L#$F@h_eTk3}DXeWT9K-2vNh2dtZ+#$H z5oh9X>ycDp%LXr``$NS7{>D3VMNQv~W$DglxC&TC{%(Lp1V8@kK3ZwgH4#Y4!@iG>2(?$ams7xSOE zZqGmEK_GZ|U8s(V6vDd&1)9dBuBuD?k?fI6U$QjkzP#iIx3w^Esd@3Bx;v8p{T+IY zhLuKiRELl3veY!WCMRj9i^tcB(OooW1bu{QlQr>i=ju%cv^5EeanH1f@e-%0qW|gLHRycXuO5cXvxmcZrlV zhi>Wa&ind}asT+&arE7LueIh}^KmgJbvw;L5%7JQ!#~yJXGo9KJHk0 zEGZ1T1A?9+hv@4^lT;3}Ty5$!s>`%4jFw-|%KsPA;J*4~9qx zt+HpUsi!Yo_Ag9TlR8XA7r=l)y}{8Y4Url3iV^+(TSK`vL9RI0|LI+W!t?no(i!iI zrC}!>tBCveKg;y94PMVucK(WCp0YHvp-~F0c6y>3$>WS*C#l#93Je=m0h(bcw-fcRJcJ zvrFSHrcS-L?U~|5(Q+32#ZP$WxwyjvR|&LBdIu`$F*Cl(@*jWE2-v(pmaKs&E>GXd z<6UFp166l=+jIf8oN#WZO8v2sp!4M|fB&XK;RJ9^+aYxV81PKTZ7*CJoWnIQznq`U zcKgdNInnwRuK|NL;57e}vQc4}+)s7>tB~=<6oJHk5J(J=ae>?`pvD6Iqo@;r3>a|$ zOzvAZ@jqWSN|X?3^0uxHC5{vthl?) znc6e5CaWjyao8_RE|yP$OC$nFl98KO$w&+N3k&NY6CoPrYD!%T=SaP2IH9#X1j770 zvDL1lFG52ko$;j>KcIH%PX=L!<&;${%kVGu!wR=>-tkGVHdjvBZH}2a^Ah?$T-j1P zd1mj{D$wEu7Q|_*SuQjmDC7lY^LaNB!xNNh`*>m?lZQ3z(>Cu^1ooJtceKr1Shb`| zOjy3`Q{?{OWvYTR@~}Q=B%JQL+kyn7bkrktH_-W#HAzEJn@*zP zw0|P}lhJns7^Ru}qPM|Om_dc{F%VR|R8guM9&_gSqCfgv&IE#+*>912_lU6-+?ZcG z=azgY)*ux{if47IIu3m;`1rvGpM|B7q0l9Gz$D-zK`$;z_&^2W02rA;9OV_;m2L77 zYPER@ylB?W(?wrh{`Jhg;X9wZSHxC<>n``TpOv+tg7Bc9m82HA!*GY%XeN|W;_$lb zo0-Yi@01s39p<(!wu=RxAGY-*Vv)u~tydq07BXjdP_iPG%8^W%(}TtdJzpm4Jn1!4 za6=tA3E=Z5YZYQkHR4B3!n+TH6yD3=V0Uq~6lS^e>ohJI)%w&MD^CoKK$qHIpFUcb zOJ+;9v5faBd)frOWzK6Aqh}5D2+#bqbj!}Y;UPLoRDUO^yJW$D`LWHg%gY3FvEfN-QiJH9mi^feYk4Lyapi?Zw7g)U<;QF6zB;SnSY z0Vtg|Dc+~rXyJg||2O=ag#u;6=dprAmuf#j>NOAy3QCG!%_*ctHV;FvMb?~pCnBl+ z>Dwl2$pNkiMsUa1xQW;?HO_T<#MwU$s;K0o+_8|h(`3UGQMabEQ=Fupc-+KMtq+-b zjXdyD-#{{f&j_nTwFK^Wb<#OU5f88#d-n~bg7C*~-n@jlju3`u+4aO(wBO}HNFtja ztSNQ1Vz466`0wXfnbSL|TR*4VyZxx3uhN+Fd3)9klmCpLb+K?SYfA=JYC}ezcZbo; z_<|Uhe-6oKxxFi7$n``3X^4Tq!4`~Ff0$vTe#S!(gGEDzspk1S4x9zn*w;9A%9=g~ zokNyxfMhj!EIE!;wT3DkJZ^VAF%uz0C?L!(0UinjA9U`)3zket*2wjIt~PHzIU^Xh z(V_$r07Jjc!m^DhLI=X1zma5)IT3LDOA8}OW7!i3gmK<|_6FS91M@yHiG|8&&a|~> z=NHc~hv@|GKuO7|SO|3%7mFw7|Mvpa8vqJq2QfT2(C?-y6Z3{!77|0q&kBP8BvOMV zSKj(~&U~+L1ADK+MT3aHcR?stO);o>v2p427ra*0GyU?9ib#o8o9zvW&#n8qu5ZRg zLM_qZg>oS?(XgXC1f!lu>>AgG5kEt~UuZJNm%hn?h(Xx(R(bvI_cFA&DU=z7xXHw* z{lwVn^L~nq>9R2~$fO}zZi7DwT5WU0O(ca-6Na}hoP$@5FXxg21LRk{%?=gpE6L(0 zu_6g9Tc0n-ZfA1RcLj%kFZ?j5KTDT0!&Ft>M*1LIjiR#MNMB*uOiUYn z`=&{);-3HjPf`K1XJLGrHmGRuZH6L@HG%?^CRZZcM+`_2Has5OdaN4<;+NwJZ>}$p;|JB*Rxi^?ByASNkMS!m>-Fyj#hY#$DFcy(MZPSC zF`}rw7sTK=Q6%Qj2_*zoCm^uwP^w?02HxNH=3LV^bdI3?`U{A0oUv;%M+ zH%UBxHWADF#f+QYfRdfw#8dT)df>zjaLPhhZQ1d^2T`l9YPh9g#-n|eSt)~R-COCo zy;}!t5J0SzAbTd#H{mk^ZlWBSR-}TGej-dYkC2=&0Hf^SH-SZNjR?R2Z!i7URx>Ax$+qys?{!%bJOdQal|yHh`^Zn3*M99W$OU%EMwZjG28|Gnl9{t*xT!lc z2z2qF$*YdKtIa=2y>b88Q^kOX7nFMUJ+IqqPtCmNk%qdBTmY867|(h`MITMS zIujz@^j2Sa=~=+f>HQU~?@3(GeRX`MhkREO7=CMi*6}yr6$ZAwy&V{@E}sAuJ-l!z zDQmGstp=vpKUqv7fmpJju~BvYX0_eDp4Qu@`w%_nJY~W1#l$pwoe^;r^w6>E^ol~7 z_9TX&?yQWLK9R%y9hTnvc2cOJj+^qGdEe@Ma$S^@8S|+E#GfBu1a+>RR;-M%2Je*b z#kT&OVuoBBCZ%LSoY0o9%iO@xy0QEbXdSF+9Mmfr2KqWX`G7rum>9ROjAM~sSkg!6 zPk@W;-^atB+kM?D{TVsTGQ&2N_Tg|`Kv%Pp5%CKSqEUwJO)D$nZG`y9(TO%=a{N_v zvBJDbIx4;*eUh7=^PX4Rl(>1{(1n}b;j{y{j-GOI#6X1>v;f`L)T`vu8KG<=t{^kX zwuS~56BC$SXQ*~trMX&5Vo{Qy>qtbgxThy^OlT1p#J=Y~>6+<_^JI0s44w zpg`^TUu>m|1s(_z14vaXD=QVv<*{d9*XNWK&M0$fO64#xG)S~j7(nAyAwUU{LW@L# z?9;s#Py29Yg8iYOKFsc}^K@ znfj)3ZPHESdRZ6A&W@)sV!})qD?Wb%RC+No=`)MpW=Go1yplO^p{Kc3=oc4+P+>wC z31e9hSr{1|ZawJHz z_l4}hkwStKG1OU7)5<*;n)$w$*EBtgl+8v{m+o`%0(fw%4mX=`92UHuplbZaVCcYkV-IFDxJ35>$7Kysru4k^-+!A!{(5D&lhE^ z6QXxds?#O|F3E>IWsdJ?UYV*x0=5%8a*B0FuaaT`WiFIDH91*UJ`DIyC?lK(WJHx0 z@3+r$w$Il{pdsIjScvWV$Mll2Bd?>SrM(klwym#M z2}qnNK&1khV2wNXsy@xeX5$TEnZoq&P)y)~l6a2qsC(18>ehL)f5NaTlcB-^gc$0l82xN16i+&NDOfrJUld zz&K}+NYJS_8#`TXr=g)KEhzz&6mM#2`su382n(fvja|SM2NP;Dr5}PeSa4wiEDGSd z{FF_dUsS-(7r#Dg&imgF_$_i*WBAcu%=od$rjBFU_Fj%>E)jSQ4r?RT*Gd_MrMFk+&WRw8! zDX!jH?+5b}ryB!$97L(w1=Z-}xB`E|vwDM%=>Y{lETF$9Y0fs(S>J82WiI72f8113 zx_`8R`4s7`Z0R^Se3QzBPn63k4*;Nk-EzBF3UEQN2p&9+=h(OQK)+Dh9+ke4f+-Q8 z@nE0_^^{MXxjsjxz7!RM$VumX`|u&}$>E^^ZLi}dbN)orOK?_@Ju%xsV2g^=GPDF_ z)y#XZvPUAr5=RVz$sM-t=!;-^U&mu3S9_kDB* zNP|YTNvWxWTNhVLAEL%I9+htx=#$KeLkLWlUk~#ux)%&Yr|^>d*mb2VDmx7DxJOtxFUZp9+8NJ5%e8ynJljA}UvkU1RT z%;D*eGD`%@%I%ud1uop(W3J=}u`Aw}neXtZ!}(SonV3Az-XEu~@>|PRfF+;!GY)p! z{oa;41)i$!Ru(ZXJXTKJ81y9Is1HLW$}*F$>RKKH^h>3i%K0lQcv$L-DKXHD6``rSJWaZIz93kfqQ?*P+DNU&PiTMD+ zTacKMlhfldn}dNgx*oG_ZFu+U!4`c9BH&`~{S-z-kb#p!Ro2`B?W3sVfza-Lzv^Jd ziqFy5aJ%6)IQ~7ZF#jG``(Wa> zCNnA+R2{(t(W{`0!5lACkl+*;lvh~T$0{3wI&iRev_F$e%`V9^5qSB$a{Mnnv1 zkl;tAT+MF3msaOJwHm$bksXT+cE`Pajg!TnccPnt6+uENq`=n({1UI2PySbp3?=Q4 z>eZTp5Et3W4EkR<3tFa0|pu?j?&_GxxqIrmpwL2Po z0!mIXM-PvMDc-X_4*jMn7kYILHa1l`?6ysGQi=VsqEPeC`0U>chUzLyECGM1rIi&P z9-b6|G;h;I8%$v|b{oRCU;Wtnyj)yV5u5XuN3S1wAjus^*BtIqyiK)Lcx6t(?^Hc+ z7B#t3M>L^_SbvHoiHXN&`yH6S(`VEyqWa@<%@1GuPW=Qo*7fojVLErEl2ch2VP^^D zaBeJ0ev#VB28*5zH>2#Hs^Uvf&nHG-*k^D1xTq$iP~tkE4!Xq*x) z0)(Tcf@aq);5QbGOa&!ZqaNgI%CSp)%i{cm@>s4h(wC)Xy;CVBT^r|}QPk}-siUyW zi_Q&RZz=}oP6Qz^_R!s2amTvp-E4fsia7f-XKnjYQVAaP1%KzmJEvqfEVY5e8=BXz z#t_?gp%NZCKPaUapU32$N)i&vdwYd4BT<6B;_vu9)eMe(hYv6`dI!q;^XMU;UzHr1 z(PP?4PACmrF-q&WX3FZ{KXJ;f*B)Jjal}aMb#FPfvdVse4+4iTWk}rwvzW}+>VH01 zajHVcx}?{D_bL zqKNr+;f14(=_{(r*Gy||^ud_pQp!L7K2g!_!CV&xZEkr;L;51F=CBZic`B3eh;LdE z!?N3K+hD)$NGg-x&sf1+$|8b9;<9hvJH@8M3hrrT<~OUAOC_#8K|R=(^Da`D!q9LS zY8HNnvF?C9h}KGjOf#qK+D3C`EhwSrH=^78XhFjaFv3Faod;RatAHekD zRnrd9i~_4y>y#YH`vl)rNNphOf+#Hm}mWrm&IgBkS$iU`Mv zudcxQUGE?2_7Y3=xBJpiOLDoahueN>*wDXXf72}}2hmV>he(S?jEYAieE5OgZrYK5 z>N`&8@ZQzndZtymOi421*d!1-MHpKOpcHFrYO1SGy9df1X4GSZd2oG?#yGH&lew0- zHx3}BKwOfntZW7us0RmBfy9j1w(9%b-@IZb9cg(@+ql59!~6|PCNr6K#|#aWaOnWq zrJAn}@&1j`raB)1SV!`Sg@hvpz(|tlet*lgxzL0BFO%B*ALe3n?in1t`gst=Kahe@ zpI%;{jt+4W5{iG_(QChD>N2FkP7Soz8nfq6Mn&&@{d%3P72KL^kS~hESC;DZJ zsMAkxmNf|c6sh^=gp87q7NuqI>)dKnk*%e4z5=6caKVot+T2X|lXGNtiz|_o@=WT` zp3+O19Bdf0XNZSWlEIXIo4FPFFY6i^@A6a_zAn?`pjoRO&m4m)Q$KTByvA)pGRbMI z4kBY4qbS+qpZKng-lm@FJ;tYz43W%j$ZUp<&qL~dH>K-cto*3SbgUsOGai81{MppN zWw$_6R0b)G!KlOhNJC(pI)yoxPmN{$)%lFN_aEO0poB?DN$J=%wdL4qY54D-@rCK1 zJpC$EzxUyng#cZ+8%|hrTk5AqBe6D(I7TsOF`+oEO-sMas&{vcFgN|t^E6DbBCJZN z4u7aAA9-p%uQs%vK1y2?$f=V9Vm9!w15G3euVca6tZh60qU$xje*4PVojUu&KzlvF zgCl4d6Qb4F$Xc(hnC#xqSXQ%nTh1#O64S&ZoU7-^nK2=&F`@Ba@M|&wyX?Xjpf1A? zIWw~gHtAdlUQH3b66eaky=G3lx0cezUqUf?%w|7rs#%X4Hp@7cq6gv7lRb z#N#`{`3CzPihQe{f!uuwjVN05ou7Zcf`<04EDN4w-9O=O*i)6I8BVLP?;VbDZ-ulb zBO7lHVMLZ^&GIkp;R1v_VIP-_9bAgD&-?;_g`GKFhB;jn9#Df%X{Ft;nMEaOWUUXT z;PCgRT%$%6F~i}35_vBYm`VB2v-aH|R@nPY`^u@a1zgb~{s|>JgO`2A+ z@d9&6#9uNxU<03yOkr8?nJpJn0q6&&ODM(HOApYUPlE8Vb$1{vWp)7_039UQRYmg-8%c5fcgo$g1e!Cd{}L zBWvCd5k_jV$Rn=O(m0_2O+|t7SMFe^FtxA;apu=^+9#KBQtJ>Z{F)) zj#3mJga*XuA(#8#8?;sXAW*9Xd{7Ug41H#Ldb+2t`|}@$$|1RHtBi{|9wK~lq8vGB zkY~=i%fqAj`)1oNQz2jFWX%Vp_TUM#a4_L++M@x+K7V{j4k?(C5vpIAeQCEWt$Q+ivN)-zk*dHf3N-nb(O8n3&D{J;T~RJ2`;`(du{c0@0Mfb7EQc5CTJC zbRc7Kr;CB19BPzLVr?ke4jE@67+5fMpP#RWZ;=wpA;iPucHWJuJ_53)joCAA<{L5P z{M(xC*#m@_vE&E0=AU=X7pPV`O?EnI<{zru{vF`&{~cfzSpkP*PAt)BVPnXO0J9r4 zD~WuF45T4h6=|>@G9_vbdzkNQkjViKS`lPPocze8PROze@ z%{F+w^>6i9yZhPe_4Odi8cyA^r@v*Z;Us+EY5i2!TH1)|)5%%ajO*=>0}iCm6%kaQ z&i4b#k8nVUl1q6*TYCv)s$_)Hyu8`H(2=q$M(KGn1FW1uU?87%)+%~%i#}C)`lltd z$Y8n6T=+Z+3QA^4x(s<{W@ay}Tk}Z;Fx_5WYd`tG0df>meD?DPz(!vSi3%ax!}j*o zwIwI(O^XFg>ek-7*MbFn`E**VKVwR9Wg&=t@UlCI7$`CQayR2nLBXbUfr1}om7kvW zM{Mg1aawgwZKyB2m}m~TcNdK4b7LspH8}cdcjn_tr>FpSJy>#LWOKafcW@6@`C$2I zq<&DZI4PR$Jn$8kSQbz^5l~D~O#kT}tsFoT>+8vgF~yZe58dBf{M~qAavh34$3VI_ zT)1LA;p?&b`AApq$=W{my&gQsgPzb-`FlEppQ5G(#j)O$^?7LZ5fG|1vGaajg5^+r20CRMSrCeq15t}(4tT$>u zpWCBukAQ+@c4^R`P?5nyU*p|Sh(>Ia_LyR=M!?&kpRywX z259q~G16dkR#|r!7a-~Z!s?k5hT5dDq2)oFI>zGE!=S%ObCdp&aP~_^ffDANL zz?ntAm(q?MDqLN7`#CENS?#@^=gy}HqmSQ~dgDL4X|rz}Yj+jh_86KZJyc1e8`EmF zK0ZF`oHnkF-hAs|!k>%9?zVz%4aq+?J5gaTIxkZkoV@=LLMN1_&XhtS{_<&?b}W8` zSwGNCV+dQWYgyU#$Xm2`Mx{QEh3=57tTLHF)m1k)E6asD8(0JdnvOh+L%p}Vx2H~b zcqyu~TruFgOln!l83<0X;4ZebV!d4Wt?`<72j5SNP>XP8VO{zG9i%{si5?zeXaxD~ z9V>et)LiuY9mxzUU81Bm4qKvQa!Lv`XbFlDe)FvF9l4m$$9-6`Oxl@`FP)n~@XWFS zz~LRJs5o3dJMAuW^R;*1*SywKEx$Ii>ZQHtkhbXySBvcb#fa!IK$j@}EBu@0x|>+< z1Fzhkzdg=-kRbhSGaJ9TRS=}(a76!2(n;;`jHlbmdSpqJF4*6LVewZTnGie)*-xZo zB-#zDGk^RuVoN^TYm&%MP}RomC>_9hMv4(SAwMlD-*ZC*n8 zQpkt#>Cf`S)}Y!fNlcN1=R1~FcX|scb0zl7s>;eJ@bJ{sR6;^Rem+U;APYBoc6vPH zdvGrSAG22hiztLr#d6wCKOUmUfAcr0Z_)khN5*THDOLa_JTNeDcyvUw^w8J)w|lJX zLVu@O%US-7j(2h!%N91f(EegQg_5xSbrV0+_v)*8s6DsaL;ce&rQSz*u?Qze zH%bvm1G?NPAs?`(2#imFd^#^LFQ5wmK*W=is1sK->eVKiSkH-;83hK7aCvmZv}%M( zsF$CX?EW39S^mqQ*7TpJ(>gCqpV&?vF2qg5t&+nRT~krQQAVvs^7mbCRsanS5B zCx$^4RT}2Wed>#;@r?!lS4Ic@cZwx~JYJ7b_&TlS3AY*w=r_`S&x9D_04fm9)<|ZO znR~{KI&F20#*7LINHA_?!e1HInQiDyMeS3LHm0)w2Qms*iMl|GQ#z`!(s(qK;4ZFkdk zTQo)e^+h~Jr(Eyh!yBP!+#kl6$jltyZ4X5yD!dgpb#Z34Y{xdPptQy1ZmXjL45!=0 z6)t!*cG;Lc@;>G6kFtx&1iK#)fEw&{iCYQS483~bJ$T=50KE+wM)k+@G_juDR`9EWX4p#cfZdfMMVIYWp)OBbhbRUyGVEITmk0AViaG1mkHd5hNS`pug*w`ktCIl!&p z!*5@|2-FoO^^0z&E4c75>^2L631E=H?DLW~HFQl#No;O#YO6{_f!Fxp07bnLTH27Z zK0^+V`#4(H*pq->ui+~xz)N6eEyT|-gi1#| zxOxCKVTDjl>+Ag@GSpOQQ+||LF44eOm__kT4Mgmq3Ohi3fJ!EGoWtdzdkR;}Af??J z{ysH|x5sXc3^&0-FbD+s#a24E{x(pEwPqMcT-Q2(>lp3D4um!*N?TW;(o*2P3_kOF zh)RNd5M^sr1p?W-F9qx!lCnp!6?}G=wda5D}GHwzamlc6Sp2_ngPmkfI>u-vs`G!YP>pQBHzg4?p7E49X(=h7?&Oq@Cj>g!sU9dTr&SvdB;7 z`h3^ZKe+b0`x1Q1psG>C4;dvqMz{Z3Q9$Mh?uCBXi2vxP{4Av*J=* zA#_mQkr%USqmL&f{);$#D>8J9e>HmI^D;-`2=Ff}l$Pc$wK_{J5$wA%df^v`i2E3xA-5FcYs0SXfbwU zRP=3VpJ7Vlb!@RV52DQ>$k--BFLmpJVeLEGf@i@|_UmM!dS$1z&9Q;7QvJc-vdS?t z8ag^Q*{kj0L|{4On=sVWB<{^XW&D%+>&6s{zC;st$Dj{BLvw`|mhcax9HJu{?K%<# zTB%+c!(M!r&c?hKV%NRCoAp10lZg+1V)^2|O+g?SgH(^K+Utdgta!q{9+=!f5M+1R zIFLQbC+{Vhe%-X#XmS5wco@4FO?~DU{_6t+7W&GRZzrH*V)g?m=JsnH5fKppWY#dM zQ}4`5!e)~|fZv1Anw%aB7kU`R5^46yYV~2iRQemhhGxTz6f0eoWZu88hU`ecNNfA? zFf$h%c}Yr!gC*rkfe?MGi~;SYvo$1a7tZ6RnAo?j`ACghBJWN7W(`_sSqNd+qF%0a zDda*WuR7cU@VJ=M*`@6BH8?u-t!;TfP27f!-$wf#ghuXha1XRmnB5SdMUzD2$K@~x zSIxXvj%aro+ujBw0lVh*y1GjmwWFu01GMFq(zwd+Hw{fJU;4!2_b7uv*!v6TDX9vV z@T6#h@D=2(;_DX|YZa#&iU3tmQi&F8%acD{=8{){iRmKz#buxk7ZX{_bzGIxT{l}y zxx@(ebbei*dXFgx2DI_goxNMhIQN-Mk{<_~sKdILcp58PZbvy-gs<=uk3rY86|*Kx z2i$dKk~0f?%Fc%r;tzGGOj%h1RRH?e`o9{UKbIkKSTG?d35pm72lSm-avBvVoiQln z0O(Rk95Fm#?J?C1B2F0oUALo3ca?<|$;lLdct(^d7d_yC0+s|U!7xT#pvfWtG7yPB zE-$XnySO)iI4zhqAotjSU(%YDJ_`+4;Vj;J|TZL$jf|;EY0!s-5?V*-UdOB zNr!JHsLslskh%7T29^P(@rR%u9G-tS1y~Z$eANz@G!{5HuJ`NDZfDgzY)SngpQPI- zT+EnpYvzHH;(4git(gz=9pz& z?&L+4B$XjjHsjdc*Tj;jfL=6#@L_lKfgm1+1QiApP^$%SJbPe)z~Fh;koT}h+IF#~ zq}TI9*BLEX-e-byhG*$WVG>GL+(X4T>YP=EV%jQwDE+T-86j0^-KCB@@W!vMWUZSizK@FEfRyystS9$&P!v= zmelt@nEulano+d80$22Kv>Ew&47yLX4~BU1A0~T1lw6+-&T%ud9OlBIYf}Ba9M*Yk zTb-o}rl41cW`_U1Xj7+j>5?bm0@%+eg4OAH2c|fI37&cK=oo$Go#df%@-~V&_ z(ByI$yC+V({eGPA_WJC-s~42?yM|A2mR9LYu_@D^(kBF-cDaXW0Z|TU2t+P8-rZSy={nP-hIEe0!I)4 z1Z*hKPVdGIZM$r^E`(Q#I45uF-5cA-^FG)rXq_HZ%o>dET}}IFMEy9%*YOc83Kz zChCh}3P2(Lo`=ES-F0Xr|MC_gNvSwpM}N$L*XD=9{a}-MLIbMB*5G^c@Q!a}biG*a zXeK~3J#%_gzfpO43BgE{IPRH!oD^w4C&XBpm*%!>16yE2+)m1QPGPetpLwFx74!5O^wT1|3-hR37TZYFke=OXm+5V!-@j;Yruo$7eY973EW7 zaUJB~KdTi0#G}NdjJSO8K^4x7W~$Z6d8u7~f$RN~FvRJ*2|uu4)tFHNtoZ?Kov=Ot zH7vYc;$-JILr=ooO8kjC-m*?h3_cL_?pFh zftIkjfa<%Xv=l%I^}NN94?D&7G0LhdzVz?RgFu|&YCK_ z!SQCwgj*F0id*tizaMnzyo*YjOKRFA6ovI%0CV|ckYIdKVaY?^YUjG{YMv!C}Mj(;fyiH%DXTrTrvh{m~Rms;c+7_{z%N=$bIy+tRo9x~tl!ig$-ae`YloFa` zY>C~^IXnGE!0+r*cPFCr{fG$3M_jZS?p9+ZSkk9hGfhd;u0bF{7YaZ=Jtdxv*?k}5 z<%d+{?Jer&ARdPu-amy<0Oo=&S3X{eRfKo#AA5f2&w!b!sdz< z?!@GzQc0VemCePBHq{%bts6Qa|LF5W;Vw9v!7UAMcw0%$N_1XIxeQnVRv|{Eq@gLK ztfSttwXhm8tA8*tt8M51aq1(5#Eiw!vf(~q^YmwRzHMbrgH?njBwumX^f)yO$^KWL z-n>M*9zda|PrdT$JaExcP4d>Umc3BUPz6g$4i=-o$p5H=4zL3W))F^DznyYMw8|)R zjK+Yt6kwWrV(dS#KS+Yc{Q4)L}oW)xr>4gh>n9cf%KG z;;41r>-AAmO4)qk_u71_vi{E5y|pl;n%Zz(K9wltF~1=AjRJKR3DP5>DKhQC7AA}% z1nR^paa-#xzCJM)zXLR-)RD%4;E&&e01x}1B4+Z4#@Z5lHf3yz5a;ZW;d!?W<65@< z135iSY{BD}9hk-Prb znXUO$OXNLNLZ+smfGvACAUC7Sy23C6-au9L-&6}4 z^sM$2Q^N<4LOwtPzKRFZ-Yl*+fu5gL<&MJ}lZ2sWpB#dhAFP%($*7i2f0D`!jl`xsAv&hQO3wKkk|H6T!JaHLCX;E!!h8UuA0(9zQD+CtaVHL( zIpq)E`|{PE)@AA+&k`b52%qDMu#AlS$xhx;3!S}$P51(py*o^O1^82GN6J*J z8XI8@6oz(Fw52U02E=ZfWHL<~t(WulK3Hy9QW>Hq6Lg!~Tn;2CHN$=iNH+f{)-NGe z*VrLhd%P}3P~!P&;^bD0qG990DO{zwlbIpK`%vq2R*VSK(%2ZibL{OVQ^N8SY{$yx zyeQ)YDBGyQ0C!Jl2)oF6ubDZ8Q5Y2v&N*`^a(ztKWz}idZvVU{B;b|ecPaS@!CJL9 z46&VxVg0`9fE+}LlKOQE;2@GG4j(}7m~P}1yhi?%3!HJexUtzoVLK4)-96b?=v`d} zHcO_|W;bBKpFC{*9(pLlKh?EtUZ#pL!XZzWK?m@aX#)QIr>A-W?8*p!Vu}(C7v9cS z%^uyar_NzTv_qe^8XD8$VS@6Q*hv^ket~eD;+0ezE&cdQ|IUb_dc*bvOr%M4KfKbQ z*!dq7O86N|j~%Phfi?nP58e@dLyRt=Op^G`<-M-qQ<~cT2B*!CnUl5Be)8O5+5sDM z<359Q6YJ8+PVa(o=l6H_Sz@zTH+PrS$klu2=r<=QK=?69FOTxQku#xoofTx$X1=z6 zr?D8hf{Ty8`@tvwd^M*Ci{;QdTVR{h&cGngG`TE)b|?&XaqDyhHHnz zJ&bn5PzFPL0s6L-aQKp~3=wGngvzA8AA^G1n>yIOT0X(0!K$l5%B#_vYr4mV!)|qn3kWPZ;#wnS6%t?>Zu+F97W=g9)W|l{Bmx| zyaS1a1D8wQSP;2nLIEXUBn$!prhkgKe?=?W0B7pR*!cL|+?+6cuYi!m42OWP!Ycyu}`rjQk1^-z5YL+(6re{k@L z*!)wrbj!0h){|dh+$wroeW{I2UnSIH=HT#CgVygrTA!MZicSJH)bQ(g7=^&GD0hC6 zW=mUM&WKJ!o6Xd;*nv!4Ls8VXBRXrk63bUly)oxL@z~b~`UvTYxjLfGrrSj#+syq~ zgU>jj7mxaDXSlUX7EU3cTcL#a&VztzSmiw4JU z0Q6&}rRAc(Z_foXTJ|_OGg>z3^5$}!X}t_gEV#QR} z0_iU>_Dc%Zpu=e0my&Sh^bYWzEb;6ZjmACotO{;0RhVi4u~fqLKd}#Re`l0PCWt~@ z=u?$3Hc#+#Gov%gDvOTZw-6J?#>T|FUauShv6#$J&>t9CU5u@KQcCs#OX)~ml?t5^ zpGk*4R(HQqt&Y>6Bptq@CKI#b%szvd2#;IWedvKh@~%eezVz=zYSqab@L0L}`cKA< z8dNbk#bV_{8thbQpI$D-?-yCvpghYZz>WHLTT%EUx?w6Lj8Tft#uEF=(j|e6k5wGP z3TfrB#HoJV_>!;iU0K!AirUq4o&-cGxF%y~t2d*isCRJ}96x^1o0?D>$>tWeepjiR zaRNIknu50QHXTfg$`wdMMWrYJS<8_trK0L|I8g>0IdiR^l&BD(6u;t2ben0Oo-Z)` zNs#yGTwCr|Xl7kqz@g>yK8EkF6Av5c>M%0w+1v8;GcpoRC>r^J|CaMSQtiu!g8?64 zoNY`YA4cFdBO=$i=(?LC76}DvQ@h`O@sjJ{$gCPFK~ATprm96kdeiy#21M3?K&9hy z$16N53bxw5ju=7hQo*@`@TGl|jDeOQ%>fpc_woYCMDb_szGJ|mEaL#dU~+2e8|~G_ z$EL69n~r?h^AY7`iQj=fKa`}*%EIC?IrTOsM)dGdy5i_3F+8epDFhesJw85uFD#A$ zJn_B1aRxUChvefw2cpP7OVgOkDkCCG{C7{@93Ury@*kQ*Ru&0}zd(SPSRLB0`5OdN zMqrA`5@;Z4%WboiW8Rq>g%pbhqZS~5KoQm75)WbrMDAEsPr#-1+t;yoC~x@(S~c_D zKn5(ZLDRiX6#X?e%H991Q-J0aEP7rQsJ8kWCjdQ{f|jMmZ(;b1=+9TO;ygo}@K~rI z;Ujx(UNq-*FXyA!2>a13XcT$=`iH8LCw85ha_WJFy(<#vT12>r6m`G)SVoQSsC>r! z*ZWHNbYSMK2jMxR+TWXsLBu$rLhx03Z7#YZ%LZfHp3hBe=_QIpQEZoRJJq50LGRA(>uV3Ib9&Q@h90GcN%z-@CzyQ_-RLirsN>IR@<}MB%hoiU^-k{RflRAt7kt zR0*bzXwo<%JosOyTe^0?Jk8XZc?+wT+N#xl0F4c-!ns#xt;Xoqg+u}{BCcCJURX$5 zK3Qw=!5(ZuBxkpyB1R8H@X=eh7Fd#NSD}}}US^UbM<6GbY^$U1x!_I8FE7tU?vz-n zUmMabSspd3=M+$+M1(Dn=VnP)_Lkp?W>XWH0Jd24eNpF3lvh4gUV= z0*2@FJ2k3`vdQOok^MlhHx0sx8qJ_%Vq#*b;UzDFR`By}F}*lY_2PtDWz6xaZ0ez5 zC$D$c+WP7S3qsZ(A0Uv$w=Q$vk(}4+!mSYo+jg?tk;fOmfHBnywdhdv@N2&S!#4*f z51Y5-%oBR|wm6iO`>wgwtAymY$H2P@HzLCGlpI}u?LHM7pv&EFv&-1MzrQD=bij$y z<5JG|9>t}CeYIrIex1(EIm-Fy9aHKt-sR|QDpDv5VXc@gx5OK00W80uyv(omE}J!_ z?r$bLvL%+x0LC<_fHGWE7&T;Zaq(}L{Y6KU#leKAHhu^Uuxz&;04OrgJpBa+XFeym zLMAWC)0aCVH~;oSV-o6VG2g%PPAurzI(&l!)VmCFI#NZ2)=qmb;#Zr?aDzmnh7ccW>=#^{jiu{cUkwejce$1Bjgl zV(=(%wtxj2;Xp(f=zoJE+H@Q$6_`(HI-0$DkBjEH@%lf0{IIaG0SfzwY7+PH8Ocu{F-$$A#o%i58>?OF#{wwybV&&Srld$q6K z-kihAhE9SAI!|3f;&SzC5J!_t4dZWPXuQb418A8UKu?#IlM|Da?8&#%+dpn&oCbbW>`tmAiBY*zkt~Vp!}&&n`V@(V?WIA1ZPf88YGAMoBqoc8^3VeL=*-2 zr!`u#?-nj~O(`@ei!lpue(l$86$LtNmacnKulA=4Y63&UY|H}-X7#{KlTqeBZS(l( z2*NsMRJ-lOr900in|aLFJ#~~6A$I<)cU0lE{or@m<#fyGaV^AB7^wZ&9c1r@|VgQ zq(?zhUyYSd5n`G8ds`XsGMMl_pG3I=^kMj*pMEcoI`kX>yugL~?NZMC=MP=4Pc5g` zSDkwL)Hi8bm_*MiSSmr#An+)qq}}sPq5HW0^c2f;GVD!)Lgn?MT+A45R(h03@gF5J zN%WCAWr!t+STq16!EtaWpmntQo>m;|Ou9H!N* z1H3iQu4WUeOC1=$8I2WSW&cz_zmpW3KYJd5m=6@hTm_XF!s6o8*U`#bN&RNb$jlr$ zEH4d_dGoN*p3e_f#wHE%)ppYM_HHMJucJL`8)uXOGPnAT=ub6_`DQ)0nShy6|W~zUxg!{_e-}VA6al6L7oCJU?6kBi6U@YTWWl;9Chb#2VGU-`ukI zdwyj4WstpQpTY)*Doq>$jQwB?fh{uwgPt8H)uxG0&QN&K`B5S7+$xV2`ds!(SL)jH z^9{f9xjSr_hAuG{@1TmIW8n!JSd|q2(&w_%?Q9CU(twrhT#hd1rIdUAcXxMp*TDh_?jGFTg1ZHW;O={W|2=#5I~*9e-M72ms;3zE_qEwLbF#l5>8o!8 zq8118P8!`lih_j;!*yd5U@4SYXkyPhIs7&t^UWlk$|7U`&+=uG7J%)|%g6w>)R(QD zE*=6mt9H-B1pE0iwMU-~quQlYw+mRVv3XXNQ4kWtJmC;Q>sgup%W|<&Z?1l$RVul3 z!K3Y=C+p9S>90)q5MxqSUcPC!^i!82i<1ZX1y7gVvT7z9&CcFl?KQh*!K>cN`3(dzeIz6Ep7?_vNR$QOJ3>F+l3RT(tXi9a} zi4Sz=Iy`=zOt^P*77zCLb;eKHD5w=$F?2NJv-N}-fw1m1I1@wvoDs7 zieqq@-(mIY;J%Uuk$6To8s^S^s_ex>#TNidlXz|GmkXvXs$UmB_D@~04Wu$Yb@Y9O zIl$a}>q*@^%d&$W&5>T5X4{IZW%Y%s+U%&HJD8m=ugwIKV3*G(eV4T>G)6FRJ2 z&fNIulR9xJIn`^9V(Y&%Cm0%*5dsz#`hD}nvB!YcYdjPe30SxrR!;$+KC7+&>mSrJ zlrGI31<1a2AFfI9JFdY(#k=MIUFWo)CLo}I(PO}B!N^eR=3R;07r=A~sTw_w?8sqy zH$)n$kMDf085k6SKYv~3TF~qK+kF4#`%X~IL&s*Xc@nJPdvZAaGl^UY%d}C8CMrso zyDL)CWfuF==V>6nFM=F7Yzc<)_}ji%PnV^!mS8paQsU3@fN_p%2asAS*~R9d z>C*atUI3-Y22JZ@3~Q%mnzQnV9ScPR)0O7^o|9ya~0iY```$LibD)%zUmo5J1Zm(r7xj!8w&Q*bB%C=@X`vV=p zvL7J`%wc9?LXL+#*;e64)5qTYqA`mmw{3)u9DBmi^Ji0EBM3gal%PdNVipTomNl4Z zNn9#%iJ4j!QTeSrnt)u*n7S8;(J0cUuF$W1_Z+S3T~aNZIzGzgw{s2+HbXw6)Tm66`hx%5sl_etggZSet%ei@*@vIgzvs$% zM8!tpHUYr`(mHEvX=leNr-JIY$a_sbwn@YcX}O6e)*KVli4m@CNTI!3|1-DZSM>8S zwHRf^cd*i3fBWtlmur1!*{zj`m_!wvK$z)~mwHx(;j7uYXl*auzZb{$S^4OU*oJ#Z8l{vQicYGMwg_t9&Qk?_$-Jd?vW&tWzqTt(Vd;5x z{jBWRJua6YEV`6YsF0V~*%%ho$^1TmQ_ zT($vfpAJw_^_KK!P99APgv{{5aOyB4p5uo$7#XbJ76f$hwp!uq>7r^aMFDq2z?6uC zogk*^EY2_0I|>3q-Vhy7K7)em;zBFjhpF8K6p#2uWI2mP9X%>ss*ScEWu*H?xC>nY zED$a4^3yUM}MqWg>r5lX`MAg$x8c?>2dzVsH!5f^SlVC(O|(??_*h|s;pgweN5}OOK4G-f(tq=X z+oMlj9O*mUXO$}Uvc2dsA?P-m@e|2Y`$3wmrxgrp+V#t`o!Fn*)#T)`Q;xFdbrMI* zaggkrS7Al6Gc!x8t0m#r&ol)v?bk-TevUx0(W~?Hi%l^K1{NK8p-6C7U$Iw%Dtq9< z2Sh%lloaSBRC38V8yOW;RmG9O$ESZ+lf%H?uyVk;{wI|J_||yHTU=ZCjrmT*!6}}y z=_wbxU1F(jYyiWXs?Iap^JG#-k^lA@M<`tOiQ6N}-)&QTUd1kK z56?LcBVNWTt?F0DIl*_|=ep+H^-$BYDpq*vFFEqbSj$UG5iDusG-&WK`j;+OM0yY- z8=PVzT37%F2}=0+1zX6I`Q{IkJq5$xq6O9SxdubLC1#MQS)??y!8XHy=(d68+iZ|x zt3d29M$9-8uCjXW^YWsfmaj~s<=?8=p>JBN;w@Rw8X*yec(L{EL~<%zO!SD-mKJEx z8|*GK>_Lq21t-WeVmy>i_py@>B6s(GUGL+WD9!#uABdY-d8Etggl!tqQ#aeq=F7k8 znzONijOl*J=;qtgFDs^#J(c{`4jy`mxW7WVfW3i@DiBk9zx$~$3RkDK9QUvm^r~>Z z>VtI(O9Ev!@sua=-$|XFDn6&{Wpqzv8jz(yARL{i;mOyMIse%LST1yl*FVcjEkFK% z*KSUu*XQq$UOUvw=TB~dx*GU=rd_||KFJ!(sH7zT8nU(~tCTWzpxx=?DJdB~w3BH1 zm@{53??sDiA;yk?7J`+?xH4EgGjAGTgcia~7eds;4eW%8gd>kO1GzM|dH{s;?O0ns z>l?148yOo+TrONkpdb6HUe)6_t>`5+@V_wW6UEkrUXa!N0jC6`YXA zH1Pbp(=(*MS$dY=Y7`X=n=p;Lq#b@QE&5gSS2Q^ZEZtC6axLn1kWW5^5nC7q*vOce zn6RR1HDs-Ie@0P-8yp63I~sdjT5C^|m~gntC5jz&7q-+tmdTlCliG2+rinoHJB5k@ zC39$Cbi@;!xJFG+Vid&z&(uHs}6C27(&ypNQAXu;-w%@3{PXIp^4S zSkEh)B#QG{;P&BszghzuF+7(*kOc;7cUKlE8V|8VOPHHV1JB&>Y7XPHbq+3mu}9Nl zhLuD2k1FiXZiOq}VVqwrdP=2KUg7?+!S8NwKJdaY#+V{O z+~s}xe=o5lB<$gi+Hl!FudRD`6BS^y1i=q8OC=$QIU9w5@Rn$<2rACSjXuG|KzVxo z`0X$|(l-dj3`@!J-oF9+-A*rCNM8w91%?oeefnQ;27#~TJ>Qzi1wQEK`R2ZDr_?LV;)|@BTHdpX_g<0&CbQ0XT&-O~f|aNm0~M4uZ)@ zf|M>lN~e)7dAWI%&zip9+cw!xlGcdTa&i(PQY8c29aKVYgXUF0QehcXFIU4Fs5hVb z6lMr9laYxovINo&SmFaammJm$<7%s@_e4H!?dfwDA-QZ=BsfR92U(qyc};DH&)+xi z4zsEw(I)90iqpo}WyZvhbeCXxdkPApcZ^@3QxnywF;K$q&o}K^;AaN0xu7bB4V1&y zg=I}N`*kP@w6mXiOo};**6Sw6Lhem~nrJySv8v0(qr{;#HB^%;;vAkfnIHbI!%2Mt zrGm8huZB-voDx`$X}cEw8d(Q+yr17Ynmu%5J1Ayx>iKL!MU`l!l(jI_qEK3I3V=1! zX1@Q$X5UHkD?LP6iR+a}KocaqGzBmPfcgv|<%VSb)4mxdE|8`GgU;AIYGmKpiqe|e zY2hY0vx(>R{|(Ku5kCkD9iKri8kPeEU>5 ztlK7fj?UjoQ3WnB(uj%d1=M9# zj`E|Q`tVM8C#hml-&!RW8z6`nSyr*vZArHir8iLFS>#f*LZ;7$q4_eLT`b@g1iBBJ zpQf=M2;tboNK*H$akwqx9==XZ@`*YNE;{qZe?t}@ghZ_d@%|9var?)mW;;e0XQA^b zd2SJp@WjH5kQ9({m7eGFFq%XI1Bx{@h2BGh#zE3nIYotQ{`YjlWxFtQ|Mqq{Mf{}2 ztL@{vTC0j8i3A6qKn}jwAi~dNkpm%sNZHW@Jcc)0Ss*GE0&1~UHAWw`Y$pNrQiDo! zIE!*ezGaLijy+1WWpiimk?$iMX2cho|LM%e7nu7%KZcT-0;=hed^$36vXe)0wlTRT zPL-1B{CN}>B5X|Uyga772u{pkG&BxZ3nQDt;%z)d>3F@Qqzf<6d6fs95Q4qcv-Xj; zt9{q|!nlj!^MZ2_;rqVtclCwV4<9}NG7(uK{8(MJz(coMm#+(L)_q(bja~s+3K^X! zqrC}I^dtvvLpyXz=bMcRCPAc_m$$cc5;9ycFnR&{h$;DQWkp{}fL;ZorurLq;XCG#AMn2|n!R6W7C5=HCqD5vnO@UM zB2iT%Iz8E$J(@?tA+M~u9s=w|oj!tHHp_JcWwcUaz)<^rzPYO7WfqA=n(M_)VjsRZ z2e#hK*Ybad>;KHmMI>011$|{@&>*}p8q2%L0vo)iU6Z7RGaHMp%h=?HwiExWqw*mM z6otvQe5E&N(SD##6d-JqW6;lQiNJlr2@x?43Dnpo$8;1a>m2!RS`S1~ZF1U$Pu*Zu7#~!3|g4 z@&O~7{}tcs7->U2G9B!fx983`-P%iH!wAyn>e z@R>CG$dAb<3%uONKW&Ft0RJTlnHb{Hk9-BbrN6XE5Ph6%LcFCK!@jglV(R;51LBQY z2s1w5%_eN(OJg7-QI-3excfW94A0EQ#zux;iL;sj)ZPEvzCmxX{pj{AH?ix?uEokT z61$=OGQOiiOarfc>VN`a=JbvlcHChcsH+0xGI8hP?Vd)9ui->L$8f^4!m4sd zFKPSS8ajGkCT(rbb&a#oY4Eaz5ZhxRX_!2ZWSRt zwse;eJ$M z`5E%nOiY#Pv_1hqA`z|EsJ4Xq8#7+}^(3D-#ob1(g4*m>aD0vH8C-!2t;iVJ<(B(F zA{cm80+bEvs7sG*05q^FhbHzv#1+7&1rS%8m%OL(>+NU5iC?xI9HvJ(pwe^5(Eu%c zOawS=zZDzC#1rui{%5$2Dgc21H!Ofd_s255QlZyrYX@>nx`?Fc^soxPSBKGEzORGC zIzLG%vXY43E}fBO?Axm%ivVJwbIaPo*XaSeg?%R;C9LA&Vt~Oz5&{f|sQ|FG0c5{F z(M|--#u*}y>IMSL%<#1J#m{wZFgi2?ZzkKcX{OlXo^@|+q3t!cyO3yppb_Kl{Oi8^ zCq|(44J?9;g7S8kr0rjGp2rvr2@)r@7bgTGlfmD`iQBHW3X1!Y?+*Ozvn##0(4FXd z(|XnomCpI-LtOICD3)gi?fx8WBC^9Q&$DI+nI*FOI}eCw+-rQJAvGg2$dk0Ew6!Pg*z?r$IQ`9&^5tYe0jGCn)k4NqdOz_?ebt5KwW6Zrn{ z=hR`NS1*R8Nvo2YX+vM->A6RG9gZDe^HZMk)Oy57+3DG-5M5ha>D@+8&r3lX!|MCS z0DgC)y}`9FZZxOI!Cm!hoo_T{rgb_GzkGC{Me%0GaAgM7R0sQwkHknsUALD^Vfz64 z$K>rqWE4Vqt~u`t^^+)54(*LZut@asXT!Q-qXBw_qy@q;zr1iWL84(xo4!I7h)sn( zHA8Rz2C9CBwo@TsDU_Q{d!y)kC(*IZIdUgWM)5U}-xL-O={{iY#uE;zd7_B`-=DR5 zj`0IzlGz5MTB(ZPTl7mPrdn0Y8lS+fKvp=&hVV0|_I|3M=^3(x%9s{`xBw1)rL5`O z(e)az-0W-A7Gq$Iq!AbcKZP_jlIgggH+HEzp^08!9^9*`#p-lfUP2b?rkAiHx5j1H zG}Q#yGwC3Yg{c&DX%mk_CwYqbG(j_RFkE#y!16OG1Rlqxt28Zwi}&rfgCAz39J9Xc zp6iS0vLA7JeB!4CaF|@r!8{bx*x9la*;Ov)C6&HbP+I$BYqOy94X z`@bp-&5fAhSTz#W+$r)!+Q!ZR6kQ$tS9sgM*C~ul+35lveV@MLl}`_oLQ!Ll%HY;jcNhIXIN6rtWiF8DH>MbFN={IcbHgx z&r>?>CYwty+uPfw7U%D&X@;jRq*HF{^L!4Ex{GmihX>i5CzpKDdU3hEh{w z0n9TZ@CRD%IY4zr?UNbADbW8i)q~jMiVsaxm+SM>228Rs8~XrC-c+lonT~VkTaRTH z)l1G$(|T8FQAGuP>bJ&*h6{dF;HULo^UKYSl@Tn!j=Cwt31cX+cj%D`e4Z**DF!|# zepqR_t!~Oi5It`(0y=KvTLFd znI1KwqOwK*Yps>(Yj=6xKF&L-;$LcpHA&uKz*Q@nf1z~9J5|ocrPrx5YI=Y0K`us9 z?9E1G0+kO=H3q%T$|%=FH${Ha^%^nw!06|f=lD4D)p`hwnS)X;Eijh6yL0Pi-jx~$ z29>owZbs|aNHQF{o6CIva-6NJggrY9JWNzp>qgl=lrx86eSi)z?F%^=x(FNk?#n5V ziWN;80uqHM+5NIHHYDVulou`~kDd)*Y8d`HL{RPd6zR@};q$h)-PWa4e6sTQalyk! zv~b)g36rp3qF@DvQ0_|_>|11MP-PSuiF7{Mv}8}yu8Z((DWu4>UK5WOd#vp>+Q3H` zCV<%oiyS>z3YGwv=>-fRelg8fr~centdNuaqT~u2F|fh*q;45QZ8j4cHP~IYWKkic zn?0Ic%yFFAhAP30OPW+H^f?A~UrSpXhBH+b0p?s=RSC_B^5!_RsVQ0#GOl0` zW-55dQE)2UFnxJ(F`NaC|GJV`hvJAPTlaEwb0b}~vDq2;PmIau^8a(-h7RloMjb#g z;}yTyU{a`F`WT9VgTrqak&$!M@$qpB2;g2K>D}Ag+u7OCtLFL~PrSYm>@2^z-@T;x zFYeeNkR~2s#FT)^inIc7B`Q+u_&x3c97@1Y?9)DUn#;z^J9^zdb#TJ(Y2jd@_1%V@ zhye=`5Q^J6J5D<)ci4n{Ut@Wk{cnbzowjS}$4(Y1je)E(6?`I+_W866&thW1u#tm8T1g}W|xJMCu#M<;v$gvtkkS8(x4{`namZ?R#9g{V4avDmkxOUAe{t6QL0YZ z<$?hjO!mJ)mj9=anvM=4pTHgN3np+~6W7`Y5cnM%K=b?trvJCC=e^UC_%HXW!Jb-RpBcmY03;}Qky-DtUn7`j8 zHY$-9BFu%;TYszX&h`ETU}PyPt7`MIDrwSh!5Bb}i zd_-|m!pe@Tb59!17?BI(Z{LkZ3Vu13d-R@MdjeONm_fzjx%8@0CVD|J z*<9IJC7<6MpT4PKcY2=o`cU3pJ)4uJ{AD{jkWjcaS8mm1JaPcObf))7=m-YKrU{P$ z1ybs;6vp}pn(*b&sARdxTGmlQdbQP`Kb4u(woPALIP>A!Cn3RyZ$l=^JLzC{B83}W zTKw>-`XcwPzaDdtcoJ*obv(r?sac7k=nXN%%6C<)g#I!-mUx+7r)2y+w(YZ;n(Im1 zt~lKTP_#v!Jd&8$b}IN0p;K{pGsh*D1bxV`7^$^3W2CPJ?UaR%SIlAP2|My3rf5v1 zsVj&K4Dz-{j8Jk3&eaotF}f@guDDRVK`SzFg^|lB%ShkLhEG(xfAV*~aNy38-u|`3 zo}81mI<~K2A*1FxF_rh$o!h9vI1ZA%p|l%*<3Uc<%_Lcf9O2Rjgt4Qb}ToZktaJ^y#YaDSZ6o{n7l^YtlV1iC+Q50#Z;NPRknk8mFVb8yG;`M>!9 zIuM|CVj+@Cn<^iM3UxJ`57pN8WDH0rC3KwfWmRRgjWfppn?5kTVMR8sU;ZW|11o|D ztO6{=AQF0=_P-B6CeayhSzNN00qF(s$(zW!P)S^DnUj#mo2~1d(XVc1=Hs(UaFYAy!wg>PL zW?X&WqJ|^aTVzEW9Z+Vw&3ZZ7sm^s%THH4zzAnI7YTbK{`xq)>1%W-S4yp{8e?!W7 zs6WP9S=yZyl$HYGhu2YIIuJh)m%&-Cv?H+MedsY+H~NBw_}JTw9nFj;y+%oPG_rtM?YpC~x0}(wyDNvP zeDyrS_(%GeEvx{rNk(>OsrMD11h1M(C$8wY=FvddD551&^?-GKujmDJe2&IgTyce|fA~wTI_?KEwY!FBmO>y)~e@U`4_NQ8Y z@dKw8;tM&Xh3Z$AF>m5j1%jkOb4-nU5(qS9Zo#3om3l70L-!8#edm!1iFNZof%RHCb*?AmYjwBS_MzguHut8qQ5XF$l8O+N0l?<~OA<+lE3VQd zgOn^;Gl$MN_D2(p2v)gdl8EEuqT<{a)U?`aozn{7G|9w-3l_l|03_WD!WOH~rw&az zco}ZXF&n;^=Jy{VVUZw_g#Nl%=Z}36Lpx}_O--CYz41vab(DNDrYJl>gT3DB3C7z2 zzCWerByk3ZZ@L%u?BGG^7bhkdNJ;^X;niJM*Y|m^o<7{6PlPUy156Nr)w1};}n|` zS_hT2wI)-`vL?0%l>~1Vv`^vFk>)!}mOc+S#Y5fPMb?aY07FzQtqjA$TbKX!Dv@YY z<8mIy9acJN*~ZPw>*?Qey)_r3ZhM*C``ONc^1(uia4yxl9Y5>C4CCm*!Mc!an14fo zD=*VcKim07*-jU~tA)Xuu|34FUSfB7`iiL?4D1uab`B(b&i1# z00;)A%RdU%QW0Jekd2fjBLcx>GTBIhf*dT2(ip|;dQN**u|aHXY~<2)%MD^^&sWop z6na=pO|99MXdc$8rN1(#vyplS$Ih#2wLC$Wz0uY$8$W)*!{_tV-7L08x>QCsQkY({ zzQq+E<|eAVtqc!w_6a$UN^xTVRl}?G#0DbMvGk(58w!{wi=?>+0R380Qqp?#EM=~E zmgZ+dxIAvtg&1dLt=;ewf*KUhtZzy2fiUX?>$uwZ7kbF?ny3^{GH6Gcd`jf^uZDfa zMKpwjR1-J8!m+;D&aEvm&c<%1iE=g?*cwcf zDdq$iG-c!-)@<@P)bZYzGc3)>@ z?0pg8<8mi`+quG6OagLz_H z<;ajs^vo5mwDZrAmGFxBiibZRCdaC~b|)tJ7UtfJjw&0IGs!qz;RBKbqY8wv?TV^d z0WRoE=XrHk{FGxIy?WZ_P>mFpzLJ`2J6aA6IV~+MK+*(``#ifVw?{QIvmf3evIfzx#82bxhXq$RxM-qy#%ZS2U2jj5lau}9sw-#y@&DkHKbew% zNV>UIaez=;Ss5I3;L(w#2pW*4q>cipkNNpf0J7t$zaQMk97M8Y!`ZbN&mvJPROH#2 z-=nRig-8n4cX%S&hCBE0k0FWJ%Q}dWi&6Xj{VROWJ1nWo2RHt8y{i_f>V@jgF417!>v^zIM*@$v)G z`M&{+WXvTWN@Wj0yZg5IN0f8EV!pVdvc|whd{A7>A10mj%MvzEhV=1LL9ee+ zUkMACPQ}E=PK=NL>E*K4@^^YY9g}xmr-&Rj$|poYOp%jPS{36jYawC!Gji#Sq8UcX zSXQPwOot{fFF(m(nllMYE^St~_LkfK9R5s;W(_&y>S`q;{5zS=<2)jMBE;t=Ok?4l z$75wzLlOlGhK3gb-+y)NkoAv9rIrb$7(gi9C_v|o0>Xu<-v-2wObrjq9QIg8*-~Zy zrDgZgn#QN)S-KfQt!>~XfDN6TSmm^Alqb#VkAfaLM$_;S)eq)ecsVLX029WDxumGt z92ipsAX)?3Th@8!)!{}Q{w#Tzu^ipE2BrjZ%}o%?ZM$XwD0p|bI@@MK%mwNEg(Q#d zIk{^`_#eA34&OsidUI)AFYc2swx5P; z@xpyM+-m#*ugz;z1O3e343D47m~bE)PqV44DSy>a-4@XWmo%wRZc|0=_uoTD^^7g0 zl!PdBWe_RyZ21F?&D6iYLKAL@1s;k;s}5aZQF7#D8&7=9j^Fsy-yWCOgR+bZG8Cb} zXk;D}?hA{P<#_RNob2qslxbpWsiR8$Iy$lrOBR`jakDwg=Z|O57m$@Hm^oeL$Y@Z2 z6apexc(L*1T-(F%kep-0tb7}J5N(HKjC1G#)2`c4AbF(Q=B@)jd$~RqSyi^wS&d+y8i>8 zGY@wvZ%Vz|ELn4zcYD3o_yayoo6*rQdM%De)4Ii{u{N5RaL<2I0WsXtD7kRxTTu>@0KcUZ-4#`)z?R{B?R4_ zhOuH4cz_(+)}0R~L&?d|dbBk*daHC=>S}8p-``$a4f(UApg=A`7mq%$)eO__M(kN@ zY(8%gX2#Il6deGm1RuI%s}L}z;z|L96rX-p&1n6%LVeu z_u!tb&4o%|i^V$+z$o&^(Pqp6VwvO%mo;Ys3Q$Tw`eC(dEXh2`;VeUY@W^}b8V~m` z;-N!ch=o-ag!}!7(MjD+&DBm=&OM&5n5qa-MIzBeA3_VlG{^n|Q$hm!>L>JnRdH3d z#y=rNJ2T$DACoDPG1p^1>T5QcJZ=(uPGgV>Jr3ndEBCcRNkJz8dpL+6Y$B;SaK~|7eofj8dI3JWqm7|xIzZ2RtbEVq!AZxqVM?WS}7Q}S^7_ZIv zW~Vgg*5zX}uwS&jz5U;z>MSo4uG}hU0*+=jYw7?g6P9vmK^NX9+bXZAK4J$X0vP(` zrpRVaZr%R9`JuzrRVe@H*XjhrAa@Fr8pSpDTl$**xNq9+k1L{_Nv~9AJ)&T^#`hd& zmE?1~8GH(p^dKl7i>ODN-@A=8>Fr$!o%_8Tn#_2l$uE|TXC%Aynf~2zw>&j9_0q%V zzP>m#+s3d0EOIl)g7t+amBJfoHuA9{jN|u@hQFaKD&b(!AiV_Do;|11vg2DXK!et* zr0ZJYw6{IYzMLlN=yPYXb8P`i_bM!xopR*R?I?7#@h7orGx$_eX0oca_fP`o6Xz?B zV#sAI)A>LFN#EiWc@h-UcmsOdFdUS#*a~H}D(Iupc$t-6B)&S|A38Vw(q?T3b_8p()QQP zp+W!2Fiw7>e*y6QXm0L(aLjR()S^hRQv?K1(r^?j! zR_)$y%TqA*+pIgDj3yuQdy;7sQL!lb~v8Bqo81NH3dnp|5@Pes!%;Sb;X^p)|Ankj5{oPtji{| zWrPC-nKlM=`CG*(czy1CH%em&s~D3=@_sbv*m)PU^JL)BcnAG!=KDh_x)pAyq^zcJW+%&OmRVL)Z%)L({8;AhiRI| zCMsBFq*$5U4N(MiR>DuTk64WSw%D~IL1IB~3zLKSyJYU^k&G!+y($FF&E5TLeD8jC zSpgXOEmkfy4|`L`tQ1Gw(aLIcaJjJJ1+Fc)Ye@c$HP{sg5MsJpQ9#}Bu+V{4_FI!N zGLyIfuh^6)QOd^j8uL=Rj~xVB>dnPY`n<(;hyfpHcL)mLB$($&esy4G#5W6`vium* zXk%q&w%;OJ_N2iwpp9<&2`v64XpcT(7sVa+yyMD4^Vj&E6ALmQgy?lo<^8VD`u#`L zlX>-x>SSa=?9}dc$b{Lpr$m~GX6Fa%sRx*z%m;fb{Qb)9zGwQpIC8^^;5=!u4W~y z+23J@c$?_Pi=sh+bM{AjMfMJT?p|Us;yMT>pf<4905WZ3<>S)O*$F_fHg2~X<9(j1 zzv;n&FbEZDv-^(z5vcoZFrzMch$|sBv$x;&y8U1a-{fy|c{J*Urlg`0R|0Nv2i%OG zVwJJ59W~ya4&)&8d)JS-xw-RRHeD2od5CLGE$F0MHz^wST25O_@~OF_2af>#B5sG5 zk1r?8FyYrCv7fU&@kPsq0(8b`Nucu#0s*-W{g@+8^!!zp%UQU(Cq5{kA0;Z^BlrIK zHOvs`G?GplEjf=o_E7c6HcLGW%@7wTICB2z$C{-pX3GWNeMNv2pe7!<$su^r-y1rA zbYrjdZ;$mg@VpxEc-DnMWzDCvc4ZNO((?fiwjxcq=R^*GXvDXe@4U zI~ff{#)U6dql=?U{9LRMSQAjqac=Io`5SK|51?^?JHnSQ#uOCWU&1Nn-8<_Zi>^jT zzm?BJ$n;I%$ZztoO2NGNdrwYJu#$%R zC2t=y92}ff5TOYCR2xxc~p~@ zVJOTGgbQ-;)KW?yP*4FflH_wo*BZabuKzajo9*kGzAc{xvIHuJ4u{7tCi)TRug)jc z`gfI1_ru*aK#R`fE7RwVSQ|oe^Z>An)AX*VLXq?&MXAei_a)7@p@g7xUuR2C}qD_ z>{O@ctM9qi$Y{qqma>+t0gKcpg#Z7E9Zy1V76Y6tH_k*e-6Sny=`5ja1yYj&u71XQjO6DLF8=`s{? z3|Nsr=r;@VdMqbXl^>=)_$ex5xNs8!v0COB`8foTfu(bU9 z7L9?VpneNaL?w1`5o@@sZQ+OBn{O^BfpaMR(+LG6fgn&pmAGd)1GbDuCCLY^vZ*S_ zBU|)(42z)0g#mAlppQdY!}zdic59WK+&(^~9!K%(TY4UK9hQPdpV7Vv?cF8PSB}p^ z?u=R?P~i8{Y4d_;NBg}Ppx*-6CqmFf(17#xfRUq#$uAB1yW3ke&Xid&TlVSLQRz0@ z&*0tZJVp-`*{nM?vYrM@{c15m-}^BAo4CBfz@M@LsB&^RspByBo4+eczb(w)wsmHt zvJtx%_B|rYMY}S09$J&ogN0oJyN`S}l9=e|RIn(rCRR?}su!Ot zRW3&^i$cqxe-0prbQ{D*e?$KE{VnaGR~XxhQu@M7jBP7B8#Tgf!wR9YhW9Nu0*_p3 zDm_9af&?C71|ab~^du64J1FKSKj_5@G%hrVQZ7|ifk}fT1^sr5r|f+S6txA>Ueiv9 z^aE6}dUk3ab^-C_hH?R@tpP9>kIJUzdzGG zpAkyOB#m&-vW$Y6Q)x?GFKttzYN0?R@S;jsiRVemr`mGnc$thAf2|r>`l`ZN`|-wL zsc~a(lda3|h-ny-*bVbNK9T+^Gm$RIA!kkXVj)Di=C?OM26cm8d|wxu?lNVj_>_pH zZYAWnCNj}~<i6Zht_C5(I&K_~G5246AYqcjIc~X(5lmm0E=;GyLT8-0 z6u^=dk1Q3@uFL=nx01__f4C&5 zZ=nX%LoDr>fwTjp;VfjGglfP-oi-k>f@)iiZ z1KCz9w;Iz46%G7M8&l=N-HN!6w{(*p3`Y1!^wlo;&3GkWn{h8qiW9&r8do<=oa#WP z`k8bBn$IZKuX#vQ0~4U}KEe6f@1O?>n-p?<(HK|n7*E}`d7GfhFH3R<<7+ZT6#zRp zTPCvH?B07pn!kLW)S!x&`m5yug>baIJtq!M zPDV|PPxwchc?4XfqkWmS^zS-X&W(9rnAxNEZTzCRWOC?ckMcFRejCX!?%@&i0M;0i zWKIyX8Ppr{Uz&dAnB}e!lP$MRic1X}_4cqj6}L$z7%M-WwQc%BVo!_H)>!*E9N+k8 zcXZ6(YY?BBBVUuXEf-!U*YzkH)UQ%TIU>Jo&;^Y6&$zNkLJl7J<7nSzn%5}v*?kFImKs|A3bXt?;Kp?z`-yExBzBNz~=+`*^Z3p6Ss0! zL3|oKm0~;pmpgU%{HcRv(-sYS+9+0DUPMv=H34{lSUtA>^%sU2A}cgJ%btIRco^8* zkD4`V8s9K*=^x+XO~u-G4jx?9{Mn%aIFOXdM*|1Vkp+S~qYCb|pQ4$Wg+0q^i%R!R zV%U*ww|*Iy`8$%4eg6_vfTNNvLW1$4pRt2X%9O)NQ#=8JO5Lh~1BLvskQ|Di;P>A% zX3LVS(pKv=F(Mp72lvzi-FVv$8MRo4{3it^B^5>?&>Z;iO6ZcjzrThf)_)AxoQSda zx*s?`K#>_v7*WnFvgrR{be=R*XlO@T(8sYp1^+)7Bf6?+{U(ETnb>T~y#CX;bMxB`6%!K*7=H^X_C4C;$lW~mvF?jY@1S^Ft<)}ABW~9_w?EJ+2sI{` zR-el9v?7t9>XqqmwLc}apEL7sqI61cGdbBrr9g|RbjW)1OW1IP(wMH7Uh1>@Cz;H5 ztMRgWx;gE-ZfcstnH#XSvEB#51b{~@M~f-&r5{=20)p9UIoo1Gyl6j7jy<&G5klMz z8`sC!e$nJjMHd|2db#SJ{Im9{bx2CjEU2WG#t>O1Eg+S6_wZFXXpee~)_*WUou7F~ zp^mDfucyzN7;Guir$0)sc6eLp$&?U=IA+A+4T1;ZMh>FuaSLxNe2)HUhbS>?p>0UX zBD7W+Blo;-A)I#768DRS#ZbNQFKqXy0fAq)7d>rmXCHKLJ?dDlHU>wa?oWK;KQ^`kU_o<>$SmqYuwQk^b@nKMP; zVo=di`wQL>-du4Af_Ar+0qEmT0D}zzi#W9UI-=3%C)+izp4>v`^I7oe1WdsO%l-VR zpx0hfTB`KDeqpK?*Ca=Wp?jrAoCOn(_+uXLe zJSPRa`rz8T>prFILOmMhq%;VUX0kP z?G$P*qKZTpn*O~sQT#3~FGu3e$ycPth>ZAeXJ5tn>|0CD&uvE@KM||IBY%&KMc!C> zYANKu-vbl*jBrAuwMjlGi^scORg%%$nkHwyaVZ80LlcquQR?z{wOY{Wc5S|}X}Z36 ztVZOI@W`xE2eM5L_f?im_3PbSIDSEZ>(_*TqUZIBBMj?Q!sM>bzYXwU`TeJ)Ua$R~A`vv5{&)Bx3^dv$MDwOP47e{W%J&+hMKuzZa?LK;?9;Dea6Ca}bbg#2_CU8R$Fd3gb? zJ-K}G|Il>SQBgnt+g?IKYLym{kS^(#M!LJZ8>G9tyQQUDq`O%<1f;uT>3rUw?{j|t z!{HoYc4l64-`BPJ6osaFS37HND(xEtGePv24>3at>%-M?5L)GX+w5b>8hd$sXw&!H zODdfd=)#L@_W5$p1G4@^pibX$6mqk2PWO`Av9QCo@^mNrYP*dXktj+6_6IZSvuI0U z@Z@kbXGxG3&@ra_{q&S>4CGP%zbwEe8%@Vp5!XDWIM;$bz!mzS{zIV=ytL?Lk!tcc zsf@d1%sMBKg!+WoC`J9 z2IBNXmb}YD=T$c^Hv0f%{>GbsYmdNUH&I;dKQPiWtT0)M)Vm;|yv=C55C#AJsK3Fe zeW$*RK2nHyApZuxTDB_b;-nf1uvo8ETu=cu5R^1xs6bwR*}Dz~!6e7`8_WPFU7GzB zVKZH4k&Nn8#{+vHT@CO$mbX>SafE$-u~@0>M05KzO+X?R2Q^Gp zT~&|-iZykD* zWj%no z#F)*a-~>UkydOS$y#3A3)&L<129pGb7+p$S?_hTpx1s0g@wN3#HGS=Ru2-Noh<@<} zR!10Qzdtnmy_a-^YFFhZC5koNY>Cf}1e5LZVmN7;mi>}D7q$X~xt{BbhU4)w;9x5b z@}U9<)xh+y%umR~xz?C)1O(1) zt6><#xt#WTWXuB@iRDK-vYBMgxccog=XY(Zc4CT7E&rwq#nJi{RDp^s(9DP|xQ8Ay zN<{JyV(un-Icw4ky(vTpaPaUfudfRj4@UoYtQd;Jozob4Czn0ROBg#BjUNZMVQT@V zqC7f!pvwE_xEzBGxHD$>JE zL_xA!0@NOOp)Efrk|U4dg@E0MB};D@qXP6a3@>f@8RO`~LXapCIR$F?nS+Jl4Vmn$ z-^D4Fr`LBgHuY2Db73r5&|Hhzf@tNvx-L8q()lZybrTDPsX}yKj;87DpXUSjpP0|Y zU|~0}$raw4*dxImh@x&E{Lch*Hh35iJS@2P=p*msbW7!*ySbg2(W8&%7W5v!0SD~- zdguCI94(J;S$9#(p28YzO*LGBVFrZ^}sd z$JUH~RCOr^lB|0RI;s@UC?sV{@lwU!oh*PRcRI6V=`^)?j3FjQb@MV`+|LnLl4VKe zvW&H%Z$yy*1!sFxLoV{jy!0bLNO)5~Vk|H~bV_t8L80G@qJl%gX`E zZS#_i`DAVgm^Sib+z?>T;EvU9v{0l?u{y6^^?lMcV?}ud;AJWg_uoeKBoXPdo)u+_i0Q7gHarw*~ zpPo$KC#XIqlYfwF&X=&g)g*aA%l;H7M?qBjt~*awZI<%ADkOZMfN%(SK*=Bv zO=Q$%6;%{MijEtC&O8^KYHy9?^=ug5E#I~O_(L(inbAatfzq6}jH$~-^&K2cKSnqt zMwT$Zu!HFJQ$|Vu)po&S{n*f{m&pT)slIM!C<|y-Zko`x#aZm*20QV9Joq)|t&t1~ zEJIuE!1>)+y-en?317>6N7;C#&s`N7)NN@zH(iAUO`9SBDXC3m{>McZYTpI?H#28n zr-QbzFyB+B7OvP?msO*>=;&xRc6JvR7mpN!pDg;8-WC@)ncW`?hBpM6cw^EAzvhf)pQ*krGw4ZBFSMuCH0YnWAB{tVTFnO@ux4F*4-}; z){JFwRksRWLLrm8?-LOQp8fIM4uUHwv>9LuummMY90mv%PA;IyfWNq5-f1w;^K2Te zICqr74WclE_bb?b@2>5UjMBLbk6%|&5wO1C0PW|^3;v@F7KdGYZGnRD3QF_jg)~?Y zS8m}C7F)*lcwa;nCK;Hc2DACmCM43QpQ~FAnK@>mB`4@v@ycCZ=VIllaiU(VOMf`Q z-X_pa={%V=&l8AIlR4J|I5i&%mP%ePV2X*waH=YES!JlxV^=7)n@!ct8}E)*l@8(Gu^N@sGiFcdP|v2v;VX zvpPhBjPCLF>yyf`E1Kw2U)f43V!K`q{g_#UX6i0Lr;QqbC4~nz+>ZZkxMPr&^LD6Q zG_w#Gn0IadYjJM2UHPs!HaBRT0P4KC^~`f`_}?Rg1sb{oNXjQ!oue9HR_sInz-b! z@yDdvnXjM&s?xJd|E8lq(Tfs%`jj}bQ`1|+RsIs<{c4_I4*A4xUI0J4%IuuEq&bfOaJkAoeRi{ zq6(oSYqeUbQ74W39bJFBB-V%LShH!We6u)qNtq}Npe{hgIeV;gE7zbdnQal)ixImy zx&JC9J!1H9GZpFHW*3`M2yBsw05Y&A(aH&-JuQz! zwscIm8JTCLrLRN=`GdD0|6=ZRKeW8nv=QiRm98p;f?*RyQ`px`SR|FNpBCKm5n35c)d!ZPF>rK{Hi3_sX=9Oe} z%=F#B+X5+Dn-mu5s0KZ}&<@K|`R|4PF!AM4h&^BD?v5_%jjkQDWN0=6(8wV~--mj{ zZUdE5U`vhjHBcZX*N7wuZ*Ap?-Bv0~4)_Jlk$&S^)>q{Yl(4Y)&YzMoECaaN(`6{r zR<^H_&pxk4rV;8~5md9U{8U7Luu2mq{84N4v064SEuU zx#kIml2Q}RGvLWn6Gs^76>Sht7zvnF9sO^zO!OaZHq=n9TE}CnKVoJ^Np@Bu5&jLh zwX%%?jQLPu(gXr&zzA>pd{=bYwuGI+m{olY^jrZYCXga&tR6r~Y2=x}6YZ zN&6(5BhavWe{nvz)lpFNay@uwKA-CSx(1_;?00fsH;9faTw7jG$;Us+B$KZYZ`z_T z37mNNBJ+-#eBkzW-Uo_~+tCQ(gZW;+N|Yp<E~teT0ZvF9hd0?cXLxN zE(bm7K}uSUD{mk2_UKyhK~wBLPho9e|Cqft;k-Vm$N?sHfbpAtzpm3* zu;%Rf3h_8IfC-v(h}xH zgpOrz#0%TkMqw!?N=bD$Wj*K3s%6+9_S!PI4{<|ZB7t)@-uBhiRXk1!i6uvtm?9ub z3ZrU#SvD~EF2Xgg8vH25{T3sOyUomWcx|R}{i|%;cUGThzVnY4dVfJRqQ{<&4D~`U#5-U)mj|pBQqJ+93A7D^ko+G-B~1qV%(BR*>Upv zD!vxvR&r-|`$i>1W#bXm5kqh8r7L4`adFL!jS5&4V@}FUe{A=AO4ncindgv>C6e}^ zKfPk}^qb?L5~a+Im(Kv%KJrtkY4pegN{f%Ac+lTMKRa-Y>gecDaNHL12U+A=z2i)8!Cg2fcMA*3~4cpU7nX zfKI&hDB1h1lAxSb^pxK#Z}sJcB8~pv^=7s0c{W3Zqf?{HllV}DSvrtSanGfatgomT zV~SQZwLSP_6GiV@nQk&qC_1#r< z32h=769|41Q- ZrzolwZ>VMRVDdLiTtNuW1r7g?P|?b3nA!K0Z83U+O2ZB%oWoh z4bJc`nIC%Pes);)w)FZNtvca%rVSA~KDIt29%Idx+wNUg`PVP!?CP(#8u|ewBtqfj zAs~Mw+X?bC2eVYuuNXW5hVg@6vKnIw^yXAwrgJcK$JTj(npoP{JJKR*9`+ucde>=O zUX1nE9BJ;TOo$nGtTW=_+Uf89Qv6BNPlJLJv|koNjMl67>^ZQb+sP^Td7E6(Sc06f z%1Rrz(r0B~Om!>b=Quj&@(;{sc9V6?@@=aNbowjbS&wd*1a%GMO&3ZI7BYKF!Z9z6DCdS)s{1;9Lb?mzSY`Fmo6y{OC|(F<1Zu11s`kC#r0FMlG)nPeQ`%fJP1uJ zk7n}y#dSEW<-y9El0E100?jF9P+OSN092=-{x9_>mxNOal9%&Z`>gnM?7MZa_+mQv89Fqt}`4YHo zt*sn)5pbPYyN-^DGGHWF_qQuA!JfwkS^I$ovPfydAl|Hz871LF^2h=p(#0JM2Z{!c zhUU(RcvP#5pq|*eP3tB6*Ej_3KH2Hy0h=;Q8n<(P{2Zygv)uNhY8+Kn8@@LOU7sIL zP9>1nogHW_uWn4~5|_ZE!fxh6P83(_2j!4bX|tQVJM%qyxF`90)|oR~W9+%fE0e{d zTe&h;?Rwg@3>J)2KKq4#j|RiGZs{Ibq{o(G%r0(j4fF)^rfTE%0)IJsYE>j9SEH9% z9MA*6T;hO!{;1x_P2FWFTZhMW)g?`t9OhM8bhzqi1G1)}GBelA87$E1n6qy54mjba z{CC1t|C)pO_P8LVI(tm_EsfrKNAvwNt}IY|-*4+2X{b=E;&IsU_nsKfVD;fA4hECL zzaplxokr+px#g|GkA=m@y1*TQ45PJezKTA6{daYy4UFT6Y#Z=HftWmiNcbEVR$>{u z4RiphBhkZx?hwLl^tqf9nK4=LJxY%^osQeZoX-e8hxczg>h?_;sOx(_l&#rGCT?B+ zS+#TX^r6fxvCJvi$Z_){>s>^K1rF&^0}M#Q)L4n8+&p|FE2n@GO6%&KHU7jXK=CCJ z>GTvbpW7?jmNf(=8gFNQ1xdcgFY2#9>FyTP)z!sqNMN4kSO~4-=l(P)E<>K8<;0JJ zBBh5|9}N|5ne=h932ZrOozb9Ah3rP|RVGR?xFI%&%*InmL<)mHwI=NK#~4t71hYrA z1Tv1>_Ros2Of}nPW%Zsa*s&xjW+QH`l2#eL{)raWhMO*}|FwxbT_!4~_LHPGKOhv{ zwtRVzIH_-yVo6h;uv9TuB5zvnQl3tU*{<;l{RaH5fQx8-{<`~9xjVh?y4|jaO%o5G zT|r`RR*Q`*9*8ngRbp3^O=2`S5EeUL`__Sg#?N;pVO=cs0iG*tQ%mwTEBHB7sXLR_ za7GFB{s(b$UZ3Bws(@g5 z<&4h{XgS+=&LD!u94R}}IVIkIBo8*|O`i#(0fCZ=Z=+MYsIm+A%o5FgC}1KB>iZgQt*%@f+2gCPuRL?!Ot$X z&GDMo*KK*B+YeG-n5#9}i7JKxbpGHU1!_X*X~H`Xm)qs&d6oF2qCRwh?U>EcSh!N6 zMY|mB-2OQ)APQG^>2+DZOAuT#$kqBCvJb@)n_pOvla#6*laD+;dct33OPQ%Xv^OgJWhc{* zL%Pss13HR5Sqmn6UX=~&3b$CnF6UhjYiP|$NdG3bHqANKbOnUpvi!(xhO5Id@ zks~j^R$G!o0=}0or7Uqpiwi^YEUw0cS5)KOK3wECO`m$6(9JYtVX>( z?skT6ena~P4Jr)|@$dE|&dH$sy7TsWO9zzYoP5ulWhlL;P&1Qgz{v6KbKJbuE?0F| zm*0;c*I0WcN`-n)%&4`=VQjJ%9zyas*pyp*{!XJ`@uK&1z~*4GtNB_hLjD-^;d!f9ws7JF*_148lsCBkc0#GN4|Xd~yx5jVN{%2lk-1K$zt4t{(!c8#x$czAw1Ye1v+)|mK>OI2*O#?z_HrIKAH7<1`WrUamda$VK%Xw7D zkU8V4%Ux_kCg3fSMMSN%{yW7i3>FrR2L%{)g6J!A|M5oQpUQLAe^y#Vy~AC6c6bTH zt@*8*29d}f52M8QN_c+h{@It(;%)en8C$RK;~gw`v9%!R-)9-KOe8?cRB4!xDqEw! z15M)vPF??vq2EDq-k>#Mrt}t>2VZB5bE$hWQGv9=K{{gd!BlTYGG74c4y1DE+}MKh zbJQ0xKa1U)A|nTm+|X!t3l`MvxiaPQW5Mu0$yIiLyY{)Z?$=MwSX9_? zWvG-H!XsRWRv>r8+?ek`s3Fb>DjG@0(4cLvSQ#~VhJA*dBsw#8*|+&AGuqx`EFmQ< z5a<{IB*=Vaj46WELt8J*6I^Feu0cQ1^0(b)=|R;rCNhD6j&96^rOoa9w+4L!x+*#+ zWhUa$v#&t#)PHV^c!-&*YSph_fY}U4e6Fspf`xk?t3i_>(2V1YyDvgmST%jcm1jr3 zg2iIBuJ8^2S_vk60Q0S9hZ?3lW@7a*5D?+beKpzdte(Ck=1A47Qj6WL4=IS3)2v!3 zC~ALRFlWwKb3Pf5Y=LZaX;_pbaVTT$W`<9SxW5NNi78+H3nenEvKEX8$FK@4wav~i zyE=i(GKGMLxGYf)w{?`7TFO~>N}oS(HZ72GUXje$Jm0%+x0-b8h9!X8v7}WmHxZtI zdA_RuBEgs7UNOX5sU{K&mzfV6!S)CBBH!DakDKi>?f&Ulz&RyL){cc;x@9}ySpFs# z5XL=R?c!>kz$GPY!wr48s?*V#*8htCRidw$eoMZy-Nsu2^ZWmr~VuF8?YftvpHz#K*3cE@+??kVr! zgz!wj`Dm`JcBF3D@KG=sd-ZSnFe1E5>d=Bk$AJMv8wB!!9XHuG^MJ-~vL3hHNrORR ze$PR_#8^5UP3lYfW<4w^f@_cubTjC1;{4krY?u*H%?Bx7`@vCqi}|Hh|myu$P6} z2Ordf9Jd>ST_G9V4J>AgkHEUdE|i#4IK(G{XiM&|c%kT};XhN!E}naCEh!2$DrEzYrjxm`YBntRQZ?WlZb1W!y)Pe)Dqg|e|boG^74e&KG<-#=ig3_yMNfsI@?B=kh! z{Jd{_4-PXV)zwq}YfMIeEtp_|=23<*NxE2xToQ=VQAg^Ku4s11#lJ7i#q*dBRev28 zp@;ED^Kb5KulP~Tn;A`>7y(QJB@=%{%ZqP^_2u9$G)0^9^YVSxBGasCb&?Y+&c!Um z135F<;aKs%9t6oyDzE&BSN2UGt_m}F-^<)K&{Kb*p--a_Mndk)onKdm^nv60;hiE`maSP^ zhGE8*U}K6}*xEU(HU#RsN;4+)bJ@#AeKMx2!$@(gJ>TTMxLQD7Vwb~W5lvzF@<^OG zz=8^b9GmypXfh*_{96B6?KG}Ev(ZM+r4pcS%+Jk9B&y^>N@fsZeij+S1=X4G5K1eM zTjhqC#X@p^MDy3k{!3!mMRl-N9eZS5EzhTtf{xR$pLYKp5JsYj{0I-IFCWe_nPpBx zopR^8XO)U zV~rBxIZYKR``~?K9M|V8xuP1!_%y^Y`3;guRhSe>&7>Qa2yY!ht0+}KA`CC|tDH7S zNaDj`eMCB*6ZZQ;h7}}K5_paV#c_WTQ$JgSbM~y$)@oud2a-~O#dY;bu&ZK}aIhd| z0BwZ-lnDbjdjqA3{OqJyoC0WdKYRD?2`Vy@W0+v(qMG=2^$MdoUn?88fa~Y-coBr- z+d`*6{d^G8;aLx$qb?o5;ngB$n~k=R)V~jNrvw; zXNC+=0!kzwU_YGf$YC}f4vnzy_LVm{IQe`+UiPO%vh}r1-c9G@#XK)ii3vCOMHm+y zT{L^R)L?EL4NR%AmYA48-QpiE1Mek2&`fjXAJLk}h!)g%*GiY_l7psY99Jh_uP0dJ z;^ARlV-}Br_9MJdrB2HgM_iUa(toS<|L?+qf}DPZ+bMB^=Sz5F8%kX{WFPK1@jx-` z)9-`BL0~!TegKG*nwqLsy>^oRQQsra>uRW37Cn2Ht9R2?qy5#%`$;utva@x2R)V}* zEg7WByWP4fp={*oKDc!X4t#|P<3FST(@c*LoIji)=C!MTr1v^aGSuXIyzk@Wk@oI- zII!0>mp23{z5DpPZ>%r5E!A#bRh!A4-e&wL#(L3_%L)p1 zpiIS)3=aP)_x8ac9IUEP8r$w1R#JwyGPEUP>yp^A8Ce(+bkmz3x!f3H8%bwvWlgs# zw@ZAE>ZRNzM-yjVucWPAL3^Z6>^pLN3+X5?D<~*1bzD7bmUAB?QsEtN%nq0<2mVt< zSDb@BP|byMGUFV$t=KT~3R7cBG7?$)SZ~W|rta&{Wlrwfa%dZ*I?tbu0kj}q{^7(O zqBY*o33TqjSo_t(HNVJTZMQiA>8IhpFPbq~Vf>$mVcp{-%N102iUL6&ZjEbW(YZwy&1m>sB{QYjW}f)b7hSN-4j(* zBhAChs3nbz`dvRfv6_ubxcGj`h~8@$U`gYr(CRcK^cFdsf+39eS;y!U{wWUgv!^Q~ z+B^>3969is^-&`WN)obTrInw+Nv5ax!D+?zaAX>qB;6dpQWU7PZ?A%7Iwanfs;_W2 zVLc=f*oWus=^DOUB^Je_7%nsu2qx`?k%&hn@6=}Q>fQQudkO;!0+W3N<1zDvIGYrR zJ6ZfO)_gi!``XN>jjm~OhuR3yTjFWBnmjRABGWf2v9r@MCc|T-W2NoXM0PL#MlRVJ zA`D5mq=A$bZ-4szft-mPGbc?H_i}Wk@U9s`g5`3QmGhhRa!xqT#ndHY)eceY zfj`$z$#-P9AMLar_`k<@efkUfMQ&nL=~QH+INbQW*x-t#&s$lH6tNecZy%~=h|Niz z3V7*ax33e87W?$`MX z81rt@sUtZ!ht3w%HH2mNtd>e*Vq!kP1G_ZPf7jI1l(e43c)e7aP?^v)p)w1qPTOfe z?xm~9^?8g_Sreo;Z{p?0&&y^#4!Im@Ba#sjlbyYH7~Hnxr-3e8bX7Eti3(g*M`$^+>u$mRY0g23g~)w#TGjIy);jgQ~` zH$JwqXhmltk%R?pG&-)g*#(s219DMO_<-)Ne59>`^MAK9oqZ8H{ES!@B3blrUV#+( z=tv)zH1T4niWNf&VA#o+E9VVMt6c>C3JTbRE>>gS#?!e;X=sJVC;C@Ya4L_9?h4Mt z0nEhP*#I%rtRCo{oR?rKJC#*^z0dztk+G1BvY4H_?;!|IjAjo*8?IF`{6mxbkwkC| zmq*4Xx5T6QAVaa1`@p{ZOXH{e>1R_N&q)5|Z*{H@q1th)vVnLcBQd$7=AS*8xm6@$ zP#0ZO5nuu3%b8kzJv|=hnBIrs`pWY15=+dV{&ov3mRO%EV+pdY&kFWiR8tedAq4oCb+!I4xmCn)S=P|P9i}DfmG(KpG#%MP8N%d z6tk%G4x#JPB%hy4&*03nKUm&+Yjk<;GKIW3J%jvps?5jrNZnWsgQuiSJz%h}qpRCh z{DkvpTdE_s|5W$+VA=MDW;YQ`kZZK{-q@s)xDA0NX^dbpkyC%386J&7;0U|XF4{#D!@UZz9os=rj|wWpYgi&g zg7@WVR^;Y3!VCT1TtA!Hg3dA#Fou24D&y3Sr^)cY4yGL~A9YHG;NO&`_SM%jngH+k za*S!mhliTA20|+VLkqaZx^r1|1p2Z1`x=K@Tr%EOqaU?_=^p31`?t@ZUYCM+>=aoSaCZL7ZL9e1OVk0+0dYinK$Q|2Hg>D}x6m@$uBzl$nF z(Eu*6$1-*i++h}1EHOU*lE7nq6OAHP2(zpkH54{L&_&jVEqB)=loTxi)UcZG%j^}i z_255og-xpVPAKZ8X{F2OLD?^q5D{hyt=;)97qQw`fScpUZC)kSA=XDQw^yv^1#AG zL`3jH|3#b_|C?I9*|*wVXCuEoW-QurJSoSmjZR^K{7JwWaOQo>pmDKSY!%v?l}cvrd5M~ zw$W`2xJ!xjBS$V~Y#ryFcaTf1N|%YpGu`9YVaeA64>C;Svqb;=V?VAxVnRT&3J21aH#CGu6G_YZ`bGJ&Q9;3L`CBOZ z2Xq~|?>GaZWQKU(f$W+v5Ukip*f-Mrt|(eFd1qK~BQ$s;MVg|%qmAMBI&A7Z`T2Ox zr0V?QZ{^Z_AW1F#llNY?j>?{KxqD_m6Fs##$ESu@lI#F1!vllh@kw4gAF;E^S-FoN zuhT!tgdf|}4m#?9g8?K_^GXiH%$9>-te$Ujn`^@H`R`u|7lRPNb_}G0LZ?qC1%uF* z>#i)avBAc=3iX;LuiK5&b$v4QQV^)eptgR-dH;Dx_1%tBZRM65|L!hBAVFblF;iE* zFka5W3!xlbdwdLzz>VwVXqGkZLjQGa#bi-e7Oe;QF9}iptmdUku2_jk5Ys+u1*nIj zM~<(1^s1rMOKUVr{UaAfCo_>;=lwH|CQDIZ!*8opQcC=21?K2!*79J7aFO?vNs?_V z)i_upoNK;kQLA~xmA1452YGr^8;vRFehe+txtJ;hclN3QIi(oH#s}wKC))74jBZ~L zNCeX(whIRTCbJMM^G;*km`c3Z z?f+?ENP_>Ap{i?T%9*Y|RYKiW(dVJDG#2q(-*P|4;GED0+$~e#Q1gcyXMV3whR|e> z?)cSP@t4pRP;Zfk;HCo)uLpy;lSJJGNMCOrfXDw`Hn7Ij(B7!i_l->(-?6DF@Ua0{ zxIvtwHR>Pm^9~+G3U8$qu>j&#A7Hw~#l|+hGLlnb7ZZh-jqk^nb&X3IWIE|jfJTVI z&f~gAR@+%6nr4((mbjAJONCvJ@_vpHDV*xb*aK9&YNTFCt7oBe z#tSpg!zS~QrdVR^I8WN;bmH(IsAy1!#>Pf%`1CohFD*{Bj)wMO>%dE`$ohZnr~t>p6esNV&Mkfk#@*!gty^!Ryrv@|sz zj;c7(#S0@|QN~p(QyOC4(Y0oDQG`SgoVD!Da^7~Zw~lF!uir#TzYpnUIF9NVn5Pe6 zQ>7Mt@1|NAJI0M(C@9Cz>_~P89W`fsk$kgQ4=GgsP1|c#r%2xP<0ZRYPjZ$mA-KGJ zw4N_V1^{X9R`obAnM1ELcAHIB z`@3EeYwka9)#^DU)YDDe^QT~S8QmcAbIOII z5;F({4gwj*V!4YDj%4XX$KY<`%c|#B=dStjD=3@beK)J$a1@E%2CCDQfXrG8c%xjk z;{+KPJlZzrDPZ@7j8SmN=3jpi|2$Jys>2>t3+>|=)Y*M63Qab|bKZkT|Lpm@5p@He zDdQ)((DzY}$J0_e(>=&=@)6m|yH^~Y(cyvA-cHQMsAFzU_J4~qm@F>mg?HXLULO=e zr0Eb7%S^d)OU(d6@neOn2Zgohx{dQzjJz%%F(}mrkc<%c>-`ffYxL=F7u7iS#Up#M zDkW5SLdanus7@ra=p*5hp4)dM?A*3fO{=Qi=`26a1#BWd++eHCgB>h!oQy>W*tn0= zzdpq1xJ~vJ$ovjBCKg@O;i!Ol=`%K2T}X#eA}6E?`+d(m$Nt*(KFE+l zve7}dThU~xbij_WqJg=R1c@tFe^z0XWZcFjm(PQR_Gq_Bjxf>B$5YyqM}1z2KmUSn z%oy*xB9@t8sOxdx9g!R%Fp+ltZjX222WhcX#7Y`5fo9X4a_`U0&3Rl9qtuobPFwJO z7I4}b4%jAY{ca?YrF~pM551yC1}R{L7^d^FC>EvSNnP*>aB-!}_QrNCrzG#HP+vdu zHoN5T`aC}GWOTyIDL7|IbJExF_}$_OQ};mw1O>4MI6Wu$W_}OLD0H=)9qFGhtrJHv zASdhaxXGD6ArlUv^?^W4J52z*xwyD^dz;hDb}{#`-PrEf-XZvX;Ju%ohdk8*-I4d_ z=GCxdmM*Fsx#QNgsVReorEX3@3kn3@NP_u*DxCX9cYq4*?hl^*@eGkEWLR$SU?4v0 zEAEEDV6BVzkJMxH?CM$!twMbci9SOV|{*XIaPp!E(|H<|v{jMWcqBZu{Q zB2?>i9{t@+BM2sdin{AJSm3<-LVB{&T+`CBwCP}yB(w?~cO@0E;wLK#(#0ge@JS<$ z`=dkO#l>l1Q+iqZHJ{;)zGqu$q0U|GMGUs`BELnINXixbn=>UGqBGH&# zb)EtlA#(TMl)>Gfa*INxS5xgHA!hB!1PG+U)%)7?Ji^(GSC3WRtcn^%A}~0L4u!lV ziR-6>&8>|S<3sOU|JO-Pz1@$Q<=$iCE*7Xz zOpc&GND$QH=Cb#=CO0ncjvU(KL7+d3!(v>vxVGG*=G9Kn8{Vxn(m2p7f`qL&tFmgz zStb=b+=&n4R;s)#VOYR8i^xbzEmax3$IS9ePAh`NEh%pg(qMDu8Ry5wPCfX}Uxc=7 zH2Wk$S8vVvhg)+&6ub#dHY`Fnny>* zK$>->r+0*I8d`pjIem-nzyd&qh7lF~$S&2osxRHQX=u z1zD+24urUjo^LXeVvd`+AOUvv`A#o3X4U+|<#y~{>94l0*R%3*E~TV)1s16!!_b!m z>HW5-$VevCSr?+d+JJxn3R6=7zQ*mLhCNpz{#!xQ?u7*tjx1GGh(Y?wDZmiIfhYYK zAqeOY2!~oAyxW)ez~~$-EbwMw&qZYjU+2T}7QeDKHwOjb3f(h?Kd`K)9hi&<1ttPhyC;0k zcU|cEEyGFQ(_lBL%g0{V(-R=UpSbdZKz&RXemzVwi$KX#TUQqt_b{C#N;CF!_Kr5# z(%GYX&-kc;Hty#%5(W@R>1k;2KYyk~BKsKOK*-6$vgOp0`c+>}nXP}LFp86y+lkzy zyACoNj1wQqw~Me{2kb? zXTs#qo)3-_0_qCec=}0v5BeCLWA<)5DI~Z4`_OrL-mSS0{QGj~en^oqm^rk5_(zaH zBDlQdIJ7!TGO|D_{^l8by)~HTU4~33`G^e%kPn+ZeD1U8f(1!cD8zSp?=alHnl{Oj z$FM1i_=WDrq{D!i3N-sO#e-%eRIHvZ4@!R1synMvV;|rDsd?cbGPfig8t@jvCI6XZ z;;7jRW`~29xFucHd4JHS-EK+7{IxfbJg+J`D}-t=2}F+w*aH*cngr(c{25 zU461{NNfCc|BK{4NPNK>0RhHL=JwtVOI2@SO`9kS<6?{N{uuc;(W7b*2@$`yeWSY$ycZY4jobMMezIYExpOJ1?u z&~3tE%9oluJeT(6TgDI1GbB9~l^y8Ad*RKYuinkZ_V$YjYtrZTD^0fU7EJF^MTd(( zAcY8k^q8}KW2%ZZ|D-J)#n)I?P!RTm3=<_#|C`Ob_uSPv!!^Yn^TLK1(gc?bizc32q^znAlh?!tse5MB8#aQ8s@KAw^D%VmsC>7!Z2c7ee%ka;rK3 zh&@|2mm)7vA>_UoY04!G^dm?op}_U+KT5;@rt{IaT-JV!Sj*36dv>7IAYiTM|8K3w zE{WD;pX#>U9=&<*k0lrkT7SLusthQgxFEZDvvqP(Y6~~jboek(>E5tS%tWi89L!-LN=vcnL-0$ciyM9JABOAJsZ7*m|%< z(PZW2=UxWh^Z|_L{l%sZO272cR5~YYHsGunaC4>;v3j9h zIm-$6d|k|Tl1n!5S#ix3+zFysI~!Z{5oe6pnY^w4SCME^sdaOhT9w6w3T!v!#}7V; zTQ0W+(!pYFd|_CcIQ4)H|k>isE^YEHq3V(s9rV zxD{95BlUu#7Z@5 z;7IIeWizcx0Y^2n4L95NDA3}1%OL;qx~W3O%k|ICLjC-Ccm7Z~e*d9`J}X2sMsPCc zZyxqLNo5$2Bj%gLPpQQl59ppL^>tMV$30xUr1?G@M8L=HB&h2&cVl?b6%DVoTzWQi zX_i1)rw%4}e}Hk-gm#K;b#@jSGDqC5!oKos7CAC7%cgsF_oTlzn?@wC*xG(}5X-uv z|80vs?U}YNiPkXy2w0l6?L7Dhuu11#I!%c@o5 z$;CM4#Fz$Ppf|`+`y2=nK^u5m)IUsBR|Co{bNAcY+5o_~IV2OHO^1PD*MSEd1BLk? zZS$=^<6+9R_MO(am?wBO63IXya>?&x34kgQ*qepGDuBR1)c&nH>^*kFx4<(wO@7@qhx#COFBpU!NaIIs_T|2w7dI%S%9TX4+Wq%*M__nGqTL! zHcp1@J7zAVR!e2z<95D1JO$8cH1#?hzYfJ%18Ei(%Ej1eb>_%iu>9kg+T{zwI8yi zBVY8h)R2zb(P*eps|DsYOMTU%S3n}!Wbd^|j@7Sjd5 z@w9{jr8H=^wVIXksQu~X`+6XO*4Neim+Cp*9x~cb#3^ zwRh0iPGdB7c4M@$(YUc~HAZ8jv2ELGY&W)TC+~GX-}rt&$JiOY)>U9%{E}-X{)B2gR}?`|tR=~!gNAgM34T0YM745U{qF&LLQg0mIHq0}5yeWs z*hN?eO;*B9xO{}2Ka$jA9Jp&l=}e`}jIFkBQiNonZ#fE6&O}1VfA%iA-d$KS0zt)G z?{!`6Z%@oVVHD7v5M)km89lp^TP4Cs)&r95xfq4LivLyHSSTiAkGj4T0d;V%U93oe z2!fjsC61CTV3Ry?izOryMdrfiV@>>H$E9cy0jRZ+UO6cxpWohva;lwtW$HjJ z!(&jPxn`5iT1jS0xy@5YSt2a+Ex;DlUQA0(1#E@QX1{*@val!xL{9O;#iglI1=-9o zF>+fBJuFBjam#rtO=lz>CAXnYJjkFSlR7UiuP4vW+*|;*sH~=zHf|E!mt&q?G? z+uL7%p5F5hPpYJWSc~c1ce>+Ha{6|zNCTFamw~pMEC4Uam<>N|yz!#@X#e@WY{3{774*2-agku7%vV^ zfRMK*VRbXIe0ch$$!?iu>LQcI{sv68A8?~Rg-(4jqZ%kX!6BlSfrRH$dU|V8*=H}Y z;t*B@4F0Lb8FSRpY<);L9&^qj?8dsQ4v{7!f=(YPx?M97&GisYVB4av1l3hkRB;~m}YTU*6ftKRJWy)%}RUeF`S-C5JB4;}yxVNw-rp`gT~gMkb1e`#l%wY$<MH)W3Oo%RA+|}=gOP?QLkWlP z!pH$XoHE^)QMSpOytg+uG6+)Wpq`U|nB(+DidrS60s>1nQ*rL2c7Blo>%Yu{lM}q0 zwmQ+R zQW9c}Se^a&)^99o(FLfZebuZIu~Uv@Od06rkU^j^=`SRrF}_f~nw|@8^vex- zD;e|OLf2NAlS)#OX{|@d2!)D=;}S<1`1T}BS+Iw=#7^BGUX`l&ef9C0CFZ{>0(q`r zxlKT1f?bKh>zssk11V5`gnDnbFjus+ z>TUIk1ryP*1BKyUIni<#mW#mJz- z!NFBlB^kQsSu&>D^&QzJUsN8QZlAtno|LUd_UPGJS;@@SE7Jj_CQVI(s2u>>27nD> zC0LLEn&;NQObunGDBR#GEUp71;p7c)yqlYU0iOsO95CMK-?1kggoS}QZ+2lidH$_` zSnAJ;lutANwc*Ntr$ei-n;J)DmR>jVPA&9~07qR*4#+wNAmqW%dHV&{51y8l{T4ke zR@B_tP|!|9iqL)`p9hj|;~&7vONL8Hk*tbJq|mu)6f|&cDt~<24u#V-Hn}FY?9iam z5d!&$C*$~xaV5P*R8?x^ji%*o-?rc1HCO#~-}co;H%>aRA?-r%BncH82CGOiZ(9Du zI!>2Uu{>AwN zeo!4Ao<`Ikhn^KXotSu{hSrbTi@{Qei*D3WAYK;M_uvT_rrL2StDK#lB7wik?+0?q zWk`E`(ZdVox04m<&X_^eElMO#BxT2`p@Ph}Fqzdo=9VHJQQfVqj zi4lYihp)YdM%l_y#NbYUf4{ry!&{Y?RxNWm?Kd?iNNVPmBLT&Gg|S2Jq;bfQDJ+0R z42KjDG5pSy6*wRhk&vyHGIBP+K6_*y-|t`>0%Zj+Saq#;*s@e|qRq6}%0m~IN5@2P z>J{odgRPS_Y1s|WRZ?a#yv~J%1t?t$E}kcxJA@B-UnYbUJvY~*6+h%LBmtG zL*I56O;IgMa|aBusq^5!H)*5?xH|nK@}>-%q-J zfR2L(e>mqWT_)C*<|;94pSs0ivk)Tmx`dfQZVc@?z>%dET3T2LsJ9ypnr89vWp@6m z&8ZKdg1hwbLmNa#Ve0iAXCeJx4Gaq`o*ci!0S_Nw=c5TbK0O6?OT)Nc@8^Dm%6%2L zvT_&y^dwZA5ybtz0Ypj=3)0TN8pB!!z{n32uR;1W|EUOP!F?=LR8##SiCS?`PCj z*VnYz=!JAEmbsmIKM|$KT|{=Uf;-H-uYR`m<(6dUta($ zBdq9?ZysTM7j2ye>u$lau+vSCc|6r~l!Vi4^YGHZcUu&md#qt`KaR}ESV1WXs8-A@ zTs<8^&?@)K-n_f!oo`D1Y0ls8#UABcU&}+R^03vaU?~b}1lJjGJFZnU@FsMNw{eo3 zE^~~h$VyjPJ0+-}oSgKC3ctNcN7mDX!XOQ^(Za>BS3IZ)E=)i8wS2uhf+ZT`t+;hU z6T$(JQvMk$oQTT6VAh5x*j@9{JHW882vko2#3aQkX zHLWs$33cDJ6ICchuSo-QTcd+rv#pugA(XujA0g4)S~m+w+?#)D4L4N+Sw5i8=+_4$ zKkp#U8ea(6)j7d=lCinM$Aj5BP+Niii_Dq7y0T9i1%#cVvrcR&K+yG*ll$mS^fEVQ z6dG_yvrzs!q_g^X3sY0sr4~5~-7MuNz2@QJTho`;C#WSySq`Et(=}Vm%Rk}Bnu|%L zC~Az<#mmY$K)@>xERF&1*cNc~NP$!{z+5E$BZVkKSVN+{edn^ON{azILM?McgFP4k zrL}0Cmt-*OtD`~c%-?nSc@d=C-TmCW>AWdSJ=XQU-FiqTP8%;Ig@+8$2jy)-bFt#^ z>y+T&_T05HmCylc{+wy!OIE5$>*)wp8em&VosA8iPBV;%hM&0V7I^*vpLYC$mbIt4 z9USzHjP$Im${QNyS&#yzG&1O%oEhy(@BsB&sRf^3fCh-e@X~)v!a)71wv5v0hRKdnK%n40KeXe+!;pRhovH_3?=DrflwqT7 z`=?BC=9kUAz6!_E@X>Y?YMBD1Hfhyyl|YB-ZrJIfhkSGt_o9|I z4jlA(4ao^npNklQljtnvU58SZ@o(&~$&;x5vC@4z9@H?OSjSqEVljy0)N@k{(HeeB zDQq>JGvoEcjw!rI2bKPZ`A^M8BNH*YR&F;b_Q%ZpL>qJ=Wj`$s5-Mqik53~1+}k#F zp+&(EC6ybQpIsNGcGPt2Ra*41RF=}KAr?Hf=ahWIa+U;VU%m*l9wdyvK7LEm$BS2Y zklt$UOn%`Z9h3DjA^w*S{s@d~)t$neUv4`?1n1+Bq;F7LQFH0F)SJ`x^ApR7yiEzLW%| zFx&QTEDWl5m_RR>^F3^B1om!Zjd81>stwjhvAtI>r0Cw81qHD+V{bLelcD9!X|l&) zuVlm|ofH74X`6GW4IdxXuNyam$l1lmqBkC46P>0YI`UCe11!m>i@)tDYa_PxNCeou7@I9MvRs!lyxm4Nvs` zvYE;j{{(1uV*cVG{)Jz+U?qJ$>%{D8n;~ZLa3MPWyk%%qYa$eYaU;Da`qM%jLZEH+Et*$CAs0bFT$7+Hx2XldK!iH&;LYLA3Vdaa{(YnCeK_P z32{+^fnUGgNUd6ZKfaUUNbfp`l;mjV^5M9Hc{y~9T-T&j#jZ5gq4H4KQMR@6us-SF z#Ajn}YwIeESCjTOxeCwv=t}U{Up*F2Y?7D!geC`=t{C7Y%1{ABKj0>yrG@WN9zCEBB>ax%PYPs?$=xDv_JPk1R-fp!W-x$ zonJQjccRl! z9c`A6xt|_K1-Ueuogb%!`@}83PS4fm?Cc)MGU=KwC_R}ys~2?r8SeMLf>i9eCggP1 zZ(q;HSE-r-shE(Ar~M8d5Re#A!h=Ek9uO)&y6K9oQAl&#msz!+=R3Oh+|C5{lB=bh zqByPaS#A~WvjYkYGcLC99~KsDDk=@_f0@m<^JYU$!=zeg@#U#f@IKSAJ^9>9O)6#* z>mVo5zej_n$Usl|R-vo2Kdfi%`E?a3BajIrWxV;ECKrnpj5p88EJAQXO5ae;9v31oN@$^O+ZLZzu zhnLE;p%NF?s6t`zh<<~@0j8K!I~bHPPb%CbSXf=Qi4lK-M)->FUD%SLp(p&IZ#D*5$VlN};#_4ql9F!LrIH z8P)kgU9Xqb%>V?lxv#>DLRTVeX)i0o6!kQjW2T@!v$)$4zlS=1!GY~+NXLkR3(ck0 zx5pIyh@mZRV*S+QBn1Fi!ClvTqZ%-X3<7I>NiMtA!^)!x?})MF+&r)&uUX zZ|vOXbYy-I9yqjNTm|6Cxk>r3e16Ut4l|pH&w~513q-mh|5>ZP^$@V!TiWreWiYK< z`WE3Gy5jTOLxVhJN+cx-&NbzC&Jzu_;Z}syaq{o}f%+)~aY%ooW%MXPMz~MKXXT~+ z!g=yp`3;3J5z7_v?}bSOnDosTnRrA`5L;y>S$7k5w#3f@5|>=$%3x;l=yQE1IH+!@PuEAsk&b5sKm zJ1u*D#?2_Gr{|Tml7uf$aZ3;V1~rlXk-0SRh$P5@;c#AR`yN=~kMl4B>Tzl#;%ZZX z?uUX>#l`ykRc9qQ5G8DrJ3u&qC9F^#b4C*AVcI4?Zy`x5WOKK?^qR@0yc7nt7Po%= zBe*+5{JdT|N*!PGu+AT0wCZC0x0W0vHA>UsNeDIh8cZ)M(*KU`G`fB2cRsvmam}O(FV+-BnFu*><5(w) zBFzn}I0_LMDX+QM#e%${ICr&i$cYDshlU5Yl9%r(iO+AR;EP|4y*3IR8a5%yV2k4c z4wKdpi;T855g`8$NsJ_@nsde=gWhVK=<3hYST9_zfU1{K!s@?irwKy>l!`_gfO5XI z^5O0dNG1(H1A+7p6Zh#|)7J?iM5?sgI!laHh3zvcfdB(wqVfM!M}U3q3fM0L37f!T zxre3P@Yw8VrZ1#-Ju-8Lzi@{Re31Tv6R0_3k#Kjy`V>kpO$IC~IoV&bgl<%mFUW#mX##Mbj;Nl973Rkr$4%Iz_hW zYome}R01|OiBpC!nx>k^PV97MKUR}GZ@7sX_Y0j%Qi@=PVw-6L{V4MtlEpyl!8$w2CIqt7e=cZ({xnqjYqMuR#(?2L7YPsS>>o z6PId3Pncd|K&03~ptYo7L$q%)i>eI_DcUWBS|UG0ZdPX|Fk`PmYp!dcoHM;oBR<$>ytpAS$Fx5sI!)M6ZtM>+{uDM#a3^1qDh#)`5t&afjwwbMwd|aXIVeBx4Z4^&DdkkE(NECKuTM zsFEYY>P$&}0gypXf5$Uu#d+(pCFc@b`nW1n z>8-cUhv0O@nu9$_i{qvA1oxxW#oLzdew{M0I9kDLD=dtzX(hg;KuziD{{FtTwUt6V zs$8QEX7FlwSTcH0IF9nSJ_rP8k)$}WW|mt*<@xN4AXkv?3UI=WhvUBB1>pygjn>kH zsg`{uL>a9eV~Nnm3lxG_+!Ch0@IDvX4eYVAF4@e-59!`DVu_XblaSySj?~BX>oQv( zPgq#kaeoW~^oNID>x&E2B3IO?G2-;_^L^-N>>gNHu%ngsVcVk21g>rf5QP$rHB?ks0VyRvI=o6uZ4RAUxmyyc z44fifmJ0#^K_Uf7ihNh51pVRD(bf9l-RaF8wFCM0lVl;Be{S&?>BMvrg1cIVKKql@ zpNZETigE4+TWF#Nlux_g24%l@8TBXXE;y9ucwyGm7}zA>Yr5zk4`|fUee86u5UNTK zPWP2c4JRByyQIo4&QFN;AaB|l!5>U6muvEpznN;7XvakS9q{fhB9g(jAfU}Q1zHTy85 z>E43P`+f{ha?2UHeAtM`$I5dKOHi(TT>t*-!i%zsG2VV#+4;YjmxVy^5=KS3ri(JC zof`UG;(O70$W6-)fl|p|T;dBxH*U;madPxN766w{6Xp*yW-j>HAf2|A8sv$=*w28IwntAdK)eo z;HY-x-H#1O@0a}!hx~0`z_oS^ywJ z02-uMrqw8xtrTg2qmxIe5Io5ZEw1!qPoPCXx0|`|K^g=#10{ zBwgUbME{T#kFqvb{R&}7i(xP2{TFr=xvyKqu4522H&sIy;MgVRGan?(&W*sxMsX*%}rRn!o+U5|Y%3#%=Eid?Vqu_W4;d zBB)%a>-C!2^)u{5`0u;3v49qecBkip#Zf2RT2+FgPp-0~{!2=)i-`-9PUkN>yO_eG z_xE=L-6LSXaCm6u<<-$|Flwb1nH(K;7bc;G)%iSm=PI$jXLr|Z7+PD}R zv}7Fc{sS;C@(egKJM=)zNEPfdt_aG@qobpb=8MM4*ekI^Q`Hh+}!9t>pN zDS@%nTSeshRc6+o1x>6seYL0g2OU#3R#P6ikJ9@d0OcK}>3qE_8GP$tVYQgMOs);2 zU9UM10G|e@u)p8X^ zR~OuC&zCmN@%8K8jhptOVLUL62GVyk`75YQO5p!Ic|JM2W)d9|SpDRZo&{_Ckdl^$ z_dmSw(c5__M+w)2swG7LgpxK*(tTvLy%Sp|*I@5YP5FN)a`2^c|7s3dsjk~aR+N@H z0888qxyAW;An^TIODZXN;sAxR-p_r|cwVWA%b0Kf*YHtO0?hrb__)t;nun!!@Feyu zQu(u$yBlJ;g>`{>sy<$Lf1F&=7s=z3lNB5Gaym??k3iD7;Dj0Ykw*mtH-i@51BUUt zB*x;GvqaMh_0Cto7^Gd%fe{l86n|M<s+R)VRoZr}e64`! z4DFb@wbyx`d{^Vo$6%6X7;#|XR@O4Mx8s!19ou?U02wr707{Qj1QZ?=$N5_A7mbdlSa8SLlGlYZcc*-&$HdL*#fG@|k(aK(KxIQJ zH~k6rpX3ZzhR#-v+BU=tRApXSW4@tst0cOL?EnT|MI<)8Phb&q8cmcM38^Sdbl-#!k%)mIvwW zK^Bsjv&wO__@6)j?DBpC0sv^R+|M{kzT>D>-ieZf72x(wt0O@~;G-wZp zKQG&b(tjaM70`1UX9zpxvs&E_X!mTIT%DbPKQ25M4phw}uf?{cpsvm(_btdRGnpT< z+Ga~ItpA;%I4G?DK7Pw&BM+ETZWNw1 zMjric0)JLPH%4NTyYV^lJ+!{C>tUFOw`jWrF&bq}0<|!n{1XVsJB*_o28uWtrX+Tz zRE~Oc)h$OC$Q%n(3%4zgPZZnmmup$JTCfnwQkh*-+PKlmQ&{4P%9@S>pzhT9E*r}s z*@*c34Ny>gT`PhXQ08$39Ux`Sc9Dq%iQmpxsD^ATuXQk`RyI4`%mgj>+Ogf87G+he z&*{-uV>PcTu~U>%@e-n_s6c>%Y(Q|Jz5&xBCyJHz%w-REsGzwooE6w?y|v>Nrl=WB zpB~@5ggNID(Koxu0^s~(jJcCWV<}5?MHU4mfG9fz4%W#$+LPam_u@Xk){X~Vh|bQ= zfVn3Oh$ieh-|oJ$)zfxs#_#@0UVyK{=#yk)9OXDm`I^3c>ltMz5USL+rgLl&Jq}-v zQZ~;+AKqfMVA1gW=A9P!Q(ftCeW-Y!O`lEt2cg(*w?w-wjm-hD7-_XR3=_$hjR%*8 z^8>1*o{pr7_nr6q^717!e+PHTxNf{M;Ol8zvI0CTfW;_3KfpMpHz>zg+BST!EPk4k zzp{?|3MI}>T16$%*ew$^xXhhX_6@EEX-&d2>tK>6J;b<<;UO=Jub^eE^6onT6qcQ3OBt&%9F&Ly z=!s~(1=2|{vIlv6A1Pcv3+NF*SmZRmHL{@xyvf}0P`I+Da}7z>P&fN;906mRD6BxDkW&@CK%)6pW3(1fXddrBV&3FFFVJ zkx9<9I-igR07`#grk$UkZ`{*6y&)-Ec0&`k{32Gxym2;)sDPCqLj~N%y@805anPW- z#lp)0di1?2V!2U zxw`qeU}Y!!G`D)A+1hD$v3@d;B({{3)1uw>%wdCMk-GozqN1YR;eH2HOULtNfI1oo zq~%(;*~i?r7S!P<{tU1kkn~^H&${Hl1Z-utB&d0C+Wb@g@dJ27gKJY0<>CQkZ_w<~ zA4+pqt}3DoE7R>AOE1Nz;&Xg^M425A1 zj%_n=gaHNwS=~^&4Fr`bJHjwfm6&rVovz7j^o|<)xR=LKSu+5~1pgfSGaY1IU0rG+ zI`s71+@H}sBMkwc_x9xQjb{89N{4?M!9@QUj)$5tn6G{Aj$=2v)ZgQEJ6`WrIQZU| zg7YMM(7#$DS~uBf;v>NTpa~Qb0VEI&Bja1isjZ;b{yE@H_f3=PWa`d9)NY$fsLB0RU(2I_idEJOKi%!%NGcq$>4$8p78Vn2r7^eLk z)Ug5Fy7B zT{^p`-SH@r_X#e0B;cU^+B$P&WI?|S5ZVH7^xf4n)C+I($KBEVHF3o;-3{(ew>7#nWWdTWGlPK=42bu!^Wt1TO!

7v2}x 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 literal 0 HcmV?d00001 diff --git a/dev/examples/03_LLD_CoRh2O4-30fb550a.png b/dev/examples/03_LLD_CoRh2O4-30fb550a.png new file mode 100644 index 0000000000000000000000000000000000000000..c3cc8d369bc1994d5ba757a80e353e4263c2e68d GIT binary patch literal 22196 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 KH(T2={C@#5r0neg literal 0 HcmV?d00001 diff --git a/dev/examples/03_LLD_CoRh2O4-5d37d1e4.png b/dev/examples/03_LLD_CoRh2O4-5d37d1e4.png new file mode 100644 index 0000000000000000000000000000000000000000..c2e382eec885edc05b3f2449cb2a597c58885cde GIT binary patch literal 67167 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­U|zZg%qKZ*2#Dof?-r5N8GLSBu_v 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

Bg8iUAvi&b1BfWP!i+Z6&uQ0 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 U9JBO&ED1kG`sRD@FdWbQ1HZyYcK`qY literal 0 HcmV?d00001 diff --git a/dev/examples/03_LLD_CoRh2O4-ce111d6a.png b/dev/examples/03_LLD_CoRh2O4-ce111d6a.png new file mode 100644 index 0000000000000000000000000000000000000000..186b6a5187105b22a4fe34532a78b5260ecb3bee GIT binary patch literal 18395 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%0D-HI_Gupa%cu;8|$o!+TvBnR8<|hXS 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 JT7{a+3cSF!*A literal 0 HcmV?d00001 diff --git a/dev/examples/03_LLD_CoRh2O4-df23408a.png b/dev/examples/03_LLD_CoRh2O4-df23408a.png new file mode 100644 index 0000000000000000000000000000000000000000..0e697fb1b03c2a0ac785d4418ca74bc4dde75686 GIT binary patch literal 48727 zcmcG$c{tR6`#vm7hR}?4Xe_g2OR^Os5;GVrLMn>vTajh#LNPJ+85AP26z!oxLiVM} zT2VswBKy8SuebaDe1Fe<9M3=Z_jf!U9St+{Ugq_>uJbz2^SY)eBSU>|P7zKfCMIqJ z648W-iA92miP;Rs44x6-7mxxEtWMfzwV9X-6ZUP|uz}zAkWKV;m|nJ`{(xU3>_{eO znV144nV4=-n3&eVQ@4IIG5IJkF-=%AF{!6AF$sBOyf@YWZ)GwdYMc7+`CHBLCc`IK zYkOs5rR9GAc4%t~@FFEteG)F0ilc27wazC3hCz}-OLQKu(FYM#8Ar1@IP!$Mn z3|cfy`OEIV$rxWX-ldZi;Zum-7-<44LWZgmkBpbsX)l#$6|hUrCA8nW%Gw^y_N9sI z372-nePNT-Y}P0Vi!G4CzBfY3$q)^XS}k;fR?!~TEkVCuv^WWp(` zEY}~dh`q|D+A93ou@2Be(W84#{IgJ8?zgfpMwsrdUoCw33#XU4}BM~#^8 zDZ>-t2n6EEq5a@rx?&w#CpX~lPYtF2c(OLPLxTwZ=a@b;_;)5jExD>_xnVrr_@HiJH=l93)|y z5ZbtFLil9t;Ymb|nx60{e^z{?gnF_P1^$E!e9ntR&Kv`Hu3R`uH5%NPJ9IN#5{0?&ufh{C{@7S)-7ou$?;x;5Q=1+`;tQ@Nog9h{1O1N0 zn4JiVqGJ@JsdVfq;fY9T2bdB`c@|m``uq9+?E_6Qz9#@&d(J81Jz7=~iYHgq+5-d? z9t4pP2d!TR#pSLLY9kP&YwG* zq2@W<5Z8S*Xlj1+Q;M8<*nPN!URXihYd#4*N zZX`@OCs{j8bwL%1(RY@;RSfnwxo|}v7xq0!}cc-l2fsOtWkHH%7(=vd|s@0*G(AjWt z`(ks~rHN;+PAs+)dK&H>z5?Bo5~s%H3~{d-4ylZg^*>C@;L1Le--4&ETLrEE$p;X6 z>qWmJYi}uZj@$WYaD*MgKqX#3CS4<7K3V4ca*y49*Q0*ZKh@$@-F~n_A*na(>{&kj zesZKaNj&Ip;c$YM7$MVtDC*t2cYnI_p#aH4Xk4~9cdpH9d(^7myX!32)+-N)&~5$cp~PBOagCIv1SE$sxu zBJ`3a5F<2M1Gv4kE(YK?)g)p{J6Va8sy}(%-QBA4=Gsi?&IYvpd{TxP$J|7qcok{1 zd!BlX6)XcLZVXxtjL+zQ@qpDe)rk#=kfolYPQ(^)7(W<1N1XuR#3cZKiz%$2@<+5# z5z3}|;C^~Rn)f^bF)Tq~qKCmSEpQnUhDzk%&85N$sYtv!g(htip}^}xg36OkgbGoH zKtspUE(btWm}L3iKQxhqJLyQ_9CZSL?yODhgD;)Lh$3tqVOUv=qK;!h16+?H97Z+S z%YhD~s!N=r5k+{9dJ!vVNZ|!Ui-G~%5vG`&LxvUNv}M7ag4;nn;W|j7v~zuqhbgPD zLxBEoT>sxZBs>t&uA!ddx&Xh6)T>iiMqKDH+LyDpE(`e-6D5M=`UAt%F%)cB5kymM zTYDJ6L63su*4FzHO>#gkP#>SP4Wc9CaXJhxZCs~XBrlzSM2w)WjbkWqhYW&|Es4O| zfv7dNg<(vDjawvgYyWE``_BXHoEo$|6~J~=ZS1KN08#3ku}_tA1aVK5Hq!_`xN9fj zf55#EWz_SOT*Y&gc(L{cVG$D8Fy{gUy@gsB-gBa^2@nomTxTk}2@ir5KrX@sWsHf2 z^CPs0_!yMVZ|cLQY*x`QBsPu=la-VPq~H%gFRU&mPFRoXY$*l>D5!}4^#drO#DjXV zm>f)}5jfR;0I5p0`sk<1o5IF-ZAM6#Sm{BkDPSTspqSFV0F8l5a_BIq5;@7jop5d9 zB)Tvd6sssuJ3WXZ1b8m&C@viETpMMdZpWQo!1B5@axUwND}5E{JK@BM*}DB%&n7jW7oA5voEY zKh794j37qB7kC`ZsD+jcBP_2Bmkih#v<@k+u+At9sfhz=)5GEapPBfk5@+!3xjD;6 zhC*INMeye8+%Dd;CVcbTm?{ZfF3yS@MiNM3o^^I-SK{xGzn76%`d-`AKdADDV5- zAtikO3ICzGsDJ8 zVhf{PP3-Uu@EV`wnN+RNZ8jkb1&5YotL^y|A*-8npccQX+Fl2x+2$F9`auI5V(%0~ zHvMT5+L4^R1YHXHfnqhR-RN$12lX12lPUuDAuxFpFSKS05)Ve9sXaWcXsTiu${1k~ z8=ID`L`WsWvW0cz42{A7xugj<@L*zL7#*qvuQuS`#uODt7)B9QEX*n#CTBovKmdd> zBT^I^d_8#3u^28VgD?pU_h)q75b|IKfp(BYNcMy&vzjwMi33GT&2z}Fa^XQ{rr0>@ z7Gb~U;uZk;ajl)TM)A;1DmMP(#ToDcTGfWRTsU?CF}{?qbhBU#&jvL2sJUw&q_HNmd6THPNsqZzt=6N(s>FmR)ab`6nQn}hB* zhYvVC@VO|TasY`;J$n6Hk;5mYG_HSQW9zHc)>m{SYW{a_!VPd+%YVPKi{JE+Pk~qo zDcnDnqbvWM)*yusD)pVL|Bz+qa6p}XZ8wves;Qi)rz9>DVMU!h!db4b?TApF9N8Q} zZ=OF4URFFHMV&-M7)j+YFIZiQ84630cEEMwBJL4ckzt@1X0_8K;J`#aXC;; zBOavwU+Tuj)>sPpjL~g+ft-QSo+wU+gv3+KHG=6V>KYNiZl|Ib3}YNd6w#-&2eGDQ z7d6?~Bc%!$L9BFGG#@M8R!yW6$!$ZVWyjhyVwpkxCBj4zCxOJGk&*FfTqb6PRJeMi zh%S#d@u{>*uP`pJ{Pb`S$c`NZ0YkWXGM=-uXLK|F?PTvmma93QvUP5Xzd+K;n2yBk*|=8etG{Y4>B#@&m~V z$A-xXWuN(SiAYO;Cm(spkKorO4P#mB5vSnVtn?a4m>R_@@E&9+L{snmHhI!g6?d@8Tml6Ilh2zC1*>_yQr`ukAsb28j=4g|hcD{PT)!W8r!{ zZ$VhmL5VJ)8dK;)2L}Um*3{HYJL3q@yiIFo^Rw!J#*Lq)2T$M2@crSU?8w+9zvKmH z73Ga@C6!CR!uK0yo!BCXuea}EM=1o%+s|l5j4Z5ueRc^F35PDdw0P(GeXdb_=cQl8 zZh1J%$nCfqy!6$!u+;T?QJ-%ww?onQzv+<~UM(``H0J8IRt5%odwaisk6Kp%0M=T| zq+`!M>-+}5)pp;&R$r;-u+isjf{{MmZUo+l~ z<4XhzO_vAF@CTTZOB|s^5NX(JU+xi%Dyb?4vEWR2j0+j&89+!Y?ZejT^Jq`GNgK;y zq|u#qieVobJ>>WiwykKkibjunM#p@K=t!g$kMaxpmvvejRKV40^8B=+v|2d-_Y`na|bwNnPtC*Ldqv?2v>dlRU&21 zKi*uTElqZ7t^Nx41DdAg?jiTG(R)DuhX{kkN|H`)ZvPFsHVp;P7AvyQAZ1N=85nEs3oEQr4`S5FaqwV z1bCuKD_S}l01>J4YXrReIEWL;FySOzI*BFT2j`gJ>X9p)8#XfCl<30+$bGv z2b^Lw`TTCV#c14z-WKrrXt$hs5iYCEz2~*f&r(m2{8l^b-5~qUsSUF3o|8G@abdv1 z*p(Y)qZB^F)jFvYo?T~Ew-)oY9;mwaJ85lv-*@E0?Bnzs>i^VoPL2Bw4RHt9_wMaq zepm9gq$Fr&4-oj{KSMUA{5~Bn;pe<_Mv?^zu*c&aD(dR$A66isv56FoKtq1S)thtm zt*wSLnh+Pbd|SUORmG)K8!QL7Tl?bgm#l)1X0<`sa_+?12mp&v5LHP;?qdL@fMxN2 z9Gd&hQYYr3+Cr9#2UZ(Y*VoqrgMzfyI}(^zW2#nT_TT))QlJf%5kH=h^l7wmrDA3` zN3_AxP&oK10V?inj%$U2;6LW}L&c_sa%Z1VYnGPy+p?kPL(?A?TEXu*dN`P4G07=B zz?3MCelW^sdNM}|D-u%>Ul4&r^B#SeV01Tz36$rjHz}8K9I{jlh%MeUE}$vGq7}n_ z^eX)Lpzq)r_E1{KNKp@_EOu~+RR%~e4um5RgeJ&qdbZ`X0^tV)IK=WJ==yNPz2=9> z=(AUNv<<>|g%fC{n&A&YP~Jh-nzv%56)8CLoD6gmCK9p|2B{BS_qxopu{uzBJ!8Q& zI3*P$ltCS8gxQRM7^Kzk0yTepPl6<2{vosF#U`;i4WuFa!fySyBg z;5c8Lwe?pYEMElo0g~;Z#C<~Y8i2*qr$1d`@;ajf9 zdi(q1X@FL5_yI_a7C1CrwG*NoG~X<>u(k;ib(l6l0_^7h$`*xT&Gge(grliB<-j=xTze7;e#aCBT(@sfK^$Y8Ec+F+AT?kc6(7W>X+E-A_eEt?T8m1rP7SIH_1Bu|E{)Nn!FXeZ4=1_uO z`ibCmpmf3CV?oP*Yxis21h#Fuf=w8ihY(#q1U6g@RKUBSzFJjnH(?Y0PE0@|j|3`* z%FI^4_=6QFu|Ql`0gT$q&VF27Juon^=(}rZ=+4;ZbO6ck-@oU{== zPk+R1X4xix!0J2Avu|;70nbx3>J;_bZ>lWSo8f4Dmt3GbVsv+~P5pq=8ghJle{qn?x@j%k9-)b zZ`5F?_Q^j_VFqq{B61KZ1v3C=7#HnS2p=5s1xVP3mR3w|_B)w^87_yRRvs?> zaX9FfaE`^m3ZFN6s8B{1NPN1;_!Bxt)#y5|M{?RCAZ-3+hmhh>XcLzIPg4h!K$ot^ zp&KQkLA|~G@0>gSRc_@H9wQp(KpL6L2?`y)yz4OE1Hl70(<~_B3m|eTm%d#AUi{B* z-y+bsij`LUZa{#V3JwGw`{Li?wyPf1Z08@J0a%OML(`Zj$d!Np`(NjW-lp3T#PnDIXldj(!!v{ z<2uu@vN4K305Jw?Q#L2T=yrn91yrtJ*)h|jsrqh-)4pGB-9i45JAkG{*_3YP`R2`D ziH3O^>_r;{?G;coR8TTV*4BMlbqg*T@$k%Ev^P(!`5qVN2zZPg=mcK$23^Q;xMNk8e;9>$>vv}Y^2ZWNo>jHpe+>TuZ@+>^G;l&(cKt>VJH z#*Acz&;=*+tTQBlf2_|sT12X4J_U*+(Be473;}K#XCl=mAMj8pG(lKzuZ?F7xRvzv zZ%zAY0T|a83m5@36OfutkN;TobwgNKSO9-*u-UiK&@##0vQ9p_>~6JKI84tGfSeT%qsO z5736N^zP6lkGBSc=Ix%v#l={0t&rx#gMbaS4XMTFz#tqs+m`F%K`Jz3wRY^e1}Yqr z!9V9v^qKf#UhKHl9lF*15;#*XU6RThTQsQgLL=~aw(b%UkZ9cFKf&j%0xD^tO=|#O zVpAKD5d7Ef2q=JGo}35P%>G^S4d5mT*l4Su00MdwvbZ{&P*PIjq?FcWczjB8CZG+p zI{=65bRL80EkJ`!<;2J{TSM_fipg-$?DUjKXyFtS zP|IN^BYo;fw1Q}&Lw|0Vw9W;`0^J~r=I?fQV7Ac#4!J|l43Df2Iq)3YRm6H3PdUF{){38OyTlsC_7dLd4XdQPC~!n|~o zC(}vEo^0U=?Fe22NgWdZ0TbMJE*&{O8#N&*7=|7Od{PikuI>aXH`hZVodo(Yka-7B z&~m)QgDF9fHq<(2(l~v^Md23 z2%1VUqx1}l$1A<{z>Vbw(87RfBCdXpnuzgzxYVE}pRhQ1ZnM8#fwbu}1Rgjt{wHWRW^UNwLB)#hxZmIi3X?fSM5p$F9g z$apVEgMruq1?VTR`;Pa|#jh=lAG!SIH!u&QhSmP1LsT>q9uH<>Kq-rd<6*s*+Vt(}Nl0Rj}{_&d;g^q(^mS1MVq0%9!wFkEro&;iq0aM@i~l1rfOII>gsh>@~RG zIPHeV&AsUQW45I~9Wi&&xM_xjy@v%QIwvH7E{qb&&T*CqhmYB@Iw-@kk31yGN2+*= zhmlwjSp6JF(2ED73^8ziJgY9E1^2)WRv1g5WmD)RMYR(;q#M{%b!9Mg$4L<6CHm1g zKATd||DfG0A;9biX*eA`Gc^OBT!4X1edy)ynHj057o^Hz(V5ks<0shvt@~AgR)Pe+VW!4fta2+-^#M|P zr{~vh^6NTAyckkzkS6`eDb44m>#Otd8zYnvot}0SPKHq$_Guw&F0~-Oj%2S~AUkXv zj^oR|Uz)$~)*)QM<931Uz4gA4-r>V29o}j+cf%E0M{;J~9bcuYA3 zWtAnaq^8!>-R%ct$}VC-l-0Iy6h}{EC>zzAyPBN(sXemKCGX)^%D=RCVG6Tkdt2I3{Gw>mR zjB4x;f`Smj7|_aD1-_&O2q8z`i6{An8ESK#r;kA5)g91#pw!xe5{#kIg(v2`iqYH{ zfdG}Hb0PCdK-!}5z%+wc@F&nMI;+~J0t6i>vf{ZC1AjL1-*n*fJnrC%kJ;Fg8f{}a zmBa*ain3&$INcnP!~#Hf*xc}@cK8Gl1w*4aU16p|zk6%~zHoHqfPzJK zEn0WR8um}B zq}O+D9*3fIL`_Yp>z+L?Y1XAW`2>>h=`j96DV-sJgQZ>Ay!Joz9JeW^h~js0I;qgO z3ZcC&$%Owu6w zasdDcT$%vuwUd0_5Hj#?p@Cxz+IY?dxbd8ABm@XY7o0@^yaP?ticQe)`r(rAo`3l}khCTmzX4ufpVz0uP`7Zu`tOI+(>J)Ha-6~TSb(md2{b%X^hy3- zn);@n-wNbw7PqR$>>`awb*>A4OnrVnIsK02KOy6-?z zEiZPR%Yr;?r`8Xk#Ju`2-*QHh4B%!rOo5<2nTTt}&um?)oWH9UU&yV@Li;pI8v+b0 z6v(z#jRgj|70>>$5R@elZ2f_gFF9Uwd6 z2VYjMPt4pLKi<;-$lo62TO@}(Jh60kB5u?F43&vywKlbh_Besu~ z@u17N3tSgak@V)u_?BaBKCroPgif@m8?4z)&RVTRF-FBR7Bp9JzBt~axn$rKQ0g?N zV1-TDvARTR00!5bL(I^NHXq_fzE3?|GPKIu|;8n95%kCr$UyiN#AK;lxH0 zTu#PV9|AW9h*waNtkGkh}!B;kzeVT3m$2xgY^1d}z0o zB^LwtGjrtg#bFuR&`d;>?$*7&)R7zx~l1~B6HJrty?WzM!|xY5iF8+Pf#gJ+eEO8&CfHs>L>H<_+Wz?Q!TS3NHsUOs_B?`Ov%L z$&)G+`>TF1Pu*ne*oW1gq~Q%w9SgC8^L<3>Azm4VaKxu`&IHmIaV$>Rtj>cmN~__r zSz`_(ap{9sxjuik8`mQd5Q2DWQ>vbmaS)={+CG+HYs)U{D*~g7*5@ z&ZH{r0poHJrLM7VM9lzdtjn&jwE%Jkkh~w&pzjWb=sqmHaCf_YeYgGoY|dHayX!Jv z)@mK-?`=X&Bfo**B&l;JHfL)Sw6<44QI5ocNOLGV6XvFne$xKTg0tkt{y#G_p}+)# zsw>bn!@x_u4;(Ad+zVwWHZn5se1P6xvyjy0BY8pNr@3nY?~Z_(xfHb4TJt%`G>1|M z%8%RZV*WtPLtz4r8A?6-Tq~>zIoe@=%(Z70x*uR>0e{~f81##Ox_176p@fIwJb?gs zx5q=b$IoZ2e}VdAC2!vXMthm^sll0f3|&+UG_&$XO6Xb&NPzrTuiOFY&<8V*#`>af zL5Xot5@vD-77mEf^;bLVuby3c)$h}73G(uAje}isRN%Zp=y76$bi!j}Il-Wypaf7p zauZGj0u%0&y%KU7v``M>gO**tBvebp+2LSop})Btp@#J#uZib}5G z;Ge%{2KIv09SRn<6jDWi3NU^b>W_qU;3N5=-d=ju+JP@^ANgi|L%E|^+1=YRcbLxz|zEk#V0QyfF!43b@ocy8$WIzg)1rS(GFp% zRhwk+Sbt;Ek&}!?%6lGrMBewV@CLbi>_(&}yHP_=1g+YD!(`+bo=a5$vFDC6=Q|HC zv6J#wm=sdmn3`6cj&b?s#!fb4?O&IOqKz|=@;3-HT~cuX47{qt$AS5Cn1C+uLU(37w1~wdvo#ov&X{ z*9=;Qwi+08U+C3|tW=4(A!nR#pm&7yoG6=Xz3bm1#alZ49cc$Cq$G)7+%91D=j;ft z{^{7B+eqPxw;>71%mopF4eE_G2?hN8yZCT>F9lw74 z0{0&b+6MBL?-xP$uncIrA3uJ8QK7v+Z>~q(%ox!mPVDlz#X{gyK|%mD*OUY1N0yhD zKc}m{0@?!r(t2;zR&UTu#Y*MI^zq5(#Xov`clm!E5Vl~1U>2Ht8cTN%0i^3{=+@Hr zVyE54bf&*;P*8c=VT)4mDfd%=1h}Xl_HE?&KG@s|`F~&8wdeKVA*;0(#YWV^3PIr~ zxI)ajvZ*7@*a3$^GZk~_SV%@Fi z)Ct0;sXyAKyd#ua%_T4Wo%y7l7XoBDc}F~GR>aQISI~ER=lR>^6DjH!X11n+(%*IU z)wy*<&=8+tavnObS(QW_c)4qM#r5p&-1Iy_j6R8I;_bL)&o844YhulrMeFh4^k``c zN=?pRFqvq$erZ|HU@6r(|+~*iM6et;+xgt$qs9l z151_~@F%B((Q6|vXoL^RHvaL9%Xs(uH{{-f3tx{$8dLB@Jf+=`sFqA-2x%N9lI}Qr zFz)6Q-BK{&Isb~o=mlBYKrV-@@0=em=kqte>9u@8^R;8VILA`AbMeau#yV}95laWg z5)HHsedy0$pZ+!yW_Nk!aekbieZaYRwMG?z?6^cJITEpHK3*6T|GdaL;vU+U1)n>a zDO_)88=-ESWvcM(>i8|keEpdIhSUrjOC>iuJ7Q}^&N*HlkN1K}pnDjl`NZ?)XUCpk z`#6`Sh{VD5N)BE7hQ7DkcitX;T>m>Y`|Yy_i4@_a(4 zYY!@}p1V-?s(aF>+%i7POS(D(B~Z=Lkcy=}9aJl@GgouabF!;Zu_8X~UmCiQ>wz3k zBDZuvzJobOX{ZR`Hp{ zYn2Zx5Ut7z-CjfHl6l~Wanvl39^l0W20Tl_agFs}Gw2K2OkcmRcOfR{BXpSKSJr!s zna$Rjn_zf+9qML6E*@5Vttkc!I6zY`KntP36&PHXB*o-p65}-*7y@RJJJSPO<V_(o6F`lX!-kcC>%^`0z5D@Jn2#Q`G0_f)Q zMzFP;n_F=37L?6UYoy%eKAgGn%t?j(rkH5!SiIW=LKpvum@FvTEqz{OiH^!2O1={% z-DS!~=3%`Tv2v9N`i)E%1n9|$R3U#dz9EHWs--s`uVY=A z^UG*hkt`hvw~2?VB`a86p6q-%y)TkaP@z%|<#;phm5eXm!WL2Z2{qAtO6z1Vx8(7PdChO-i<8Z3BT;yp^yhSoR^w-tB@%Xc4{K|Pp3RS zn)daq!N)?Y_w5Q;?MH?=3ZJvJR$sR1`h2|D$JS7Y%%8RL6?bYF>wDWfRQ5w5cjxZM z6GMwnV@ogYarh2C|1HOo9x)yxCCZ+&JM&aw_js1Br~BCOo$Zf<5?E{->3k7U8G%@Z z7o~rklX%TBBUD%yfA$@4uPt6MxwuH65CQtHkAg2O0Ac#K^}%tOM_{sJ6m;D;rUtgB zW>({8X8XyT6oO2H9GatLEh+4mgzfTqsfjz}GpwT?eTFZhVeI|}N4GnsHGd6GORj7+ zPZR1DzD=Z!S$G+q=jAy_A~}>ep3A?&;({WYUPwjf4DpjC!4{IIp=e3i0)N9pXZI6F zK!AWJ8i8*!2fh^(yqGIqk1RfSUoG}~?p3wMJU$&EbbjwM^Hly8uDK{*hpL7Q zj@u6N(D+5x&O+$6`_5F=7MSL#{rveeaG5v3ZzZ9>*h8%C>{vh;kJ)o=Qe0THs#CEr zxip|}LU%7>$EYzGRM=11Prp-UXdkgZ%2yu8NQ0Y60t0fj-fFWRe6a`Crf03m5JvI*PlY z8d5hb(mH8&-78-myX+$ND_*$G_e-ZHL*VwKxo=n8gXh3>0bP8J4jM4I{Xrn(Qiq2v zF;2gvkmR4trwJF>!>dbzdrJal01ODR*)8Y297iQR%($hU>UvDm(YxHol1=c}I=8Y; zezxxSSBg%$)-D!RAzRSq0%v^7eeIt6;B7>8sz9DGsRoZVFlOwT(A6~)=|A}R(TJMj zkU*B%Ex%?wH}7}yqn~W@0<}7rE>58%LglaGjwpSOQqMAr{bqR6{_?d9s%#CHr>vo( zla95E{|tmv03HX{CN5R20~2{MP_t~mKVbP;A?q&j>DN`by6pQpZcNIIm9IMKluw*W z5FDItPhlfBH+f1U#*BE-H7E?~>3O9TUuHK}m!a9gu(EYk-hI*~cgs{>2bUQf9L?ef zS$fv|WO1f*$+AG3T)xeVPMz>0syq6o!%#ck|J*$oJ9YLQ2Rn!R=~>2vZ&Q>|;7FcM)01PV7c3=CW6W(nDIY#@ zF$p{Sa-Sc2A4faK**|syTX`Hwk{^nKqg?j8xh9?0*KbvI{fQobTOz*`K&Bs}2d}3@ zFj9YIPE`g}RIymd`1SDNw&MDqohk2I)H=HT?X8jG@X;CdOZtq0nU~7C{XeccrN^G; z#+R?Y)suf7m+I+f#|U{_%a*8++yC(M`X#Eelfiek@+($;j%RFC&TLeQ@63shuX4chi4STy4DgL#47&U@ z6r!Ku?zXs`e}#&};W!%P_{L2<{@A+LWoDkP$mzfDU6EH1&-eOUx_^qT7wWNxXD(9f z%Xiy7*I&xwbbT~V8oq(ib^RYDAp;mioN{sS8m-O99S;?eCr_!b+rSKgTF?h;iMwF| z`gzsJE}83s?~G&3Z&d5==1rT%0+({bFen>#7qw@jgdZg!$*ru0z3J|iYsFd{#afF5 ztwq3#nJ!!io=?iU3DPPPgv<2CldSb8$l*qLgZZVcZIO90xtu>?Uk|1}C`M#vL zwl%!_POxPuIO+U)1Jw^;Xs>0?tYrc#ZEw$yAM1~-)*n?{L-mq8050}jg?mgc`p&HN z8pmfQI|j!e%6;~ia_JqVBOhdv5sofwhUwJ2ksX z9zRU)x?sZa;wCa0W}PtUhE(=~=**-qGLz5==AzAQZ$BEzuuGtNcu~3%)wOk5M^V?; z4J&3JlInB~AE?LQ#@w}Lu;hpDos}=l=R*9ZNFGEx@e)iMRc>cqPd#Q(IX2~K*d3Vk zz&J&-FXXO7XNQCR7ZJ{e1U#XH2vL~^hjc>mW`*}!F@56V2>IYTl zh0zliMzuZfu8ZECWMpfnUH8&M|{F8)@ruCd-b^~?J=p>P)_`RwI`GU~h z+&}%Zj7PWSR3)GFNM84jV~N-=@Mbnw3}63^CO5A3G3ZAgF|$Yl;Z=us#OvRqJ&J#B zn_>3jR78?UpZ>IyhlZn7 zt#78xBv?~Y=U&G6oh*G7U3pF8_1mtU`6c--v5Js{jNabsBV2ZhwB{iBe%l`@s;~Ib zvNb1iPt#9h9Vsb6Bc&1ia0jhRhwvf%%`V@VyE+3C1aFum9nGX2tl5KkW9(4&ulTqM za!xAKzXrbo!Ml%T=vrlt^s$*q-|`Gtb%v~fNtB}FTmFj2e6sNmX>Slu-9>-ex0UeR zVBYDjkW!bAH~Hn}W%zx3u3A$0RFr7<>r{#6m>kA@&cmPG`<@70lQ`O6&Yv_4`*6Bi z*O6a7F#jxX{7F%m^jI}4-_IE87lT%PdD$Cj^3tc<1bMWC)Flq^r zMUZIZ2n!hBy>(8}_Dk*OE>)Z8G!IIy!38mfk3e#%+!lnVYbVdlZ` zh%G2%&#$Z;m3ngMs8sIxFQDB1dShAYF{mFhq7SlxoTUE!IeHKm-=(Me-()5R z^XgJJn4PFkqha8!_xj5>(&b8gtQM>-r@37`%anh-IG*|yp~iP&>(9BJ$emg7>7QlA zg@tps!KCHPc3;&29qTylP};8LJ-80zJ3>D;LGiuJI>yT*#mI$`qhM2YL1TO-CDt#$EWI&`B#tMq-4~0I z_EpoX=tk{BYTkG54(_7!Mc#JtG;7Z>d)4%$`?S~nw{;c|uEgi2S)64E_=@5~NcRGZ z)K}CVUgh($$b}^~{q||157Jmf^!MqS(O>~O_ZAqOnHdwdkr^Eq(D|W+w8D+ow5|%m z#V#i;&-s@gC0#GljD2d{w^OPv2C(P-sQ2;)caSs z-d6Q)ZBIae*WC;$vG-fQ-ar*_sK zrKG*P;HOo*5$hMVb;Gy$PnCAMnfl{9HW>W}G`@(B1UQ$NUptjVQ7nMaVP0(GCZ!?jk!A)ylqr{sFveVB2*#ke4xmB%ig zBsx|N&+nJ=Vtw#MS9AWai{x#N{(N}ON|dIk3r3!n`mNy5!HW}VbFMRIm&<TG}N_zGNKzUnncuCKAVZWxt6IP+gku>Ad9-pJi?<+kM zjUvrOZwst|3A#q4)?)Vlr9jP(_?7DYA+y~fQ{B+F7RED!cp$;%;~gA_=VLxJ4Q41e zq5KBb@HP0l#rO_N2Vzf9KHXykDpqH(+!nZWZ&WpOL6vM3JGbjxZg=nOx*&ji1uUuRvy}dT1;uYiBKM2MSfl{b>yO+eoAYSI!-%ngb&q z3LBf#Gu!g7KGbxSazZ!ec|D|POlrkMocx&WqE(m5&SKVf*TClI0nkH|g1$2xy5bkA zs@(4O04J_qn@zJ_%-Pg03RkH2R zBqmHK96I=V2=b{Q>a3`Dl34m`V8*Z9lINfVRjKig)-ppN;#B#Zfd0Nq2bV~;nLt+Z zjgeYz8m8vLP&KYT-`%cZFa3i_3g z(1_#*FAj8KzARa zC^?+iMAo^OZ+{Q`XC4OUbE*}wzRigRXU^*@x0@<_>IMq+Q%GN9#Lmn#-`~Wq!LEJ_ z(;{7o&N{?9n$ZWE>Tf?wdzZ8sh}@4oMD5)Z|So>VN!~@$=;tYsoFLdiL9;{dX1lJ6iSo) zeg46Vs&~FIwcfb9i5_w<4dkENX$j<5-!p@%jk(!1)RYNt>$Ayvq}?(ra4?mE@3^TlW$M%qGI%E=! z+Kyk`AM-_R2CHm4{LH{Q;;BmW+51fVCzz8)usoQq4@ReKqu2~sE@^!&XZvuh5~lI3 zg8f5zu>h_R+1NY$Ku=&fCiS3@TH}}OJF6TExUqB#{vT@`FZgvxnRtzT9`U|8Eoch9 zC9$^ds`bl2OJ~)}OtmvTzH-)6M@JQE^(kyJF|^F~QOVW|49?^BM}wEUJ}sr!?jaN&ITcc zV;*}0lf^tmE-*#0jFR|0Q!hNC=F}Wdq2Sa;-A>7V%;Wg@vb&(BMb@$wfuoev#z+b< zPH{l{8WR(yIHmwa1_*@b&|Wi!u2mz+sk@9O7Ju>o{nG!0LHz|DJBAJO_-j+o@~H?Q1J+bLz3;;tHJGE#^_W|X4|~6}I#XS54DT zb-$U0KX&!vkE4?Zr)v7>Gs&n^C^E_RgcQSgFV7-jYO~!l)izRhHOebhfnP!Z zb&5AeT2*walW_OmDWl4l2-W22D{RI+`9E_$|CTlHgyC~Nt1Tw9{l`(mlI;qSUv%Q1 zHF?qHE|E{lxhR+YP8~cnRVANe&wo3dattHa#9>~Y^i?L!*m9bl6h=G$m-gstDq4ch zg+8s>l_w(f#{YLm(1^w4%1{Kl|PDV z*OuBds&a5pI`Or7BKw|txw|i8uJRX4Ux2nI)!}X++n8METS~w!+wMCyHAp+LhySxB z#m`mL80LAp;8{kRAf(!26&q!(@1^dQx=@#K*yK2ah5s}M0c@8xC-hoFs-1wsX*u5* zBVERKOgYa2(-R@^Vl^jV2ukEIAx0V&k?3)PLwbK=pn+JiYhnx0a(^+cQ-21d2srF7 zRF}k$M?Gg>W`ABSvXj509Elr4T5-Oa{E6By{&J()f){n_z}fgR9P1C*lPhoy@}nBX zl)&rN}!51@i5BEaoA9o1WZQO1-`%sQ)Io zu+hTiZ|bAf!o*>Hoz@Xvc2gmW;HikL-=l})MBBJZzB$}KwD0n7d!0-V8Vy?^hM&{P z5*DFkygxER!ae&Lf95n>2tVBM3HH$6*I9vahI6M3zxsP6%XGKA=R_ zdj19bGPYLb3nzI$8B`ST8MNGNF+fz~WAXAe;VEGS1k6}fB2`-UgIx~k;E(h1k55$& zi!hjhEiZquxp@5x2d2R58ylm@aQ$z3+n$r_vYC9C)O z)skN&v(?47zueH1$iF)LkeD8brJwI7kJRa+d7{#=ExFaNGz{(FE$WMo5y zS?pfR+mI_xoO0PP80ZQTLmRvJr%v6_+k9utF^Vv6Lr^5X$$PB zKkfhFQGDISkah8AxA*0}G2E)A>oQJn7Ghf*>(8oYO-ZM?kFDI8g;*5&D44#$pS-K; zfJGvW2zQ7xWr&t^qn(-hy-sZ#9?5S@q1X1bc+$Q|eH~ZLM*gr_#r~VKk_bUynxJ>B zV866F)FRR*ORh`>{%-ivmizPGv(E!O)sjnfVXN+T=KlzxY;XK|$7BCOtETpI>5ENS zlZ^ zs=q=mZ^yJ!?omMgbMvANRZ|c7Qm(pn$E1lyXqR(u?bxu&kkt*1H!?fFk!6cU?B(BSkLK@itYi+h=E;4N7_&?GqNsFm zlxkyvXSUJ!1~32k!y87!Z+5dUN}V*f&z&>$icN3K{Zw1>=xBfPpOUt-6PmxS2RKvw zxJQ2P+r0ne>@n$tjs7GpyY^pu*>`4cyt}gG$5C$kKGEjy=u5*VhEvPUwuQ#Cn@w~fUNGZY`GByhfuf5eY71*W{x`(1%dAb-}1)Lz~4TwNK_PS+l4r76QAb zONIE$xn<~yKZZu{8raFH6^86gS8CsJ=IuawTuo>7(DY~3;!gYAfF;^b{Ep_X1L-|v z{sH@(j_m#Tfag$Y6df$6({$Er165C3iWBCqskDP_0X@|0Nmfy(=8 zj<1Xb%40?LDDvNrSWcX>;G6TeiPVeBFv+27EVU}HWDBmFj3^hP(Qpm|ET zzcRRksL!|hAibQ7($d0y)|t(&fV_*=N>bH*$CuJ5HMJcgw4u3~ zjq9G<`KxOuyTLkX`r*ICKF;QFnlwJE?)S60(|8f`_l;LSZmj;ES?%R#+fD&Y=T&QD zc95QJs7oS~6``Yg74H_i{us-NxI2Rx19~*1Sk+fh)$#rm`iaiIIef+^BxEE0>}LGk zZ@HeuoefdtX=-X`l26K8PkUO#QF=cUeQ7?_^>K#J&CYzb22xqf3&Y{nKOa{~uVH#$ ztBZUs`-{rGOikx}X3w^u7s=Ok_E=aM(46~*{%!avd!5PH16-;-Dxn?EL3Uz zIJtaXT5afgX;s11j_=H#HOu*@txamJ_8QL;uk&}Q42kM$*eke>e;X1H%@AQG-!3M- zaieau_(jU3mtti5W9OHbha|U#R4iH6+Ho?+@teffRqj%~k~)nypV(53_H0aYv8hFLr;DmMF7IX=&rdBe2#v1!VlFP3%(^AK?y8(L zU9gz+7FG9b=4q3d!+ndzhvQy|SAV2cb1z+F*GT7CNJ=eu5C@GZCs$&0T!bM{ye{k2 z=I6mHE{_Cz&EL=0eRW-Oj?k>hY+_5=`Kt9y+q+=xwBgvG-}}-|i=}gzJ|p%k+&FPr z&e+7FLB&0v^D3wL|uN5libatv0!j?T6Ae`^A%0Z4N7uP2O3Omys)eNB1G|r9O~_uQbi}U*~Hkk`_x- z_3}zySf`dhV}8SIy*DE>MlWyje%3&`Q=Xmc@n)%(0lz!C!CZMd4b zn5ps-HTNdn+txdmE+`zfpXCoxXf-yW*sozP8)Cbx+g4xQ%;(DT=2?Wg!gN{A`(ehQ z5<~iJY#}P=Vs`1S5M^Rpox3A@Z;e^7#s}Makrh95PrO2Nd{v!M>7EG6IQG6=`%F@+ z)!ZVVj*3teumH?lh}&~W)1{ra0Nen6vrb?84Po>SfLs3 zx@h;X=EmOEwfm8Sbw6Av7$T`IjX4KV3^CYRaWEPkzhxuieobC%Ke6eL-y`KvFW|E?|>1-ZZ9`n(ZFy%jMtZEw_V(t*saFIPwMN&uLJylbUzK)|) zMs8Wbf%gV?7uti1&waejC4-6}9ZQoFz(Y!%hK1QnFuDFx9_Tzv`~G3eKK|+`M{o1} z@_jWiHmd*M9|xH~&I+BU>`6s~31ej-OeFLFn#g?L^r6-)RWfP(N6tq=_~(A|rOWm0 zRi<N<^$;##*jmxg9di8rl?ZoZDHr7Ki775Xqx-MI;OdEOl(49R{Yh zN_-FUo60L`%F6X$Hs0UnQr0XRb}6jaVdv@b4^}eKjrL?(VnVwZEB1+x{H0rA2;0Wg z{FZ(rrIy-hQ{hn6=qcVeCa&+5>~p2iw^FquTTUoh?UFu~jq0Up$DT!CkW)FDb3#St zFYV&zS5;$$rWSOm zRP3TxlJiIPsFWTa^{M0vb{3H}V^wQdR?{Z_@TwHuuU7cP$|<>)PD$|Ww;TIY@0aE3 ze_U>R-!MOORwnGhca3xA!%B6jJ<3+;6|AwRBTk5@H7pRVj!c@diJMj#r7EZURvv_G zNv>9Te9>s0u>0M3*N2r1(HS!G;;u@%Tycq)6Fc{r(R)+ss?Ga9+@Vt$%T}m!polx< zqj(y8y&b!~$5iL!TE4n+isYK>(Y_gT_Vnh4?BwW5FVj`6>nmaP9M1dS4Tq!08^>8!w0kr`WAAr1?&#aOM;FKrc-Z62b$l+T{n2o zuCbqUh$s88E4mBDzKp$_mFO;5%r1H-NP%^ z&|ku2yhP!@8>NK3-OH<|f8EUGKlL%Ct)np2b@To;^OVN@H$M(Yx3F#(lOPGg*=)fR zYMfx8jur!zTcUjp=6stPEK*k($%NB2uS3Sk^1pZ?!hOeX7K;n^KN7zC#Y@Qy6~R|k zUPlQ%3t>^ZA=w}sw6b|e_O~#zzhsQ#cCx0LQWlFtlI~zAg_0~vM<1!6d`}__i1)S~ zax|bjN#POzvhI_o+hOs2&AFJ^Fzan4rJ26HMDiS6%qb~^P`jnAx za9hNeHCXxK+RGGweVMM*5YM@L6O%p{o5iTStuNRImr4ZFnCr48t1WwQ*@r|$1Xe68 ziz&v3d*|<)4^rs zXdiI@aj?s|!Hdy~(e}u+T%pTO)#PmkLdlx(K{p$tZtfQS(3c~i<~~4n<&;U1pWc8m z)oOAbtKor#Jdn@_wHa&@UgG^^y{TixAL-R9g=CMYmw(VIYJPHtscGVX3Dsr;!FtZm zxQ$Bf%Jr}pPLwb9Z7sb)Zp60xdsC)OpYQHsk~g;aoG;2ydb+k)b2fBH ztKrg(>*`>&)OAuyx^+({t@C5{_}AXa`FKpiyN}KN%7%&iqqH`c+^JF_EAfVFbdJ3i zr70)OGE2RBdpx|X$Gf%&ONNoFo#D^3J0#~@WUoFXb?gY221SQ2>$|`zg#HA}1>F&k zlKJIbn*qn1r#kpwXX-r*@8u4;M%|d7L`&Q>J@!1y)ha{Yy#3D2w>xcD)^lWp?mp$H zf+bKuJWh)S1>Q^AaQnyk$Ir-kySN?iVw`|`e zy-oV}ks>D{HpYvJ#*zwp56>&S$t~^jpYtB8rzGhe7HOA^4Xfa{{DF#u&f;2s(vE3?wz8cj6l3}U%G)R<8``A2h%;r zKJ&YjeDM80y#N8O+|pYvj6F;rf112_+a%9_sUfC>C-SCGtqq-8W#A%v+g7zAyK>tc zI;YRaB!lCaG=hIQJbCQHa^~KhzGTU++@@n1 zDFY{KH=h0d-q)tpvcVmAciDb*_0D;@N0*-SQ4~)Bdbq ze3P?%#11m6QkEfiYvK3I`Ufaq+fXI@t`E5Jc@DEpClus%84gqWUJ`wN*-)RZi)D9>A#l$}oZW(7lxCGIKQK{1TWgnkr0t!D&x@L$ zyO*`p6vJ}6OLZN1$(rVW+?)4$!ObZDMsxI8LK=Uk=*vShsSiqLBS+FRlU7<@9F+{14yuSHx-+cV0 zjDnn1_XyF_MUpJAZeK);U1fIBnmTol5?w)yyYYlySTKO(p40dQ)s|2meGIe5u26QIQ&-?^zqs-KxL2c7 zJDKB_*L-64Sp$SBE*AOP+~5z;8(0kAVxw}dMR-x}PrT6Du3w2x?G$l4^~Za@y(Tg^ zKAyEbp2c8Z=y#HsJR7u~x7(U>=7QVF@V%dtBHCHjlMOumCaH)FhaBVkm>H7n8`z`E z>y>#+K6CNfUO%5R=|3R*U0G0iPUTs~^{V3h>QJX}^TTs{+Di*&{g?N8akJKCDD}i{ zaZ=3gsa~Ws9#^a?h_|PeaZrw{^%+s+OkvTi&=I9kjw_y&ffuZQq)(unNRv~i*3 zV@tV5^D2}bp58W8u{oBL!OC&poZ}=eKK5Uev6Is-@$(y%QafkQA~Zsoy}v}^SHB98 zVetBz%$@vwYy%N=DV6nN+**RFv{yfhtvikqzbh&!1-!VefC0X{ceh|tgrR`}rr3)K z3zG#H6yCd+xP>KOR(D^$CTD=yVPiB^{VmNd`cs?5f2t})V!+S0oy9b!`@7=BP)gw~ zrbSj?7<#XJgzZ6P5((#X6W7(z5oRq|WX=Y)}$gT~niZ{O!f~`1rImCPF|! z0H*JY8m8LV*~!Stp4-@U!e4wgP?cb1ID6N3&9CF+md7p^);Zb^%91Ua8kWTV#8e;| z8JU$2A4WSmJKZtM4et!)l$D9A@-tpPDf*r!P_=;R{9I99;b_;Mh|fk6nZAC0#nI*E z8?ve1r`T}H(OGmjCOl_k!?Bvo6D6+lRzmE{-ycBu5<(17#$PBC)x+kWm7sN5} z;Ca0}g^MmTB_Xed^E?edWBf*5ePnipM8{m<4Bwz@&^orKL|rQKC6DQRPNc8;Q)Ab6$}Jo>N07T_z@~p( zU?z{c?v2G=%GKo8P5LVLcA3m`Z6^BCSJmDp#-2U*x?#3`Yj^)3O-#p4T*oeO1 zd5RalFav4ss6)0px1;xmLj-nXib82&-Zi2^M`KNa_b7V|q5C0$JjK&7+s9Ek+MA~y z9zV}N80PadLM=aR{fz9lsbEKebA9Z4U!U;pFZN}vIN}$_{zOs1816g6Nj$7Pr6gK922VWb(-jgh5L=2jvtY znz;06p*5eCzw&Z}_%uzn`x-AfW%mFX`Bs`JcP~QpzIr*+M!6(=7RpX}MP^Eu?nX-d zp0^{l+_}F>F6bkV~D)CtqXknZoS5Fy(@l%_rP_cp;n#c&Rtiwv?9G{62n z`Rm@H7`~Oho`JSLJfWtX?r*nLliWG#=~}wYV~SYI=>gwt?=_~ID#227gF;2`zg@k^ z(te*-i-{o3Sx6?%(L{M}+KN3i%iEae&$fS;vS%T54-oKZxUx4PI;XydzfM>i|4i}V z`9&dX$mWo(?df1QT+AXzUms38*vQ~OUFYst&p?))K50`#cHrQ-{)*SO6mHAjH3gj{ zPiCW`#0!{mQc}ndpFe$44_|W&3R?_9Jo6T^ecCnW!(>%g4aOI|BHDr4`w3BtaMEoedmt9%sO|aPut<~0GPj|g-`}Ob=t`oKA z#73lIF5WF%_o3``A=56TrPQ_`997mGo;`XYf_gQoa+XYP=0e3`f_xe=s`oOpP3WGP z=$ef9-EI!bF+z(BE;<)OgPDnx^lwNh20B82ryjM{0F-aBbI{CdR_{;8gka^}2F z$>M(BsNTISHnw|s_3Agbd}rfz8|9AMKc^!1v4pciYm4s$+EazzUe<)k8Q3b3_PL|l1KV6!{a&Y# zg<J(6#AV+m#Ty6k)&R zQK{_Sz3qia9U`OL*@i_{%6Ni`y2S<}`@s{}x|SVom1mO;HU^i!nZL;=qrMqQY>p%& zBRjD=^JsAJ;N1w7Zh0*&E&L>$@8H4bpFVw>x^a+?ho{J(Ev2t=cAHCkxRsrq&*8&{ zR_wf#m*-DAF6gxeEl>|O#>K@EA7E}(-@^LmFJIP;U)%|;#-S^xe}3K6-r>?-QB_q{ zRu;!zowOvlF~aphnM#B z;u*I~Nm*K3>ozH$_~_i~EXc=~lr1MB0<@;0smXs$-^uA2-c|MV^jwcl7Toh}ax!$H z!fKNlky-u3M}97@!vO(IqzEY{A}ac5XbA6;Cq9nv%jvQtBL&X6K-Ft}TmSn5|L_)r zbEKb;g1*iuve>^*L|Q7}^AHpiym|BHre8&6B^4zl4JEm<{S}Q9K8~E*3oxhKNUZDn z{QSI!k53%a;f^RWEZ?TKR3h)*GwlFf_?o2y>tDWb&`@sH5F>jvH8s~%tnBTX7#Q@G zrdmS|H%DS_&gOY%XXiDYFRQP%ZDTaBI&ZlGZQTf9}#xwP;9|Gxga!9dk*?EkMv zSXd6jyTD72ubm1HpIx?ebo`E&oloGd#Egp_Wp?bSy>TNnBt*|NY`%wm{ z&(FslBsvL4JM&>F59^LDH0iM+}3Fn55>=7PdXDANCm97WQF; z{K4x_-h>sH-u3<0K0a+)`uMU9 zr@}RP^wJ5Y#b>|4EtQp(!T3Q8o@0DrV`HOHMvo!p30}d0KF61*j=s8g8h<-<(=W?G zuJ4p8hJm8i`SaWAecaNeOP4k`!`rX@{`qZsa`MZ{(~xf;U!FX95=RwLzyKr7FnwEE zTKe6~wr{Bd8Ze{m9fwS;*tOJnU8|9}F>l;KCM*B)<^KNu!#+Nwaip%z_4V?CX(#^v zIlXu9{qyI~V^wTzZI$_8cfP*9)|C@IJz~<*zLD$>FL6pNf_qCwZr)~ zMhIg5$!y8!=%{0Rc!R!3!_Av12?-Ad1~93qHnP%CT30IX-TP{0 z<_`v0cAw%_^cv`hrr?RItg3qW;6cLy0_ho)fzNn&csv@OjEn?!#!%r^Kn6OxE=j`$ z*^t){vq}uptl3{%LjU%s54&JyKvH-dwU3xIpH zv$M#5x^^=M28qeW?O5QDkdPuv8n>}hWB3vVUA5f0^>L(#;?LGNcSb?Y@YfGHFv54| z&YcYo3_>z8ei+BSzP^rqH8C+Ec`nm?%;M@#+qSeGe)Z~AjI$bx$EjTtG5n&hr{~4J z(|p>twpo`iAB3}EI&6G=e}z>^a7c(o=zC@2h)|>!ZUIliK^IG@v+}%Ub++>yh9qX0 zl#%8r1k&y$;xvEM= z>taky3}z2aPESuyP3<^%>&WM~qsS=)j50q7Fuu6xrKF^U88pB6T8_PZhInRRVBqdv zR_TFC1ZZ`O1~;>~!nLs;a9+MMO+YO=)AozpmspGz6KMC1+)2-MaM^ zlSA;IICnU!9v#$8i{Q02TkJ9>*kD|bD2<4w<}WNREiEmc6{%?RJTX!Q zc6~7?XK8tPd3Dv*$|^lOI~z8i`GA~)qRjf;%F`wsy_I|M;>GOjeaw_jTG`&2nVCS* z@MWi#V|OuXuf4q;|9NQ0jDsT!?(qu)&k$kk?Cb`MZm{^ z!YfTr8a#1lq;m$~@wkb)x>X>(sXEuyw{M@coe221+<`br2v7KJc{*SyR{=NU*i5tv z4h}wg^h2(Kr?Rp#a;ToJZU&YvBV&zrbkmPtBg{-9Glg$=ZAuqzq`RvN(W~nE_35U= z`vEyH60y0t87qtVgGI05;WHTTh4Dz9-riJhm_L@EpTF_uQBrEEOQRQUTK{Dg|7?uI z`}KXJsi`SeS6C|xGqhjcJvH6aL9xWsxoSckE zkixIV`e+g{z$gPZR+E@$vOIMILkf9WSu?I)ox$921bZf?w9yj7rNzZ3&!001YI3iB zfWyK2uq{(|4(;JV*qCF-YVY0qgE+T+`*zq3x=yDskxiHV7Ear^A-rZ7Hse0&_?`*dXF zix)4jf|*yY91RHA>ovd}DWiOk7w17COHWK_>xi-T_V%Xms>q0olg9ENJa}qxARYJ& z{sRPu$sWWxVt)4E>&Msj8lKZRM}6r2nLWrNg@taLYja2-FcF}yM*{;i^z_}=t*xzt z-;NYvTnhoWE;m?Aro;U3;X|T)#OJp-5NN0Cy%(4%($`1*h}E2Qf4B*-djfJErjYFQ zo2Wo^05*WMhE2jFCMPrCuRx6L+XU0>U0q!d9;Bzzy0#Y?6K{uKFDt{SU1L|*vpC-X zNdhtN76Js&3LE^$(#nd3ot=^@&V4iT4;EimMh3Bhh)`2k=W1`?zqA4KBZYyC3?Q-c z8#hu~gpC`ks_3>JIeJu7R1_lvTirTidV2JuwVB!2lrWAECtlPzw`TM&L<2_5Fd1jy zA>nhl5}8nz$r6Ai9^uj@b`1@U|9u3EFmyP0@N$0sd}iVLWMFXc!=WLN@+Hj2FD$IB z73ARH;O8&6az%iRO)taC%WDy?!^+AE^o>;+$?zo-oBgMc!4?ohMbc^LNMoEr-`fE2 zJ-)gJf$r3|kFcY62ra6rs*xDKxG5$lCx;m@2)m*%UO?ikOP9h=ouZJEmaeR+S$WZ_ z#B0fp08!K6*)Jg`w)p0aNtw0sUTk-3YbziZuSS?0`?Fg|H84nVZEX!<%>0_xmHq_- zL&KlnzvCfyYG@pkVxQjwk5FQ0I{JLqfddDmkQVms+XtK9?s`vCSU6hf0)7|aa&d9- z*RMzt-sl@1K8Ea$ZPyfJB3ygC#qHQJL8K3UetrRgqh4M%2M=mM$V$*>#fD=*IsS*} zn<19JkNJF7)+A|M8b(p!r`mJR1McrZ#Ke!(-8u-8lGnd}cpiWLJZ8L~eK%GnEG$e) zsoy*gAI`aaxee(J@kB=lwhaW}?(UAqMBXg)#eB60gfPtFe>^UlYdFe>lakOMhw|s4Ft>q?$Y++sY0P3>} z2wcHwEsqhxku5RWZQsVi{QMa93TWi(+fhB>UpnN2=gq$3SNEJkvhDF`C@PwR&yzkk zHiqGWYl3EGW>{3bjr!#N*}qsEz0RjkTd@%FOh7qnMRB^oYeq%`m_80$8_8u9P`6|c zo$I1Hc<>-0n5xK<=;^rth3xX>>e^Z@-!ZYoVgjrf6Xwgy%5FH_eE9e=Q^04O&Jln+ z0dB+zHX=0SbTCmMv*-AGW+q!yG{qK9E-s7(8lIX0f*$_2C$r!^etvh5(FFHIV5pN` z5yl2#g6%V8087h@`XUPQ@-$nwBBq#|nkFSD_w*YsBpq;clx9r`*A#RyVAc-|tiN{6 z73?Q0Y*$+UxvnTOid1~pLf=*x8Q~RNfRw3f5BVQHJbnM{*=8>i62~-Cz;cXr7U1VE zoPGbk>c)*j*4B!Fv)TlY2Gw1=re3`|`{&npj*O(7U7f-c|gV=EJtnRRtLXS#b5*na=|g>M2fqar6`2NY;QWdQ-r zk4Pj0hK35L1$!aOT)FZR0BxN&LrmlNTcqD0(tgPelHbM|E*Kbv;ghf?i}B`!1X|u? zUX}Mlc}g&Lcs3?J>5juF?qSwH99m6H4FQ9J4jzCIk74LO+;L*Y1o#FX3hcti#|OEV zv|%ln@05^{!D?U?&S7Ac$v(fZproj1lySZbC-_`0D2QC1+79<8U?Fzw*g+cLjupmg z$E79r<;1$@0$Ma9LhRVVSl7_f^6lHV$AC=6#tF&EV#cfp0>HZr-G$L5C7#I8z$=LC z50*AYllNf#G1VBiwrkg}kI!4`va>l|y8Zz~(vcqs&iEc2XhmQ*Na*!QEFRG|G`xgVTYsTw#Nr7eW;Lgnk*OcTrl zM0Ru}3k(W+3de%*0rWAvu)g--iq>h&Xok}lE4aA0K)N1!{P^*}0C1KJd#SZ_8YW`# zZiO}CM8q5%%@_J^EVfum`2&ttKt?+e7Pimx$dMyJl{hD$;NnFj5f4M`uf5XaF7=^+j+-zsYEeS$iWDDfO4=FaAhS01qE5z!KY6h z9UXZH#u*kC79^i*_C+SX0>VjB2#~*(N%LB<7#60cZ%q^5^|WjCgtJs1o#bt=P@SiE!UW-17E= zw@9gm-C)kMc-=dF@HNZ^0df^V2$^aS}m6C7MtR<^sl8+>BDNI*5v4VQ<-!+41!cS8MDRBpnlK+<&Qa9kur z9-QqWEhFR97Iq^$dkP5j<%<^t)FL=JIMg&WFr)ok|H51d0PgC8Oi3_0TN|4Z5(~f& z-YhNI+t}bFfO~iDkn)hSqN3k)tpGdl3kF_FB1^2T1p;aB1Bv?!H-P2V*43r;;Wz#u ze_+7UnLocyy15l<3t_x+3Vae(40g~P2wef*-W-C0J2;bCFoYdBgG1Ktg1(6I+b0d8 zQ7B%>%2p#lYQi-jpCGv*rBi8-e}=b!kzC5kB71>HeSYgG~!c5Dck`SszCx% z-Y1eSCLw{podkx&Nt$o*9WWixWY8~~n5eF~?s%;5@87@UxAIX#+B$g|>=Ste8-Y{W zzW?|!uYzkL79PZCL!b}1pX;GRzj3-UFE~6mw{}r+u?L72M#0a`&A}u@OV+*J9qmBt z%*~I2-Gf?TDqT2-aRvZ|m96bdIM`^(kkap#|I-U#7^_sYbR?1Pww`Mg-Rhl7}(&I>W#10D=BP2|XwFxT}o%D}lwAK}13K@E_=@K9D(our2<3n(jIloSbwErzu|m;Z>7s^s3W(>{2M&Ninwy!8a07oK3KU?k5ZndSkJmRe zbee8P-pk73APK}T>*cCTOD7QENlGPPFODYxaeT;vALO>msgbc;L#(Fq+Wy(gva5B4;!K8?cUvAotTt_%PXs>n6s}5 zLUeGowZ+uWVnn2+*RP*Gf8KWI&b%#Twj7f(M3x9TBJW@$2rJMGwguR9znK{{&k-EU z6VuwN)-6v$5lTwkZKPvr5&pn&-Y+g*g66kv+kL3EMV1$GyYjXauRqOhVvDv5?b{XC&zU6;kmh>&oWR(jG(~!eAq% zPDMopNEdeI3XfVC@Fjt6zoeA#1X!~pdrgjOY3w# ze25PoK%68PWfUm;vgVhe_PvFY5-|;G=#PICE?~0C7Ho1W^d#U^*gs6qH^1-aJA4Te zkczT$``x>SDZCt5p@=VjKnKduflY|SiqupKP#JxZPCn2cpP^jDhQwYEkQU=iiARvk zWo46!r3lLAC*F?C4Wx?#NrvynRggGt)z=Hr6k|3#Vgf7<@gV#G4pal=MI-^-pv9tp z*EY(qIdA};{~S{up(TN!ui-F^$5%9f9okDvz3^78lO0 zuHFYj!tb@VwPlJut+wA8tzCcmXPCdgf3$Ygep4KAM~BpiI18K%bu1_-$PzxiCvdg{ zG>yd8lSzUxorHu05+-t;@&5g37cOX1Ab(?yvW<<+k>|H=Ko|_)3lYR}WMZN~#ox}z z$jI7y4B2F)5P6+cVcog&6*45&ZhhB>=PmIuB_$>I@1F&^K6dPwwl;wsV3UrXo+nP& zn02*pY>br-jD)0!fHZtqS&58{94W+efIsYzm4&J2H#8`aLWZ6jhZrj<=_75eZkhSs^WC@MI4)F%BHI#}VnEpjASBqVLbAw4* z1MerRN&CxAhpfoQ%#33Y^5tNH%^~VJnsj^|-@_4|B1z zH-jpG=aRkw4+bI*r7kEm)L=uq(*qBk(E7XeyNIymA1EI{WhU3fH#q90MHbTGW00~ z({eI06v3Ubr`Y|Uo12#agR`=}fB#-YW}HDm&Cp?3k17JhcNFa)_mW)5G+Pdp9e52f zMqeZ$H5His6Hb?8XJH|W5~7Jb21Jdt3SE5#dIIb}B0^n<89PLbX>1IJphG0SMbSuC zPj9qiXoz8T_CDrHT3cs;K!UPhQJDBunR$4g;;<=Y9U*3YL&GgpRKLN|aA(BAIzlW? z-9&zc3u9E@{84NyOxFjeQi4{4Bv1&^kZ*O!PDxGG3R`i2F#)lG`7>?P0xF^Ciz^s^YTx{%|I4>_RXtcS71rDs=z>y)P*6$!5#WC>2 zq}9NezkhlSF$4fyQ?RbQoW!3|yy8J&Kwm_MO>X;klrc!qO!F6XFQ5(Z9iTU5a}-s& zUcLH@b3_noO0|Ww+0daqwzXMjO~ZBhH|?xrw@{-EdQ zR|T}4FT_p`;537F6UUYalI63L+NULOo} z7$wRHOB>$_2m?6YY4z28DD1M#H28CwwJ&5E^zFrwJJle#scUE)VE+P)f+`e{BblY0 zU1~xC%DPTqvq-O~X|JxQhp`F6Af1~jg`Ra=e|kPorvUiiAM5c9v! zh98E~a~G)_vImkEHd!%AnDuH*WmKQ^+|r zOG!vjuXa3ov~?$lash%!TwEW5pF{SSuV1ObuW`hiRH6xP3kB}f)O~DHiJu@Dfh+yu z!;t~cacgAAXMnP^Dp*K7BPk6q?fr$x$y>Dn7PeESaKaf&YHL4&s>3lTEgc-f;W)_Z zt1sJ5plAVc7;dI{`bTqo{1zwDF5y_2SrjW_Spe-M<_a8vnh*dP0ir#wgX0@KkuXMlVy5SI*qiPg z%6_ATU^5^*(4EYUjU92Y9XoK|$5;1Xl^8O$pMzr}@Vr@EL@o93e>oi}psO0@k4lzL zKtS5GJOimwx0QY2mZhgRC^j9M*KehZmjp^O94W+JTy~iVG~nR z)TC{=hD{^_D&jhLJ`$=&TtuB)Td2bn!2~P)9EBEWc_n2UZRqji&W&Eip`ka8#B>KQ<>a&gC_)4RMxcOXvP?R(HDG3C6>>0+ zj(r3r;^8G}TpMS)sz;$>iS!IY0)c!!Q^>dx?h3Q~w6OuD_|DnCTI>krzyiKZOiUmf z)PSN`s)+UZSkT?PJf8fm`Q^x)*c}B36_6+3Bf3TSRyY$@9jR|C9EXjSl_m!0L1ovj zzWeK_dcuWCm11BFd?M=Z-QNNCe}|z%0MD&ggh==M$Cu|o3s?hCQiPtX1qHumJ1MY< zc&heCNY?$yJfh4rAlE1<{#OU{@$x#4zQaQxWLIz93i}W2x!goJfr&(%Jc+NTj{+if zklP_66HJQnh(gGHsEds~dXyq`0SH!1QW8i^Q(Qc@+?P}+zHeh~-H7Ex5=rCR{Sh1n zmA2pE4~QnXWbags?O^jQ(XKSU6I!-RY zt)dNNWO$gd0}KBRUV&mfih~!$Xk(#EucD7=@89of$XPZrTNxNgu^Gw)p2#?(hYu1r zWZN;+zM`U{04dNAwf;R)ikpvbKTZ<_@Q0w3s~RNY@)}i}+1WtUxv+r%`c|f<2m>xu zR8%B+cCwm_9hi2!&hgqbF%&d9=AT(VMZo2bgY-NP zk+%W(1P~p?DV+Vr%*SVHHGvx;Cnxvt^!%@S&#t*=503T%7E%JrMWjYcm^;i30AmG0 zs8#}&gB(pe#U$MnonMH*SFT*aV=)z?p-Eagp%~TUMNmBGHA_oNIMOA*eDnxX6_S86 z1Yh{1Wkq%M^Sh^7{-@ywUIwmaB9;LFiq;;eqUbWa>du`ZwjRL1uUg;Sd>k$WOaM5D zd*kR)J$CQ~=y(TQTxxM1Su8*$YzQ52r(piip6Qa3DT#-f&%-T9y&v@t@)tQ|-(KxF|qN;g9c$?afsAbJczL4IIRI@E!P zZy(V+HV+15g-6Cc>NR;{c>Z+=ryUQ44kYX!q5;}M1hpc$xw(xp#0c1QjGvAx_l=Z*qP9~`4qA3Tf-!{_ z$>74#mH-7Dl=H^Ii$B4=3_CVrAAI(iT@xXu)dVrASpiqXwz0ivTjzmBve7v*)^>m~V z85(jeshoDA9!0|2w^g~gadtqn3#}&V5bkv;o~C_1>6nQ5}_hw zxIm2<4R1q@7;BiEmIf|0Ju%VakDgowD9?$-kUs4l9Z6NJ0|ypXSJQSHpu7v>K0Y=E z=!$>>SHl|@q^?@%JIIrJ!`EgJaP|YYA>i`fZf%`gD3tO8vBE{LNxi1f8Bj)*%^8$V zBnNgs2do3V5&gWkD=Lgot49?IePDDV=>xsJRM(iy$8m5my>Ui*dU|+5Qqmyq$T3@- zhMZI|eI5KA7Iwhede^ZRkki18JpBFXsVZ%7B2MyOHY^|HGPJoN-%U)|L~CCxD9{AF z!CzmU{reL2E5Kyz7W_wmcP(5Kr9v@ zTBoaU6Lod3(1--MgK#v6x&s~bcSOXeD6_yGfJm@ZIES%AzlRM z^71&J64*QfJRkuCSyae0cma}0hs@)k5Y(~A3rkAyJDCLqq}FOg#S0f`ptwW|!Jg3! zvVvp=yV>i}LxcV$q#nFs@2$x(B zfc`?VR27v;5Ek$PC=2ijv~&8NIde~61Vj$IBx9UGa*?z9MbiJ{rs5J3fFpptI2#!{ zsF=7o>hoxbAw}K85ZK`g6WEQUUdR&wdu=B-B%FkJuaVXV5gwb$P7_0%uDz0zGmQsr z2Wi4~EU2I!>Ehyoyao|83v~-`Ok_Cl1Taxk`GmWIancroX@dijM}cQucoGeTASbnNI1Pqb}lYxxR^sP z1UcZ&BPdJu_L9bm($Wvm3J(TOr&}~KFz^et$s)7nY%-=^5=bpXORSP=npIo`c}dmCqhq8sE>xF%9K$?Q+n-@1j?g?U6xI06MZIWjhu zOa%l4&IvUZ;e!H;0J;e9Y6+B!Mgovv1g6Miplhml&5N|=#C%S=Sma7l11<_~s5}iix*Ks5GO?)WIk5+% zR+xVsN0%Qj{cB<=EQC08fSt+>WiZ9OAt;#Fo?~@kX%MMNsjI;u^4*v?0j8pucLc3( zxPM0+Gip9=iRPE)O$ zL_=WcCdex*GcYlshvJ%oC-t?*aO6|Rk1I!^qmZPOLEV5<)seH~zjjxI9cY92;pQTM zD_}J=)+p$5Xc9)JCu%Udou~#%WFo3P>gl13x_3`2pRCo{#m441Tx(>+5{=3oeSH!t zDp~ytWNY8Pfibz>i#!<^D9;W$0h#UCOuH`{q)_W8Y|BJB9SRm;H|Kb$@a4CX3LwDnm zLx%*qJ&;=>fq5%MM z+9;BTK8bsRE&wh;V#DZJ*{!IEGR`G5+2n6cEC!M$wVS(lQ-j@Qh>;;bNukTP7VC_3 zfe?yfCz%i@siK9t7BcagF=PX1ZfH7q`s^7D=o|1qHYz-&sc8dY8oC+~9N9%N=>vq0 zr43T)1BemIJb^huA5HkACfECC@3*ySn2(1uQR?XL+ed1Ef~fWM=~EJDf8gcO@K2@| zZa(%hq8vTk!Dt$eg1JCBc4-SU7h(o;V55xQNuILbbVm*#z~y2o#0{yn?~%wlSSQHU zWQ9^y<>hanYweJdg4zwa1y@F)slBL3n1ISUk^x8tR()P}c4dX+AgEa4X5bxxzzax_ zom<3n1_6g9Ig>!p*Z1M(k*F+;jO2IkM(3DH6mA`kkY}u~WAg|x(A?6} z60jM{HOaAZAQS_0LdphChp!?U5#9oBVRN;L02%-ha5ulPu_*edrKN$*Lx&Gf0DVQS zMe8_-4MUXoQ>ZKGbv*W@UdPnb^x(mtBuWXb;qKi%1k98J;XqHmo}=o|EIEZ z52rG1+xQ}bjHX3uRx-61BeSOLr)Y~L(ZBIwnN&hPBdKKC zOoeDgDy_Vx>7B+V^(rcxB$f32o|^ZM?>N5WJC1Mum>kjaJoo0h&g(qS>%OzH^hSDl1JzUsl1>Osbv3?ArDHc`L&G|YD8ij`HS7xzy7 z*e+!I!TI{y#yR^qC~p)@`Tzx8bab@V5JL^RMPK&y9opF3r4O}v%&(*k{Hqyl4C6I* z>NjSoY7cMa){uNOoB|To87;&>gqg*_U{6Ly@Tye~%dhTXiU5!c^1aoQ-E%3(zN0mC zU~r1Rl&U4Tty>0agh1;j!~?R8{#x zhsuwVxcfW|xyX~y4D@=?(J@9}KgtZdA(zvqKrzH?JCcpNLTKCp3Jjgr*F=oNd17Ul zD0q}?mb>FsQNa)w-q#myAlOlu330owUB0bJ??C8&88)Ki9~RxeY0 zBxKc{x{J8v9Et+7ytcFUDjzUDXoW0IsZOP)NDMtc4*CyX2TKkfvP;l%{=zE$;;F!=!6W0k4LzWhoRZRoZ8q0y@Gv;C{@YFV-vPa`ZsEN7BI9cW z5LefoToZ|TmvvPN~yB#><;qESw?klbvl7`b`Vq+N?*7jI{A_Uqw zFfY^gZf#_%U<Y8%!z=3Jlk_nVBILJUw zVpILWetM%VW6J{sCsIK{JM}3|4{+fy6rSGR%d8~!NsM>+g#q*rQao^p&;p5SrD}iP z*RjIVc|FY9Sovx!lffmgxJ$mBdJn0W?mE`zgAfOQsj+d^#f$zHds~XG|Ni>~Oa=}P zVVHr)EfwEy?NQCb1%`Ydx{o9sp_)05L07a0wxjd1cC>lqlZ>f_8R5 zfYeXF_8A1aG$#3{thz@eHoSli6r=}QF~OxKCrA3k%<_PA8xXFp96I`_r#bu}cFoV= zhTTl{M~(WKvY4Pvr`P9cSLuPE>%n;$7m(eufkgf}HPv>*LrcUzbyADkXCy@{qGeMbS_w(DQ^9V=Jq*z;uPPNeULb^CpBkLarboQT|Y) z?j5)29^vZIqqBh(JNaT_L+Btg%4}pEUQz_rOk1$9>kuW>t{j z=HkNXT(3J=TD4Rx?ooz@=oh>r2_(;3_O|zQ>7vDp8P!I30xEk0{r-XJTo2Vt7_CEA7#Vz#C23pTSCo_RVF6~_D3 zcTUbMs2}KmR{QR?T39X&@aT!(?e{7809$1-=8U3?uVl8i!%UREAtBvt8LF1jW!3s3 z5cG7A88@y26F<`*>_3sUN|~PRnur@88IaoPO2H#G<>9MS~2tkw0PX#AnZ)+tktUhBQnk z=GU?`3Zb6fUW;+#rqBgIIPEmVK;bcO9%iOq3bnCw(%0h8q|xmBBp@I^fZ1^k(Gu2I z<-(t{5+o;p^$Zn3;VUuzK1|xkJket3s`ltvKQ`N2;NYo@(_uVk|E04D9;Eld}@ink194WB~~%rvp}&ysJoQu6XvIypIQ-Fm?* z|GvG2om~&b1y+KhLV)!<4Sql66x)&cg{{3eoO*b+hsV!gg0Tl9y6>z!Xsx{I;_Q5h zdeZ0El95J60s$}OU`=3>G)CO**R1--DZe#%tGUQ_gr)x!%H}wr6o$)>_4Ujq2)=bi-v(j0*xa1ecAiErVU)X})^q z-w%4}RqvC<5aB4FY<|iI5oi^s#{#UCaMxHmV8>w5f&&B9y1gndU&eVHP9o)@33mjk z8`rL3Lw|}ag`F5?!VkVDBjf5iBf;w5l~H{BI2{RD-ZFY3E0&h=V*uZ2Z~ND8-@aWC ze6nu0Lk9JBG}17&UhJ$LHnmF;Mn(hFeZz4t^dne+ z3ihv1hra*8)YJvgkgVB@1FzZv=vb13040@*3X^;aE-%%*vQ7|uv7)%TDgiSjgp9bv z#3z6KHc_q{BX;(mKgI8Wb5=Uj{=Q31XkPR*XLC+}^)MTEiI$d@Qc_j3JTTCj@(tL> zE`@lQZK|I+Z{nJN*(L9FE2sy-^gsE2`(jclv){Qm!CH8$HC>^fv(sp6;L_7#v|-Zh zARvUaXkI`-6Qe@M**P|VwOko_UWWw-Y16=t#fQU~I+8O>nz~NvelqFQnKPl3zsT{7 zy=GXwYl7sfB}>keNhlMVngWs+29l^KTo%(JM|>m<858MtT=B4D6CiA|2sdNP1C(;t z4rQOTNLwxxq>v2g)BM22^{q+lyu`#IRUUXjX^?b)4<=DBDqex*ZZq_~S?Ug9UnX4f z$WbZCbs!j!*=PFIWR=(S3wF0*cg;I;WT5tKe=RV}A!!sb96;~nZ!u=fK>(J8?{RYR zj@FlaC~WfIA6GLRcuQ$R&=3sDg{K?T!|K6ez&b2Xy>n5bCQKM{|7)RtmrYOO)_w{W z+Nqqijf)&cTYkf)6gauyFRPZ$zzvHRO~_yVnLRxlqRS6?nlq61pI>Rol_%ua2Pc>6 z#=8Wum%81tRWeJf#)tBMhHJ%T;tpTfeKDGK@eZ)CUHIbqE-ho>i&Z|rm_ikCgF0v; zZ8nfHhvRX{GfZ&L@MU;lPfeoJ#h2m~c~aygM(X-*#R|<7_gvK5O&d12c(9ZgVw7OA zFgfphTSi(YYEn3C#e;s{ml#h{!773GZeTyopbP$EaJ@Ub{n+fJy=tR|li&ykxuHj~ zA%8SuW1%Y2Q2hoGf*EWX?ts+;!jlcgUQ`{G$X&Bl0ahYNO2pj_u*)n&;V<>ZKSm4Y z?#+C>#U#oBTY|tsS(?BCPJh$B^eyhiF<1_S2Z00H3w+$TG9rl0KK&^2ZE!e36F?1sl6DX-<7i$k!R(kAJG9iB+!;pX-b`Nw}3f(a>> zk{S`MW%}CpJw`Y7*=lW%l4|#DM&l7GGx+6c(?$ca%A>`%+*g(S3$hZrrtNun9EoNV zJPy(_+;&+G{?>^TU+_{ov4}e+6DIs*trW8KOq+Z0_epSoK1l@H11im zuHZuYw#4szq*uO1z^Ya8X27ViT)q+VlJ^4+(OC>^-1PJ=is#qS2RCD77ENT-}pttO6%pD9g;FAKQ<^ktE+=be} zwDgM$R19AV=A8#2VMI&lYlJ81EAEQV@mfWN#&a<1N9!K#asMn*sFDeR2qo+s{^`=~ zZ#E+6V56kC88}61V#kIUy`XS{Lqf)d`T7g%Gj*nG_Bv!<3PgO#yy~Rz9t9sm{V9>_ z#B#rF1zUV^>9z~B$`cST_IG=*84_KKm!2Z@vnIf`;FFwFr@Zs(@K1NuSeD*B9vJOY zP;%nLOF_e}7&=|JjE!m({3aaokeAnrmO!&oqU)zu)>*+|+k@Q*(#Cw;tL_@hsZ*xF z#viMDWH@S6*I1ll$NVo$GBZ<_m#aC>m{GxF0G1GNMDXZjh!dPrFm9Y~O!9~_X4TMI zxy)t}K<`(YM>u8x7D~k1873<6OqijxBYNU!?4}!-a*YwXhB0KvY9nu8JuSfDFJpdIk*a>+9?8zH8sUJH&YU zUv2@X$j#{ALaroo(yCW->Qv>A0u-dR1tt!hrll(h2nl>!w6gtrFkfB(;+RiXheD=(ls%0nPIH>Lk?CMf^-#TR82nG&n2MV`FD7Sz>f$oe0ck zpfi)^3K1lkD7eJX#7W$_I7;f6<1K?FrH)q%4GpE$xCd6r>{k18fS`?GVyK!@G7yIa z1)Y%dSkyLfG67X*Ufp2f+<_N}rL88SD5-hc)opKHbxj#sM*hk7{{8lCTcv#xO!y7B z2~Zm*vE!@n*pQk;hKZVys9BK|N2qO>Ovw4nCZIPqCdLSkkpM0VJwRV>5tZpSj(WKp zU}f*%P>$NLp`&4{m6doqb$Wji+_^+<6_`+7iS|_JLuvmjvtn*Y-)E^GG+76uKVpsKpVahBY^0cOk@GyMEpH>KQ8U7ekggXOw>H^DmHN{NYBx3x)0swzSwSiv|bq4_lD55-xV#dUUwHFj8Q zrUJfk+9E|P&Gk~lR!MX)&``7NC265@0M?&>3{^mjK44}o?;a%;1th4E&zkIS)YTO; zZsI3*&pu<;8Po*p^XZVrDn&$p-wF5JOK*R$){L~?*=Q}%Wz@xJYR>_yJl=f@A`+f7 z=9De~@Ao*!L-$;e%b#cpXU~RtdmAuaPGWM3;5MNP8H7Oz+|TJq)GR&)^#mX*J>doP zOzX$gYF-lf|H4;k_SZscvV zOj58yzormDg&^Px*#ax-pTCY5!OxL4f6B~!!}YTjC|w2hqw%Cc!A_c#!2^MHKZV(3 z;K+G&{i>Bo1cUP&9UUFs_e;v4vNA_ef_2>g_=`06=bZil1D-f~>MLFu2%#^G#8)IH z79sn@QG3-$p<+p4>*1Agp>)T|1#K$y;}9+i3k$tv9|$rNJx%;306s+6-Ak8(Sa-aF zi0#g~V{9ggT$bjZ@9kVESx``KvrpGCG*ocJk|Mo)eXG_P$&bQuQfaDT;vql~<7luJ zcqUZDqWWN7t7@Il@#Nzbn(<>90x#D-fT_-jO zS_#xaJ&npUQKHLQgBuh{Q{4U;{3RR7H5-aYDB4-(q>3S$(R8;sJFAQMwbVMo_Qgcg zLMIC@HoP@N;>w1G1|02XFiOFI5UeFe5YHJso z8z2P$Ioxyg4`Z5_=44@3fu>Yi&Ol{yys%&=Q=P2wbGY6#hw!C^IAh!~im{;9ANZ$-R>O+bg&j4rRK z@hG}I!w%TX=3MOS>qzy^!Dd-1g$Sb!b}!&*Et)}@(DM~g7P)Je4!#aB7u-i278Z^Z z%f8)i+=jn2FOPn`4_)XOczCBck0s^Li<;mOWfdw+u=dOqK;a+9o0*{~DXk7n9pRo5 z=+yU(4Rv+4G8xBvI4xVVCKHl{2hbfo#oor|B+>oYF?g$L+T~YdM?Eyn)}_B9S~ zNt_7SMBt#%+Bhi_2t$?N>3Q?xr4h~d?nO<9-#)kL3D{v>w#q!kttb4A@EtVoRA@a= zBK3iYY{*dr2-qTUA?t2`W~LgL=kK0IMuqQ!Ob~&g`NcvP0_zE#;Xh%?Ew3(XFnnk_ zl)dnWl`_JmZ+zywAIzxbwT3CvN%|Q#cXcjy*UPvWTw--Xzr1q3Mv7N{3}?V@e0WpM zOr|%-$R*Tz-<*GA25MwtE54_7kc3(8@|k+sv-8ebj>G&4N0_bQb5UAg$?USc@_Dgc zjrZ*5<<&J`ZU}ELr1GlG8eN{ryg9gg<;+2s2aEV`_RM)M$D9MA{u}!<5i|e* literal 0 HcmV?d00001 diff --git a/dev/examples/03_LLD_CoRh2O4.html b/dev/examples/03_LLD_CoRh2O4.html new file mode 100644 index 000000000..fea0dd6bc --- /dev/null +++ b/dev/examples/03_LLD_CoRh2O4.html @@ -0,0 +1,88 @@ + +3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T · Sunny documentation

GitHub

Download this example as Jupyter notebook or Julia script.

3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T

using Sunny, GLMakie, Statistics

System construction

Construct the system as in the previous CoRh₂O₄ tutorial. After optimization, the system will be in an unfrustrated antiferromagnetic ground state.

a = 8.5031 # (Å)
+latvecs = lattice_vectors(a, a, a, 90, 90, 90)
+cryst = Crystal(latvecs, [[0,0,0]], 227, setting="1")
+latsize = (2, 2, 2)
+S = 3/2
+J = 0.63 # (meV)
+sys = System(cryst, latsize, [SpinInfo(1; S, g=2)], :dipole; seed=0)
+set_exchange!(sys, J, Bond(1, 3, [0,0,0]))
+randomize_spins!(sys)
+minimize_energy!(sys)
27

Use resize_supercell to build a new system with a lattice of 10×10×10 unit cells. The desired Néel order is retained.

sys = resize_supercell(sys, (10, 10, 10))
+@assert energy_per_site(sys) ≈ -2J*S^2

Use the stochastic Landau-Lifshitz dynamics to thermalize system into equilibrium at finite temperature. This is a Langevin equation, which includes damping and noise terms. The strength of the noise term is automatically fixed according to the damping time scale λ and the target temperature, according to a fluctuation-dissipation theorem.

Δt = 0.05/abs(J*S)   # Time step
+λ  = 0.1             # Dimensionless damping time-scale
+kT = 16 * meV_per_K  # 16K, a temperature slightly below ordering
+langevin = Langevin(Δt; λ, kT);

Because the magnetic order has been initialized correctly, relatively few additional Langevin time-steps are required to reach thermal equilibrium.

energies = [energy_per_site(sys)]
+for _ in 1:1000
+    step!(sys, langevin)
+    push!(energies, energy_per_site(sys))
+end
+plot(energies, color=:blue, figure=(resolution=(600,300),), axis=(xlabel="Time steps", ylabel="Energy (meV)"))
Example block output

Thermal fluctuations are apparent in the spin configuration.

S_ref = sys.dipoles[1,1,1,1]
+plot_spins(sys; color=[s'*S_ref for s in sys.dipoles])
Example block output

Instantaneous structure factor

To visualize the instantaneous (equal-time) structure factor, create an object instant_correlations and use add_sample! to accumulated data for the equilibrated spin configuration.

sc = instant_correlations(sys)
+add_sample!(sc, sys)    # Accumulate the newly sampled structure factor into `sf`

Collect 20 additional decorrelated samples. For each sample, about 100 Langevin time-steps is sufficient to collect approximately uncorrelated statistics.

for _ in 1:20
+    for _ in 1:100
+        step!(sys, langevin)
+    end
+    add_sample!(sc, sys)
+end

Define a slice of momentum space. Wavevectors are specified in reciprocal lattice units (RLU). The notation q1s in -10:0.1:10 indicates that the first $q$-component ranges from -10 to 10 in intervals of 0.1. That is, $q$ spans over 20 Brillouin zones. To convert to absolute momentum units, each component of $q$ would need to be scaled by a reciprocal lattice vector.

q1s = -10:0.1:10
+q2s = -10:0.1:10
+qs = [[q1, q2, 0.0] for q1 in q1s, q2 in q2s];

Plot the instantaneous structure factor for the given $q$-slice. We employ the appropriate FormFactor for Co2⁺. An intensity_formula defines how dynamical correlations correspond to the observable structure factor. The function instant_intensities_interpolated calculates intensities at the target qs by interpolating over the data available at discrete reciprocal-space lattice points.

formfactors = [FormFactor("Co2")]
+instant_formula = intensity_formula(sc, :perp; formfactors)
+iq = instant_intensities_interpolated(sc, qs, instant_formula);

Plot the resulting intensity data $I(𝐪)$. The color scale is clipped to 50% of the maximum intensity.

heatmap(q1s, q2s, iq;
+    colorrange = (0, maximum(iq)/2),
+    axis = (
+        xlabel="Momentum Transfer Qx (r.l.u)", xlabelsize=16,
+        ylabel="Momentum Transfer Qy (r.l.u)", ylabelsize=16,
+        aspect=true,
+    )
+)
Example block output

Dynamical structure factor

To collect statistics for the dynamical structure factor intensities $I(𝐪,ω)$ at finite temperature, use dynamical_correlations. Now, each call to add_sample! will run a classical spin dynamics trajectory. Longer-time trajectories will be required to achieve greater energy resolution, as controlled by nω. Here, we pick a moderate number of energies, nω = 50, which will make the simulation run quickly.

ωmax = 6.0  # Maximum  energy to resolve (meV)
+nω = 50     # Number of energies to resolve
+sc = dynamical_correlations(sys; Δt, nω, ωmax, process_trajectory=:symmetrize)
SampledCorrelations (616.354 MiB)
+[S(q,ω) | nω = 50, Δω = 0.1333 | 0 sample]
+Lattice: (10, 10, 10)×8
+6 correlations in Dipole mode:
+╔ ⬤ ⬤ ⬤ Sx
+║ ⋅ ⬤ ⬤ Sy
+╚ ⋅ ⋅ ⬤ Sz
+

Each sample requires running a full dynamical trajectory to measure correlations, so we here restrict to 5 samples.

for _ in 1:5
+    for _ in 1:100
+        step!(sys, langevin)
+    end
+    add_sample!(sc, sys)
+end

Define points that define a piecewise-linear path through reciprocal space, and a sampling density.

points = [[3/4, 3/4,   0],
+          [  0,   0,   0],
+          [  0, 1/2, 1/2],
+          [1/2,   1,   0],
+          [  0,   1,   0],
+          [1/4,   1, 1/4],
+          [  0,   1,   0],
+          [  0,  -4,   0]]
+density = 50 # (Å)
+path, xticks = reciprocal_space_path(cryst, points, density);

Calculate $I(𝐪, ω)$ intensities along this path with Lorentzian broadening on the scale of 0.1 meV.

formula = intensity_formula(sc, :perp; formfactors, kT=langevin.kT)
+η = 0.1
+iqw = intensities_interpolated(sc, path, formula)
+iqwc = broaden_energy(sc, iqw, (ω, ω₀) -> lorentzian(ω-ω₀, η));

Plot the intensity data on a clipped color scale

ωs = available_energies(sc)
+heatmap(1:size(iqwc, 1), ωs, iqwc;
+    colorrange = (0, maximum(iqwc)/50),
+    axis = (;
+        xlabel="Momentum Transfer (r.l.u)",
+        ylabel="Energy Transfer (meV)",
+        xticks,
+        xticklabelrotation=π/5,
+        aspect = 1.4,
+    )
+)
Example block output

Powder averaged intensity

Define spherical shells in reciprocal space via their radii, in absolute units of 1/Å. For each shell, calculate and average the intensities at 100 $𝐪$-points, sampled approximately uniformly.

radii = 0:0.05:3.5 # (1/Å)
+output = zeros(Float64, length(radii), length(ωs))
+for (i, radius) in enumerate(radii)
+    pts = reciprocal_space_shell(sc.crystal, radius, 100)
+    is = intensities_interpolated(sc, pts, formula)
+    is = broaden_energy(sc, is, (ω,ω₀)->lorentzian(ω-ω₀, η))
+    output[i, :] = mean(is , dims=1)[1,:]
+end

Plot resulting powder-averaged structure factor

heatmap(radii, ωs, output;
+    axis = (
+        xlabel="|Q| (Å⁻¹)",
+        ylabel="Energy Transfer (meV)",
+        aspect = 1.4,
+    ),
+    colorrange = (0, 20.0)
+)
Example block output
diff --git a/dev/examples/fei2_classical-6b435b86.png b/dev/examples/04_GSD_FeI2-6b435b86.png similarity index 100% rename from dev/examples/fei2_classical-6b435b86.png rename to dev/examples/04_GSD_FeI2-6b435b86.png diff --git a/dev/examples/fei2_classical-9c3ace5d.png b/dev/examples/04_GSD_FeI2-9c3ace5d.png similarity index 100% rename from dev/examples/fei2_classical-9c3ace5d.png rename to dev/examples/04_GSD_FeI2-9c3ace5d.png diff --git a/dev/examples/fei2_classical-9fe52114.png b/dev/examples/04_GSD_FeI2-9fe52114.png similarity index 100% rename from dev/examples/fei2_classical-9fe52114.png rename to dev/examples/04_GSD_FeI2-9fe52114.png diff --git a/dev/examples/fei2_classical-a20d933e.png b/dev/examples/04_GSD_FeI2-a20d933e.png similarity index 100% rename from dev/examples/fei2_classical-a20d933e.png rename to dev/examples/04_GSD_FeI2-a20d933e.png diff --git a/dev/examples/fei2_classical-de3c2258.png b/dev/examples/04_GSD_FeI2-de3c2258.png similarity index 100% rename from dev/examples/fei2_classical-de3c2258.png rename to dev/examples/04_GSD_FeI2-de3c2258.png diff --git a/dev/examples/fei2_classical-ef051221.png b/dev/examples/04_GSD_FeI2-ef051221.png similarity index 100% rename from dev/examples/fei2_classical-ef051221.png rename to dev/examples/04_GSD_FeI2-ef051221.png diff --git a/dev/examples/fei2_classical-f49e7f7e.png b/dev/examples/04_GSD_FeI2-f49e7f7e.png similarity index 100% rename from dev/examples/fei2_classical-f49e7f7e.png rename to dev/examples/04_GSD_FeI2-f49e7f7e.png diff --git a/dev/examples/fei2_classical-ffcf4af4.png b/dev/examples/04_GSD_FeI2-ffcf4af4.png similarity index 100% rename from dev/examples/fei2_classical-ffcf4af4.png rename to dev/examples/04_GSD_FeI2-ffcf4af4.png diff --git a/dev/examples/fei2_classical.html b/dev/examples/04_GSD_FeI2.html similarity index 50% rename from dev/examples/fei2_classical.html rename to dev/examples/04_GSD_FeI2.html index e97cc6ca3..615cb23b0 100644 --- a/dev/examples/fei2_classical.html +++ b/dev/examples/04_GSD_FeI2.html @@ -1,5 +1,5 @@ -FeI₂ at Finite Temperature · Sunny documentation
GitHub

Download this example as Jupyter notebook or Julia script.

FeI₂ at Finite Temperature

using Sunny, LinearAlgebra, GLMakie

In our previous Case Study: FeI₂, we used linear spin wave theory (LSWT) to calculate the dynamical structure factor. Here, we perform a similar calculation using classical spin dynamics. Because we are interested in the coupled dynamics of spin dipoles and quadrupoles, we employ a classical dynamics of SU(3) coherent states that generalizes the Landau-Lifshitz equation.

Compared to LSWT, simulations using classical dynamics are much slower, and are limited in $k$-space resolution. However, they make it is possible to capture nonlinear effects associated with finite temperature fluctuations. Classical dynamics are also appealing for studying out-of-equilibrium systems (e.g., relaxation of spin glasses), or systems with quenched inhomogeneities that require large simulation volumes.

In this tutorial, we show how to study the finite temperature dynamics of FeI₂ using the classical approach. It is important to stress that the estimation of $S(𝐪,ω)$ with classical dynamics is fundamentally a Monte Carlo calculation: sample spin configurations are drawn from thermal equilibrium and used as initial conditions for generating dissipationless trajectories. The correlations of these trajectories are then averaged and used to calculate scattering intensities. It is therefore important to ensure that the initial spin configurations are sampled appropriately and that sufficient statistics are collected. We will demonstrate one approach here.

As an overview, we will:

  1. Identify the ground state
  2. Measure correlation data describing the excitations around that ground state
  3. Use the correlation data to compute scattering intensities

As the implementation of the FeI₂ model is already covered in detail in the LSWT tutorial, we will not repeat it below. Instead, we will assume that you already have defined a sys in the same way with lattice dimensions $4×4×4$.

sys
System [SU(3)]
+4. Generalized spin dynamics of FeI₂ at finite T · Sunny documentation
GitHub
Download this example as Jupyter notebook or Julia script.
4. Generalized spin dynamics of FeI₂ at finite T
using Sunny, LinearAlgebra, GLMakie
In the previous FeI₂ tutorial, we used multi-flavor spin wave theory to calculate the dynamical structure factor. Here, we perform a similar calculation using classical spin dynamics at finite temperature. Because we are interested in the coupled dynamics of spin dipoles and quadrupoles, we employ a classical dynamics of SU(3) coherent states that generalizes the Landau-Lifshitz equation.
Compared to LSWT, simulations using classical dynamics are much slower, and are limited in $k$-space resolution. However, they make it is possible to capture nonlinear effects associated with finite temperature fluctuations. Classical dynamics are also appealing for studying out-of-equilibrium systems (e.g., relaxation of spin glasses), or systems with quenched inhomogeneities that require large simulation volumes.
In this tutorial, we show how to study the finite temperature dynamics of FeI₂ using the classical approach. It is important to stress that the estimation of $S(𝐪,ω)$ with classical dynamics is fundamentally a Monte Carlo calculation: sample spin configurations are drawn from thermal equilibrium and used as initial conditions for generating dissipationless trajectories. The correlations of these trajectories are then averaged and used to calculate scattering intensities. It is therefore important to ensure that the initial spin configurations are sampled appropriately and that sufficient statistics are collected. We will demonstrate one approach here.
As an overview, we will:
  1. Identify the ground state
  2. Measure correlation data describing the excitations around that ground state
  3. Use the correlation data to compute scattering intensities
As the implementation of the FeI₂ model is already covered in detail in the LSWT tutorial, we will not repeat it below. Instead, we will assume that you already have defined a sys in the same way with lattice dimensions $4×4×4$.
sys
System [SU(3)]
 Lattice (4×4×4)×1
 Energy per site -353/250
 
Finding a ground state
Sunny uses the Langevin dynamics of SU(N) coherent states to sample spin configurations from the thermal equlibrium. One first constructs a Langevin integrator. This requires a time step, temperature, and a phenomenological damping parameter $λ$ that sets the coupling to the thermal bath.
Δt = 0.05/D    # Should be inversely proportional to the largest energy scale
@@ -13,8 +13,8 @@
 langevin = Langevin(Δt; kT, λ);
Langevin dynamics can be used to search for a magnetically ordered state. For this, the temperature kT must be below the ordering temperature, but large enough that the dynamical sampling procedure can overcome local energy barriers and eliminate defects.
randomize_spins!(sys)
 for _ in 1:20_000
     step!(sys, langevin)
-end
Although thermal fluctuations are present, the correct antiferromagnetic order (2 up, 2 down) is apparent.
plot_spins(sys; color=[s[3] for s in sys.dipoles])
Example block output
For other systems, it can be much harder to find the magnetic ordering in an unbiased way, and more complicated sampling procedures may be necessary.
Calculating Thermal-Averaged Correlations $\langle S^{\alpha\beta}(𝐪,ω)\rangle$
Our aim is to study the classical spin dynamics for states sampled in thermal equilibrium. To minimize finite size effects, and achieve sufficient momentum space resolution, we should significantly enlarge the system volume. The function resize_supercell takes new dimensions as multiples of the unit cell lattice vectors.
sys_large = resize_supercell(sys, (16,16,4)) # 16x16x4 copies of the original unit cell
-plot_spins(sys_large; color=[s[3] for s in sys_large.dipoles])
Example block output
Now we will re-thermalize the system to a configuration just above the ordering temperature. Sunny expects energies in meV by default, so we use meV_per_K to convert from kelvin.
kT = 3.5 * meV_per_K     # 3.5K ≈ 0.30 meV
+end
Although thermal fluctuations are present, the correct antiferromagnetic order (2 up, 2 down) is apparent.
plot_spins(sys; color=[s[3] for s in sys.dipoles])
Example block output
For other systems, it can be much harder to find the magnetic ordering in an unbiased way, and more complicated sampling procedures may be necessary.
Calculating Thermal-Averaged Correlations $\langle S^{\alpha\beta}(𝐪,ω)\rangle$
Our aim is to study the classical spin dynamics for states sampled in thermal equilibrium. To minimize finite size effects, and achieve sufficient momentum space resolution, we should significantly enlarge the system volume. The function resize_supercell takes new dimensions as multiples of the unit cell lattice vectors.
sys_large = resize_supercell(sys, (16,16,4)) # 16x16x4 copies of the original unit cell
+plot_spins(sys_large; color=[s[3] for s in sys_large.dipoles])
Example block output
Now we will re-thermalize the system to a configuration just above the ordering temperature. Sunny expects energies in meV by default, so we use meV_per_K to convert from kelvin.
kT = 3.5 * meV_per_K     # 3.5K ≈ 0.30 meV
 langevin.kT = kT
 for _ in 1:10_000
     step!(sys_large, langevin)
@@ -51,7 +51,7 @@
 fig = lines(ωs, is[1,:]; axis=(xlabel="meV", ylabel="Intensity"), label="(0,0,0)")
 lines!(ωs, is[2,:]; label="(π,π,π)")
 axislegend()
-fig
Example block output
The resolution in energy can be improved by increasing nω (and decreasing Δt), and the general accuracy can be improved by collecting additional samples from the thermal equilibrium.
For real calculations, one often wants to apply further corrections and more accurate formulas. Here, we apply FormFactor corrections appropriate for Fe2 magnetic ions, and a dipole polarization correction :perp.
formfactors = [FormFactor("Fe2"; g_lande=3/2)]
+fig
Example block output
The resolution in energy can be improved by increasing nω (and decreasing Δt), and the general accuracy can be improved by collecting additional samples from the thermal equilibrium.
For real calculations, one often wants to apply further corrections and more accurate formulas. Here, we apply FormFactor corrections appropriate for Fe2 magnetic ions, and a dipole polarization correction :perp.
formfactors = [FormFactor("Fe2"; g_lande=3/2)]
 new_formula = intensity_formula(sc, :perp; kT, formfactors = formfactors)
Classical Scattering Intensity Formula
 At discrete scattering modes S = S[ix_q,ix_ω], use:
 
@@ -95,7 +95,7 @@
     colorrange=(0.0,0.05),
 )
 
-fig
Example block output
Note that we have clipped the colors in order to make the higher-energy excitations more visible.
Unconventional RLU Systems and Constant Energy Cuts
Often it is useful to plot cuts across multiple wave vectors but at a single energy. We'll pick an energy,
ωidx = 60
+fig
Example block output
Note that we have clipped the colors in order to make the higher-energy excitations more visible.
Unconventional RLU Systems and Constant Energy Cuts
Often it is useful to plot cuts across multiple wave vectors but at a single energy. We'll pick an energy,
ωidx = 60
 target_ω = ωs[ωidx]
3.7312072301840273
and take a constant-energy cut at that energy. The most straightforward way is to make a plot whose axes are aligned with the conventional reciprocal lattice of the crystal. This is accomplished using unit_resolution_binning_parameters:
params = unit_resolution_binning_parameters(sc)
 params.binstart[1:2] .= -1 # Expand plot range slightly
 
@@ -124,11 +124,11 @@
 hm = heatmap!(ax,bcs[1],bcs[2],is[:,:,1,1] ./ counts[:,:,1,1])
 add_lines!(ax,params)
 Colorbar(fig[1,2], hm);
-fig
Example block output
In the above plot, the dashed-line (direct) lattice vectors are clearly orthogonal. However, we know that in real space, the lattice vectors $a$ and $b$ are not orthogonal, but rather point along the edges of a hexagon (see lower left corner):


Thus, plotting the direct lattice vectors as orthogonal (even in reciprocal space) is somewhat misleading. Worse yet, the [H,0,0] by [0,K,0] plot apparently loses the 6-fold symmetry of the crystal! Lastly, if one works out the components of the real-space metric with respect to the axes of the plot, one finds that there are non-zero off-diagonal entries,
latvecs = sys.crystal.latvecs
+fig
Example block output
In the above plot, the dashed-line (direct) lattice vectors are clearly orthogonal. However, we know that in real space, the lattice vectors $a$ and $b$ are not orthogonal, but rather point along the edges of a hexagon (see lower left corner):


Thus, plotting the direct lattice vectors as orthogonal (even in reciprocal space) is somewhat misleading. Worse yet, the [H,0,0] by [0,K,0] plot apparently loses the 6-fold symmetry of the crystal! Lastly, if one works out the components of the real-space metric with respect to the axes of the plot, one finds that there are non-zero off-diagonal entries,
latvecs = sys.crystal.latvecs
 metric = latvecs' * I(3) * latvecs
3×3 Matrix{Float64}:
  16.4035   -8.20174   0.0
  -8.20174  16.4035    0.0
-  0.0       0.0      45.5914
so real-space rotations and angles map into reciprocal space rotations angles in a complicated way.
To resolve these important issues, we want to use axes which are orthogonal (i.e. they diagonalize the metric and solve all of the problems just mentioned). The canonical choice is to use the combination $\frac{1}{2}a + b$ of lattice vectors (equiv. $a^* - \frac{1}{2}b^*$), which is orthogonal to $a$:
(latvecs * [1/2,1,0]) ⋅ (latvecs * [1,0,0]) == 0
true
This new vector $\frac{1}{2}a+b$ is visibly orthogonal to $a$ in real space:
Example block output
To use "projection onto the new vector" as a histogram axis, only a single change is needed to the binning parameters. The second covector (previously $b$) must be swapped out for $\frac{1}{2}a + b$ (recall that reciprocal space covectors, such as those used in BinningParameters correspond to direct space vectors).
params.covectors[2,1:3] = [1/2,1,0] # [1/2,1,0] times [a;b;c] is (a/2 + b)
Binning Parameters
+  0.0       0.0      45.5914
so real-space rotations and angles map into reciprocal space rotations angles in a complicated way.
To resolve these important issues, we want to use axes which are orthogonal (i.e. they diagonalize the metric and solve all of the problems just mentioned). The canonical choice is to use the combination $\frac{1}{2}a + b$ of lattice vectors (equiv. $a^* - \frac{1}{2}b^*$), which is orthogonal to $a$:
(latvecs * [1/2,1,0]) ⋅ (latvecs * [1,0,0]) == 0
true
This new vector $\frac{1}{2}a+b$ is visibly orthogonal to $a$ in real space:
Example block output
To use "projection onto the new vector" as a histogram axis, only a single change is needed to the binning parameters. The second covector (previously $b$) must be swapped out for $\frac{1}{2}a + b$ (recall that reciprocal space covectors, such as those used in BinningParameters correspond to direct space vectors).
params.covectors[2,1:3] = [1/2,1,0] # [1/2,1,0] times [a;b;c] is (a/2 + b)
Binning Parameters
 ⊡    31 bins from -1.000 to +0.969 along [+1.00 dx] (Δ = 0.064)
 ⊡    31 bins from -1.000 to +0.969 along [+0.50 dx +1.00 dy] (Δ = 0.057)
 ∫ Integrated from -0.125 to +1.625 along [+1.00 dz] (Δ = 1.750)
@@ -161,7 +161,7 @@
 is = intensities_interpolated(sc, qs, new_formula; interpolation=:linear)
 
 add_lines!(ax_left,params)
-fig
Example block output
Now, not only are the dashed-line lattice vectors no longer misleadingly orthogonal, but the six-fold symmetry has been restored as well! Further, the metric has been diagonalized:
metric = (latvecs * inv(A'))' * I(3) * (latvecs * inv(A'))
3×3 Matrix{Float64}:
+fig
Example block output
Now, not only are the dashed-line lattice vectors no longer misleadingly orthogonal, but the six-fold symmetry has been restored as well! Further, the metric has been diagonalized:
metric = (latvecs * inv(A'))' * I(3) * (latvecs * inv(A'))
3×3 Matrix{Float64}:
  16.4035   0.0      0.0
   0.0     12.3026   0.0
   0.0      0.0     45.5914
Finally, we note that instantaneous structure factor data, $𝒮(𝐪)$, can be obtained from a dynamic structure factor with instant_intensities_interpolated. Here we'll reuse the grid of wave vectors we generated above.
is_static = instant_intensities_interpolated(sc, qs, new_formula; interpolation = :linear)
@@ -175,4 +175,4 @@
     )
 )
 Colorbar(hm.figure[1,2], hm.plot)
-hm
Example block output

+hm
Example block output
diff --git a/dev/examples/ising2d-f39f34dd.png b/dev/examples/05_MC_Ising-f39f34dd.png similarity index 100% rename from dev/examples/ising2d-f39f34dd.png rename to dev/examples/05_MC_Ising-f39f34dd.png diff --git a/dev/examples/05_MC_Ising.html b/dev/examples/05_MC_Ising.html new file mode 100644 index 000000000..e7bfedf6f --- /dev/null +++ b/dev/examples/05_MC_Ising.html @@ -0,0 +1,17 @@ + +5. Monte Carlo sampling of the Ising model · Sunny documentation
GitHub

Download this example as Jupyter notebook or Julia script.

5. Monte Carlo sampling of the Ising model

This tutorial illustrates simulation of the classical 2D Ising model.

using Sunny, GLMakie

Sunny expects a 3D Crystal unit cell. To model a square lattice, we create an orthogonal unit cell where the $z$-spacing is distinct from the $x$ and $y$ spacing.

a = 1
+latvecs = lattice_vectors(a,a,10a,90,90,90)
+crystal = Crystal(latvecs, [[0,0,0]])
Crystal
+Spacegroup 'P 4/m m m' (123)
+Lattice params a=1, b=1, c=10, α=90°, β=90°, γ=90°
+Cell volume 10
+Wyckoff 1a (point group '4/mmm'):
+   1. [0, 0, 0]
+

Create a System of spins with linear size L in the $x$ and $y$ directions, and only one layer in the $z$ direction. The option :dipole means that the system will store Heisenberg spins, as opposed to SU($N$) coherent states. Polarize the initial spin configuration using polarize_spins!. Following the Ising convention, we will restrict these spins to the $z$-axis and give them magnitude $S=1$.

By default, Sunny uses physical units, e.g. magnetic field in tesla. Here we specify an alternative Units system, so that the Zeeman coupling between the spin dipole $𝐬$ and an external field $𝐁$ has the dimensionless form $-𝐁⋅𝐬$.

L = 128
+sys = System(crystal, (L,L,1), [SpinInfo(1, S=1, g=1)], :dipole, units=Units.theory, seed=0)
+polarize_spins!(sys, (0,0,1))

Use set_exchange! to include a ferromagnetic Heisenberg interaction along nearest-neighbor bonds. The Bond below connects two spins displaced by one lattice constant in the $x$-direction. This interaction will be propagated to all nearest-neighbors bonds in the system, consistent with the symmetries of the square lattice.

set_exchange!(sys, -1.0, Bond(1,1,(1,0,0)))

If an external field is desired, it can be set using set_external_field!.

B = 0
+set_external_field!(sys, (0,0,B))

The critical temperature for the Ising model is known analytically.

Tc = 2/log(1+√2)
2.269185314213022

Use a LocalSampler to perform nsweeps Monte Carlo sweeps. A sweep consists of, on average, one trial update per spin in the system. Each proposed update is accepted or rejected according to the Metropolis acceptance probability. As its name suggests, the propose_flip function will only propose pure spin flips, $𝐬 \rightarrow -𝐬$.

nsweeps = 4000
+sampler = LocalSampler(kT=Tc, propose=propose_flip)
+for i in 1:nsweeps
+    step!(sys, sampler)
+end

Plot the Ising spins by extracting the $z$-component of the dipoles

heatmap(reshape([s.z for s in sys.dipoles], (L,L)))
Example block output
diff --git a/dev/examples/out_of_equilibrium-c31de6b4.png b/dev/examples/06_CP2_Skyrmions-c31de6b4.png similarity index 100% rename from dev/examples/out_of_equilibrium-c31de6b4.png rename to dev/examples/06_CP2_Skyrmions-c31de6b4.png diff --git a/dev/examples/06_CP2_Skyrmions.html b/dev/examples/06_CP2_Skyrmions.html new file mode 100644 index 000000000..ef5246f0c --- /dev/null +++ b/dev/examples/06_CP2_Skyrmions.html @@ -0,0 +1,55 @@ + +6. Dynamical quench into CP² skyrmion liquid · Sunny documentation
GitHub

Download this example as Jupyter notebook or Julia script.

6. Dynamical quench into CP² skyrmion liquid

This example demonstrates Sunny's ability to simulate the out-of-equilibrium dynamics of generalized spin systems. We will implement the model Hamiltonian of Zhang et al., Nature Communications 14, 3626 (2023), which supports a novel type of topological defect, a CP² skyrmion, that involves both the dipolar and quadrupolar parts of a quantum spin.

Beginning from an initial high-temperature state, a disordered gas of CP² skyrmions can be formed by rapidly quenching to low temperature. To model the coupled dynamics of dipoles and quadrupoles, Sunny uses a recently developed generalization of the Landau-Lifshitz spin dynamics, Dahlbom et al., Phys. Rev. B 106, 235154 (2022).

using Sunny, GLMakie

The Hamiltonian we will implement,

\[\mathcal{H} = \sum_{\langle i,j \rangle} J_{ij}( \hat{S}_i^x \hat{S}_j^x + \hat{S}_i^y \hat{S}_j^y + \Delta\hat{S}_i^z \hat{S}_j^z) - h\sum_{i}\hat{S}_i^z + D\sum_{i}(\hat{S}_i^z)^2\]

contains competing ferromagnetic nearest-neightbor and antiferromagnetic next-nearest-neighbor exchange terms on a triangular lattice. Both exchanges exhibit anisotropy on the z-term. Additionally, there is an external magnetic field, $h$, and easy-plane single-ion anisotropy, $D > 0$. We begin by implementing the Crystal.

lat_vecs = lattice_vectors(1.0, 1.0, 2.0, 90, 90, 120)
+basis_vecs = [[0,0,0]]
+cryst = Crystal(lat_vecs, basis_vecs)
Crystal
+Spacegroup 'P 6/m m m' (191)
+Lattice params a=1, b=1, c=2, α=90°, β=90°, γ=120°
+Cell volume 1.732
+Wyckoff 1a (point group '6/mmm'):
+   1. [0, 0, 0]
+

The crystal is then used to create a spin System. All parameters in this model system are dimensionless, so we select "theory" units and set the g-factor to one.

L = 40
+dims = (L, L, 1)
+sys = System(cryst, dims, [SpinInfo(1, S=1, g=1)], :SUN; seed=101, units=Units.theory)
System [SU(3)]
+Lattice (40×40×1)×1
+Energy per site 0
+

We proceed to implement each term of the Hamiltonian, selecting our parameters so that the system occupies a region of the phase diagram that supports skyrmions. The exchange interactions are set as follows.

J1 = -1           # Nearest-neighbor ferromagnetic
+J2 = (2.0/(1+√5)) # Tune competing exchange to set skyrmion scale length
+Δ = 2.6           # Exchange anisotropy
+
+ex1 = J1 * [1.0 0.0 0.0;
+            0.0 1.0 0.0;
+            0.0 0.0 Δ]
+ex2 = J2 * [1.0 0.0 0.0;
+            0.0 1.0 0.0;
+            0.0 0.0 Δ]
+set_exchange!(sys, ex1, Bond(1, 1, [1, 0, 0]))
+set_exchange!(sys, ex2, Bond(1, 1, [1, 2, 0]))

Next we add the external field,

h = 15.5
+field = set_external_field!(sys, [0.0 0.0 h])

and finally an easy-plane single-ion anisotropy,

D = 19.0
+set_onsite_coupling!(sys, S -> D*S[3]^2, 1)

Initialize system to an infinite temperature (fully randomized) initial condition.

randomize_spins!(sys)

We are now ready to simulate the quenching process using a generalized Langevin spin dynamics. If we were working with spin dipoles only, then Langevin dynamics would be the usual Landau-Lifshitz spin dynamics, augmented with damping and noise terms. In the present study, we are instead working with quantum spin-1 (an ($N=3$)-level system that includes both dipoles and quadrupoles). Here, Langevin captures the coupled dipole-quadrupole dynamics using the formalism of SU($N$) coherent states.

Selecting kT = 0 in the Langevin dynamics will effective disable the noise term. Then the parameter λ effectively determines the damping time-scale.

Δt = 0.2/D  # Integration time step (inverse meV). Typically this will be
+            # inversely proportional to the largest energy scale in the
+            # system. We can use a fairly large time-step here because
+            # accuracy isn't critical.
+kT = 0      # Target equilibrium temperature (meV)
+λ = 0.1     # Magnitude of coupling to thermal bath (dimensionless)
+integrator = Langevin(Δt; kT, λ)
Langevin(0.010526315789473684, 0.1, 0.0)

Finally we run the dynamics. We will record the state of the system at three different times during the quenching process by copying the coherents field of the System.

τs = [4., 16, 256]  # Times to record snapshots
+frames = []         # Empty array to store snapshots
+for i in eachindex(τs)
+    dur = i == 1 ? τs[1] : τs[i] - τs[i-1] # Determine the length of time to simulate
+    numsteps = round(Int, dur/Δt)
+    for _ in 1:numsteps                    # Perform the integration
+        step!(sys, integrator)
+    end
+    push!(frames, copy(sys.coherents))     # Save a snapshot spin configuration
+end

To visualize the state of the system contained in each snapshot, we will calculate and plot the skyrmion density on each plaquette of our lattice. The function plot_triangular_plaquettes is not part of the core Sunny package, but rather something you could define yourself. We are using the definition in plotting2d.jl from the Sunny examples/extra directory.

include(pkgdir(Sunny, "examples", "extra", "Plotting", "plotting2d.jl"))
+
+function sun_berry_curvature(z₁, z₂, z₃)
+    z₁, z₂, z₃ = normalize.((z₁, z₂, z₃))
+    n₁ = z₁ ⋅ z₂
+    n₂ = z₂ ⋅ z₃
+    n₃ = z₃ ⋅ z₁
+    return angle(n₁ * n₂ * n₃)
+end
+
+plot_triangular_plaquettes(sun_berry_curvature, frames; resolution=(1800,600),
+    offset_spacing=10, texts = ["\tt = "*string(τ) for τ in τs], text_offset = (0.0, 6.0)
+)
Example block output

The times are given in $\hbar/|J_1|$. The white background corresponds to a quantum paramagnetic state, where the local spin exhibits a strong quadrupole moment and little or no dipole moment. Observe that the process has generated a number of well-formed skyrmions of both positive (red) and negative (blue) charge in addition to a number of other metastable spin configurations. A full-sized version of this figure is available in Dahlbom et al..

diff --git a/dev/examples/contributed/CoRh2O4-tutorial.html b/dev/examples/contributed/CoRh2O4-tutorial.html index 53eec38ca..511ef21c9 100644 --- a/dev/examples/contributed/CoRh2O4-tutorial.html +++ b/dev/examples/contributed/CoRh2O4-tutorial.html @@ -1,5 +1,5 @@ -Powder Averaged CoRh₂O₄ at Finite Temperature · Sunny documentation
GitHub

Powder Averaged CoRh₂O₄ at Finite Temperature

Inspired by: Ge et al., Phys. Rev. B 96, 064413 (2017)

Authors: Martin Mourigal, David Dahlbom

Date: October 28, 2023 (Sunny 0.5.5)

Goal: This script is to calculate the temperature dependence of the magnon excitations in the spin-3/2 Heisenberg Diamond Antiferromagnet and compare to powder-averaged results obtained for the compound CoRh₂O₄

Load pacakges.

using Sunny, GLMakie, ProgressMeter, Statistics, Random, Brillouin
+Powder Averaged CoRh₂O₄ at Finite Temperature · Sunny documentation
GitHub
Powder Averaged CoRh₂O₄ at Finite Temperature
Inspired by: Ge et al., Phys. Rev. B 96, 064413 (2017)
Authors: Martin Mourigal, David Dahlbom
Date: October 28, 2023  (Sunny 0.5.5)
Goal: This script is to calculate the temperature dependence of the magnon excitations in the spin-3/2 Heisenberg Diamond Antiferromagnet and compare to powder-averaged results obtained for the compound CoRh₂O₄
Load pacakges.
using Sunny, GLMakie, ProgressMeter, Statistics, Random, Brillouin
 cif_path = pkgdir(Sunny, "examples", "longer_examples", "CoRh2O4_#109301.cif");
Define custom functions.
The function quench! randomizes the spins of a given System, fixes a target temperature, and lets the system relax at this temperature for nrelax integration steps.
function quench!(sys, integrator; kTtarget, nrelax)
     randomize_spins!(sys);
     integrator.kT = kTtarget;
@@ -190,4 +190,4 @@
     )
     heatmap!(ax, Qpow, ωs, pqw_res[9-i]; colorrange = (0, 20.0))
 end
-fig

+fig

diff --git a/dev/examples/contributed/MgCr2O4-tutorial.html b/dev/examples/contributed/MgCr2O4-tutorial.html index 16c8c5240..9f9f1956a 100644 --- a/dev/examples/contributed/MgCr2O4-tutorial.html +++ b/dev/examples/contributed/MgCr2O4-tutorial.html @@ -1,5 +1,5 @@ -MgCr2O4 at Finite Temperature · Sunny documentation
GitHub

MgCr2O4 at Finite Temperature

Author: Martin Mourigal <br> Date: September 9, 2022 (Updated by October 28, 2023 using Sunny 0.5.5)

In this tutorial, we will walk through an example in Sunny and calculate the spin dynamical properties of the Heisenberg pyrochlore antiferromagnet and apply this knowledge to MgCr2O4 and ZnCr2O4, which are known to approximate this model. Relevant publications include:

[1] P. H. Conlon and J. T. Chalker, Phys. Rev. Lett. 102, 237206 (2009)

[2] P. H. Conlon and J. T. Chalker, Phys. Rev. B 81, 224413 (2010)

[3] X. Bai, J. A. M. Paddison, et al. Phys. Rev. Lett. 122, 097201 (2019)

Setting up Julia

To run the examples in the tutorial, you will need a working installation of the Julia programming language and the Sunny package. Some useful references for getting started are:

We will begin by loading the relevant packages.

using Sunny # The main package
+MgCr2O4 at Finite Temperature · Sunny documentation
GitHub
MgCr2O4 at Finite Temperature
Author: Martin Mourigal <br> Date: September 9, 2022 (Updated by October 28, 2023 using Sunny 0.5.5)
In this tutorial, we will walk through an example in Sunny and calculate the spin dynamical properties of the Heisenberg pyrochlore antiferromagnet and apply this knowledge to MgCr2O4 and ZnCr2O4, which are known to approximate this model. Relevant publications include:
[1] P. H. Conlon and J. T. Chalker, Phys. Rev. Lett. 102, 237206 (2009)
[2] P. H. Conlon and J. T. Chalker, Phys. Rev. B 81, 224413 (2010)
[3] X. Bai, J. A. M. Paddison, et al. Phys. Rev. Lett. 122, 097201 (2019)
Setting up Julia
To run the examples in the tutorial, you will need a working installation of the Julia programming language and the Sunny package. Some useful references for getting started are:
We will begin by loading the relevant packages.
using Sunny # The main package
 using GLMakie # Plotting package
Setting up the crystal structure
Before specifying the interactions of our system, we first must set up the crystal. We will begin by specifying the pyrochlore lattice (illustrated below) in the manner that is typical of theorists.
Picture Credits: Theory of Quantum Matter Unit, OIST
"Theorist" Method
In this approach, we directly define the lattice vectors and specify the position of each atom in fractional coordinates.
latvecs = lattice_vectors(8.3342, 8.3342, 8.3342, 90, 90, 90)
 positions = [[0.875, 0.625, 0.375],
              [0.625, 0.125, 0.625],
@@ -388,4 +388,4 @@
 Colorbar(fig[1,2], hm)
 hm = heatmap!(ax_mgcro, qvals, qvals, Sq_mgcro)
 Colorbar(fig[1,4], hm)
-fig

+fig

diff --git a/dev/examples/fei2_tutorial.html b/dev/examples/fei2_tutorial.html deleted file mode 100644 index 3eb210db3..000000000 --- a/dev/examples/fei2_tutorial.html +++ /dev/null @@ -1,159 +0,0 @@ - -Case Study: FeI₂ · Sunny documentation
GitHub

Download this example as Jupyter notebook or Julia script.

Case Study: FeI₂

FeI₂ is an effective spin-1 material with strong single-ion anisotropy. Quadrupolar fluctuations give rise to a single-ion bound state that cannot be described by a dipole-only model. This tutorial illustrates how to use the linear spin wave theory of SU(3) coherent states (i.e. 2-flavor bosons) to model the magnetic behavior in FeI₂. The original study was performed in Bai et al., Nature Physics 17, 467–472 (2021).

The Fe atoms are arranged in stacked triangular layers. The effective spin Hamiltonian takes the form,

\[\mathcal{H}=\sum_{(i,j)} 𝐒_i ⋅ J_{ij} 𝐒_j - D\sum_i \left(S_i^z\right)^2,\]

where the set of exchange matrices $J_{ij}$ between bonded sites $(i,j)$ includes competing ferromagnetic and antiferromagnetic interactions. This model also includes a strong easy axis anisotropy, $D > 0$.

We will formulate this Hamiltonian in Sunny and then calculate its dynamic structure factor.

Get Julia and Sunny

Sunny is implemented in Julia. This is a relatively new programming language that allows for interactive development (like Python or Matlab) while also providing high numerical efficiency (like C++ or Fortran). New Julia users may wish to take a look at our Getting Started with Julia guide. Sunny requires Julia 1.9 or later.

From the Julia prompt, load Sunny. For plotting, one can choose either GLMakie (a pop-up window) or WGLMakie (inline plots for a Jupyter notebook or VSCode).

using Sunny, GLMakie

If these packages are not yet installed, Julia should offer to install them using its built-in package management system. If old versions are installed, you may need to update them to run this tutorial.

Crystals

A Crystal describes the crystallographic unit cell and will usually be loaded from a .cif file. Here, we instead build a crystal by listing all atoms and their types.

a = b = 4.05012  # Lattice constants for triangular lattice
-c = 6.75214      # Spacing in the z-direction
-
-latvecs = lattice_vectors(a, b, c, 90, 90, 120) # A 3x3 matrix of lattice vectors that
-                                                # define the conventional unit cell
-positions = [[0, 0, 0], [1/3, 2/3, 1/4], [2/3, 1/3, 3/4]]  # Positions of atoms in fractions
-                                                           # of lattice vectors
-types = ["Fe", "I", "I"]
-FeI2 = Crystal(latvecs, positions; types)
Crystal
-Spacegroup 'P -3 m 1' (164)
-Lattice params a=4.05, b=4.05, c=6.752, α=90°, β=90°, γ=120°
-Cell volume 95.92
-Type 'Fe', Wyckoff 1a (point group '-3m.'):
-   1. [0, 0, 0]
-Type 'I', Wyckoff 2d (point group '3m.'):
-   2. [1/3, 2/3, 1/4]
-   3. [2/3, 1/3, 3/4]
-

Observe that Sunny inferred the space group, 'P -3 m 1' (164) and labeled the atoms according to their point group symmetries.

Only the Fe atoms are magnetic, so we discard the I ions using subcrystal.

cryst = subcrystal(FeI2, "Fe")
Crystal
-Spacegroup 'P -3 m 1' (164)
-Lattice params a=4.05, b=4.05, c=6.752, α=90°, β=90°, γ=120°
-Cell volume 95.92
-Type 'Fe', Wyckoff 1a (point group '-3m.'):
-   1. [0, 0, 0]
-

Observe that cryst retains the spacegroup symmetry of the full FeI₂ crystal. This information will be used, for example, to propagate exchange interactions between symmetry-equivalent bonds.

In a running Julia environment, the crystal can be viewed interactively using view_crystal.

view_crystal(cryst, 8.0)
Example block output

Symmetry analysis

The command print_symmetry_table provides a list of all the symmetry-allowed interactions up to a cutoff distance.

print_symmetry_table(cryst, 8.0)
Atom 1
-Type 'Fe', position [0, 0, 0], multiplicity 1
-Allowed g-tensor: [A 0 0
-                   0 A 0
-                   0 0 B]
-Allowed anisotropy in Stevens operators:
-    c₁*𝒪[2,0] +
-    c₂*𝒪[4,-3] + c₃*𝒪[4,0] +
-    c₄*𝒪[6,-3] + c₅*𝒪[6,0] + c₆*𝒪[6,6]
-
-Bond(1, 1, [1, 0, 0])
-Distance 4.05012, coordination 6
-Connects 'Fe' at [0, 0, 0] to 'Fe' at [1, 0, 0]
-Allowed exchange matrix:[A 0 0
-                         0 B D
-                         0 D C]
-
-Bond(1, 1, [0, 0, 1])
-Distance 6.75214, coordination 2
-Connects 'Fe' at [0, 0, 0] to 'Fe' at [0, 0, 1]
-Allowed exchange matrix:[A 0 0
-                         0 A 0
-                         0 0 B]
-
-Bond(1, 1, [1, 2, 0])
-Distance 7.0150136167509, coordination 6
-Connects 'Fe' at [0, 0, 0] to 'Fe' at [1, 2, 0]
-Allowed exchange matrix:[A 0 0
-                         0 B D
-                         0 D C]
-
-Bond(1, 1, [1, 0, 1])
-Distance 7.8736818956572, coordination 12
-Connects 'Fe' at [0, 0, 0] to 'Fe' at [1, 0, 1]
-Allowed exchange matrix:[A F E
-                         F B D
-                         E D C]

The allowed $g$-tensor is expressed as a 3×3 matrix in the free coefficients A, B, ... The allowed single-ion anisotropy is expressed as a linear combination of Stevens operators. The latter correspond to polynomials of the spin operators, as we will describe below.

The allowed exchange interactions are given as a 3×3 matrix for representative bonds. The notation Bond(i, j, n) indicates a bond between atom indices i and j, with cell offset n. In the general case, it will be necessary to associate atom indices with their positions in the unit cell; these can be viewed with display(cryst). Note that the order of the pair $(i, j)$ is significant if the exchange tensor contains antisymmetric Dzyaloshinskii–Moriya (DM) interactions.

In the case of FeI₂, Bond(1, 1, [1,0,0]) is one of the 6 nearest-neighbor Fe-Fe bonds on a triangular lattice layer, and Bond(1, 1, [0,0,1]) is an Fe-Fe bond between layers.

Building a spin System

In constructing a spin System, we must provide several additional details about the spins.

sys = System(cryst, (4, 4, 4), [SpinInfo(1, S=1, g=2)], :SUN, seed=2)
System [SU(3)]
-Lattice (4×4×4)×1
-Energy per site 0
-

This system includes $4×4×4$ unit cells, i.e. 64 Fe atoms, each with spin $S=1$ and a $g$-factor of 2. Quantum mechanically, spin $S=1$ involves a superposition of $2S+1=3$ distinct angular momentum states. In :SUN mode, this superposition will be modeled explicitly using the formalism of SU(3) coherent states, which captures both dipolar and quadrupolar fluctuations. For the more traditional dipole dynamics, use :dipole mode instead.

Next we will use set_exchange! to assign interaction to bonds. Sunny will automatically propagate each interaction to all symmetry-equivalent bonds in the unit cell. The FeI₂ interactions below follow Bai et al.

J1pm   = -0.236
-J1pmpm = -0.161
-J1zpm  = -0.261
-J2pm   = 0.026
-J3pm   = 0.166
-J′0pm  = 0.037
-J′1pm  = 0.013
-J′2apm = 0.068
-
-J1zz   = -0.236
-J2zz   = 0.113
-J3zz   = 0.211
-J′0zz  = -0.036
-J′1zz  = 0.051
-J′2azz = 0.073
-
-J1xx = J1pm + J1pmpm
-J1yy = J1pm - J1pmpm
-J1yz = J1zpm
-
-set_exchange!(sys, [J1xx   0.0    0.0;
-                    0.0    J1yy   J1yz;
-                    0.0    J1yz   J1zz], Bond(1,1,[1,0,0]))
-set_exchange!(sys, [J2pm   0.0    0.0;
-                    0.0    J2pm   0.0;
-                    0.0    0.0    J2zz], Bond(1,1,[1,2,0]))
-set_exchange!(sys, [J3pm   0.0    0.0;
-                    0.0    J3pm   0.0;
-                    0.0    0.0    J3zz], Bond(1,1,[2,0,0]))
-set_exchange!(sys, [J′0pm  0.0    0.0;
-                    0.0    J′0pm  0.0;
-                    0.0    0.0    J′0zz], Bond(1,1,[0,0,1]))
-set_exchange!(sys, [J′1pm  0.0    0.0;
-                    0.0    J′1pm  0.0;
-                    0.0    0.0    J′1zz], Bond(1,1,[1,0,1]))
-set_exchange!(sys, [J′2apm 0.0    0.0;
-                    0.0    J′2apm 0.0;
-                    0.0    0.0    J′2azz], Bond(1,1,[1,2,1]))

The function set_onsite_coupling! assigns a single-ion anisotropy. The argument can be constructed using spin_matrices or stevens_matrices. Here we use Julia's anonymous function syntax to assign an easy-axis anisotropy along the direction $\hat{z}$.

D = 2.165
-set_onsite_coupling!(sys, S -> -D*S[3]^2, 1)

Calculating structure factor intensities

In the remainder of this tutorial, we will examine Sunny's tools for calculating the dynamical structure factor using a multi-boson generalization of linear spin wave theory (LSWT). This theory describes non-interacting quasi-particle excitations that hybridize dipolar and quadrupolar modes.

Finding the ground state

Begin with a random configuration and use minimize_energy! to find a configuration of the SU(3) coherent states (i.e. spin dipoles and quadrupoles) that locally minimizes energy.

randomize_spins!(sys)
-minimize_energy!(sys)
49

A positive number above indicates that the procedure has converged to a local energy minimum. The configuration, however, may still have defects. This can be checked by visualizing the spins, colored according to their $z$-components.

plot_spins(sys; color=[s[3] for s in sys.dipoles])
Example block output

A different understanding of the magnetic ordering can be obtained by moving to Fourier space. The 'instant' structure factor $𝒮(𝐪)$ is an experimental observable. To investigate $𝒮(𝐪)$ as true 3D data, Sunny provides instant_correlations and related functions. Here, however, we will use print_wrapped_intensities, which gives average intensities for the individual Bravais sublattices (in effect, all wavevectors are wrapped to the first Brillouin zone).

print_wrapped_intensities(sys)
Dominant wavevectors for spin sublattices:
-
-    [-1/4, 1/4, 1/4]       37.33% weight
-    [1/4, -1/4, -1/4]      37.33%
-    [-1/4, 1/4, 0]          1.60%
-    [1/4, -1/4, 0]          1.60%
-    [-1/4, 1/4, 1/2]        1.60%
-    [1/4, -1/4, 1/2]        1.60%
-    [1/4, -1/4, 1/4]        1.59%
-    [-1/4, 1/4, -1/4]       1.59%
-    [0, -1/4, 1/4]          0.77%
-    [0, 1/4, -1/4]          0.77%
-    [1/4, 0, 1/4]           0.77%
-    ...                     ...

The result will likely be approximately consistent with the known zero-field energy-minimizing magnetic structure of FeI₂, which is single-$Q$ (two-up, two-down antiferromagnetic order). Mathematically, spontaneous symmetry breaking should select one of $±Q = [0, -1/4, 1/4]$, $[1/4, 0, 1/4]$, or $[-1/4,1/4,1/4]$, associated with the three-fold rotational symmetry of the crystal spacegroup. In nature, however, one will frequently encounter competing "domains" associated with the three possible orientations of the ground state.

If the desired ground state is already known, as with FeI₂, it could be entered by hand using set_dipole!. Alternatively, in the case of FeI₂, we could repeatedly employ the above randomization and minimization procedure until a defect-free configuration is found. Some systems will have more complicated ground states, which can be much more challenging to find. For this, Sunny provides experimental support for powerful simulated annealing via parallel tempering, but that is outside the scope of this tutorial.

Here, let's break the three-fold symmetry of FeI₂ by hand. Given one or more desired $Q$ modes, Sunny can suggest a magnetic supercell with appropriate periodicity. Let's arbitrarily select one of the three possible ordering wavevectors, $Q = [0, -1/4, 1/4]$. Sunny suggests a corresponding magnetic supercell in units of the crystal lattice vectors.

suggest_magnetic_supercell([[0, -1/4, 1/4]])
Suggested magnetic supercell in multiples of lattice vectors:
-
-    [1 0 0; 0 2 1; 0 -2 1]
-
-for wavevectors [[0, -1/4, 1/4]].

The system returned by reshape_supercell is smaller, and is sheared relative to the original system. This makes it much easier to find the global energy minimum.

sys_min = reshape_supercell(sys, [1 0 0; 0 2 1; 0 -2 1])
-randomize_spins!(sys_min)
-minimize_energy!(sys_min);

Plot the system again, now including "ghost" spins out to 12Å

plot_spins(sys_min; color=[s[3] for s in sys_min.dipoles], ghost_radius=12)
Example block output

Linear spin wave theory

Now that we have found the ground state for a magnetic supercell, we can immediately proceed to perform zero-temperature calculations using linear spin wave theory. We begin by instantiating a SpinWaveTheory type using the supercell.

swt = SpinWaveTheory(sys_min)
SpinWaveTheory [Dipole correlations]
-Atoms in magnetic supercell: 4
-

Select a sequence of wavevectors that will define a piecewise linear interpolation in reciprocal lattice units (RLU).

q_points = [[0,0,0], [1,0,0], [0,1,0], [1/2,0,0], [0,1,0], [0,0,0]];

The function reciprocal_space_path will linearly sample a path between the provided $q$-points with a given density. The xticks return value provides labels for use in plotting.

density = 50
-path, xticks = reciprocal_space_path(cryst, q_points, density);

The dispersion function defines the quasiparticle excitation energies $ω_i(𝐪)$ for each point $𝐪$ along the reciprocal space path.

disp = dispersion(swt, path);

In addition to the band energies $ω_i(𝐪)$, Sunny can calculate the inelastic neutron scattering intensity $I_i(𝐪)$ for each band $i$ according to an intensity_formula. We choose to apply a polarization correction $(1 - 𝐪⊗𝐪)$ by setting the mode argument to :perp. Selecting delta_function_kernel specifies that we want the energy and intensity of each band individually.

formula = intensity_formula(swt, :perp; kernel=delta_function_kernel)
Quantum Scattering Intensity Formula
-At any Q and for each band ωᵢ = εᵢ(Q), with S = S(Q,ωᵢ):
-
-  Intensity(Q,ω) = ∑ᵢ δ(ω-ωᵢ) ∑_ij (I - Q⊗Q){i,j} S{i,j}
-                              
-                              (i,j = Sx,Sy,Sz)
-
-BandStructure information (ωᵢ and intensity) reported for each band
-

The function intensities_bands uses linear spin wave theory to calculate both the dispersion and intensity data for the provided path.

disp, intensity = intensities_bands(swt, path, formula);

These can be plotted in GLMakie.

fig = Figure()
-ax = Axis(fig[1,1]; xlabel="Momentum (r.l.u.)", ylabel="Energy (meV)", xticks, xticklabelrotation=π/6)
-ylims!(ax, 0.0, 7.5)
-xlims!(ax, 1, size(disp, 1))
-colorrange = extrema(intensity)
-for i in axes(disp, 2)
-    lines!(ax, 1:length(disp[:,i]), disp[:,i]; color=intensity[:,i], colorrange)
-end
-fig
Example block output

To make comparisons with inelastic neutron scattering (INS) data, it is helpful to employ an empirical broadening kernel, e.g., a lorentzian.

γ = 0.15 # width in meV
-broadened_formula = intensity_formula(swt, :perp; kernel=lorentzian(γ))
Quantum Scattering Intensity Formula
-At any (Q,ω), with S = S(Q,ωᵢ):
-
-  Intensity(Q,ω) = ∑ᵢ Kernel(ω-ωᵢ) ∑_ij (I - Q⊗Q){i,j} S{i,j}
-                                   
-                                   (i,j = Sx,Sy,Sz)
-
-Intensity(ω) reported
-

The intensities_broadened function requires an energy range in addition to the $𝐪$-space path.

energies = collect(0:0.01:10)  # 0 < ω < 10 (meV).
-is1 = intensities_broadened(swt, path, energies, broadened_formula);

A real FeI₂ sample will exhibit competing magnetic domains associated with spontaneous symmetry breaking of the 6-fold rotational symmetry of the triangular lattice. Note that the wavevectors $𝐪$ and $-𝐪$ are equivalent in the structure factor, which leaves three distinct domain orientations, which are related by 120° rotations about the $ẑ$-axis. Rather than rotating the spin configuration directly, on can rotate the $𝐪$-space path. Below, we use rotation_in_rlu to average the intensities over all three possible orientations.

R = rotation_in_rlu(cryst, [0, 0, 1], 2π/3)
-is2 = intensities_broadened(swt, [R*q for q in path], energies, broadened_formula)
-is3 = intensities_broadened(swt, [R*R*q for q in path], energies, broadened_formula)
-is_averaged = (is1 + is2 + is3) / 3
-
-fig = Figure()
-ax = Axis(fig[1,1]; xlabel="Momentum (r.l.u.)", ylabel="Energy (meV)", xticks, xticklabelrotation=π/6)
-heatmap!(ax, 1:size(is_averaged, 1), energies, is_averaged)
-fig
Example block output

This result can be directly compared to experimental neutron scattering data from Bai et al.

(The publication figure accidentally used a non-standard coordinate system to label the wave vectors.)

To get this agreement, the use of SU(3) coherent states is essential. In other words, we needed a theory of multi-flavored bosons. The lower band has large quadrupolar character, and arises from the strong easy-axis anisotropy of FeI₂. By setting mode = :SUN, the calculation captures this coupled dipole-quadrupole dynamics.

An interesting exercise is to repeat the same study, but using mode = :dipole instead of :SUN. That alternative choice would constrain the coherent state dynamics to the space of dipoles only.

The full dynamical spin structure factor (DSSF) can be retrieved as a $3×3$ matrix with the dssf function, for a given path of $𝐪$-vectors.

disp, is = dssf(swt, path);

The first output disp is identical to that obtained from dispersion. The second output is contains a list of $3×3$ matrix of intensities. For example, is[q,n][2,3] yields the $(ŷ,ẑ)$ component of the structure factor intensity for nth mode at the qth wavevector in the path.

What's next?

The multi-boson linear spin wave theory, applied above, can be understood as the quantization of a certain generalization of the Landau-Lifshitz spin dynamics. Rather than dipoles, this dynamics takes places on the space of SU(N) coherent states.

The full SU(N) coherent state dynamics, with appropriate quantum correction factors, can be useful to model finite temperature scattering data. In particular, it captures certain anharmonic effects due to thermal fluctuations. This is the subject of our FeI₂ at Finite Temperature tutorial.

The classical dynamics is also a good starting point to study non-equilibrium phenomena. Empirical noise and damping terms can be used to model coupling to a thermal bath. This yields a Langevin dynamics of SU(N) coherent states. Our CP² Skyrmion Quench tutorial shows how this dynamics gives rise to the formation of novel topological defects in a temperature quench.

Relative to LSWT calculations, it can take much more time to estimate $\mathcal{S}(𝐪,ω)$ intensities using classical dynamics simulation. See the SunnyTutorials notebooks for examples of "production-scale" simulations.

diff --git a/dev/examples/ising2d.html b/dev/examples/ising2d.html deleted file mode 100644 index 546fde37c..000000000 --- a/dev/examples/ising2d.html +++ /dev/null @@ -1,17 +0,0 @@ - -Classical Ising model · Sunny documentation
GitHub

Download this example as Jupyter notebook or Julia script.

Classical Ising model

This tutorial illustrates simulation of the classical 2D Ising model.

using Sunny, GLMakie

Sunny expects a 3D Crystal unit cell. To model a square lattice, we create an orthogonal unit cell where the $z$-spacing is distinct from the $x$ and $y$ spacing.

a = 1
-latvecs = lattice_vectors(a,a,10a,90,90,90)
-crystal = Crystal(latvecs, [[0,0,0]])
Crystal
-Spacegroup 'P 4/m m m' (123)
-Lattice params a=1, b=1, c=10, α=90°, β=90°, γ=90°
-Cell volume 10
-Wyckoff 1a (point group '4/mmm'):
-   1. [0, 0, 0]
-

Create a System of spins with linear size L in the $x$ and $y$ directions, and only one layer in the $z$ direction. The option :dipole means that the system will store Heisenberg spins, as opposed to SU($N$) coherent states. Polarize the initial spin configuration using polarize_spins!. Following the Ising convention, we will restrict these spins to the $z$-axis and give them magnitude $S=1$.

By default, Sunny uses physical units, e.g. magnetic field in tesla. Here we specify an alternative Units system, so that the Zeeman coupling between the spin dipole $𝐬$ and an external field $𝐁$ has the dimensionless form $-𝐁⋅𝐬$.

L = 128
-sys = System(crystal, (L,L,1), [SpinInfo(1, S=1, g=1)], :dipole, units=Units.theory, seed=0)
-polarize_spins!(sys, (0,0,1))

Use set_exchange! to include a ferromagnetic Heisenberg interaction along nearest-neighbor bonds. The Bond below connects two spins displaced by one lattice constant in the $x$-direction. This interaction will be propagated to all nearest-neighbors bonds in the system, consistent with the symmetries of the square lattice.

set_exchange!(sys, -1.0, Bond(1,1,(1,0,0)))

If an external field is desired, it can be set using set_external_field!.

B = 0
-set_external_field!(sys, (0,0,B))

The critical temperature for the Ising model is known analytically.

Tc = 2/log(1+√2)
2.269185314213022

Use a LocalSampler to perform nsweeps Monte Carlo sweeps. A sweep consists of, on average, one trial update per spin in the system. Each proposed update is accepted or rejected according to the Metropolis acceptance probability. As its name suggests, the propose_flip function will only propose pure spin flips, $𝐬 \rightarrow -𝐬$.

nsweeps = 4000
-sampler = LocalSampler(kT=Tc, propose=propose_flip)
-for i in 1:nsweeps
-    step!(sys, sampler)
-end

Plot the Ising spins by extracting the $z$-component of the dipoles

heatmap(reshape([s.z for s in sys.dipoles], (L,L)))
Example block output
diff --git a/dev/examples/out_of_equilibrium.html b/dev/examples/out_of_equilibrium.html deleted file mode 100644 index c6e1ee9e1..000000000 --- a/dev/examples/out_of_equilibrium.html +++ /dev/null @@ -1,55 +0,0 @@ - -CP² Skyrmion Quench · Sunny documentation
GitHub

Download this example as Jupyter notebook or Julia script.

CP² Skyrmion Quench

This example demonstrates Sunny's ability to simulate the out-of-equilibrium dynamics of generalized spin systems. We will implement the model Hamiltonian of Zhang et al., Nature Communications 14, 3626 (2023), which supports a novel type of topological defect, a CP² skyrmion, that involves both the dipolar and quadrupolar parts of a quantum spin.

Beginning from an initial high-temperature state, a disordered gas of CP² skyrmions can be formed by rapidly quenching to low temperature. To model the coupled dynamics of dipoles and quadrupoles, Sunny uses a recently developed generalization of the Landau-Lifshitz spin dynamics, Dahlbom et al., Phys. Rev. B 106, 235154 (2022).

using Sunny, GLMakie

The Hamiltonian we will implement,

\[\mathcal{H} = \sum_{\langle i,j \rangle} J_{ij}( \hat{S}_i^x \hat{S}_j^x + \hat{S}_i^y \hat{S}_j^y + \Delta\hat{S}_i^z \hat{S}_j^z) - h\sum_{i}\hat{S}_i^z + D\sum_{i}(\hat{S}_i^z)^2\]

contains competing ferromagnetic nearest-neightbor and antiferromagnetic next-nearest-neighbor exchange terms on a triangular lattice. Both exchanges exhibit anisotropy on the z-term. Additionally, there is an external magnetic field, $h$, and easy-plane single-ion anisotropy, $D > 0$. We begin by implementing the Crystal.

lat_vecs = lattice_vectors(1.0, 1.0, 2.0, 90, 90, 120)
-basis_vecs = [[0,0,0]]
-cryst = Crystal(lat_vecs, basis_vecs)
Crystal
-Spacegroup 'P 6/m m m' (191)
-Lattice params a=1, b=1, c=2, α=90°, β=90°, γ=120°
-Cell volume 1.732
-Wyckoff 1a (point group '6/mmm'):
-   1. [0, 0, 0]
-

The crystal is then used to create a spin System. All parameters in this model system are dimensionless, so we select "theory" units and set the g-factor to one.

L = 40
-dims = (L, L, 1)
-sys = System(cryst, dims, [SpinInfo(1, S=1, g=1)], :SUN; seed=101, units=Units.theory)
System [SU(3)]
-Lattice (40×40×1)×1
-Energy per site 0
-

We proceed to implement each term of the Hamiltonian, selecting our parameters so that the system occupies a region of the phase diagram that supports skyrmions. The exchange interactions are set as follows.

J1 = -1           # Nearest-neighbor ferromagnetic
-J2 = (2.0/(1+√5)) # Tune competing exchange to set skyrmion scale length
-Δ = 2.6           # Exchange anisotropy
-
-ex1 = J1 * [1.0 0.0 0.0;
-            0.0 1.0 0.0;
-            0.0 0.0 Δ]
-ex2 = J2 * [1.0 0.0 0.0;
-            0.0 1.0 0.0;
-            0.0 0.0 Δ]
-set_exchange!(sys, ex1, Bond(1, 1, [1, 0, 0]))
-set_exchange!(sys, ex2, Bond(1, 1, [1, 2, 0]))

Next we add the external field,

h = 15.5
-field = set_external_field!(sys, [0.0 0.0 h])

and finally an easy-plane single-ion anisotropy,

D = 19.0
-set_onsite_coupling!(sys, S -> D*S[3]^2, 1)

Initialize system to an infinite temperature (fully randomized) initial condition.

randomize_spins!(sys)

We are now ready to simulate the quenching process using a generalized Langevin spin dynamics. If we were working with spin dipoles only, then Langevin dynamics would be the usual Landau-Lifshitz spin dynamics, augmented with damping and noise terms. In the present study, we are instead working with quantum spin-1 (an ($N=3$)-level system that includes both dipoles and quadrupoles). Here, Langevin captures the coupled dipole-quadrupole dynamics using the formalism of SU($N$) coherent states.

Selecting kT = 0 in the Langevin dynamics will effective disable the noise term. Then the parameter λ effectively determines the damping time-scale.

Δt = 0.2/D  # Integration time step (inverse meV). Typically this will be
-            # inversely proportional to the largest energy scale in the
-            # system. We can use a fairly large time-step here because
-            # accuracy isn't critical.
-kT = 0      # Target equilibrium temperature (meV)
-λ = 0.1     # Magnitude of coupling to thermal bath (dimensionless)
-integrator = Langevin(Δt; kT, λ)
Langevin(0.010526315789473684, 0.1, 0.0)

Finally we run the dynamics. We will record the state of the system at three different times during the quenching process by copying the coherents field of the System.

τs = [4., 16, 256]  # Times to record snapshots
-frames = []         # Empty array to store snapshots
-for i in eachindex(τs)
-    dur = i == 1 ? τs[1] : τs[i] - τs[i-1] # Determine the length of time to simulate
-    numsteps = round(Int, dur/Δt)
-    for _ in 1:numsteps                    # Perform the integration
-        step!(sys, integrator)
-    end
-    push!(frames, copy(sys.coherents))     # Save a snapshot spin configuration
-end

To visualize the state of the system contained in each snapshot, we will calculate and plot the skyrmion density on each plaquette of our lattice. The function plot_triangular_plaquettes is not part of the core Sunny package, but rather something you could define yourself. We are using the definition in plotting2d.jl from the Sunny examples/extra directory.

include(pkgdir(Sunny, "examples", "extra", "plotting2d.jl"))
-
-function sun_berry_curvature(z₁, z₂, z₃)
-    z₁, z₂, z₃ = normalize.((z₁, z₂, z₃))
-    n₁ = z₁ ⋅ z₂
-    n₂ = z₂ ⋅ z₃
-    n₃ = z₃ ⋅ z₁
-    return angle(n₁ * n₂ * n₃)
-end
-
-plot_triangular_plaquettes(sun_berry_curvature, frames; resolution=(1800,600),
-    offset_spacing=10, texts = ["\tt = "*string(τ) for τ in τs], text_offset = (0.0, 6.0)
-)
Example block output

The times are given in $\hbar/|J_1|$. The white background corresponds to a quantum paramagnetic state, where the local spin exhibits a strong quadrupole moment and little or no dipole moment. Observe that the process has generated a number of well-formed skyrmions of both positive (red) and negative (blue) charge in addition to a number of other metastable spin configurations. A full-sized version of this figure is available in Dahlbom et al..

diff --git a/dev/examples/powder_averaging-07908bf2.png b/dev/examples/powder_averaging-07908bf2.png deleted file mode 100644 index c71115abac72c6b32858f52ea9e490371ed39e5e..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 96671 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

%wv;MHUIB&oSZtz$*D*K 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

iEOm}9&#FKL*!rDHwT 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�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 diff --git a/dev/examples/powder_averaging-efca91b4.png b/dev/examples/powder_averaging-efca91b4.png deleted file mode 100644 index a585b6f3248f678cb77653e45da62534eddb73b5..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 96159 zcmb?@dtA)v`@YXg2c^_Zl0(LH9JN%eP^6g7I!svY+EjAdMdVbZKGh@*sp%XF>40@e zc5UrO8lrMq+ge(E5ye_jvQ(sg*ZsUFyZin9{`|eRRZTPR_w(HMbzj$Y-_KN%uea;4 zp`(Tl8Z>B_yW3pJph1HLg9d%FNc|H$qR-bi$0wB)PV<}w4LY5o*&93r-~VTW#MODw z$s1#y;TyqHH_5y~gSMIt8uVZ3ph55O(0~6JG-#9cph15I4H`5fXV4&nb^CwxbHGyv zxzBZ)AMu~I>Up(q);M*&Z{Jd})^m>Y9|_we!IQo$Y8#?R3SDZva$&qcbK@v&p~A0O z5HHxfVEEivA^+CZAfGswA>O0Ja+l%)$#-*vN8fJ$kiWt+y!)QRm0R!nPkn!5Q~sSd z{ZTjEr;X80yx6>M+TxqJ^ohP(kT-qc!Q21;9<2B_rtfJ?-(Mw;A1>RSe`R0w+TN#x z$L>8w+vh><`<@dI-koslj(6E*b{DT%}Mqf%wzs? zjrof%;Mi&G*m>CT-Qk!IcVa$#Q}yU-JV_maKnlKHGxMU%Ea8x|HZcwjM&x!bziRye-b>F>~K-}c}=mh%0I zoB8M7{{D?)-($xtmUJihM0cj2s_d-)>HeFO zUFX`jY}os$+KC2Yz08ZvL(=B9u8Z)C`qTfwyYubu z&+9}z9K5*g+RUg|yO#83$Mj@7zCYu*?TY>VSNUC)Pty|>dLOr$=s3Mi_pFn7)yep|X~Nb^!&8M~`p&CPHGD<0wqmR_ zal}cprp4t+rB1Ua>P=P89@=G~J?W@*Z&m;3FZWlZ_jjlCcgK$Fj@60jzF5+r(Ot8o zw}yq_eO3SaA1YfvjjBO>?jPt*I`Ht@s6Xb6d)Ix%@y6KNqEPX|P!AbjWa}muw$7Cc zFDBvE89Z@)k`sNBdAZA(F;bx#9KY`9x}&8|cSXmgo(cQZ z-{b$pD-+uccB~kF{?V7`Tfe;f2r;2-+eJUN>+3*@o^5<|6+zyzy>02Z_msA*A1V`0 zb?=?@7?D_^y~WsHQn=qj;>|atPldGt%QB&Tokw{_Mro{8@L*B1M52&otP?fP-r=hl z>!#t)z8x!3;0aDSX?jz!&N&Med3AXS@6+*J^QPV(?%aKeWjy~O`uV;Gy-#k&^u3O% zas1HWc&@YFGHh$ZzG=O7k?P@UWy1I->G9e*sh$Z!%V3X%3Yk}ez9?8+tWc%P`-YnG zbB9{8I|)s_+%^93<>=bsYsG<^%a)XDh?<@DS0sMEWc!=3?Gabn`}^8s+Pk9LyP|G( zMLpsj=&p60)%oH<-;1#A&%d1RFsw{yH(o5`8-|LfrsgTUxy^mtrKmZ=HXJDwGamTgRes4SV)4yHbQYC1TyQrqqm%F*nBKt2Vly zbU8U^b6Q@gV}*8r5*H$6B(b}u18k4e3Z-}uVay9PbyyJoS@VrTsq4dQ%|lG=>o(P@ z+M14blZ!-Uv2FZ?p%eH48pyuvI9>w8=cIkWL)=%HzT8iDlnPCc*A8D;C}ofU4o>IpkFxbcr`&F*PJoq1DJhqXw;MU6fu=P)!6JRdJb(4!?R_gc+<>3Vo1 zQ9xOrXlgpfXo#p;WWQmW!xU_A&O)Sd{zp6@I$TsWxJA(`l`GZToJQZFYPpN#4t-xo zaA__wvkVtiXf)22E%qS9;TnkQT4(Goa~;ZP(?H(DJ4z2^tlJX=8pf~81vFSU$4=9YN{x5y|Q4D zkJW680QP%#!ot77@*z}R$H^l?y-Y8ELPgR#HFm`f(fzY$UHANpxfidB7q&*jfH})<4$aAw)@{5SX&NILkA!pT)^zrh+*>6iU_BKUr5kt75Rowl+F^ zZ1W73U>U7}%PC5)%|wZsfpp===@}hIsI*-@?)vOlHyNQ8RcMRCMFH}>Q1M#lg#)+y zxWDW)ivK^V3tuAbGOb`oW!bUZk7Xsd6*ZFW@O9_ix}p}d(7_e+?}9*;_!+oFv!pCN zGb? z!B(GT_O1^AMZC)4F4|TKAUJtI4sbz;*Sd&}pd1wB^bHXewW^)vwcz|h+V*iN!v#Rg zFopW_FVovRRQz{h&6OdUhdn3}kI)7V?;K9GX%ssd)ajsNSP1dP<|{HN4k#~EEr|l_ zK!psbBlUI8TrYmwhKRyYaiB|?FguMSZy{xv?TAAi zNaSt0GHSRcql0+5HU*26C=R06QkC$63iWE3(3bU+v+b2h318tHtjzSm6<@Ex<3~pSewDG7z_=O z=Mn5^`#=N(_&~LSKJX9&3nGK{WA}*bOCOJjU%}AcRPzuOO>gbbjR}!jWwFX^6AKKi zVW3L?Eo`{3H!V_C#3Bz=v0EHn_gQC1S|+hDB0PQn^f7C_PtGCy(9S(Zk^phrR1ytY z288`@AhAjmm^#cLOe{`Bg2E#vGMswWtqVCkIq~9~x({^%5F%qNiWB8SxqB)ccd#ej zgykIHi3#(x8|)v89=)I+6%rv&FH3!OekhQjY*ReA@un3AT)( z*~%E87)+_&O6IQho~nL_F;IE_&ag_!;iZv^f!`mg=PzVi=)ImM)apbA2L{HWN#1n{5`Q!(BW?1XB+FFb*IL;!Oy$(*07w8~zg^0~mlE zhgm*sma^+ORWM{3CU0GN2FFkTS|x&}yas3=IRvU=`4#iI+v1Udz;ekZZL}Nj4{j+E z_$&JWiUG)!B$AlfUAEYjLnByS8Ngf)|KNG-^Iy;{pUf2)s~qfSapIVhE*=z>;VZO# z(iSIzNsoi2SyO}(HeXm++Z;1owQ&-<0CEk7YUikvc({JbFeWBB#g^!Y3Z7ZY7v&kp zrTX|zl`P;oQEr+(RtVb!cPaG$hs@BvmBfeWk^lP0Hsl6n8B_@HlN~>|)Ql&pZGvx^ zSvRltuo>zBt(iU+N_R#=NXQsTv0afdrF1fYQoUlee-|}U)@IJt5?sUE^ozG^VG4+C z$QU&Uwg~*ogv!Q{%7eIMs(L(=P^x`~RNxJA1sg(XBk^R60IR}c;?Hu&`T=aJ`Ia0t z!eMusR_AbX4&ZU>NhsOa1Cwb^Y~Zht!;WL^|JahgvfP+U0lXL|;mVrMFDHS~I@D2g zLfhI+=;1!FhBka`_*jk|mC#23K)395=upVoP)xv;usG_(WCI~Vj|l;LEc8iYKt@Hw zL7nt6`V75+7UJ>`U_gY%g1bt6LrZ+&teAi7EK`qfGx$fnTLy~*hnD%@^-^a z8X6DG+;2H?$F*!%6Q&WEX+;3H(L@ zIA{^)8vnshFsIb~bW4psMx-(nC)g_1 zF^nF-`+#jsA@_|nNt}^ zC+C4#2g^8t17wDEEzt~-9mR)4i9`x|Gq3ilw@1WZh=iRvYvYdBg1gBVp=W0=7)T}2 ziW?b)0i3h;06zt0xCV{VMzqEJ*XUY*(=EffURo*YnAl{eB?>Sma9T(f6tb{Miq*q( za;T=15zT}WSCg(0!!XhTM9|xm(Kn2aNKXBQDSI(J;~L;d^h1-Tp*JU17nP;|1DBwL zlg7t6W6ODRDg#u-0O?Z=FuH{S2A`7MVE0iP6wBsAb()?SW>8AW>aM99i@uAXU+6a7 zX1|3w5M+yyTPU2En+7)=5;be2+oz7Nv{DG{bcvvuTx6DF%?_rRka67=T80iuI*bFB zIo^9ypwVp%1h5W)F&GRNpKi5Jl#aDC7)!gc^0Gm$8p1#(cgB!zb!MS>@dq=;)IO>Wi zzv2uf!?IZt&g&fBGDAU20-)cfCZlAt(>%dC6nUZ^Bw7_KNq3MEyEKZ(PfbmQ5oe_j zkSN_hwRuuequ?XbDTb&(>|k)C05D@NibjKh6U$<~>TYAK7a$kL^F`qTy7vy>(0E+* zu1LTDgc|)jXh(^SMi1nXRn=y+ujXFpbqQNEM_ZM;FIC9VB@J(>n|G6&TVbfiOd+S; z$_5NbLc~$OL;&ci+xQS3#F!)g01Z2H9jBK9AQb2a?U1+c4h!!dSG$R3ksRXrksi+A zEuc;5;{Knl35$wn9p>|>O`7o@hf7S^%jVc<_Q`WR40U97W3>RWK(qy78AwX!Q+`Df z1s6jFCHVhQNlemdx`m-Bp3D>$R$vb1hiqaExY?1-pRT+hXPPZLe|DDJs}IyWEZ%B? zzjHYi7KP()hyGSGI}N=y^-Z82AQO{ZpO>?zst-sx=VdTPWr~3=!fm=A!W|xx8eRbA zs!wXhp#|G+{`NlGa9^byd@WZ3fJ`0!Yu+gY$IojGJj&K0eiqmmP37}Z;K>YZ1lz5 z*+ikp?qUz4xW$PMQm$mtk?zBI=_rnjARipqxf?Vcz%#%1WtHb)l!wbOKB!v9`+JHy zzkF21tO`fQdmKNp#-&w=X%Ce@$GxN!l9oPrN`Ep1%r3&lqsIVyfo-9=o22>`m?klq zgK6}5IeV@1S|P_Y%odQ3*;q&hpOPdd1F>F4O(! z9~)rCf{Y!Qk?kB(PISc$lu(f1XDpwvrQKz2Ul+`V`nnj)!m*pj^P$(Q`dNrt#_zYd zX<@!&1s*nX9vNDNsE2x}&%ts(7F5&RMe=>>_I1%@2OuI26M;S+4w|q4t`*T<@sgbw z&gzt>^y1`Yh2Cr&7d?2F?%0#=Ac4lrgTMP691D7p1XU^|UgLkJC6 zZOd@gig;g0C;-4&ke1mbOVCP5FlJ}?FR7GCGfie-YhJeCr1aM(vOS+7ERZi$h z{9x*urVlDdFN9n{p{SFidW3ap3a}_!a@XC+8K)%7R|MmbsX{waow+Wu0mAsz_RcHu z{s8X102`ke<~ZP%4BvdeLWiXu^^+GWJVxe2f_)MIJJLj|DXqF`0+7sK96~W zL+*VC=*+*jS?BeFS?_M8M7J1^Yc@37vG9Jak}iyznf z@Ic?Q1AV{xeE9X=gTBq@AJO^sgYL_AoeTO}eEOv3F0!WF)q-s5nmMV#p*52L^oCNs z`pGDIUK-Vf`BSUS3aB5_Nhbom}WRFRKNk~ zu;ct6V&4DI9^LiRlKyvhUN0+YcosD)=K7teVTt`HV%(RQ6T6MahKbvNXE(T176U|P z|Ds42IocIhbFDHbMyRo@*MizppG!OdDdF1tITqnF@$L(}A);y0hhHXr_{*pNubaKs zZVtMcKNImc*tRa!Dj+TB_U3Wt?l{<{`y>gRHH&?}dg7EF=^KA!{QT=uo1Y8(W}1D{ zT>SK^t8nfEmp}isJ2OS6YiHCqAAab6+urv-Rqt`3ZL>bij+1%@o4ch7f;IF^+)}Ic zLIuql!MSZJh7Ml~o#IpsYg;7UV=eVeq6*w1{Nx=*%`@wFDZJ$Zaa=~&M2GQ}7Ex+q zMUl`+rXuo8?VM%);9|@>pZ;fb*xnD|Jd5eO+21p+|8Wd^FGl|>$G$5uJ(K!d9eWe| zFO-B?wn<$R@&ve(hG(i^uwiYGVeM=MuiiGbY_gnN)Lo5i#TH+aC|3{H}C znb64$9KliG*x|f`e*c~ymsjMt6!sC_r9^)A_N0@a8lT& zVijCOyi@6-K_%P|O%@NeADr7JEyA^W%oIh=5%W_!=dlcYsXl3fUjFdF`6dp>+N610 ztXw1JM|>6G*Qk+=G$Ck<>b)0HkiLBt)A8&Fo{7VFhY8rGlY%f1t3{i4IApbKh0sYg zWrChb?QAp82*qqOY$MDswX>k3phJoaixqZ$c;4cn?YjBHjr5~6n>Chcg!yNc`u7br zKM5>8`)vFZWSm`psU=1IOt8-OPS$d{c^UUuLlV6b zkTH>+cw)Etm+7qn%VR?Z7hc=uTDk9udUjvF9Q zbYbiyc1&$`xWGJIs1{x}2K)17ked4vNNtjLNCoMpxUm<|6@JuB-g%@`DiGHnuHTkn zp5aN9C&>aEtKIqBU_?si=hJ%rdL~I-Cn9*nX=MQ; zEU>XsbFZvUX_BGe$c9U-}Iipe&TOd9A@cbOkq8lgHE3}8|nXob=WfImO*Mu4hhvrKE^Jd-x;^axTJ23mEC z^t&rc87hg^q(WET%)EC5Lnbx{{Lk-xY@s(%Un3?V-6v+<0E>e-5HYsF>8bIpvjI?9 zhHEC!N}EJTv#M`k{b08I;e}RC^*mKcRvk~_9qE@U3?_1*ymB$UOM$(s@nA^+N*NJU zcz0_fsK?9NThH}s9*~vu}O~4wRuGd zf*2fXg?(4d4>TyW8Vuyx`57%JY=cS$DEY}uFSN{mVrE{Mf1y=6!Y%=uL4QaJc*Hsk zM5)47NowaV=ZIhGO2*BPNGauQj+2@aoRmmHh}Euw%fJU$=hl1E#?XY#mT6@rf$-;I zr7VMzdRquTlN+xX8h%c%QMT(aRc&PX!mVyjZheK`=^9gW%!R8JV z9LD$lER)))Q<{I`GopZsIjMq=sCEz$L#x4tZV`$W@jwBhctEG^x`p&=B8rq!|II{8 z*nP#6)Fhw}OyZ>QMr9Bq+JiwhD~dX#9arX?u)wd;(EGSgJtVq?m=$rS8kL$Niij?; zfc-L35l)Xp*qJ2IVB(Paq7I{F=HMRihO}BjP$zZ=GINQ2Sz2-EIxJIEz=H$An~KQtVa%drl25%KF>RojaB>Znsl0m?QDgNFOY zh#X`GV=*(7tUT7s#0qJW3z{XVbkA{f8Q3D6yKl%ywe*|a%@3SE(J@x)Is`m!#jFUn z2x-E8!%I0K9|iAk5Fv?boGSp1s#K2sq10ij)S3wn;H%AM*58RML*7)X`Uy2*kNo zYT>Tug-Ae_Ao%GX6@c2zR!)cku2JM&>XO2!6|H_u0#MpA0y!kTwnZaY0~L+zl4d{~ zq@K%wUgg#+T_fkqQD}=NND6yH6c63aV}4SY53nU_2;vPv;xuWnhCSImHA%~Ccr<+8 zTwf%N&qL@5a~cwmB(i`Db{r|=LHF4G>Wj$C#fOEIA!G#Riy%aMLYIB>K6MF*HtNgf zNb{H}$Va6s@IbbK5j1&`f8BZ)`gr_(goh zawSYh^%^<^(|tj|uz77>xVGc|jw1v*n7_W_AuvMl!HQk@kH-uUHp~FVd?3pAu1L>l zLCb6iAh=^p8+0%jJbJZ71MkR1y=mwb(k08V`$CY4XJc;d!z(}<;2of9+tWw9NyO#d zy>CSRmdQ@ zv#6RUla6w16-!0k`6Ed&CD#+y0}nZ7v2wR>mGm@&M;Nq=V!h5Mbr?Z|$|1GTUuc+H z&o>EA^P=7j9-2*k1Z)JC$|M4`L5pVRkRFYS)B9^DfgVFk8TP~D>aKO4I-LR!;z6hM{wg~cfiVCHTNouemSS_`B z8^~;MZtow8A_0L~FOZphSpBFkV>=4deX5RjFhQJ4BnUbVGFgG_J*~}t9Bj=Im z1f-eVV_)|Zg$X1T;cyOM4&|Bw^P*%d*VVG$9 z)_t1x9I5DqhKp)LODd0`If(xumk1p2rWOjD-VBex3=`P)ls*Byi);+6GXaeQI%jIl z!^@C$71)tdC_8G#%u}8O;YcmZxHBZzDxp**SGoDc6W|;xk1U>G&l5=|4#{;m_-8Dw^2+Rb$$hgZ9>M|JqL)?o9B##1UJcIc$^pBh15AOf#a;7CrFjDC z@X&#ZknqZMp9lWkX3CDL1#K5xM0pd3AX>6Z_so(k3IstTV}_h(8@{iP@PFAHgH1g!%a?R z*(9+OGw%#5taOb)J4kGSW`mkBAB*gI??zE}Jx?ZGRyw)S5K0j7RXLyfFcWm=WS!74 z^KenLv%Sw1uf1n&|FYR0UV%ditzkCt5G@0;H^%L5g)y2GA-=7H){%a78l~rzVr_IE z?^FOb1qI#iHxY-0azXloFB;)|M7DQDw&hdgur&_jty(uRmjN8YHN$V2K&#LNx&<)m zKNu(NQYTBL>~>HUSCJ^tRC?=X{9Sx~Dm@;0|p7Q~u3jip$ zj{UXC+&Xw@-!TN3Yj%~m4;7IWPxYc4N#qX)jKOTMZ6#Q*2}Tdwq26SZ&h+DDG;se~vuC#Dc!i#7vN&?=ACZJx*w;|Gz?E1<9b4kX^x*K=)?- zKT`30Y-q@4VgUJ zq6!Z{q_a?+_0J*VZ5er;1)%pbUX~EnOF~ssg#Q5zP#y(NnC?1^3x*L&hgu-KnsvhD z3$PYaFBEW=qj8K&UtF(Y53g#dxox*Vs^cNAQ)|7^IT^_t71Ni0fx7PSy9L;Z5>t zxiL^z1*MY%hN^*3_*B7hWa-Gc=-oeskf1+U1PgNrqk5wSo54JF-izv=Q{b?me?f_8 z28mF@>3m5?0n~}>yBX222-Z<5xg~AVn>7+OlipGNx%b2jA+N%C3#|#!;L!*p&>#zp z25j7a3^Inl0nMV@r`d)WKA}w-h68Zc*^w@_f#M?eafWCSu`&;ST`q;ABt4FkphwIU4kz@!O(m%bs26v(02 zl))v1KaP)&*YVC8jj50rRrgnBIsk^HjJ`VeB^98&4oy5JTIl9j@zJ1(Rqr;emBw~g z0ima2v39<1p_Q7C1<^JVNVsR1M*!ehXo5j{Plgh+A~aRtqHhu&ID;S>2@_24orCd|zk8Bh)7+}JhDqYz$m6n7L;^}k3C?2safj^F5oyDV+u|jOQX%*8P z-(fJTn-{Osx4ZWeCTHM?u|4%viT(TVpk2(P_`2C_q)MI}tRYxJizQVd;;FPCSHVq# zF{)#>#5Mp?eu>NA&`FiGUZ~>%CRl;`1pfe;7^s0!2h1yaImjP3ZG(>lPgj*+WP)2w z+|OowN-I!tI;uH-U1v3O#IOR88bAvr>5Xtk`L4Cv(z1uy04u~H)t*QQOab>T&8wyc zf|O(u%qZjHxTc;@GxEZZ!jblv{a>p>M2`$~%Bgke+9nNU_K?V)Mi$DE5pzXI?dWj? zzd38I>{?*AW-FjlSeN#!oTlyt6~-u0lx9HvbC471VLAv^fI%bbjU0#x-HOOLkA^YL zVk}->hCW@WmO>m&#d=DUr4cPGEI%p+8butAavxY3dVeD{hX~lBfs&ZBws!)MH)k!7 zb~=itEG%9eW314QUa+=yY{huCG9KnlAOQ&mpY^-qv;yHi*c2aiNgF|{prOZV6n8{z zMB(=nC{87QwMAKBC%?~jG6J zg*d8{nmRmdX=s-yC5=r4F@s%OYcQ+)bW`dixD{$O4B+U!S}f@_00`LAMBHZ991m#b z*0zWNeDoBU`(nHf)D1*Zg=IwzY;q8Gq9 zff=@pR5p|F8S$>eP~x$86ialaHU%p#1yUnYFm}UI!AapbgTk1$#t^%!_+*En z2^lRgVr?G!XXr_%k(0KOK8^V>O~%GCif7(}&Z3-X9!{rBKqQ@i{43`mN^AnCfZ;BJ zc;VFS@0{Pa!g1OXcH)tWwjY5cdj4JS0~Ii6w;6mEdln=H-v`iKUx`ib8Dv1P z3z%A*fnh{U^8-el>W<$Lb`Wm}4eKvJO3r=P)S4$nbr`ffDD8EutrGWX_xw=11V}Zv zC-PZhwFCkwgvqBPb8e92xB-!cMnbxY0L}oGG`7&kc#3Ny@M#ZK z)paGN+MmjeN141}Qqu(YhAo z;T7&amyvVH#LT9SEycjJOWk;Pj#R@d=o6k-tj2CE&p;!+DLvCy=F9jMU` z%!`-KSRRxnvZ))bJ~>CV-*NrqmHax#w49d1>aWUXSI!>EcJPU@8FK7WXD<+72!gPVTQtjrcmxtFK?&>T7l4b=j=Af;`QH99!|N zl+1z>3-4>O({sJAB|Xd8V~Bgd)I~-&7RMSQ6$NgWT)%=mcqks*5&IQ2A`qB4k+f>bRxGW4t zxRwXa7-ynFd+4`(<>Q1p&?vs3Qq1ZAC1Cs{DJ1xCL}HKDYfY~Q)lmko&n0&8A4I;B zJvx)v)#Pwotwt|C`whP)dLqBQD|z45t-iaT;ibr`7Ej*9;FPZ<-Fe*ku3h%g)z#_=%q92$Wfg_=>m|%kBovx0cN-d-KQ8~pCt*=n`}K6)vW6> za{W#B$Hhz2P-BrNsOpp4y*djn?c64PHc&V!>DI##6&3%B$o7SuVXk;JB}&x=wdaNE z$MAK$j$(pB6g71m4 zM$V_*Q2iK-Z@K!8Ip;U#sq^~3T-IBU&EahbVKr3YirqY;d(g5_m&HIDLbkO#B(`8JoH^HQ0a%TZR!&At@JCift%8*!rt4a8+gf;C8AF z7dGzBi9=dGpWEA(wC&O^scsihG2M_5Q+=Fox%}c{YlC97Ymc}3f(L3E&iXq9o@{bB zsaEsLj7iUpEwV=PLq>_Pu}6O-<0B-dfA;B;^6A!U;AX6}xO%j@v6uC*YZr)Mi79vJ zP8v$oN&yC!cI^}~LfFVaq}Z9V@n;KFcezOyw;^OGH*Fi3fR$4qc#!ZMG|C@Wpu~TK z+GOk4X9P8D{bBNmSv}da3ES99gLU#MY$T-UuJ!0Aagjk=SLQuJI*fkEd$j(ZDE}w~;G<-AYy%s3%FEYVtl#f1Db zJ+v-Be^l{gUdpf~i9v4-*e*`%bqi5+*W${BJdc%oNIj=9Wr?knxr)1Mev zKS-{=zU9FAw6uNg=iW;^*7jXrvBbCc(NCvD(aoHN|&9P-di(_>I94qPyFA7<7ry2vi{_SWcj& zO_E{Go@cNZ7xw222Kg0_-2i2eZ43~3k65d!xxB_I2LfYH{H3%Y2!KlyZ=?+fa8z+{ z+);K#?o#g8f<}QihzXI@v6H)lVl#;e7hJme*+03Ee8Y~4AS3IPt95pBX9b=N+4|$+ zn!mn#!S~7T;_GBv+MRwee@%z&Fu&C&{CBPjJv{Bb_vr(gMErL)94bGlX7|3rx9z>l z`a%mzEfpRwCw)}{L5lN3X4va)r6RDss{CDiD?l#QK4QqL-um?8eD@G05|A-SdRmG> zPS8*ylHgI`M8+k5!?nQ%g%|WE^zx%40`ri`W3d=ftbaywJZBiQawxVdYYZBQM829) z^V16t-Fr9ATs`=;z1h*r9=Fp%mTmR$+y7yM>_d|XNG;FTta-Dzyzyp2NIL^CA9{v5Y=0szQ{C9Ww??tlb z6~2p8G9UeD)YSIei86R=bWLu-A34<-m9Zc(ud$=3U_#OilD5HwUR2t+j~+q^&*`}U z?L#AG>)<)u50A9s*8$bJq{m1_T9v8(QzdeTaq_A6`k4!5T~8I)-zYif@U%Ud1xsf%Twu#eKMEoY(n}}9 z22>HL;}cN_m$6-tYnXhr1D_a^oghcdTzVTp6Kb4hHynvqGVpfI zNr!uzkF^#`B*_P7EDW?AC4T<7tmL(&?71$#JtgnahtuI3zS5CxzbATo-{Qu7i+Ad> z8!V3+#Q-3gj8Ea{P&-U0kP9k2CEdf4Y_J`IeZYQucy+3hRDdS;Tk+#BLBJownpJ1y zv>1U*{;|ad@@-Up%*BraLMJnKsVu*z7Y_8+9q6UMq1IK^zkOEjrJ0Y6{w~JMkeb!3 zGbuG{TKwDNpL~|QO7@+#2EzXKv)e`3?)+@an*i@`M>FOd9|`G5)1AM)sC@tDvMaBh zUu|r|o-_9Wz->>RmB_6K2Q@vhF)lwVl|lY{)88mI=u3h z;^yxMJ~STqK)<;$slRhl41OKrX}SRs5SW-6O6*wvY-|nh$>eL3g3cdqaq0N(1vLX* z_qQ8*oPV|Jz;=C)wZGl0I{2=){m86-o7)YaJN&fxXjZztWd0S8P3JmR-@`Y~FYNgb zlAUx%@$s9Q9x`8vGz}uND8$$5j;7snby-)=*fUGDy{>HJqJa8EiSE$YorBs1GIx-% zA7~w*2I*vCAulI$@>bQf<>+sKtR$?ergFXJefaLGCX-|#`6!6c9z(BqyW!{}eueo) zd0KxqR2NNctZqWYiI#EhG83D4kthw<+ym146+LB7P;4?pCUVn>x@^AKMzj@fWtmMbV zM}di}nJcm_Z-+}nM_qht9-0~-xsmW^Z`#*ke4l&UWT$@6wBrgwvKZEinZbgThs(!U ziuXKRrci+$k^HEPxg>(6X{YFv#(CcsbK^}O_*?KE?@SAXzDd|ybi|`yJy#5S(BX>=GODwSEhZ{KW$keS<`;> zY~G*YML#Z%1TTDQo|*Qw%7W+fJ@UZ{2FErW`hAOR*%Fw^uBJ-IIFNz_1+soWQM-6t z^*kTHmeZ0V3v!I!tV=Pbt_uZ%oiku~`G@mHibS6n?@!Avw9uO@;m;J`f>L9BuBxkT^@k_zg^*LA=b@FKRRdWpNuHcNI_YL@w^la79x?e`>l*7X&Rb9 zUx{0tYaPGF&F?Q={u&iKd4W2$(u_aIn6tK(H8dtpa;r)!XjmTl@R<-7n;|STqr^+e z!I;sk30)$1mbtQ>1!rK*F$`+3HXmm)Wm@E}gadN+_e^j0_c-?de(J;T_m3T2}eGztw<6A4O1&_u68QHyn6#b%`3n`rtV zwR4+~V^&&B=~rACA$GrS&Ii|CbuTLP@cZ7osHIUID4MbG*!IJ}pW?4sQXcvH`QnHw zwVF*3mJNrfA8}pR;OeXO(l3mUA&gBPRYr?3@v0S?_hOM~Z<^5hQ&sULa=nKN)lJ0~ zqQaKLp|X%d5~Zne`~FB4O86eH{FG5kTNOk-APZkwjERM+rVHO4>cqlkR<7$bepG_G zjQUzo7Xr$KTZ{0!N5c!#wrZ1W2i-2IX;hE?wAX64O?3CganWxZSM<~G6SYS@wNLx6 zjmuo$-kt;fJu&aY`ja2+nsol*5?h<36mw8dgEjS+O;*eqqKmoGaCXD%@)zwBKVNI~ z+vD&G*}kjWj;$&A9X=!T&+yj9v;HU47HA#QoqysrF!t1W)A9N5T{dm^`Tnc&$flDR z8yMHTX%d~}I_f5eQ9%ZgI`Ql^(L4PPamQrD?*9 zrny>#GWYSjGb+7{Em#-0^4$7{4F0Xr2`;`x5dpTQN?SouqmdUHxr(QVn_{Eax^%7k zvoU9U=%OMPAZFwx$&08Po2`eV#xUep8(0y%3!|CYYXTu&&xEKkqr-RJ_aS^mjL||30JU?0$as z(xP%B%bNS6YZ^z}p;I2`WFz6{KH5}Rn2PA}4;7;2WWd`wl0VN~*9MbLCXoAfI_Y{0 z4W_5v87ScGDt4}6eCk$^t(gY0Z^HQP{!OcMFgu|+6A3>FCy)oN!(gP~4>%%B33R(? zphfd1Yfbba^sIrA1|}KQdBgYadA2j8w4-{OhI?g=;-&(B<9A8#ANVW9A0G67pg+i5 zdyW3A@{B!?)f~I4!#?~L_93yqV_bKO`EYcw5Fh4#r>Q+&@r zcIC0B?D?xb)TW-XTZ?j(7u516rKc5$L^pJscJpgSI?3UMC2$nN5Z~h`{N3Dj@%L`r z0nYD6BDkpLOApO5`1Azlk)p`FOS^UX#^UvFFV91j7Y^T2WD%}%Q^Myat1JE_A3#=s zT0fY2YebL8kc-|KOi##&jzW``L>`QWS^y`JCT7JOi>vpcprc@-`ib^lCr>)x{fPcX zZ*=eDas4;idvBcT`}0)isl5@fwln~t&OKz|TF7UGbwcO*nU~Zgv)2AZF5>Fh#58yY zgo{xg!UX|6`(plcr`t0Y$d1_s+Q$94_{iI2PE00#p8wUU`S%9bTs-aXV3fjtABiE^ z`VD&yjx@Hg6&C?Q7@j>DbL)$z5Rj1~nb)fs5|pg2hpbo$KZ%5e3)6O?D)`U2j)h0v zG$EsMHuOmx;vx&#jbVIw(n!Q|CpLeje%@P*&@gZt+>kp1Wz8y^##Mj=J6K3zUILP2 z#j2W`%-uPcX0lL|$4BR~6h?QCZbKc#t+&&zoPL?I>iF|_@LbPNeAZWl=?+b%x#pWj z)5{+(uR-7F^&g$*<4GP?-79JtExCNwv+m5ArzEE@=A*AdoT^cmU+5hBt>UoV1k;-m z@ZR@faOk(`DdbS!S~7UOu#|n!k{uq`wBOj`vbwA#|H2rLwZE&&Y~sNFdg-E}q6%FX zl2L@m^Ev-e3%)5XM5#hB5GDc}KVAs@fdEbI9_4%a0h4Zi-`y|QARWPOJ=dp;WMiD< zBs=6VQI_QB_PEph2m*|T8uMSwe@0NZIRsI{aBF8u27zlV2d?U0Z4^6o^y2Kk?4I5c z*8igFL))2~UwqShW_=~d3m{w%xAu53g`Flm8$)o4Fx|#-ImQQ=kD<3S^h$DniQ1wWR{-XVQ?4 zAqD9|&E%c#rM39o?idIkQ2{4GP`4iX{Um?=6m)gp z$PQ0x+W(lr1dyvAe~-`#w1v4x(oshxtck~A%3O&)o%a2|^dr<<%58Y&_Z za`9LTpfHkG0w?l&w0Fg*U1)`|*v8ttVF$)wJ-c+;=hWF1_SzlTuFJ~q>5_vjuwAG+ z#AW6Y7M!f~6<6I+b)0dnc^Dx3H-7_xt>~A1UwnS-jq_=o8|r-cMmFod-);vW$;+Z* zy6bl%n^1SKlp)r-kT~q+sOHIw)XMN+oH7-pE}>VvP~w}nI9=p=h>7` z-*y=1TrM)9f72l_AVg{k=fk`~(Nvr)G9+kx(3W$7o=ZVmgxO0^*`?iW{1ZBBg{qJ` zD;vZ`!r6*j{&ZA}3Auv-4l-mo+kJwg9ZOhPvkKS0$4lh2(DD(2G~s}Z&0eWuP)O8- zQ7&te$>{IHnb%D^H^k{n161trqFnTc#s5uQqeChd{QOYMI13B~;f+Ag&z%@h&>CK? zJJVYDg*V1%vg)xO`9(B1pkA6esHY5Lw+U#s*B8w&Dqpp|Bx0n~tuub1AuyILFzN^i ziUcEeFU|_laXQsjU9$C|LSGYckjaE34?YD$kMs-5-m)yo!bMfAlP_-PD@@G%`MCun zjmr(`oC>GCFkolwWQXn6p5@oz98+_7&3-Q&W@5y`OuZ{{5I7puLGzevagZ{V^m21L z76|%tpa_kl%cKvlSz{vXAzaQ_)DTor^~LD&ym? zH0=)QH;7;kU`9X221j3CmMqFn4|$%v52A+ik^mdE<-stN=r)alxzQZ;)WLYCLqHCd z6y{o9)=73Fb6^L^KEvmj1z+;XVzuPxN{5Pcb_u_^ylA*)&E<{3LnH2Pe&u8_?(9tR zh->c6f$O104}}yiK@EjVzQ<76;T!ZLfD8+cl^AYF>3ftD%Bz`x8A$2gQLy#XgT9Uy zXLb2Wx;p$r2?aHE^G0J+7C1TN6Z6hB5o;d%-ZWu~#oTb?VX~hOrs}2h6`++a*71?R z-w#5cJhEx-xE#%5f7Uf$R$sf74gg&-q!2WJ6FY*AyE=M!+V935qY! z*-uW;*G%6Vav)vbw$ z4J%GKo=~$pFtaiSM?Y#Q*p{S6 zuea>`v7j3_)D->uZBn*KB$cNbxVaa#+!l&&xvb-PObG6Dw&^THU@wPCg-$3e(I3 zaWypU&9+{@9oV9hGq- zr$&WbNVT4$E!IwKOKH+=FT0&*c-rW~Hsf!LkL@%5bg)T-M+DYFpr%=bN_o?zxy9Bi#OK#V>BL-P)bMG1BbB=f7-iEe&*k zo>^E`)br)uQ>&(GKW=wl(tE%pH&nh{{PdOX$*$Uma?c>znTPeIJue$bS((<3R_U0`Q zw@t2aog((%FI)bz)fCO^idBaKR*u-~GqGk^pmHZF!{h+_2JW1=h7zLEWA27@#^Gf zonAjWq~p6c9$%aqgO`sh{P5*3QLddX7T&wOMxIe`5Z-+>wXSkPt|0f|UX|M>w@na( z*PBN;{wFuyORv3p%7{}YJlXQ^)i=!Iy`8T9zU31 zr+Ha>rOQSHW5cQ?*o4=phMaAe>ZTOycJb$}A2lVOB2>K!|KNvOdmovMx|MTzO8W9} zz2ud1ai-M1#`)F#5wqUcUfMR?F3Dv|fo}3N{p$w^ULRcI>OI6K`)OK_Q(gOS z?H*6oMVft;4-9;_ddy|-QT9j8j+(hY5i~gbQhB&X_9T0XWr^nX18&*<%B}x95Qs^S zBKTa|*@W)`-TU&N#1>kf`ubeir(>4u)^o8)^Gb974F4@l>vr?9wadl(9Ug%lx^gZ* zIhZHdWo@PST6eP}?`_Y8Z`U-c-?LKusH2#%nLcbc2cB4JZiSEc0;>_hKU?h|u{U`+ zqOl=mT5gwM)GdAq(4cz#py7Vi>&_Gjr^(Zjx`Ot)Po9olKbpDo2ir+1HQT=IZfnqM zcWN?uDcbvJ3SQuRMsML>HE*5IYIYs#*%&!7cbr?`ou?Bvlslv|NGyG7y;(Ak7H+GS z`^5RR+v`0~zS(Q;?K9=U&%N7zX|+TCe{`UyE1~ca4_~^S!G9yJCln@M3{(kF31}L> zA=TaXsMmzO!J}RWTaA)moA+eq&V6$ayDv>!X_dAs{*S3~D@W`qy0Cx^NCv8n+~hoi(5@W31#xjH&7CL3-_Ajnruj2g{NOPzHTsO$%c1vPqyui@%f^k z3V|yCRvT0eg>ULP80h?Bl~yzM$8|^C_fC0Yv>uR@6;G9XqcwL|3 zZd>C13#!BT7b|bgI$?62?-}*yR*G3wPj64XuY2}1?>F{AwQ&0N*M|1N_&Dm05{v&o zWW5PI)cgNE{=HFlW=cr*y^y6LB4uBaQr%EemMle?v=Hh>G7&LS))YdkP@=>&p=9Zz zESHdC`um9|c zD+CU-$UK9EalZDRk}Zt3=1_|4W7<&E8Z3kxBP*iJx(6DDk!K*37Ug}poU)82Qt@T? z=$Z3A;{(?oy??PPOv}yKr+Xkzx`mLRY&)`RupWFh~+mfc5R#@hjGkrMs z>q5UD@drYFbJlK6>$vU-hMiPbBV+lcXq z%i1SJ+Iun^yKSYs(gf;N;xe_psqHQmf7e-c)|oj2FYKPrDZ(=)4L!ab75B#{Y83<> z2npDFj!{*C94r*s$VNE)#6()PEp0#sXfiX&x8{*MaEN%szyr;&&+;|4VFq*{(M^Dz zz^#5Vz882Sty$-3J0{Iaj*gF|%TIDuul({AwBudF;fBGxQZK^Ik9CyIAZ6%F> zX}ekON7tj2m=DP%d0~S|8Xb1-@c^aKU|OctYKrYs4T`mAh8V?09^M#`dqi%bt!}?U zP-KX8ipskZ0G2jke}fm>m- zqP&4cV>Y!gLhYCPspMyR=P!aDvf7j}Z(WP1mWtquZkEq6(;8bONqnAQTJo({BVVP z%5QoT+E)iULqCwF_|+LukSfo59y?bIeGz3A!Go{nv6p#ws(AJbt z71ePWM8swq;57z;o(;Ij12I8z0A?K2jw|5!Vf?_9Bb6PlMgRqyks~wk$VSsaJw$rC46Iop89S z?sq-6e9{gSz*F_KLL6u1S9j01T4(lLNibF0i*+kl58FN!=|)%9fmRDF0Go>rAbSZ} zI@x|j$#Hs0U55Q~UllEGvT|_?V97K#e+V?$mHh?#{&=8jkzUrar|1>Ve=2{1D&J+} zsR~Lieu?~+`(NSeVCvo+->&hi?1i?ZSY_A)6U6xfA;#qS#&`#^mkxTjS=Y43Q_>|&FmDlU$Sciu zQ$`I6qT+(pb6Z54`e>*I?w890B|jJ(8t>iQl;03k|9y?_`M5M(`2!~UB4&9l5O*vs z_Mt{A?MmgP>2pJN%MCSY>uFUNr`6Mrt!v#8SLO&D^c{oaH`x;;OC09jcWk z0DgmBh~Dn`SCRh!{a!5i*})ou8+iKC%OnGPR}^*~oDS|i+`xuO)^oR{c<)cQ1g||0 zZmP(J;wQ=G2hC?&BNPwz<_CVgH`E5kdB^JTZ?{d>et$jw#%Q~~7c7N#2(gb<$R!_A z-oROJ(GG-Jm(bg|&@$#t%lgg;MSq%=(_9R7Bd`H)*<}Nj(9GSX*rebhRT{Nx@RkVE zzBpJB8+_wBAi>&dg{FZ>7p2rQWcS#Q1!2tm1;lz}$_KKHTeUEpnT&fp6!B%Xaw`35)!cBr8 zKvfx}11kmQ8XVq&rt>GXe2-S!mb~r%R(M`0p+dOw=+}6s?qIj9%2yvgYQE_Y1#957 zH`NmMbejz@0f^#rCC%BWp{l>WpBs`j-0ruG_TKjnxjO`L>=0nd5 zY!mD$aen^PCj-y-Qe&*dKrpB)QoSe4h*2`pq@VHSh{3#k)DAvzaEj(LU<~Z$+09%l zoORY+&FmcE>0^pt;o1gK5RCr+*Ig0lh)Roa1L&9 zq$#%Q3lm-_PJ{Xnn89Y(uw6FQ<5Sy06Z&1Idy~X-BWcvUSo@BrM!9I0yoiW z1tNp@31t0<;yk_Wq6?pgGK`W2Lcv=LmARBxFMFD!5)Cq@4?jzzv{*DkKRjVK^Ve92 z>$FZ=P5&D2o$um%!S|@?q*KPs$=lz>0V!my0C#`Deq1JWP;sI+UBalFrTI+`$Yh%r z{F|^`7pdL4vD-A5Wbs3CFe}}C9LBGE_%Rqzm)tZd3&jOW3vyxC5*pRXV#tzhhJI%^ zc}q%qWAuU*(DMvXG4ypX?j$x|WAZWi1}*^G+51rKH_>p(!2f1)DEG6j136S|e#_

    IdS$6vH+HqTwEv&tXEC4<^Me0r5&f ze>p6bO#QXF5nlL#TO9Jc?j;Q~TrDisS`qv`4tbnA$@&VWJs^5YwCUw$+BrS|f*%z{ zz^Z~G>(O7bg1QgdJgyAw4R9hLTKPInJWW7UOXgMnr>(Hs!M3~5kVN5L3bQF*qqQ`_ ztF<&x!U)%#a42ouC~bA%*9A?>GGC&2?l7j0YRY*cKLErC?Rz&PD~kh;bNdib>a4;E%gni_7|7Enfmt60tB``4RbP1GS#-&Wr>l|5krJ zukpW&Gzq>B^9}GZ{KNtB?;>eOttWRF{zx2JoR&G1I3(TFkukHdsnB*%78D%KtAPgY zE7?-n+@heeo2N5ZfNIqbh^5|5vMn)a%vRxv1xlZpTLktt&WqrgCw0XF&}3U0lh0BS zTF_Lt&`#y7r5a4Gapm>2p@*l~D`TYBtYY$ICmB9gg5W?7q7C5i)Sao?en3!#u=a7Y zFhPIw{*?36> zFbngDSnI39w5q|6JZY=jT>UQi%J^0ed{j@{k#w$#y>+_=wNdBDf*}$KN~!Gz(Sl~Y z>kRt`&IEh(F6?U7h1&c)+xfPzAX^%Y$nZ0hj}5woG0=WX(riJEl3+9&P$6xpLO)Zs z7IzQAi9~yfDr_Zewq*)BH48;IUXC8YPJ@PHPO-(|3~dLcvQO#DT-9=rp+k?qubFUK z|Fj|H`_60SCgBhJ$Bj^oS`n(=^a9(fwy?Zn2&}3Hguz?TX6%oA={5YplQz3%a-Z*u z7UP!hX>C8!?i~eb>3frBzUMRl_c!0l)y}7sOi`wpD5n-6pniM$b z72D?nV;hbrjot7NnByy)SJvEAHP|fw&SnwOj;#jUtv#GLc*Ou zYw$&EWUaI=&Zj#Q!PJ(4Y(tmrtQ5Q6bZ7?!+Niz<{(}&PU~n^SC|~aA zd@X7*Q-uSfd zzFpvcbP*XY6^`q0KQ#4hJJ9b2$OoX)afKl4Fzr|__~hf>{U0qR7dC0x49?2q4sbSN zBkr7@p{vtw7^r0%$t+OYT`%?dc%$i%Doh419;4+3C*WnmAL}&+2DWh>BwALw5Fip# z1i8ysG2z?B-R7*4vfe@06s=66eM0Se;QeFE#`_7V)`16#YO|vV^t1f_R0P`ZV=u+~ zhST$x)`$fojaCz2Yrjz#z6x+q=a9w0SAo+)P5b-+Q9@1UX|->T4+*3d!t{cFi2x73 zfPOh7Ofs+ffq0iNQL)(w*nvpm=zZu3(>ujhoa**Z)QD)(1mi)Cd+ilr0LshcBcS=R zX2{2TW|4+lmqMq4vkD^=-~`?mCn1#=Pb#!iFwNbeh8u#t!CPzQY+CVUZpGk7wW|BZ z5L^Ae>AZBRtma}cji6oFxQVuif@ewr0zXrTZdP@b>YEj`s{Coyv>p4~>?UDD06}R$ zaUgMQDB(~a4UzzoHEvZBY=m5X)I$tLQg=EIeF~`5OPn(-bPr3=(>0+*C~;oGK!8|w z%jJGGkYt(g;eZJSYskxl4*~}Z#iKF;vjeBrn}yAX4k@#`DEjkS0E}Z7(bOS~J$ypT zfUh!ddZPbZbu6>$$k#(x>IJ@yKfPLi2ExUnBxE?~`BnhAErde|vVLu1A0RyeUApcB zv5Upz>Xz@@(zN_87;Hxu);7OOtRIIAoWhz2wZ(2b7Z=dK z=~fwMxPj3I&G*lY1}0t*H`6qQU@`Zs$Xn~-(!y(gRDWt?C?y{~78uE-ykPaVl&PJ2 zA>W4S+Aqet)jrKI)=7Cmo@D||US1{)uriQvrPNhuqbXSrzl(wTfWdwSysg3HpMHO~ z9no|6git49dKznGz~J@3qwz7 z0;(<7VIqBR^C=Yay3^2VI9{}p_Dw!Tea%jxPd-8K}bXt&^c!Swez(x>L4h9 zv=C1ewpJ{S-6@HSb{NXvWs-*`h}tj-Z?Yi*5&Xn*`@|d77)K z5dT&6CPhrYaQA+GJe-V5liJPnVnSA$RtpJ9m}p0`(SJ4)@=?oTgEE_-go=c`GV@wf zOU1M}(9u>YDU~J-)@|OlTtDbdvZLD|J_O@gW)1r}rXw3&ZVl-WY^e9v6ZL+rXDx5R z2PJNo2}6@vE0m`b7viq{J^*Kh6{mo+Fcm-nY+}7JD+|2$ry@gKWTNe>2EaJTrBFG@ zSzj2m?_DHBdZh`tfdJI!K1>xt+3{SWSHb3 z`6~XxUGuaN((a(PTxwJ95;z%bwTG>Z(10mQ<3$~0AA5CSohCIbpVhEDjCn!dCu`oU zWu4F9uZ*aU{rlX(e=5t2C%Ni7cA25-vIaa8yh2IsHCxZL`dGdp zJQe|!27?8L5L5J5&v#NV2`O-?kkC6eJ=X1*Bx`f?mC-pLVLd}{Lu${{fh<&Vl7(~S(Txy+L4tzE$rHOt z7F^~QE1om-@QAeD^l>lE#SL|rRPHu{WU*I_V-uLZpPmtd09-GjgJ?GEAtQcY)pYFD z$F=Z}2CYv7uf&c4l74=5hJ^;#i{q{^U1oo6IU%>sVNxSsU10LpOaya)@gBdH0)e}IPN&p(D>-1DG|6L zU@&&3s@bVByA~zD@ZO0k`MCVXa0+%bv+RtF#b$-aQ># zU`WGl9Y7xy0DMd5z|QeRJmkO=F^m|vQUUv`pd4M`%eI~<=1oFE$Sbl;$xwllWL08a zhT)QwDLEKHi774I;_$xjH=Ntf?Kvg8>U#IXdvR&sZQ740*P}Tk+x-6`pQL;M0X7Z- zJ3;t}DB8?u+Rpy@M%GUS!=oC_UmySj3aJ+corLp=6(X({RIU+#A<~+gTI((gRTxFO zkI>wkqQ@t&4w|{@d^$du~kWbR6mZ5fY?0zr{kyYMko?qxvFm zgk$+mJ%z_Qb8GGRW42h#bv&{8hF^6=wwQ)9MMq7=H=!m%qIMfYj(@&#ut)LpA2$sj zy?$_Kt=OLC@qN+v+yB|4YUq??ynaH`C0irpU2B<*`Q`CHXqzRM3MJQBN-mX3K51uu z`4X$##ylz~`w~+jqeRfUF|Z~>NGDrfS7?`Ou!BXO{8mYpW_hpvVxMkfxjKuuF3NH# zoi+-!*(FzASBmP#us2t-%%h+4E1Q=`645ziN)yQQtO6uYHK&A7wDJ2<~r!?=%o7W6ZK%Yh34#v`{$Q9h?>&Pbwc7a9N|f4d7ebZ z4(go?YrYJBtG^&{v%zltWui2k^Dt>uz?Vy4X2QQ9(P-K>)AC?P1RA*_h zbn#L(7M0rE#cO@qnc@j+-poBkH@94=F!4v=S^!aLeXYK9QPW9@5_xX}kCTet20qmI zlzxVdxrL-cDGTKT5#ojQ67SL_X53JpMe<*ujL4YY#W!r|F9IIgfT6Y9_ev4yHP|J*J z?P4`yQPr60S#Kv*2dA(~XdTD?0@`K+@ql7YQWE@5a%o1af5AmwYcB%@mSK7eC1@Fg zTA%}a-t!R3zkqs5S1?i3Q_`o~A5i4ccv7ODu_&Gq*zAp!NIdzN2K7>iD}klIl(+o_ z4uvHV+kckDt?H$lRljJQ$Hrhu7WEwOT4=!y+?KZlVlMKIaVsH2I%>Z3X!GZ2A98@_ zWp9!Kl!OXj_#JT zEpzE2IW{r&=Kouu*~4{vb{W?MGaMy;!Df5W{RnlD;pXH=&x`d$_DTz@2Rw}Yb|Oe; zB|u_CZ})b}qfdX7xfD`Iw3`)#T8t@)>nVGW2mj3@zRGd%1g9=>&9$8JuwkSy!}TgF zn>S{0%);clW4nMSm$hzy&q%`ya z6lifmk(ueD&@;dPT#r^8MKJ?8MSrnJI+g}nO>o%%q@n^cu?^OQa0~zit{*2f%xNK8 zswiNo8i>Z)W^9+Jsm>A=%bb*+h9yA5Ooh&WJ844nN4wznTfYpg zsG7d9FMLEmtK!e|-wUCdD>M~D^n4C6p3U}2?-?o3xn}=Uxl*P}%#(N{h z7|GQgS<~acp1NX>`SqM2*t?^%+@K?5Fm*54-T zK+kn{EDubqn>`9ulSx430+6vw*6(^EhfUm)OC`lksqv4IY8zi?G_8pv=n+$<@6 zj`yyGM3jqyf{>2Spg)uj(A7mz1RNr|QctE}^#EdoiZ*iphk$rvE)q;Z^$0aDVY1-* z>qSwUfR0i`o0~yw0F2zwfA=q@h$az5GZE-64e#TUh2P8k5(&TAS{3@~xl?&^>ex){ zTCMO&_~mqw?|+I^3`)P(US9c^#FQ>HDt~_9A!t-rM`Kgt>hf2A^)ERrb)m}S(AvGJ zyY_wVd0r=d_hF136jXf0`VCLr*3=v`G5y|sO-tV7$J>Pi&)XJ)F!`jOd@aKm*=6oO z$zX(?DmlO89?uiiCtS}}u8J%>C&bo5P)^kq1tW^$(F>ounci6(W3kRW3KSHq05J#R zkM6M(d`Nl045`%Op-pO6yo#XINQh)EzHr8v;I+bI4Jw z^9MeAOdE4QSK*y_GNnHwphUjCg__?&9eK?-c%VjqB~l*|M)n@G8l?L%U=I+L5gx_q zqDf#40G8VU!$@muVGCpiM3dlq5gq=;p$oqi0j zl(Fv^;y0~uI!$(VT$cQ*`-;l(xaf!d!Nx}i7G! zDs zkEvg#7U8j9RWA5;^T@>bnPcClj?GS0johys39TFsbqgD}yt?ASn{~Ytn!OYF4!2O> z8rhkC*%|zOT6izf^{d0bp4F;WJI(4ejM_wtnOhW?Umg2bSzF)LGuQOXpBtYuIaf*V zKW=AEXtO=O%q2@U{{iC;6SsE`=wOA|!B95XA z#7rCv2vb2zxr8)A^{g@x8c7kG!8>aQ_0Zu0-~Mtel1t-aiEmjL9|I7ddmkMccoHk? z)7s5YI*{ZOz`x*8bmL0w2ldv*pnq$IN7$@E?D0cGKISEL?|RLD;MtKxq>JRcI8m^CMbn0ex z`He8z4n>u{aNu3Me#0O`G823>+a-~P7e}hRQ_lr`%r2g>9CUf@xFp*~vq8zW0tVn2 zKmCD{=3yF@6Y+BpI~|{LT(Uodtz@KRFh)oM%cGqkhG=l(~Gc_M8}{` z)yoJ3e+oSD)JUdm_`$=`V5>LT$Jj#88x70jU9Fcm)D;>Y>-Y)Y3i>1dhP>O+=~s8F ze!T0Q3h$k2K3qBZ>imwOwKGn2iV{ZofiVt6a$;i|fkMrhT&|kn0Ir1urw>(!v!FqX z31ETh1$^K2rhtsSObJzN+(;Z0Ktw#gd>22i^owPA!7}5#(=ahbdV{KZ}n0uaYYzWj0f?v~p#H>}^gVa58gGL!6cLc31AjpRAqT#FRIZtA#L zAObQA2R`$6Z9K_w13(?fwkvnL=FF@0E$E^I9cTuLA1SlC&UFyRU&+jpw%3e7umiy1 zK4`VTWnu4w!GdjpdIPs273BRI2bT*$s*re+7tq+XjzALWGV&kjdLmY&<{lgE51~1* z2Ct+L!aaD0KL(7z;@Y~sIh|_yW8C&KHztof=oi}erE2d3pwDCD;>X5Sk4>nOcRD{V z64n>DFKqB`c=z20BirA9g;&XFzjjT%QhSjR4AkbQSzU&fIj==|YK|KT-PFu9`e*Ro znW1XUlH2DD?$dx6n+%Qib}-TdOmWID(ZmJDcSlJ0WhmFqkJnynv2OwWfqzD3>0C1Z zZ>f=xE)tC4R0@Xy&H#l)d=kl%3*#t9oxls+bdV}6=e6eK5CC!Z2Ece-TTH(-l3%LV?{{jY3G_EfAxXMbdg=V8!Ct13gad zgl?NoPONdsM*oDvIa{v4FOx4w>IEJPX9rBZ47Oj&2CkJ#>}LqVoYm}ophl2PTs0Yl zRr`O9=Q@jh0G@;;V4gtAfGH*y26fDGbh<1hp_~e8D(nHA!>_1Qq?YIc;17`!AnK_* z(5c(|^ICuhDp8Ic`pwrS`j#>ZE`fJU31|48HxINLJiNPa7^==@N@R&6Ksynjyg5Pb zegD_&W9$?1I)|Pgq7k4k0#m}ac^5!utgLHF!GlWr@U0kOO89_k_4o@67%U#JC@NYW zW9#0}*o9gKUJCLL;>Z156)(gqvg#I+3Svc(elZ1G32ut#$^3=QU`-(`BqJ9oEvgon zC~CKTHv!8ZU z&Hi{lOWu|pJXJ`4l=zGB_`}~>THjfR!yX;}Q2Q9C|ELo1{6%t-aV7J3e8cLJU;Qo{ zXVf(K7Xj#lb>IbD725;);nh;_Dz}v-2bM_xGzEzRHacY;X6~X5{)~|pLr^l0f5dA1 zwoyi$(cb8GacapPX*p0oE`Zfbq(eXLc+>3x%^ixG0o%(%q!NAx`?Y zyg0jpDZt3KK`jG2zJBinFSh<69LbFMAfuf&>`to~Ml@xZ-%_rB)s`-$}wFgJ-P$W`)vMFl+Er$mMS`f^&m;hIUB^4*>wKiY7k9I%@^ zWAI4RjkfkPBl6`*_4MuY2S>{^8J-3M7W8b19(A?T9(>mSc0J6EE2WC!$)bn>1-OgW zV^E9UA2^f(d6qS*(~z{l z%nQM|q@}e~=k{tngDm>o_2-((+KkT~-M@C(X^8K9L5KoJZh!I_IbLFaze|`1FGO++ zYWv(w-9-gz{SGw4T+Y6+W!hNUy4l|~r*1ik@&Ko7?`mcJ2}Uu@NeM+_x(VqW$M2H~ zmE*Tq<-9S05L77;F<8tJ zIQwY!i!8hxR`0A(?+2l=W^wUBH!F8h3_!Q%mt_aX1V3rM_%JB!WOS(P(0 zQ(dk5tKcSLvfy~Z9KPqAG?+J?OzUvH{qkkTtJe(nNrQ9;BVeV6bY0g(J`6*&ryDZ!CL$o9&iJ(WWpN8fcEdC#bLH5OLCXP0PQ z^AgG0-{?C#`uJ~tIXy30UnD%RK{L&IvQI%s&oTeqpDrr1GoyZazws6J7}wMGDxdxU zQAs>O<|&W;g%<;3qC9pT#uZ6pYg=3U=P0&^^o`cPE}%zAu3(4GQLzE0Y$7dmBr;@& z2??30IA;)?0TiJLN!B^y-dj*{=IFtoj^A>68Yd~3G)eFWY7|!z=W!X{O(6yx{poBd z+Ta~K879d|u^1b;L5ew^h>g=mC0ICc#Z?{2;92#aFP-pm8{^6d;0pE)^^!+ z;LC}xx9;(XzbWWv3?6E7$&>CdpIG!L!0_f;j~=@(QxN+BT^hhyO=PAcca)=ssOq6T zk{$#nMa?I{dtdkL_m7YFMWnH(eD;8aK?%q@eRGi-W+;00zgBjg|0FhfL?34ktQ} zlzWslnyLY`!GpoZ7{^qQu?8eWX-p{R{uhQMU9 zRU1w_Y|I7OU5A|v^QHsPW4~zK$XTc&ln~pN$j(n8uO=|H=U}wj{PcEcU^38mt&?#l zG7dNnRF#Km-p6Nq2YMoW+0U==+Lc+eZL5E@k$Lo9;kSF_1qH8UeZ2xT>Gc>(JmZC;Datc$&JNiH8`OokEclmYf`K^N@=gFa?nY zCk}{HUE(l_oJZvpU&5S;#Qcm!1*Ew_alrY&IP~v{2sj`pxunMi!9$B{t%^26hbVOE zL3_usrhD+92$Lk7CBaS-_k*P+b_dNm6xue?xTdTl_kUGqF7!Ej{^^?TIQFAs{n3e} z)t^0Af5sqrdN_**BGKCOJC06g!b^oBI1PRF#A&U8Cb#AsZ~sRBzrp5(#zlb3P^oiG zn&q#~jrpB(<=(wGvt+Qe$DgM;z8hW}1@v4KUX^JSk(rDvrDBu=9R-~}x+P|l0dzPr zCbV}>P-(NeMWYX|EW4K7EOPvWjQQ&LL?1gKA;S>3BQ{~OdmR%z;@maBolD}G>_vbi zIeQ{zoy_UP5dlac$H%;VG0fT^3jRIn!6$M9`3Dc$$;{^r=E#@-sUyjk0iS?bD7N;Y zdh`GKN^W*QasmR9Ea|F)D>Drm?EAV(d=ABGh2fY32irb(H@I#xewzAllW!0G!^5u? z%6;cL!awR8hK`pz!EyDMsq|s$ithbAV$Ja*{biaxUk?}z^e&mn99XU9#;%t$j0hWP zhj?OCMc1F{VB|+H9RGMr;li@TKI?_m2ac4R8Q=9UXj}L;IBum|5WT`my3p~_o@d3E zG#q6hOd`h|m?$4u_O{8h!gN=e?&*4m&C&r;g?R4h2;et^nz!9|shH$ng zg6>{Hgc`FDn0FLHZe)`$P=-7uy*|1@w-Zx|4J9e>cI!OL~7=TVkEsy4+jnNv+WqCyYT%~X$ zH1JG{5M2_|vIi5O;&k;Sr@a@vB=2${*{QZAW~UDl)MD&!dN!i5M833(GUA_cBS*26 z9`!gR@)ig=%#-5eP!D@O{32e5@~gprrtxgqfi|~}y3|U6^Y8;W=@6FuIYd6hlMnU~ zKIjkB>Bj(hm{+^=t|Po*0l<=8=-@6|XU=4GEfUdzMki+%M92Rf%>UO`!dYIYvIrdw zd(uBJ{^+Vf01BQS0#HJkkN!bfnHhaLGYSIZc6jz<{^}nKR*x@`o&EBtYCyem!1~xn z>*;-s?6Y=q{Yv&=hMvKiL5E0o8867R4^=}z;BB5!dO_l@?z=M0R1RIzM}G076?OEq z!jcS+OU_+4fG*Qcc3L4-mUbC*<57>I#{rAQIF)ZJBdHq+>C4uGT9bn1w3ZpTu~i3h zc@o(zmE>HIaVV$^`t>|{N!yl7A3+>~qf7S4Nr95WFnhVP6H97`G7hx_ zx@wM5m4^vJ=Vr1}9I7-z7886`n79>!*nwSku;2b}C^1BV{=$OzE} zj^x2NAeTqy32E{PEHIvI+!BCsvHZjDJ3jrsdOB%!y=T~{rz|l&@M7m@QoBOo;B)qK z)^uuCd1d8L70=)uT{tm~+n(c05x74*Bm22eb@R77*Jo$G89#l0@J8sn8$WuOR~X%^ z<=qPsqSP)4ADL&n@xJeTTcI?INVVz~nT0fllqmOHWea^jISbR-d16c6>9U?g%p|(6 zQffc6ZS0%d$kz+QbSV*y_NkR;p8mMKto`r1tIljG6d%1re`oo8s=-(JkFD9iZ+)ef zop9arsY*mcWvrU(DYf(A;*MqW1AnW&!!_`SGgUoXam$J23oYa%;fuU@c);V1RdIZj z*PXh&Gf`gBak*!t>sRgZ@|0gJU>$DVewcifs#iR}r$#;1saVa+@o~lem&uLlE~2`H z|9(R&R#WOvu6az??Or7UnbyQ|?W2{Q065fr{1!ENXn<3HgkAyi=6wx5qm{cX9`Zu&m9L zx&6G>60DS^`P?kZNo^H#16FE;(Y9bOvMr%iQ=v~yzFoi1MXgTmsG9i%2hO2ip2BO3 ze}8oBJDM_LZtGRE$V)o+!#f+CQoZm60#(PEbah5VfxUo-e3#CsVVFV3 z>ZUqjbq!+7#G>#UCd16bu`A=f)`co#A5SdhDNA{sLMXLY@GkOw{RcZz;`HMZyyk)@ zz}eQo_V~H7Z5M;&H-V|;V88Ix_cky)Kl6mn~a?bwY_=A^l*Vefm}W)Ys^hES>PFBI=rSRV>G zGx|c=WqGlhRI=Qpo&L{l=yEnFw(^c6`@!BF#pT5k0;l4jBYc!b3h)QI-fn}RJ>^{< znH6vK43ZG2ch^uFakdeLhaMEWP}K+iFpyhDJ#R10;9&^V%mrl6b!V*M_K0>)S(+`! zpB=c3z}cPG+8_x~O%M!?a8iO%?Zs;@p+KpQbKgg@u83 zrkgE1cQd5xFI=gXX)bHG8x`O4{P;$Ni)VK(zn&;n$5P1->#z2tMyXR@^@{k&L^U1v zv%JoTe+@U|npA$<4K_;w)@?D!6PB=cHkcm*n5|kLU3eL$;ni*+DbVHoxXw&pOm~l0 zlfhC`s3RM`2_5E&AAJ-kc(Kn&|wK9MjKwhj`3s(U|eSrp!y{s zSuu1xcE@)-S3Ou5Dt-6!y^aTCaPiRpeZY5p$@&WZZT!^wu$jrM*~<6dOrA|T*|Z;g z)nL|N%8$FKtI4kC?D4ug^X|XBv2ugm=vC8Oiz-!J9?b`;brfbZE?@J3ohu2&Wh+J; z56m<3&``=WYo%sh0n)QPU@>La`iPYW{D4)p+0va;(AcNurbPJ})<0781d@Tu`CE20y!$Vo^2O2`NtcgoOnOMQAS~ zjC)eTo~wl_-9nA*e#@8(5q!4x+-!w8j%7FgUryjKZa<-hIaJ2Zs~H1W?J`HXIsLrm z1itpwnVQCFP7mJxUKsk%2$rnk6I`+erEQcB2eteLub5x^G<+;*$G1B>zSXU$q<(@6 zfYi|xub-GWUzMR{G}n;=w}pE6G=p17U8oQ(*Y}BZl z6hU{!aqXHl@J1GZ%GZqQxH&BpE**-HV+zzOLX8mtOv_E+`HN}URprPTFs+(FE#TJT zl~wZ+fG@z4+AK<;_SCX+$`8MP(G6Eq?D!J3;|qrW9Th`*ciPJ~+J&^GzxcSScXCz6 zM~Jkxzdt&4A3!@h;d6Az$K*@3$V{u&kJh7AK9iMG58hwNzo0NpLIyZ1cr|xvMPQUx zTtoq*?zY@#rO-U_>dGU7Td%#idiU*`CF9v8$!h*z`_v-Ldo4w8TAW4y;J=JY3cixX z%e+YB&6c9%puC92gpx~x<^hoR_+zb!(rvN%>TGi;=fCo%yGP1WKGtlAV;H2~t&CnC zU%|ALM>uQnTRYaz0ozc)EL$;uk~I`oWpXU!OdO#EPSNL2KB=o<5*!1rCEC`2HbI@) z?qQxs;5O+ZbHN(W?Bl!^mZE#rDaVPL@%rpX=kSYaIgHD_Vksj++rpA|f}X=7RR?)9 z4b=Q&Bmd!|558l)RkPcwK5fhT)-ycz&;2R9qRM~wjl!^3>gCnLt7oTuvcf+L?F)Wb ztf5skfsPvXX7#r>>yLdMsT>>Wta!~|f3#}2VLK|EsDg`K=kJ5+Kk@|UH3dc z4|L&Vywvt?U0sgr=k33sJ@kij>K0IIi@&fvn>Uxa{AIH;E_eAsRPdPBjJ?&KuO2T>O)3XEHS?$hPC#0%U4)1J?F9WMao?R35Vt>NI) zq3U~8x5XSgA%M(V*h1x^l9KI&f50{)%ImLA_|_TA3VZ@E4OIrVMZ|_OB?QuSKNEjT z1gunWZ~gx(T;O-z3@5;X*#;}q_bG{a$wYz29asD5apzBg>*`{&tcCo~BG#;tAnr?$ zUBr1FrknGi?bd8|le1=X0+B2LDwr^IU&M=9$Ym^EXkjV}xOJ~s!)AmKMo^P{Sx%I7 zN$>j|6U_4!Z`SQQQoq)Xbpx&f+;;@tCkHNa5y5lUW1~fnOn$ssKZ}>X>~Wh+!(tj= zWzCB7BjyW$@O|!CZwxuz^v9!%^cz<09kPYZ$s1V@F1&NP`O)0!`Y8!spQQ|GmQ94&{_5DyQOXoWgfc~)qKaHEDtDezg1`3C zqr+BabY=atyK+d_vAUt}w^TWfE6}QRNBz~H+ky_afPs;U`(FnVyG82m9jAEBtKH_L z9`kv#%~!c?k61&~4WUZm0CeIrZX^=xbqjqL3@V@OiWRn?3c%H51Amlx-Lr57*Ts{e zB%u^l??Oq=RRFUUQBM^@WkJvqEE3R~zn4h=c`bke3!qBKn@}&sA%Xii?_P>1^CFY` zaG!nMlHTcsP8~L3SvfH=X^{<}9 zi?)p_2aS&YfT$AZ#2p{A#X$hGww-(RCO^x>$Y@Y~Jum~311(RwKK@GeBHGP6^S^oD z_jbLaJXZMaQM0fs3{cTUw@#_e&h!R#<7P-6<%> z1myv<*8J=SQo}zuXSG7PNy#K?FLty`8cZgq~&Ii!5~Q8uTjp6&A;M63IlFk z#-%&5z(g1Qi||QAIC6)X2bk0(c|mu$BeqP?LYoq)RMxU{y)K2zo!1jOj(S`T4H`%J z{)2LKzKC+(IsJ@2t0*OkgEIXDU2#|#{Dcq8&b-5E=ExIujYr;-Ap)n2frW(yclKXC zI{`;GpLmXa;3=J44V$GI%Zw$ zx%*Z$7&NUHpSDD(->Io|>HqtKU2(ja=*{3?(pK~2wn7A!P=XQ9n-{@rVSa$Q^VS;; zC14A4i#2AWUab^b#Ov;7HN>vxiv06a8Q%dgLf|X1WDR;CAaa8!97+ zZ(uz^*ZzO?3}JxADVYZ5m~Et(%G3Ez1%awngRbeS@=5i(2Js?n&u(=4+Is%z!xdqX z_dB+h&!=8KJ2@HTaHM15%$|iaYem_-E!2`C#+2R^xr%mEuTyW2GI)(=Z_oBUxmBl< zEmgNHJ5V|MdiXH1th&dpw~UKmw?LcL7;JiV77&=+)F)#L`UN*1NjF>QW%oEQXT?Q8 zwe*+mHffnZEp17iI+_SkP;*t@mjnp#kL1^B3h+D`6*I?d2%*$tPN}_yu(&=9c?1y zpl0K9<|=?|$omt_*v&--hi`xIg>kBPc4lgF_16Bg;N@a`?Tvoc#`)^q`OvKVo9>dr zfa4!&wPd>Jd@4Pr|C`F-?}D9K~6YA=E{& zq%ILcmS2Sti{f~FHn31e7Ik?0fLx0Pm-LsyU)rKQ;lV!&}1{Eja# zaNV}EOSWe!f1lXj$Fi=mK?HpZM; z=|6>o^+Dkn)ig>x%x7}*?moATFx7RondjlYo57M61y=)#0PV)u`9IEbSibqC(s6ve zk02^SP02x#Z?9;E7(4d&+D)(fXiz_Bzp&Z8f9u@n$z8V$dke*))Tcyz z{O8=e6MOKfcfjXACDXMO#uR0==b|)=Lj(~6FkH%*3-gGty^oT3Mxv{n416q0Sw=Yz zg1x_r>H1l^-m*8*^?InjNPDQ#8OTuH_RDm=T2&l+-s^s|BVX}b$oPQk6mfV`+~d^_ z-*jE@7u5&scAK^GxIhqaBasAL0B2}2aKbCb!`;R~T-yR<^PFxiC*gZEv#Gm(5Fa2pP#EgTgIoENv}M$N{G-+cz%x~_Y= zFL12Yk?B>P4{+A6QJo)Ho0J_bTf`~-+#bB5oaREPF57F`NLcvqF4lTy%Nqr#pTBg6v1`E*C-yq0t1enL^Xcd z_S1eJ5-_)s=xL95t#mw5Q1TQ+cV&@lHp5I54|xbtUrw58LE(TCR2gy-bR_b8d!It$ zcbr!RoO}5YrKg1@aPa8S8Jr`HswR!HLWWYo_6(9MdyCG5U!OX9=+NiqJAOPTr`$IW zKNv}`e3O3YzVvJp1}}ixD8Kc^K5QAjV|AmsE*mTyBu+#|Tp=Ef(LRk?2++9PycPQ$ z7C{m1Gr`71M&$x=Ef=a`nCX(y4~)Cn{Xe@t6vHO5s5nTIF~<05X69nF1TkE|!5TTfd8b-zGU{RYFt{uiaV5}B z4#!Atc47xPGY&Pjpds*=@o_ZQ;CTWdgQ}M1PLh{$cU>M>fJ1!9_wh%wh3Zs#NQhxw z=ldxiAD{0}f5)L_VUhMb8?o$-WfKaWzwdLsR=e%g)`+;!U2Tu%yH2X{6haR78w}S9 z63{quSRfXqdb7c01=KqW)kQsuq*P!9AEM)f8XYJkLwKmJI%!ZBGekOnu(DTI|yT{FU$gDQHwaBd;LbY}UFxpRciJoD3TS`$f zqp#b8LxUiI%bhK?5R|UWPU7eVY$miFN`{xSXB#+TPis!r>#rf@qNrZ|%MO!S`NiW5 zjqF?CGsbYf%T9m^nRFQE-iGL`j>=D;#%{bs2qr*LEvoZ8lH_ zH^J^VXfKR=cr%pXtJCb`j0o`p$YlXff>cZ~ahC3oiZI&xWykCt&`n7X_rFUFb1pdY zcO1I4Z%g@>YgzB+0sNEAd!@g|H$@h?TJhy^fwGIhTfD>aAwSl(&^FA6A1c#NZr-Uu zrARvxGS2fL{)bbjgQPWJ|d!tB`{@o4;gUrltDuhvROEud64LwkV+cH%@!iX zP)rCwF0JK(e$Yjc#j{Hx!7$awAAn1z>;|}Khxrnx9J?g475EQtNZ~)+2Mbe30lSZ8 z!$Azd@hdqvu4W&v#ycz=0r=u|Skm(tLWG-!=)9`-UY6tE1gW*T219y4CjE)0|H_Pq ztUHoXyE2@H?c|N^mQ)XU{1c?SQ@UYSZ_%6QvcbD1Eo&wjTwL_5H*-K)ETkyX2nk+u z?tEIFKn>UYVdl$-M>fkS;`Zl36E8b48!8pcM~&dlGpK0HR_3}9Gxp)4`oZX+;)h(t z2cLpLRr6AQT)||E9y>oA1>F;bs4Fw^z%}+<%8p|ms;9#-7rW9*?`s+>9VsM zXR3n_OsEPlp~6v2%`1GrRgs|(e zS*#82{!Yc%dkIbo2ADu=&xJqim`Cb06U2`6PIeagZPpjaFdf{gUPRk=HR$qLHHu@W z;2zg;wOM+I7WntRNjFP(H1wboxEYd4j7!0GuqH@r=V|qsp{eV_-el`v?4EQYI5ds|giRF;I1D{|3kF+w! z^DWU!kg7FsMkUDnvr{52R~`;X>|R;H^ui0xvxL-S4%HwX94V;|+*!!YafIU#HO3mu z0TqA|`8NSOy9(f(b8OXBG)roXlg^!^DUzcQa#U~hxB?l+zf2if?JQirHRs$i zl-pAC#C!`3Dv;n3SFw}d;R=cm79bZ2fM*VZHH29O3;o%{%pDMH9Q){Aao1P69AqbK zzeKxUf&Y}H`=F_}Ba%g^GSTX$9}gGVT43WqU<^hOn}>?0mC!@++A_K+WRod%0ebMi zvry$b9oJ?f1&4IqOM6UVSsbIuko$Sm(fks6Nx?ulWho3aYLKuc$)|>nykal(Jy^_|^xp47c&YQ$*gu2nw*A7KKnNhyrK8trKDae<%Y)y27C6FG z0>g2n6H@GTMzcB5VB|RXv8zR4oPikvRMKIu$+*!mW@D9g0{Ev;b! zIVxZXG6OOi$U#a#5d;Jw70lMqL{6f#E6Jf0SP7Do95e?>(v;!jf4@J!lGDulKF@t$_jO(O{S4qp4QkyajNg6x!D{uN z*GWN|uF8;L^6-53E@0(rZLSOFyz}oQ04suIiIJ-ny;mMc`ZIwa3rIHK>PN-y^QXsXlqZfM13j`Ir{wgk2O0+QD z`=mK8{4&CpU4a>b7B&z{EsS3zCgYiKf#xrSx;$+&L?sr|0|Y^r-ajrO>3uZ_6@4vX z)QWfBO{P1zLy@T3qk1djlw$tTUT>T^!pF>_0d#)?vs#Q_L|73eF(5aqFke26!rf%n zng9nIj-Lv72A^KZt;eC`hi_w|b&)@XF!nJHdPYZQthw?l|ByL<7U6yn+;zmLCZf+j z9E2VGtmdtYm}v0~=bz>$7k~gTt;4zEpDw+=_)~*sQ`@f(GKqf(67TqfW261_|Aa}) z2byr84aNR^uXJQS)3B}UDRDS^XP*U!ETvE?fh8abB84$JtqjCkh!h7bN#Gn&e_#zg z;Yjc7;@R8@TXPMSParK1>G`wy(y3cMQRWI415pN$>=7+#q@5xT%Nyqu%t5_@beaxe z2mI(+42vd8?u5&iXdj~Yo;Yy=uSuL+mHq1{{tr6ZKihtE-+19uFJgee+3SWA8(xkz z*|&MhmmXd8r?(U4+5E&w`4w%vrB3k$j6Vzyyz8x084@uBT$*M<6rOsK8-{8Ez$=4z|7u zdd96+*I&@jz|LJuTM`VrM>;cFlJfkmkb)O0 zHXAqE&dn;`<>5Ed7U4HOI@rEwsFSZV%K7QV%D?^ee;@tzXx4|%6gAHcxosXP3_QkAD{5qRj^|5>1`e9Q6uRZE3=_Y?I4fR{~^6{B_74Td>ZO{>XMBM zF!Du*yLZ``N!zS%pXf11Z)qyq?6?z}-jVKT^~TaPNc+8+mV2vS9&+6J`MIw@+q+s- z+9c<=;Olwb6{!h^2g~Zvs2YZOz4eE2RpE2ygXiyb9lL=csK;iG`7v;U+`hO}40fbr zub1r7iaB`3Ez!hm`Lo%MSBe&44Q>Ba$)9P9U20xbh&Bp?UIYkO0xP6oumXpQ(|!(0 z!E2Ah{DH^4TTCZa&pV3BTN3bRP1B!!TI%M1QTKj8bE#p&W~(!;t32p^9nXkdwS|W;&!iCGSYMVb4-pW;c(9G8%&IeTHxNH z!sdyOrb@1!EN&h4Q8gP0gCI0agXcG8%#sFETXt(&;S>*xZvT1pK6@VD;i&Fw?fEApr}p)DFIChb3ne*EyRnbb#P`Ob@$hph|rvtUF}i zi@7h(Ff&Me%C1MaME$|iB@U?E)DC$0tu!BnlLOo5ZhlO_%NHb#Dey1ZXZIBGCDr&j z>9L>jlhg0>XHnY6y+wm%zb)yvZ~F8tLk-)H?p?L* z*7Yx^ZM$umu>TiXj-9R1&*cHGcDi_VX}|(&UHtLV0M{q$Gw_+~lV(dy1Co@_2IMudA;G~X3I?*laxiVx$>6wgj@q9uVNqAzr6pL@_^Ulg8^P+p<7O0<4=+H$wYJCJ3iJc zUT(ry5S~lz^N%tsS(#s+;*izTt&z3NtVnULZ16e1dQ6^w6@@8K5_xQg9QATMVT2FZ!LAIwf-P4;F%}uGStRT)&VvGFLfEiw?BH& z8*}y+!L!^nU~+XaE?Q)N%IVo7BS1^wiMa^dSNV4~+ahE6!C1g6PdXF^=Es}1EG${+ z>yRtoj~E1d%e|UZV>hj4RQ_+CSMIeAS@OrD*I(^uLHjSD}_>jrfG>hx<{ z^VgLJemNK>D=%$pL1bk9=H*+77SFa8-~|wBiM7gGZ?p{`h<8OOig=3vDdVOAQZW%V zOJ3>P*c3oK9ly%YHL=*CeMz_dfyCwRG46)|94svNDuH8mVH1Ee-J;~EK`>$>Dk?V6 zZ29a{c~wgHnXlhE`~9~1ht2+@&5Vn9DL7+vy?2N&ei^@ec1*%hi(7W%cw#f9!BhNA|Me!){p-!;88-yZ8OPPYT)O zL6mV~Ny_o-2I)=C_>Qb_;l<{}@WS@|_WVeEXecRaS*F?^Rl7=j6l< zkKVU6IeY)!z8`-pRvCNL9k`$HQ^aU!ORTNYGOxmaFaIRMZohHi<;JfTSidX_x*Pk7 zt_x6g(Cl01KOig}T zBLl!b`FQ+$li|uw4Op8~yB!XSXtCKHRj@h*!dPjj|I^KlAdp&kxgxE_>$PevyaH{Ofo)Ijwgh~`u))AHNHN0 zc2fYVr_d&OOW)(FW7Ow6-CDVrcuu*_bp8Bl^?m^`Y%;P?Sa?l6<;L1X1QO*J4EvjH4|%P z;zZ?`AY0Al$^8Xl+o(;@yxE0qrVO^=Pta|y_459elV9sQqqMfT5Q~i(fOm4QA{Ub_ zG)}oAx;(A`FSfF%nq1*)_-y4S~KIOu#C8j?u&A==j_Vc?_UVId$aLa zq^(iN%IDPKEFQZ9SK3v94U0sgXmP=b)&iehXpc-n9GDWQvFVYFJF%Oa+9E7OP9x`Z zt;fD^`A!t=M}7ytTmEaHd%3ZbmH#)5!0!b|SOi~eOzd0mK0o7yfj3}P<8($q z6&n^9g8mYWsE}(6GKzPd$AP?|X`8_JjY$+hB=zECi{ zdAuL?Y3P~2{>MO0d2mQeho?1HWxV!g_d5-9u2jBvv9I}|g-PKJ^XxBwTNE>VxNj1< zJ0-E+0Q~u`eQxGE2C|tc$4RFk&q}#}-|;m@m31Bs=CBJ*?}5_p#%8SdDr~=E*laQs zVdUTG-;YaPF*-Z^dZM?n$HA48&0xY7SbvsmH1{8*>kPrvkV%LjTxGoJAwp2TVoj12 z_!al5elFhKsvCw4cR00Be9b<$!#GzC3BngU?&UA+E=U&%muH%!`01EZtSX&BQYCg|bYaCiG_laaZAN^PupL z@=d=iK9ll|f;b8U0sgd`rpZQk^0s6Rep^x{ki8|}s?e&dqAxL}rlTc=#oO6oNgs^z zp?l#i?|{cqEg%wo9!ezv#P@@dt4|^dg#?)_TMmX^Aq)C3_8HGQ>;LpXaYhpKhEB8t z_#*m(M%O1#(6{2+^AWdz{7vM1nxhF+!w?`fP5?DQzr^%ffNA^Gc1e9$1yCPRyUS?LIqB3pFyYBbzo0@|Hbwfk|01~-f}l1H`MKuszd9I(yf@oO;8=$MhFi> ziYII}U4lLG8iJrsm5KtEMB#4ing!P2DL4xLn`{K-G4|MZFlzY%+SUiLVo&uM(mQF7 z(EnJ8c~H0rV;Hu>Yl|Jz;g_&nDI@r*w;VS%fE`;7tc$8e^TVn=l-WAEoL>MCP9a`? zHxt08J-ffi`fB%hcZvU7J?n$L>AZ$DeNBff!o53m@wHJ#sJn|oZ7Ayc9R^kxCzc2y z6I+a5X9P78qJKpGWeZFafVxa(5(zqXGy2B4`AFW6rsc*`2e)aj)XZUnlk2UQxVN>? z2v7*2hz2W68;gK2u{|zQ!YFx0=mzrF9cux@ozaS**iWPm&pvU`WH$H%=|e0ua3M=( z2b!^}G&Va%{%&()bO!yB=t!E2O`h`ZF0i+1hDVE94v&R~<5~D3Q!IjLZ}F6|OTf)n ztjTZL=E3>|pezFN@v$DGCK6IX-9N<6-did=YJ<9)Uruig9jUioE@AVHoX_3$tShpW zMf=6eN!NEON-qXy=^f7sHYd}d8aJm4SHxs>Ff{lK{RX54`ozkWQg>%}BT|>#HFf4n zfz4X8=#1fM=M1;@-Eo91D(!o|*7LfYEtY;a@Gih6TOfEOfuYh@Jt*d)kwJ(bBnWW& ze(E>QNI5=a<5!A601Ha)tjBZ?8Fv##$3PLdu6wbT7bpD10ww2>bI!Z zYkSBZ){IS)IuO+Og}|k~-xp93kzb)HjY)z>{~PMcsi4_cax)y*MdXzAOaeXO*S@Okls6SgCzP?CO_zXa2*W^k+wxCXh4S z`Kg)K8s}!`8y+y|Fzxi|O`9vFhTxc$U3P6W8U(Mx-stSMl^YAMbu=XZ+7@)T;7H5A z7Fd4=9q|nnt_fTVosBX=1BGBBjMr$szA8#VKd_LJaxb5)nu!02X^r_pZxZYI<-R~~ zgO)4v&<{dPB`T)-fH6#BBNf|4TLpv1OO@IOnrZ68n|7xRY}zplC}-_MrGkrUJ*Ilu z84piZC6}P&C{*#E!S17ma7}`)C(--}ow)#*h2=G+OW~b`g@UP&{(qJ--){`S1S9MF zOO9-vH)CU0_3Q3pchn9PrbsrNL`U`wRUU|v=>xCz7%Cr?=>!X*yqI0I#IzR{nr)^U zPg$ey222+u2(w8%aWJt2y&)YFE0sky{AM{;ctLW4KBD=vZ*Xro{$5I6x!3AVYg`Kv z%vaw1S;(ZmZm_+s)xIxEoI$p@c*?-4S$sg#_LZy9$(uqd=e_RvYvu;;=a+A^`?&KB zP66u0NU6~kP{zsthRon4ugZr$LFaLp-kkB=yA!`(~YzW6Vlo ziDGsHdS}#_H5b`q(c%$HXf}#Kl#EdFWJu*`FBa|lViI^()!o|Hw5@4Mc=mT_*fI%h2SSXFS9N$>yI_|mA+aST%>+I zte#c5VAu;+%vqXZ5izFH^BFM2iG9e4X@rR0PLmm^rpl@KhLBaElkRBC5bVKS9iq&| zzMchkg^Y9=TtHiT=aZ?u&jgy$+ZtYzdwGxig{BG(sFXH+(*q>*E|}t$fqShUM2bw%Qj{{?)b;-c4m9F)Ja7bh$UWb|vbWQ3|pf=v#<}7|sBNJ?ovO zGFgviDDyeAqqR9ix#vg+(8M*M`YoPRNJN94E&v-PDkaW2cs?p-3am?^kQHevhoQkx8@47%wE^G=j z8DHsLLp!#{D@q6xy)<-?Y%Ru4MA}i2Ff@?Frq~HOt=We?9__6CK;ngZ>@2fYfD;cV zF(xAiK?`&N@3{cy9OhGkuG$Ni+)j0`zE|z@x^w z;8C=Cq&YTbZ#ZRbGKGp-p+e*94TPgce~Q71-Nb<9%H4wQZAD)hEuCgE|J$GP#Jq~5 zgB}>Sdbk@kFp3G?=cUA`p74U*IZZhwdH{%XEe22sHHNs(aA+K$ax4O?-5oMJ`yY82 z(4oHAoaz}=UxMspK=?5Fab_A%rx{7OX!L(M^1KvtKM(Ru6L;OS9MrxQv+rzr zKZybt!T=x!39d$)M}nd6!Iv@RGh-C={KBz_(*ctSyxv)l(QNxviBBbT0Obb-4Ht*P*(tY*slDn7pwJaz4e7n()5r+K;e|d;)nGdiLFT0$nrw27_+OeHux$! z#-f#=z76P+J%tLOh$py`yP4ohVQ=)5vcl}qEHExZQIW*m9Qg}=zX%mhP`^~lE%l^Z zy*EX3i&?jbDsGJTFUx4v^rJfr(6{n90l6{zPY)RY6AnMUz2?2$q%{*wU`$>Yqx%a1 zxSz-t36qF$pQ$&kgRW@$69W4&M`v%0onqht_V@>663>-pS1})EM1mSQ&rwWW2mKfG z8!^S@ZG`*n-_?QL#&V)c5P-K(WNiFkONGe>FN%TH4}R0ZCiMrR8iJ&w5$xqe2RMW? z-&k5;VViLTg3+Rw#ZHh1xPs&%zAe$eSZq_kquornPC#)E`9!piVk66iJJ&Z0pO;it zT{Uh3dH8u$)XuguK7}R^lxX3K(Yd~Q5Jv-Xn84`>m-GjuiE4$E3ATrV5oe7LN-j#2 za2)$s2zdBzfb9_TWq@N?pAq)n6Co4Mj@uD~FUatGGh-ZD$fO}fn@+wzBfK?b%ym8(7-WxDhPri3C$V?Xx zrv(Se$;_j%B8dOg4Ka9On|0N)QP|YdpJ5lpJc4*EL)1KjF`Q2^MZ<3Q)RvT6AI%ly z$7zVDMYjI}Eh{mPW$Q>JpvsS8kZW-9s~JW#c|w%d-DN*3(VuJKH;pSd+I^6x=l0{J zGE%%dn(b3D&AnGAOcD5kj4+|sdjG^mNbm0F+}VaMpLCki?!fx=))&QI`po>-wTiUUCYV^ z);RTWn%ECTc3c0yVSogY+Rt}*L>-dMNcPV;7l&0ym~<8h+7&2+6U=#bljlrqB-@W{ zDA-ci!VQ$|0R4PE!ujx=Q_2d=yKJsa!KCB@Pkz>l@?{24Q~% z(j=}Uti0s}zF-UAn%67FTI@~SFg&qr^a3_XaHy#kTq#4GTuB5uARrVKigO2+cX=lYo1~}pY3ZSNDoKI z(i~bJoS8e3;uRAu5=P{49_&Y0FzhQPh#Yg)^_x--ri(*rZUli4F^``>R)_>J77Sv= zb_em<W3>{Sw;#ATIxZZ$n79*xxTa_%<@z~D_RD5C_j@ltB0px{ z=-!{->_y8zl;1l7D)%>y?qGLCBMXto`NIVsZHrhi6Vg05JY!bYrZq*~ml~V-P}1<# zd*d^=r?hXr`?vjnxu4Zqv3b&|IiLLNdQFkKDCJE9(^XHrzBqQWTwd%s_Qb&g12eg~ zqgw5AJIK`3tW2qh3mq{H-uL|C9Y5?|bnZb^8-Fo)>sjt1V``??l*Z27u>wdgn zSe|UVry^=-lIqICFYda&)A#B6ivL7;chsfqbq)Wf<%F&&tls-CR;r(SJ_uF2=g!dX z;C~hC%be5fWohomw9_&Jk7;)#wT9$QmaqDt;p0y81cyVZ_K~`hsIo~NyLLyZ3tYCW z4V@m4J9W;g4|XYoOQz20{lCz%iw3-ay$v3cq`PS>yJhC1&O1Fnf8nBmgXuNumRfrg ztxdRHnW1^BMcVBG=d@ts){yz;AB2|86IaTz4la571uV)wpvj=7Y?6=noI~X)-5q#L zfno;WZyQHF%^h(e8+l?t z?&LYw9V#<7r|x{Thk~TmX_-9*D&1nN3%8J)hm_gl3i!KBW$wJDW2m)Fhc?7G{CV$= zUG{iHhjvp^LV9YNuBq)(LHYHTwjftu!zkD8X+QQjuCL%O`jM!qb1t`pmCZXdbL=1^ zfmLrz;zqFCnli*?Hp4Y=I5&!4!u4@y+!2f3`NF-G(W|>&tP3hrZk#IihIPnKyEyK$ z4{lnwBkiN5euKU1w1Jkla((TSy)&1%YBxodIlJNiH23+41)nEk(e)xe#O`rl_uM4x zFfFBK#P0B`Tt`6DRqfX;+`)T>s7_enV)5O&1BkUecB!ry|009Q4l; zXbMp?%tL<`ITu^P#t`nz$l&vHgU^4$f3`o9KATU%1I-*m>t=;o2j{+h`usz?5!afG z9K*G{31PGNO;QPf`7=rXZ*7Dc;&L+JGJe6hIh0(YVZA!IH~@|hCl?M2fFCFT_H zC{qTwa`^yHKxPEq=>a?&yDBT-4lw_G?I`N{yOyx}jLWX! z-?gljDtr34e608dk+SElZR7}s6oNn0E0ZjN3Tv(Vu;F6@3HyjDn@HaWq0@tN^Vj9( z<3iFl61!dogwo;~0?x=rW~gqIy66t=8kfmuI?Qyq5qQ{I)PJb@q5-2naLlqd*@Msz znV;rvtSj+V+z33=)@E^wOyZ-SR5$OiTBZ9jLnr?KY^L|xPbz#r9Y{KwhJt3D^IzX( zRw_{=Q^TxO0rPJyHr6dZrfoEgYz1+J80%t*;9z`FUx~ecP5m-(e$8|n-askC2X*#V zj#xEnnfr^JHs|!)k^2?`o~xVw?fosE5HNx~CKKtv+8xKY6A!h7v2=0k4(+`jR6Wq< zSl9QT?!B+~m+0B*_hLcy4p)YjfvjpW6{uF=%7K-wzpzv;03yqs5af*qJ{}l5U;hlK ztnNb;NQs0}QAD#>IW|n2o&Gmn&i2v>4U@%fOi`JHmO0-#Zy2GS)*-M!%puXr+s(kL z#Ny;hghHm8OnY5gKlJ19Mt|R^rf~qUOw{~$Eho060zLKKb5^xlb?3~> zC0q41p&*Gk>`0K-st;_}|05L}N70CLlB?^oWwcBJ7WQZSyamiR~; z*koX?-;rnX+&^Fc%G+7|^37!lV!OCp-VORV}D$@DTB-O@27vB_K z(moE`vtjwydxyDJxP-stBa{#f{6T5rkCYFvmlB}o+IGK9nIM%5_Rt4u75D{|IvXXb z-mTBa`e}30XIDM53jF(F=aF4XNTc8eCI zQQH5eZ(0p1^)Y$cM&EwK9e4%enMYoHAkGE<3I-PO5^?r5WRU(V=vM7^u3=W~FIlOA zNn_slnA`>Y;P&H1WTd`8=nfLYa#2&_98lm&`ulqkz&OaEcZ8nxlA$1>mT~H{jPw4;K`r4cu zftEF3B>LKdB;ENA@Da=uSe%#WS`9j=$yi-hFqJfbxFA#%L;FLCvnuipRpgZoRG<){ zc87ny)!%P^_~`0OEDY4O<9grClAgoTj3y4t81E)Slri;P0ku~U2t z#DffHVgaEeZ)0yLd!k2#k;M%}G_0mdu(L^ zFU8zdNCYtxs(w9nZ&b!_cj8W$Cbo#hlT0byf{9!GksZ*yZbloMRs&%H>M_z(9BZdSZLqN93vNpuOlHn&* z5aS(5hxc6!%g`Y_Pn!?H;JF>{Io-IPm^_|4X&|E3zP_ZpOY8997Ll%N0 zBV~N1tz{K#@FUCssWv{=hsp&ZN^W$5JuO#Fv=1)pD@61JE>>YlqzD0X7UT;bbV6Fv zcGC4>S$Gh`6k66Yd)2*_OaVj(8JD&p;7S(=7)@{~x<0I0SJuBsJCr(Lwn`UMw#Vmz z^+=>n4x0rO^RloaESe1pt1a>x7xhaOS#OmiS373x!j_!}@_lbN zwGI787H+xWXc`pkyOy?lJvwaxv>4kGBBE{dR--k&P19$9P7r~B%Y4nn-Q)4&%S#)`>uH9`0$NU{PwTg{MC!&9hDC|@ayZ``u}fj=Y&*D zS_K_CFPsRlDkmuBou7OA;lA{fwI2$L$evj6mb-B{oekN6Dg@6obCKPTJsnTLMG5zW zuZX07uxoq=m^35KA%H$Ya24SOlb5zEGZI!$_zM7(WXh^7O+F1hUq$o4h)kF*l&-#N z3itSr4dag>-GAro=xzQ^|KZW^{m%}K@s}Wqzmf7&pfyK^}b$SUJw4i*bD9uH^M#OM7PYTQO~o4h~0)a759;NyYk`}gmRZ2%WCdn6&Lp8)YHZyych^rR4fK5gdczL=4H z{9~$jI`|iC&z(Ex_QsFPvi?ffk{0KyO!ls`4=|3-h=&Iv1SAy=sS85K@R8DRLPOy< z!G|5YCdpOZJIWDqOpAmF=`a(TMGD`Rs;?y>`!fJZ}6Et$!-SxqaawWJDZ6@YqogxVRFT#a zstCsl{w4S6_3`$iC)Uzb@uB=4tsfHbe&>;_^DI3vC856q!FBI1aN&@y>#1MHn-|%Q z{P|&9RHI~P*%V8(3E49M7^$RdI+0HrG06*XQzV%8Ndgi+AKyIpUcdGu$F{16-&Nrc zS3d0G-?Gm7d2`GIY^UaOQ}!=6QU>_rNLj0h)PXNDbP4@mv;`XL&`$4ip6GFLMV9dc z=ia|6^ah(=#GK5z!QoK302xvZ5x@1|r7uI_jZj$*SS8Tck6%ffZ^bzrFeY{xrPu=m1>mkO`we#4I=(|-E_A{s7Ug#16$GUc6AcXtUYD-&?Xbw{9Irib* z*LIye&q)A^jm~+FdF%KS(^B z4EP{yMrf&i=JZjwz#ISSttz`mmHk^{&TkhFdA)k&<%UmMc2>ie=yHACyHW;@W{~5Z1BWdIVUy2t6i`y7~gs-c9?(xfy`wi8#zwyi0OS5uOCk0}9)+%|$L!qF%4Xvl?W+np-NSIhX@qrEkMGTR!@f;{@K2!DEadHchs_kD9*i%Ne&h zb3$0&9sSxin53H+_n#M6fV_$DZ-3^r%Llt!<_5#93%X(Jfy-a?R$mO0tI!#XR@X*; z%W!2#?JOzmxW9GI&dGDc@reX32pXws_GzIsAGORCv>_gjsH2oDSNWNVIi3D=L9_|z zG%)Gd_dwr<4rno*$(`zx(JhBVt`Qf+lf`U$;ncOe1czYm`8(Ib6L|}nWgBYV>fdZ7 z>^l$-ssc$Z>r3B-VGM|fO|rleFSwfX;Q{zI_)y$MFfB`9c1>*%oTDusEh*Vh!}}AENoOT-DmMAJVXIC{i+JoJ{+uQ+R*L__~kD&s3TvC?0@_n=>QWq~WNCFdwX-#2uDXXa81gD7W@AHl^XAI8;6SIeqto{}^Ldj@Z z(pU2w86TV$J?ovLl9WGMD7YE;%O{<%si8B$;Up z6fe4eFh1`6!dp`v-m)lb*!tVMnLoCE+@bCG-xvS)o^#h_YY)wFN4_P5A=Ap&(Tq57-08HQ*vjcY>`=n#_(>zgDqLNta|o& zuf_HA^E+qFRAFg#X{I&CcJ_*8gzmDyz`*#T@~!4rUbBsP^V9JLT;63<^B~-CVy&th z*701ME7z`m4olS$0CV%Sck=T!rp@myzmSm=!W(N}QKpinK+B%-P?Vg8mOh7me@Fz#ZBe&+&kE#wt%#c^R+UQmT*_pgTihW*bs3=~#0qz*JiGW)3x zTQtt88{X3dh+KyEgy3?cI<30#FDGNEmfqwzi5+ih~@SBB%=<2M3)E!?txU1F3f0HH@~ z1Mrh&T$k48!$-^XS+c$iEQA>)Yx`P{i@PhrFVBn<*z-W%QCLNB4=n&!-kgg!B8u>~ z-xssS?QQ$=>P6WUB5bDI0s?7g&#Dk0X87<1?4t7OQBawkhB<@AU3UQo`@==5o`R~w z2E`V|k;omYQ6%YH+g@iqYz?qk0FHP$MB;3E=gds6=zG%g+7Jj|PJGyVTvEbRYCW zM7L;mXKZ|EGQ1rKjhfD7q(T-#I@gTbj+t!vl$@cL0eltU0eZ36fz$y9;Dz*BC`ee; zHvnY9YD9s7oV|<7dEZb8%3$00;Xt+Qb3vud{GCtotj~~bDm1K#KvW@t#+PP5G01uF%7C{Pz?N=c!UIpqlWS%08><0dMrL81?5?HE1~UN zn=EWbzNT@n8dUK#)yh%#xvqq?CX<#ZF^DsgxgKlsy;o4Fg@y+Ra!jwty0tH3R(KCD z304Onr>!0MlaNZk@cqCJwVXA`w5mMvvu5ex7}LE+V35d1hJRf;*5^NBxY?ji8HplA zg}6}3dS_Jz9h>31n8^cS>UBzwEkPF$CYCn>uRGtke&BjTpG|sSbcDvDKhSsZ-vOP& ztiW05}9>hM#Ayi&$r<2w)J*mO82m!B-!PX6 z&7DZ36fT#{Amc6p@?VGCaia_+Nrhqfbi8GpbOqU%f@DIbb&m~15A?p(34n>Ok(0=p z6ufql3>XZb(kRJEMvw``p6%VLG*elsDTJ>7f^BmcEt%c}EDMy(&Lrc&%Z=yS7S!VP z0(+zDqh* zh)0KN*AJv3gnsv8^>-vM!k{@s7snJu_UwaQ>hjL)*-cicHLC)z0CqqvTmVdxSGe8} z9WV5Llo+HGMfMj4oaF+d(sL29Gy|Mnr+fq*p)mr5k0FnNXVm9D2M|-3a?k$dzJvQv zC$KDtE%ZTfKd^10_O4aly?HCaHtT6gKqcZL5_MBp7D6pjr92{aHiDdBCjd;LmTGmq zZYi$HwGc8`+@@{%r) z4XF}5hK(0mQ}+zk4ixG=4s`_gAi?zQp0F`e3FK#~N4GJrpgWWWly%t|L&&wLa%KwU z5USmm7t?Hb_BmNP+5z&2Xa9xBf!#J_;xHrnA65alWRFv7-+BN6Z<4V>A)5~r&Oke$ zIX-3p*IlH7R0DB=m)%AUSq%U$`vNjEAmK10AJ%}5UC5qjF@!h~YWh&2)ctl+haYt) zzGiM3i2$sDc zIqV=zoZtZ?#ohGLp~x}90<8ZuZVR^?3LdIj+;g)83`FOrXExkt#=xJ%^O#L%RJ4QM zv4B1V<@ReLn+1DFtj3)Q6J#y}poDH9^Cc5m18Hg@SYTg53pf!)cSB8*kaR%cm|*lC zo{@I@rl|0>^f%-@KpZU-_sSZTo&{KuKC-;rMq6z^g-J>5N!QFQQk{8vi-ukxTLCNn zbPtt~-bp>HGNcOut6|qcmL#cqe99u!5PWOc-T4l-q6~NcdgEp*Y(&3?=>ob;l`&It zltS@~;@;DQ0jaDXX=Q1q13r?ON1@}ps7_%P!~=w{0%*wWWPfQpnQvyP|C{wZQ~UNA zu>{IdY6xUBDatR@E~PJ;!6?q7n_!~#0c8Or)2xK!V-ds2B!7LYdPWhmsDDp$rO;yu zZb-SE{W3fInXj|k^9z@Dk0Mwvj9wne9B)GSaceXJ@Jl1Yqzp>#)XDfVTOHh1{TxdY z_6E{l0lh}ir`u*(0lf$+VhZJF7b*lJ@bZmD*aT}B-nMA~Z&{TtLWC_}@=q+8?2XtU znqL6}iZYzfV{j{?ns`C6Omvo~??{SI=}NhxR|rWIQ5hrlBQ{Q`J4qVgpoKJ`ef3(> zWo_K0w!S=`e|EzZD8Cvj$O=MNxOBu~g02V;1-t7>#%B!K!6KMInx0Fbr^EJw&5#5Z z8=7ahC-^ksL*U`-g%>?scQ>R#ba=D@OBp0tBuLd5>60=lB1Augi+kx?Ms!q+zShf8 z3KAiw?;)Ti0|7EcDjI&lLwg_fMdnh3M6ZHXQu8rr&>e%v5^b5D)X4f5*3-sHz(SU= zYBqXkDPX&A-h2%V02ZL*qWOR=YJf(6dNwZ(Dk@fn#kBdSqA!vjRj8i1;@AxCX-M*^ zC@?w$%vWG&m{FD%(Mq_wjJWFRGrN4$r@8c2q;Rj zuzS#FQJ|?cXtNv4QKIahyQfU=q6l2xO-eNEUn0r2b)Ycz;0pHMzZYM=3kvP6JoOOW z{~zoE2QhG$fE>_FW~C*aNOsm&0bsg;TC416VR$3*Ked5#Bl4w*i4t-C947C3XjEko z8evhIj)Hv=KEzL!%{chid85A)#LY@T_@ok?A;vOPdR&OC zcXl42Eeg@X2XhzY;o`(V?p|*=w9`huX0>2wlM;M604VyNJrge|yrx!6U2K}~pS^jO z-9EBU{!G?l+ye0PP54%p9P7DrYhP;Gl|~H8r21nr@rE*I1J82c1u9z&(G_wrs`xb= z0hxiP>A7LdeRTM3-Y&&?=+!dblsKLACutK>I#7u0I}2H6Ge?IoWo-`TArl0E=RkbG z35YQUGaOS%)Gz@mwAoma=-yE=llV>TwBkJV)|6nq-8n9r{luPPYmyc_GC`f3NQ^#} zU^{AnjzzE?;#BTUii9>%myk1|d0H=A^IVw7BGwYj;RDJ=gPe2VB6Sj=$-tgi@*19_ zXQ}mE3A(lKNmY`gSYmXS)#oi91|9v20FSIqCT2ENOIs7kq{**M|DcfX_zSNO7xUo_hQAM6P!?t-g|-(F#o`M(3TP$=v!>F)RY`) z*-&gaV@&4E;hn(+h1Olxhcj*^V7SIIhTbEO!vL8?OH^yrlCVy7P`-O;A5u-zuAo$e zIiw92wuxIp3D6W^5{Iu^lgCmx62mMc7QLzHQojEcJ#f1wphA!W03-4zX_zk0IQt1) z1tx{SLia{sDU*%v`ZrSrMKK|~0`Gb$#}(?NL9Sg2<}yA8#Tamj=`L$ij015+wq*MH z6I9Q3Zh^sw?}YQg6v4a5hB%XE*c|LCK|9RvJvLr|8Bm0Dh={S|gS0kWr*sRf6NqO> zhy#WiKUl_bb826-xooB*2v3luJ_pi(OFU5jNYp5j?QQS}s&YD9msW#e5uz(Pc@D7Z z_2keS*ki8~eJ^_p5<0@JP>?nSdW3b#BDZpuLEh?GHg>%Xt2)E?+g177>*;jHD^p~&TclBrH7%J-w#v~o?L-s=P>KT0*F>d zVj?7>6OeP9002*->_d|Kd_)6_%}I|IOaXS-qGt9%};$bBKgyMw!mj4B)xv=F)O8ts!uU zbL9QM(qp2=6I6sJ&t)+2d1!z!dh8*}!eUoxNkdjf$Z9UR)Zw)HY-%8hsPyw~VW305SWCc6SCB1cnb76OD7 zV43Kl#_h;_gp0$y*p0;Om&DcQ@o1i3V3;?$9u3d&sP}8^_Y{$rmH->|5jGYFa zNb4{D;k<7o&~8XNYdM&qEUc~G!t4`AK+$>#=nS0DfIfa#a22f=FH#jfa=YNh;6AA? zX)MktFt)DL2cHk=#Yk$W$kSOrrcfeVtVVROkLGRg*}$p4#_(*aj7mq@mw+PnFmiD( zno*Hz9>?+Y0QC;MVn3WyyNw2jkxM$JS7-|YFZ)|C{o*8zl1)RS6{11v5xGH~(NW+{ zhrUJPO+lM62jLJhyHDS-H@=Ly-{@O7Cu5O8ti%D4@KOwGozg$|Q}hJ%_F!1#0rJk{ z20ZYxGY6C?iO9T$)U>`aKH|L=+nJbaak48T%Ee`Q{%Hm>eGIu{+s%FV!iRCItZnINBcTnytiT4ex*kip zF(LGY=*YmU^#mo$EFF~(Ux~2>_arm}=Q3yvBybJ<2@S&eMw5OVd-ji4%Vf@{PW>2n zxcBt7ll31K7tVXZK%w6C_>Lu}D|UxBoxADzmHY?mXRWlaCH_$TxWZeh&08Y(2x;6h z#kcfdtHys_l>Wv4X5Q`k?S8}M`;k9?cXE4-)iouKed5hz{Y~3UWgI>xnWu#Wy6#mk zY(^+0D}b7AH9BQvB1do!*gclYPmFm8rN!9SO!2x^^U$ zdYYH2*F-s1dpjr&RnVcRSFqILtA%{b2mU(40=w`}yxG8zZd?24(`zw!E%ub99=DY$ z<)rTAv`Ib=$$XB>C2cS-xw&n6-Hs$;Fla`SG%y%F-;-#6R>?&M)2;TM?1Mw=*`iOw+SV(-UrKj@;Zspq$MDZh@=P(L$CHsE6e)z@JOF!b?qzU z*F@u3e~J2oYj*h)Pp~wl;ll@7U+u{;RmT>e392A<}B3NaSJ{ zhG{owr&y-%UE^D*>3Mm;J*^C|2r^>g8OJJ=orfmg2Ip^{L0L*X#gk?V$!?HmCYqPJ z1;m?~*AM`})N#HKb(!zuN!;RhIZArIYRFP;W?Gh_&s;@XWb+OHNy7OJAB z#}~CYDJsjebu4q}r)(cD;RrhMAU2hVhJ$1|4|g0Lh2J9_#_f4MB^o` zlOpE1;+BP2kjPZ1k$%Ti<2X@0Qc0gtv}c8uZk~H8*w-uqXYDhvdyQ$@T(U>o^h_h4 z6ScssnwU{K>cSaq2>`5fOzo4*2hQVzYOJ*#>jLBO4XCLot17Kn8?_9eDOE3=8+gx= zJSnZlg|HPBsC#)}Om`u^+_Q9M_rc_gO3Q1Y5uCw9qi$(9)#`KLvy-|f%}bMkL%bC$ zjPV`nD&DbZ5qXcS5Nw&`HLr;8& z8Mje4(M2kJID8=h$vGtI{Sm^G2Ap)ekRr!K;M<_?+n!ylWZVxdF1_@pU*m+FJ;J-V z|K_&H-h;`V@!JurU?V*E8ZWK5@y0@2tPGS)gwkb^7Y5EB&)8VhGCx0S6WYO0#0EB> zNCbbO@R`NU`kW8y>?A|z1>&w~W546H7P4kcRpH+h~7vFu;s(qoVOkeGoVTM@wi;zmvqNj)h1eryd=Sg^~DcF~b_?AQ#}J-N>V&40+uJ%O~+wNLRj) zyMYxY|Hg9b=;?m_=S@pj#1HR65PmV~z5z+Yl*0z-aNX;r zz#j0&I3YIJkK)Q+Kt!TkZLmHtEUuHfU0FegM_T8eQuSC=V|d1rVCm~TK(7yoSt{0C zQjY81bF3n4iWmVATA%8kR>r!io>Ez69f(bnkASd5TyEaJ2*0%w5((N*C5Hc@QYPlSjim zjcMtt2GiqVQ3PKQ6265f@47}%IHW0O8B>5M_ZC6BR++G}=8P{KuB&)=15?pgCXPIC<(4%1ALofx%*Ml~cE^g2n z!P2I7OL7ArUc7=*CZaB>5z`ZHURtVqCb#p4gXsg}hvoQZ*V@NN{Kxq-fH}YH88b6E zQPgs(h|;Z(CBhD0H@|KN%vP#@2c>9##ai-;Cw+@e4}dP%j6lDA)1nGEUxJzXEaa0Y z7kKf2bhunXW=}y9*h&f}5+cbo3(iVLMI!W8{TCLF@W(g&$8PzLjkM>SxqSbZA1#tM zQXnZ1nnwCRBx}EKVMUoId;!(1Wdo7vq(~&f$j@Nn2kVCCP%5j8Dl;}-W$_X7m5pcP z013nq<#tY8^{%GJR!}BWKH(+A#UN+8N#(EhZ#tZ*Iy`?vL2le7l8byq?`Hx^# zjMi^Ue9g#O%~%$6cg2|n1YU#Bh&fB*5fNlRRTE}Z1%rtPl8t;EuAS{h5t64M9P=|} z@GhvF`2b-!zMyAop;Gjl5843gG}XvYiw3g~S61eT9}w{$kz0*cj@wm@*5?fM)?NfF zTEare#6Hqg@R`B_(>yLyuL0A*Akti7s}n|q{91*VEgS+@&{asZIR*nid)MgyAaNYz6zl?$DprG{dSdY;w*c3@z1dSC$>Iutim+!1n7b5p zPn#a?lK}&2Kz~k0Bi-eaHa*k@_JMB_SxN56DVaB?#OI&1Je_f8-3e$NNIBK?tYdZ< z%^_aSD4qh1pxBh!XivdXtzV@>+t^Ho@1dxC9}l+Dj^l+As~85%nxn3Is?@0Z5*M)R(&T931+`Kp_%SO=5tt zrA=E{ZlirqNLQ)~v?mnk5m#gX)b&W6g#;GKT#+q17eoEcLC2?tLn*tWSE3|xsR`va zf~=i%*)?+m$8P0!hqO1GK54n3{NKfJe^7x(PF{hz*f}th5z!VA%4o~yX zB(UkOhre;uWeZgPkeR8Qjnm-Ni5$ zyYCMU{kAh_cxOaJM8m$8-!upHA-{wk=sn#+MqH05hL*>0dpdXpL2am)treHc8rPBx!ttRT)AubIPfXr0gj3faKEfj;lo=s_v|@Izz+cHshh z@DozlCC!t-t~~_!!jf-0#ffjQiTNABVEZMiz6T^W#Y?4h4 z8(mtC8&1N0I8}pksR5F$Vm*l3((Qu%r%y^~&)RI+uK}9?R|Xx9FtSo2x)5Q}g`P2! zG(?yJNeT~XQtlLI#H~Yc(~gcmKK2~IMSg1fLDn?cHSF%4x-GF51Pn3I$L_f zEyty1=D*Z-sN8LZ-@EABBOp@<4NL-TAfq!-h8O}sXa^+>ijxGA^BPSf!-lRF$wwL! zVL|bq?&Z>*Wv_xD3TiNIp8fX9o0&2;$oEXSI*-Dtag%_^_@nFWn59)$yAZyt)7 z6f%+);%AQgQFThGJPZdYb0NDMAteiIcc5k$Sp*q@yQJm^l(vuqrl@82IJgp%9)I=- z#3h;(lo)4BcrS(*6ofRDXnIH(LoWyt+@rL0Och?H{UJ^R=}W=ZAc^6SP_V7!2BgYh9DN*aJd|;C(^LGaSr91; z%<^6vA3qif?rEPZ(eIK`eL;Qrx6=8px6>T#PG*-$^I#6ur8h{2%PgZKuTKDXl;d!$+K#viI^VrPD>gGmSc=(HUEQ{h+d$6Jw5X@D}qfr?r^=rG5?5 zF0}%F=5^(op7+97{OH2>C^#X~!!+iLhz^X1;1c2%8lZswXZ-0gH!NSWK3oe8}cq{*~Ymn=8_MefWL&M zc7{o%yLm1|1`A6}SjR3@ik=u;i;)FdlrP`_7Y!c8NM0%c$gw}M$LCj-YI^P}p>JuE zI2-|Y8gyho=D(37B&(+LsY@~&_%3HsP9ypq)CnqKb-9?1RA(fLCrM^Ys(%bc4>ia~ zUZMNIQA>4LgQ-6vInj55VaXa^ificcq~iqu9pRIvR6l=|a(phwy~8_7vthygyDwOP z<8ttt{{BD`b=$*)@||UFD+J|GW(4f?P9YC7T{>=H)r0ec{07hB7En3;#tPCjV^g;y zYbTnoavMxSVBDm9yefW_EdHwQ0{!~yEca4slMz}jwL0C2PHzR~(rlq6)TEUOTO&-t znZF7*|Nkoc7N{E2w|#!0om0Dm=_H+t8ReU^o4zt3|&_kCU0eLc^+ z?N`>3WiB6=S$$H+*}u=|jT1UFP2@1B!FqpS1fCAcQcS@bQs8Kg=#1fZxR4+2;PSi7ubSfYhy;qPKI1Hy)L3ke zmUHlhdx6WNrTBk!rFLXpe+m;24r$=LEzonO3Y`BV)^w;(z8GGG4h?a<%K#EbI@mej zn>bl-h}2^m7qPr9Y6AA?FwD&ODW)riWH(2dzVa7Q-)(l$91VmV?wXBsx=r?S1X%$ZIW$k~9}hmwLS&OquWP!Ckvaf#MR-InxcjxGJkXgKYvZk^a` z&G22e8HA%iIf@nYgXBf*l&<^tf zp{LUdnX{JZ7Dl^l)R!Fmz^dUCdI6LxH3<#X1~zyhwRXlj;Z6}9>3|%V=Wef+I@}F; zAgow6O*IR;Mb3oUtnUMPxZY^l&YEnJY~u{V0LEQNEzYJPl63q)y`dp8l(vnyEx_zW z>3|U?SF3*t83|HH>|d^$*yq-cMD#bvIvedUaRmIp6@FzYziWg+#^~8NZjKcVdhEd# z{$>Cp=Qu}&pw)q`N)D|wt?PWXqXU^JHU zU@$qc^&}A$kSie z7IOISiw02lTLG|r|G!zl{`AI@s@X+x{`LjVv**a(BY6w1?EcXX9J|>oGY1-Ebka+H zH^l;ECxbUz1=X{!OMj8c!DXX{R~~Rbbiac6#b5xQ3f-z>G0wQLcf*Y}`+wtr(D?x! zS&fiIn?lksKFj;X;yujo{dIV?J=MO^{Pjx9msBJ>#s%( z2lpy`f^gs#C*5{|OTpfbZp%P?7%h|ijT>8dr~Kxwlg*nbI;9 ze4sJV?!pjhw0T2hO;AGg6WkBRnI?`wXdep{qkvIz2jK)qsf2qED(P!BORX6EV|zx2 zYnVk^Y!^26YX0R8sdOlH*qCRdrmQ=DM-qF#kLFL)9cP|>t2?u0{_#J@W;Mt8ehG5S zn`|0tdnVzJ{j++`6rO)MC#_3D!cpP_3LL)k<^DJG|J>zWo;Y!JlqOxzkwYV$Lr(qCD zo_lPdtB9kc5=yU6wkVC`vn@@3RysQWn&&kk6TVlbW-6)o>hY7*px(ni!d|{jAL2aY-0;OWQfU`GsY7(9b@HiouzI^XJQV^ zd#p@B1qM);XwfP?U8l2S-PD=z&YK8la^#t~{J1Js`!q_dEtap4TvT+`O2b2H9?Vk>mTG9VnX3eh8d04VFFIqT&8%> zjWT1Jrfk<$HkR0dN4Sb1GAF<6i3&qsb>1n}_}*-Oeag0=t3V34MBbF6R8y_!RYDABc=Mjblm{0BCXNS&WZ$%Ohbh2E4I^ znM`*6fgvk-7D&xQ`Gzya9Y!rc6><>b#$|zUL8XSzjkx?4!3pJ8DhHZk02U_uC;4iX z85u$)V_$&jpK8vG(k^mhu%+K4G#AV==Axvslz|elN-9q37E4&kVdKBvbd$@_nlKew z)}!y_j|dI9VjE81KVad{fq+4cED3&rXG_LdYfb*vF#aRWRvNcUaNeYp16<2w3Du-* z+Qcf!3*$$Ubv+F+@&nMYDHxcV%LBmHDu>EIanhE7vy5s7Cj9D{v{a}h3zKE=+(^hW zGm7U_$I*hJuHXq0&Y(r2r7yf7dIQB|@Q2A2f0w2z!`oTL!lo$}J7waaAfxp}Bq)@lXR8Z<_)m*8!cRlXnfQ}TRR@gl_v~2ISZIP_ktE|(bFtjp z7+o%ZBE!LKW&pApQ{&|JnG06`%Fl#mQ-2kj^REgp5njo(E+iz|fQx981Kdb{nT%-E zlnK9WjoBmX$pFcwaaQ{Rzx($@uhttXnyO2NitW}fk(4n_id=-JYo2@M58|aE9wJUk zEYpAiPu@RNH6&e(mY=Esxf1}I_bu7T&2yX z2F~MHs9DN52O+X_QPqqY+Z(ia{PNxxkN%?4qv=mkG8Qm;3Rx9z0DdR)-(P5oAjLuc zRxXY`Z$dya%v6)rP9`ZRuuRErjh%uK_mv$cCC~;#Miap>Sk_vQkvu~u53imK!kH5# z2rWeqb}`lJJ5Q;AuORi6w!aQkPitf+2Ll;$O*6>%%48$@RySIz=)-L0YAV%uPSACH z>x>mNrHP(m9HI~m*i`bd2$UJ{1TiPXE!J~dq=!ft_#G`b0k7ga#n~e%Hk>3%3ND<& z7(k{0P&o8j>+>~)8uUnlRHW{4f1x>PW% zyh%R&4k$@Ubn27IN{>F}1H(&5WJ&2&oSDd*!rB76hDQI#bWNxs6N;cxm;%CZsGE+Hl4%x{f zHmMJMw>G5ElT3W_tR4Hxq7=rxb%p|D8+;K2q=)~PD4QtT5k^h$SjO6G9mPW zUFwn?YH8aSvoWU#@JBwtN(`BFUS_Y5bK{kME!dwVpdIURL=#_FVfbLAw zpk&MO55k4rLt^d7O$ZqylsroYR5;RPi<1_U)*RLKtUTl&<_Vdzg{4kmMY=GafC&kc z=W`a*u1S(IPB2W6MTZAkkZEddlKZhxFvg39!cuB@lGmeNNuI$k-Z+%5a8V^~^Xc^z zz8-f{?TF7Ql9D`kZjd;gMM78#q+5-e^U*yb)QA|07a2)zjkc2(?BUj`)EqV!JO-Hy zVLO;?69`coY}j5dhco0w|$C}atU^ch^dO>7+dft{V z^j4-<`MVXTOeyR>(^1eQKK$LXg72`Mg+(?MP%N}bli4zpl?K+n6J;H-7#L>x@iB!0ig%Oi`_euI(xd=Mnl4)0*^=o|FD*1DQ63%?S(JYYX;t zm&ofBL=A^O*I(Mopa^XZSsRN$$v;DN+{U5cP+?*W**s$_m!-PB4|UmQFcj$8b9e}{ z5D9_iF%1c(5NQDV04cQB_4ih(YiJDMeOg(*2@BqTdT5qDH|XiQ`cEfZbs~EndXIb> z_>k`HH4RZCG3H`-aRO`Q5>@QaY>yHONv1|+T&AKmewEYTv&y3Ot)Yd3GvNPe(ZBR{ z0fb!wN)iYg+kBS)_2w7X+pgT75z#PMZxi%%w$Ibw)?}rHxA@z4pWO1|x_0Oj&k$-_ z&>4ujaV+=+o58hUlpel+7LUOBA2r)`*D>!nbz|D%oDxL}E38ldyDVyXfY_M7>aAIs zk?L|vQ9T>z+JK75_E#VPqYZIWnYbVXWEZAIeW^)rf0f_YbS`mIrNmXoZqcHG$id!o z3AXVTckkYf=xhHmH7QAn?Z+ORJ4^GZ#b_UaAD{j!)3#)=C7EzkT^_&xS2uTN3nk7l z&J@($7nu%y(AqP|x+`3^YF(||l#%EuU9RS(Q3?!qm>q^VJ#H4Z$LTEWz}-X>WQkxz zOW&8XSoQ5M=S33{#+G@f_wU~?)X>z_)X=CajIe3k+rBgXMP8sv<0`N5%PY4c>+sA_ z6+`R*35AafIVsB8OY^?*%yM)`w`G3MRL=ZamJmU)EvAk$mW-dQtae->8x9^wnP10wnt7Ypmn9pDGxto;mt$}wb?qZc`D|vNSf1LEy z?3;b{5!H5m>s?;$ZitlE+1vT)-9rVvShiEsPP_&on51qiy-_^ec4$U;z`H+wQFIvU zyixS|lFEwtZ;mdRO0Q&{t@h$39X2cK|I^*9@b6>p-~aYQ*8_vZ%9Bg>rh8y6z`t z*UA1xKWhHgnHjt3d^{r6i+#Lunk?q5ujxxR*|)^D7dINBrNc*D8v7d)9eN%wQQ*0R z_15`E_uth?+xw{^_OWzVYwh-i$iBAPE4~%SjDnv2h6#0Jql}v=wZ4gV^XAXL8UDHD z?$m|C-c>yUd?t8w(fdUEyT&Je!bm`ECj)Ly0X4Mml5ez>xa{iUY9FhWWnq+GSI#XAN zFdm{1J#;_1KswwJJ@}$wBsYDy)mLY*7M~*SeQDi|cGUXscdL5#pWb@A84_Cz2yE;= z^=ypJ&}(_K+fCvZTl3q7x~olMM|$qaDelF!FK&l^OweA)IxCIrh-irTRAG{H^KHCM z!J8>}7JNwE*-_Y6AJ%w;p6l>uhPwh{=!=&2UGTbC-<{SsdGh4x+sl-ShhG#&*8P}b z*Z+FI>x?~yW?5pI&*6uHur7=H)9+@Zl2Il5#`nG4S&g7PSi^yzTmD+TA@naRQ0a|g zbbp2mXO+;_&jl#Aq!FwCEG?Zla-Zm|Dbsz4s^OAtc zii#?wLR|rSQ#`KtcsalQc~FkFx_bXPhcD+`&N;G%H#ZbTHVjnlZZDROd`ORu8W|cm z7O=$GK{Pk$``kJ|q06IFa}NXaH5I#y2Va49;UAw~GC33Sr?c9IkSCt5N>1sgZG!8w z>_4A}BaqT_PUb#a-~IeqQ7_Qh_-++9Vphhz!)gv)Wh#$0?ey^(Q=7lLV`sJ9?w8x| zD>+G%kAJ5hJF@##=(AyZ%mJ!nKTzRO^kzyhc=2@eyx{z{>s}YXzqJ0AWrlTdeE~&5 zpK0EX(Yvb_CZ?>EC`P?o9rX?ii$sDp4!5k9TX%hP9aQl7wIGO)x!t0n&bzCL|6B*)jz8DiT4!ZxX}P<7{qt`niuGLyyVoNuvOA9t z*;`v$UJb0tbUysmneF8oVDfj%@CP0;5ljiJFW5uN`E5NbQ(oRP(%*ZU^zsJfGpvN62> z%^?*h>AK&2O1i5ZJXn!iQB?y2gJ+5SRm%dK|I7$_c6mcVn1x=?S@$`&{9at&Lfm`& z_}kn%?yTXej-jgaS!v6(zW!1cJp446*ahTAYaJ;^N>XO8abj7O(sMG}U)(Tb!~@U% z=&N#&?$ymGo9X7|WxBCI1knI%P};o!Sukb*!SCxt4_*E7VStCTbpB7OdX=+Xr*9vp z*He7gRjIVn5)>dVXYBlM+DP)Q7n^p0kxG`Gmy#1p{$OE5U(}mP-nF^@)we#R8&2^TzMBfX; zJA}PCpf)4C=`1?tCPYeJZQuAwVG9rxs=%*AKE9mO84l=cf7KCoe__)fot>Sj3wC0} zl$8jlrvCFYZ|Oa=sO?B}%)bY^Kct5~U8Cl`x64spn==WIg?Sc@HXPl#U&pUfg;-=|!LZ_{L^)?eEN@&VG;P!3|!$anC!la&VJF z^puM~e)%Rn>Ps`p9bvcW?4c1n&|?Q+IJ9p={;pTs?oLr#zin*e%e~!?6z%(ca_b7Z z%C$Tewpnkis*dW-4azC(?R^pK(0;S=#OyUYYI%oHwtiAoSNl&`l5AREG~~Ybk4`_k zw62eyF+t|Ywk@w_q`hOLogRE(KUi0dMsQ$gpVro!dKn>a1tylpABK)V$>!$lc{DW8 zE&W(L@)0(C!QV%h#H4m7d)U`)o~PmO&U^e_gEqe0le)sKGYj znk)Q!yhGZ%8jsjqUXy!}?G$iHKbD<&k-8oA)9-UO7V_^+T<_(Th4lZjdgDNH`j8(~ zPS{QVK>1D5!t|M}qm%!ZTSelWx%~79$x~}?^@M{54}O1n{T?vXs_OOY*VvQ9{QUFS zmmfFw-KK}Mzzy$wUkOjJHXGn-{s}~NkPcLPEO@6nV)o7I%hNS9_OzVO+UC$-q8Kyn zoA1rvA5h!aPo3$ni>q}YBS&0(AxWf&9?@TF3=$XZK>rDj{J2iTNZ=W$dep^@U)l24 zMO6Pe_6n^c--Q26W}3kXnq~CzT%vtAS`Z#$k!XRvMBfZNGyyXz0gVZUy?-0_e^ z>GQ{Du$(R#$NR?@_XZX3DpPVbe;;R%PZ({(9k-XnOth^Ec_`SUF; z^=D;_TZC5JFw%R&V^LRGACLq@-GNjP#$H8q6e`;FJO;Cx%Q`!^EeqVX?dU%MxPlO9 zj`aRAlX+WThCR?bG=`E4Zph2a-`HID>8xU8Kvn93n?F80@oM{hZ79b{z`FBQM^qoW zH5tg@q4Hq!O+G%ak3n_come-gpwr2=>&Z$FpnLX)+sFSi7n)DhYdM{pEf+4 zJ8SD6wdgLjBQE>Bx4~+?OVv6uVM_!!aDB^*-jTlIbhcAAwS>sGuRVop=EX}N!o77% zupfcj^ezk!Jtz6~0L+TX)}n#;8SW{U*WE}My~L^tp1!^()8ssr+pB<&Aqq&=QKkbekJ9eKssb;Wa z2RYY{9c1UI$>2A8nfD%oZxnXQ+R8h2{W?SJBwR`<36W&e>$R@@N}Gip?AS^;+=s$(xLg^vxL(y0Sms@hQwbDj5Ik zN3qyXuBZ1TXjFdG$O>#(N{dejT-vzIZ#S#3R$igFbVqtQw$o>3_*G|7XL;w^+<5yj z{nLVv;|+?l42j>f|9`)`$ycm)nnRFvmG|m9MdiVA$K0=(pF$T2iCO)<5ZPeERk4mvjue;A8f*mddp+tZ!GEj<))J zKVz}lJhqB*`EAC7N>W*C;N{FaX)s)DlB#9TwKg9c{6==N^5LL;n%l&7HgloPAuiezL_x2 zTb<+FnrjW*T;Nbu~0BbCUHe_iEul*MkV5ztgUlt#KpU6%$VG?rv__0#PV%Ubw6$qFZG!0 z+_O2fr(&&t*6GF0v9U4Ejd4xItzWH*^Y3~6szukUL|^}EzBcL|Fy<97#`JK7qDwjP zNTiqvUYUYH4ZoW~&1S1=Gpwx2OgS_MuZCAP3~QT5Ls|Pq4p^;P4qgDC*r1yEz_P+b+jC)QWD-C%kQv@>|TYI8Z+qw2R|W zyz3(s!I5*6;`+#~>p!aV{6>y!eG%RKf?#GbchkfVP_Q<%OL4_~aM65l?akl^W9pI6 z&{Vp|><_v4)$mMR%6O)cW9~7Py#q_dgDbZOS2`>Eo zt1GMd1x&qO%{HJUSR0l~=N1-%+=rYB|DYv?jU()>vBLk?XF~Qx2*lek!Vg)08RmxQ z>748?(}N3z>j-M{!Zkfb%$U;SU8mhommM0GrPkz%pQaXx@MTt zKkcoP74P~OBDO(i>kv%M6B%XDNY^I#*wIj$COtlc39fJQ*zokPCtNCJJi|tz_wewW zu9I2ustk>u@DsfX-YQqGn78S8zMHaEyv;{JTRC_oK+eo+E0~Ta9xm4}K5})3;x3LrM_Z|Kgqb0D5 zZ^|t3$dm=12`!FZ1J--4>J&8(d+19yFcDj_&Z#VL87!!*YLk+|th?-`8~Dx=Gvc(j z6H=PM)eTO>D{G+}ja-0G#b`;>Smh4E>PBfF z$G?D=H|o>w;%?fjCh(X&Sx2x-Gx11DsF;aB*1@K|zn$tS!XBhYe-ast;6B6LPE= zo{Ql=-EZ|ydvk-2s~H6&d zVG!sdUH~U-mAnkJ%5}yA{Zas}nB<_;MZbc0Q7}NVDg%5^Q9n+J)9C@a=&69412MR1 z$2+7Oo-Q*0$DN|aK#JMVKn)2i{5{@P04)VVm`Vr82&OjSM*s3eIy0(ZWRS_Aqk_-YG3c%U6bX6Q9JkRdz(hAK0JWErZ58&h^$KXtc$E=~8Idh*BV`SHxy&8gN+ zp~vf66d2s#^_YQ?FDa2ps>d*N70K2QL2a&ixY6^_f2|~NO$?_L=fW;Hf)8_r)imuj zgYW`tLQqx84q?>F9uf#I^!;{Mb6{(8SrLllsS6HoyiWIo!0TGTIwC3nKfs1zD1_k{p@Ad;mWqsWm3Z=p zb%N}!Yx(Ea=Rq=lu-KgMdOdpl-7)Q1zcD$`kX!R(ftzET{y+6AhCA{C7DM)&c)zf| zXt8x1^Z?K-kE1e{NiCF+WTqW5*X``=6qnr;>!tX-p@RRo8|(LN;o;VLX6%VZDZgd6 z>uI_H^Y`N0ff|v0h-IazQM{zd(&JU*LXiTh=kT3sf4KP*`DDbk!7c9RK*EQEkJ(ee z4^U0v)x{v-z_p;QAWc00KV>YkyJn*frCslOHLzGK8Zak(&702I+xwSE;Gzjq7!|W? z6|t^b!BGAo7a%YgD(6|$A*eJ2R3HBwuU)3hYuJf)3C~pPej2JaNhT4+HgOSXIY5YzklwPkTPiZlB%mOa)G8hJ_{sR(<>*!4W+QOh$ktB`p}1kJS`gIY{;{m8|#zZIt_%yUK{H zhU~?PnU0Dy4e?fpB7lp6sWZ6u^OU0e4#yx(tV^((^!OZ*0*;2;e2zJncrWlI6eQ~} zEk zq68}FB&0kd-rsypTK1L5q5ZG~?2F_Go=CKMac*!&{UgIh8cbZRp@M>VTbURWROvP` z%_&gmfm8#w1|;T$iSERFis~sA;`nQj=%|_z0Uu0C70hNJm-P6rZGt0Lups{KqV*v zqKDRiQjh`@4bTjubODit5P``Q;tSwj$XQq@k#(!vf5x(?1#>c3h^_@v0rWb=dju6V z=sroF%;3iGkueNrQPtcapmh+i~>WQ=jt_F{z zHGvdGdICBrVj}&!B%+JM+3>r?xv11MasLHA5LQnd(mqH$5v>Q4MbJy&-o)Gh(VeD~ zbOhu)iP1=5fu;&vNlbZ+(@&RaK#(DuEifk|ronLYJI08$5EHxNWJmZyw@WT@Ip|s# zcO2`({LU+z!TTFR7>A+44&H}qN<=0pbBVsPRzmN`+y^S#6f)V*kZ1sD6`1P*aVYCa z5x{8hvDsbB?MS?1q^(TRg-34v?O8QEAnmbymSN)}0vHy6-_0Q@f_lVC=? zHcEb!5kz7K;{dw`xu>(ByFmRgy4-H;;w0x{F5W3V1Zaa*5*QA&F+d`batzgdmw5~* zBnwGMj|_LfLPPlN`%nX7pAClo_9TWA_y-Kf5|kKtRO69QLSZ`Xy%VcE#8d|;f{(F~ zl3ObgBSnOY3K~>kjRqj+HaMJ^>-(*haFIJ9Rr+p>M>2@>utYLo=9AKaBmiK-W4kO1 z;1M(FF8d#45E)nvr4Y=+;)@xK^_kG5PI8ePOEL~HQF)xS4h$QZ$U^Hy{)Ntd<`l7h zZzBR(u|F5_KgLf8Q*b||3ZZ5YdnXbT zxBrjKM4)j%9^cM*6m1}7G{*RyawHQ`MZv-evBX8j{3d7wNHnQIeHyW5V$8c;<}vR3 z_wrc$L0&++2}2lSk9ADVCKszl7)Xc+P^W>N)#x)ps6ETS^MVLbg1N27>D@s1p zF2dkK9ORz>W+~DQq)Z}`8Mv;E;ea>~Pzpxv@Yly?yr~AcvG9KxFv9pxNFfnf5=SAzvKv{OIiJ+(H);|vVsde*AmPn-?Q0n+DgSy0t$#ZpS4uH26|^bYWXj#b zE`${ZIizXZKgw`OT^sO2I|0zJd>@YBd;&cS%s{XbhVBU5fbjyj8uKSxv@fDbNuLr>%fM&oq&5K*BT@VP)vA}uMCc~Bir*|5(h{3KN zNaUbOhXoUrdT>8@p%g-S_qK{%Cc|-rI+T-G?NyQ4*M2PjOlpW1bd(j#Z)P{wW&=N% z4$Oa4-E(j!Y^azz$hWdq{0NKnpR$o}ZBCXFtmpeLnvs{WFCY$rGr6@In9sm#AGBR3 zF=#SSBMHIVC379yX@G`tvqpEl#s+pn%3A$r9AF2eT~~1f?FXQ#Jv4^_6~kNp^sNiM zZ#R15$)Tl2uClhw1)vdg4u^2fYaMj%%h|}iU#Qqpxt+N7+c~;7?6VFc{02NIJ1FT| z@xFJk_FL3%m=5i>Y`z`a5v#blQrLQ8t;MTiAtB&ZM4Dv+f;=)j1xGPydl@Xs!k1cZeG` zuV{3P1|%4Bk@6Xj*cRT6X^4Z?LDal#+Q9B`Q*bm!5h@@QM`WS?pdlvk9iS1h-nQdz zfzzYTai1-9lay8MQ|gPoj&~u?x3tVOP2t8=3Gxj}z4UnBcC3{l(#e0B0A&*XfVg$l zd*Tw#I=a%()kK!o{<{*ZEfq9Z1WkbYbD$C|{76Yc3Bwc|P3mn8R0y9-vtQ)gwcwG|fJ%N|do|1x7;9k_0oyaf z<`$?A0WgzfHC7FYf`ozhGGGZV zQUY1&hK+5AUEyLRhQ*u;-noTnu$~yE{8Jx(ekn|DsM()jcs5Do$;$zAr6I(f+4L-u{J@aQJ^6N(8_nN(Ih@?)v&98xh zCm8k=KtcC=U^5j9KwWt=MJj+h?v@HrDWuMP|vU3gL;x2%2>*hOecW8IM$}cZ7>(}D%EPd?=0rnE1>P)nx^g8Dd43`G80In#MFt7uT(L^!< zu`+=HY}dr{2%HNUA;WgOrF)#+h1^T=i?SrmbC#0Udb{(pelBZu^DLA77Y8onIu+Ep zi_5!jF8)F5&{yWTTz$~N{N09Fe$Vb2TF}M+1LQD-D)fMjFBlRKr7A`f|I7b~5c(MN zt?%9cUOQ%?i~LlvxM_ERzq8@*>pub^9Iic1Lf6b8!Alce?|-+ZbufF!DAMhy=8lyD z#P=}5!S*5IU9k=f-Hb|&RA5oV204#7Pff`AOpSf1<(vE8{aoad&haL-By4p^(;cHt%&Xt8#6mOvd3H-6M!?C5dIwjO@)sd@3DG zHAzJa!vINd7U+*VeuB~!WLnVBA6$Ez^{qXm*szIIle4!@JX5{jDJwqJU_sohrzAXLvA~~5Voc89Lcl6@SbElY`WXB&L0}BRzek0%GQc1qm zuwPf9@WM|y(egQq=Pu&5KJ!6qJ>RIz3L1`*3Kp?u!0gS8F4bV>6gJ9+nn}Pb1Kf#0 z18jC*QNuXZwCD_^XT?Ze;6Ww_zV?!VE%y&KvPpFjoA;WLd!u`+d$dK^9QwK*zR7>> zfpXTm@o;-BGw?#peh})YiU5D9kO%?mO;BAR_Rd6_1jimDE?bW6q3xSX|K{z(Ka#pF zy`$k)Jww)(-jyRY`^yp`0Y%}KW?JVfDILtKXb~pCcA|cO85|nGniEe65N9!{r6Z0( zw&h3Ax#6?Xz0bXDyeI1>_$T|%^|L3G#397=IC|XM{ls~b&r8|YKS{hubnXvX-Os5-#}#++O|b)T9~x^SjZW6|aw*OLm@HlCw*i(XzUI=3EtJ@@-Uz zNg4+xQ|%uGvArj(7K5l^_6gW-R2jDn1b?#%K+Bm@&>Ae+a1Cp zY?Edh`lHOxJ!e)$KRSuRAF8#O&oMsKOb%px_`cp-;^X(_ujS(b&8mmJe$M zK`mWVUKe&RCGYQ@3|?MmCv^BOum-;9n9IxZs8+jD)bM~>V< z>qlJlup*#XON_?}n{B~jQ$qF7knk0ekFfH?a~5e)O6xFb&6GlYy9SM|2!-pnixv;l zRcyVjBPOgiBWtci(r85b<=Y2m{YAqW zpZHXu?nVSbMU0W+Aj{(pvhWC3u{^E|WGq*{&s?mRnO(T0cf^bcWKM3r+pO=jJ#v2Zt;*F>0zx zE&@AMEVrdIfh_z+dX=8lQ$0%D-tb6ntCNJwR*$s!9-6a9U20UDw@rSfBXKY;Cv{dBcz&(KoMezk2zCH zO !IiIq#v*JYPS4Ld0vY0fEL-pN|7zNynRyFK2_0z*R2GyE7VxI^GQ=vR}U%I1q6j#&+cVway;JrYo&q&E-aw)_EW z87`#=d0D(vMDtu>o+89q5bh55q7SLogVpcF)|l=}VTA5lgBRyJrZX?(sdD#ZTGm-U zL;g5_dv%GM<;o^fXp#19we+>)&rCIRgKjz5O+Gr`B1kBlGTKmP6(m?O-6t+_2(DhG zu5|7d9|f$AzbcC9|6bi;%co*$u)HcU)uVLP@}BX+2Cwd3FnZ?nc!uGaM~G9g3fypg zAM^RAY|Q5qUl7PBCCYXzd@>NTeRgn}+4iK^qa1J)2e=Yl8wKsTf-FTR$6i>V8TOlq zN*ihdWB5L*i1eyEVomy#jM*~bl<=Q0u9x6BLDhi(q%WyE%~Le)*^=Jdqh3-N?c~5& zz5EE@{VVW&Qd}k_Tg0XGOVqLFg&I^UH?w2>i&WdF=~>2E;JUOZRItv^pSw<3UY(9d zCO~Mbhs2Et>{$GWu)%!#i7=7PdQ)xQhDDPniR|urVl(-nec;TF-Q}M$&IpH3eyojs zL``0J@LtxXp9`NPylD*xV*yiw4<4oUMdnuF#jc}p5uwxBDMJ1Hg}*jwp#YkYdOa&= z0)XXDyq+=ot_lnObVcnyVdRQ4w@;E0PJMkks;sy%j?jeBHu)ea`C5}a)1`DR)8f@X< zaPTt?{hyi`Ef8}C)-H>3=EN&$=5#ea#mfutPHE^%C6ag{+(FziGsnk0Usasq@)1a$ zuVxjwR%(wAYY9>}FQzMkGf1`1Tr4K49%G*=P#hw5pBp-gGaadml_uI`h zs#SWKE^&7GOn@jJ4+N+w!y|F}pLRdN($pY&*d9j*_cDc z*JGE?^^S!-osJ++6^qyp<%)v?D@vWv=o=`VDy>H zPn7st;bwyPhQAmZ1SY5q5$%XB zby|(5k5q_@#PS4!TXaU{cj6$zeMC!49B%7K$gj}!I;8f&C zbh~I}xSis^d5U;;e+QgG!UMyy5G2JMt)aGrXjop9@*oJ9);O`qHD3OHCG7%puP>Ap z@vF1xy`SrU_~E*&#>Lk~-IE_`xctq9bDTDm2o>Iwe1>+l&E$VDL`eORI6$Zr66mGp zJXzLEUzyw1YTni=OeLMl%$%-XHFs-1uIu-ONlHrU{Hs!c*EWSbJpSZ-W5fnDCXtml}1wFmEk#9!&yR0M)ZN3C!h-X(DLCHR_{PL z&~looPs^a0XxI((yc3Kf*0|6!L6+~IpC`+DJi8`0`+C6~4##JmSbUb5$t&_+MsBRQ zq~u!p_a_Ojza4D#=`2(WE!q;TT|BPO)zJ%aeOceXP#HS z!8su~BfkQtgT5AZU0j26V)LhTeHa}QxKQ;&tPGguATkvnIQ4dVu21^Y+*R+6C_SFI zv3#cVnk#?hdr+7QlkN3G(QuNpgtjxT<@fx zM`4Vq0FMyCqH&e5VWIF_!`wI;u$WEZ+2c#Df8Es=xD$1LD!k3`4tMV5yBRpT?1K-q z-XT~>FMS%Hxa?A$4Uq-i0*ent=2rw z>l-Q&!EK#r)m`&4%!;i#=@(;1QtjP)T0I*5P1X_CoyPg9`EMee>{$DkIG()l$F7M$Cl&N(8uef>PN6| zczQWMQ_C{#Li!b!wZdqP(6~DfO3R|R3*gNI;YT37b`efQ594GNQDx%RLt&N0MSs%C z%;GZk7xsRyqI`pz_rYE)Yovd3rB3ae<$<*ruh%wqc4MQ-*8*VfztT5$!pqJsqG*fH zjFutNDu+a zn6fV2Q;jnxe5|Dp<2)stnWdzmcxL*T4=7j?m39a7y6*-0wgK^q^vBRQbN|JTYu+DB zXUfLXmSLl1dBAtp+^fH+u+Z&;aEV{*vR`Xq+T!zC>&nl(x?=HJW-YTE&QAOiZjaTl(w^Bmd|UwdsjMZ#Ceak0x@=2ZG;`^|Pz~H;ajiGWGSl@1F+-0xBu@z-d;6<-P?t zfY^mS9kkk6viWh(#z$cDyuzixQ_?ONVj-(Q9~g)6EA8gEU5})@J+2V7DKQd3>h@t7 znbq^EoT1lN<}9;$coyU!`(_LgUB>Mwpe0)n2S>a`O=fwKDBXq@lO z!%wZ0Pyv-ER*9Fzp2|ZEj4DsFPphrc)wx`nzRQPL6YE_bWq+hNIn;I?RS&&2hK}bG z`W+w_LgjT|=)yOmOYk?uqyJEaIN zx*IrdwXMr({=7hvE(~kkLFuS(BL%qFfRB$GcV^vX;d(SHLDHFF$PrIP?jPN zeQwT3mSs%{N9A?a8*GCk$${{Q&Kbe}>tAo9eZaR1a&H&rKZx2jbIBhDLWF(+3}d)F z^pOJmc7O^pRr5HANgnUC3ymq?Zi7-kP+pEw)guI1wzHQdoTHk2e3jnZFmsX|!p2I4 z1dxnDJwd>^T{_lW(T7&zlYfV8I@f|N^jTQGy3ioCr87XjNB#$#l^wO=TuXGDfm-!X zj>X0V>+2!PE_1H~4q2MSDh-;j64>MN)6pv|FNI|u&Bf_=7{}UYI_agFv!|Cke#Lj# zvPJMD6})(%;NCmdHa(SrI+>zar?2?xt*YXX;WLC2H)brE`UfP-t9QGbu7OMY>$q=1 zbF)h;CRjf7#V^+f?38PnUJ-1`AVtsJx*~CWySqWI95&!0NU)Z@Ymk$b&7NG{n|Hl7 z`r^+FBo$g@Iz^NL_n0on>!}~ppBKV$Xgf1ymrv+7Ly`)4J{^6gemrlNvhf}w+_8=) z#|M{SwLoaGTEUfjhC3Zs?NWEYr#i;(ZXBC2@eJAnWvNha`>Zy@k9*R?gEAQ8Ph{?+ z0pO!{T_*+j#DykSzVgnmIu>c~E{nhoI40~z&$yAV*sZ$MM1Orka+izoD*2|P&0dA+xH zz;n=lSz#_pcl|Esue+d4s*xCgBlT*Xo3k)+AifjS_7B2gBL?j_GZS+>^ME!~E!E>^ zgtNWv^_vYN4nJWbwuu<-K+-P~B=Z*u97^CZ?c2G}+8|@`A5UqREDH41jPCp(Ln*O3 z{bFPEigM+hgQs+uZ@;9BxU!!#cnF2ALVL*l4Lq2)i5@*`Zq}aNusgAkRD5-|d@>gu zs`u)1sV@nbEGh70V2b$w^erDwYpl)^8Z6*_S2lvbl*aggoDnv6q3_`F7&nL|l~X96 zpzGY&2&3I+2`6H6wZ}h)lB|<{lC3$cSs_#eMPj16tRlm*(cp}e-~%odHC8A4jvHI9z_0`+8SE!nylkb5eaH?Z0U}kJ!{(cEqdEj{}Gm>^l z;sac(#Il-r-Kd!xzNy%^8Y$RT#y-6adE!u^=Fy`OV(;q!dc@luggmMaNXToJNLT$Z z!W}PeO;4Ut_j2A_-haS-to2cEuZGvCJh9>}96T>Th-FFsT`PK-58QZ1)+{p$s_e#g z_kCT z?+d);*;!3%E@?0YsuU|v`j(bK%ZLM_hW?$X_R(-e=kBXVS4}H;#&GbML)i^YLDbwr zs&HFA6<|6!Bq(dTSlDgsl=0k^DI1Y;d*opd!v3KUV)$;~hE(y#u$|RZ;q<-akRlM| zvqy?eE6uo$5yj#AFJQoH2C6|9vQw1hGL=*bw=T#*>(D(R^*3oW(&!&<$Tj@44y?*uCdug`wddKu-kumjYfaEu5fEnKb^U9`1@W_X`D~iH%5tk0Tpxx7(=hN{ zI!0y&YE< z{qpuGu38ix_d!lwO?vn%$sxCFv_)>#51!xl8Er~JPpA>*`bd zqeReKq1i4(L>@&`GAM#ACZLRXaTf1BnFj%jg3(Vjxa08>ZIg$7a6ULl4ADS9>c!hrJz3^KD5}NH!q*cBEnhPCluN`Y>#z z!T~Qscw{ImFhnQm@b+1NRp?5Kd!5MBmj2G#s8(FB?)MtpC{$c4Fbt7y@ga!bS z{8d%jDs3=cH{l%CWDZcnK!_h4IxJ&q!4P*1`XX7?He>#tP+PkDQsX zNI-pPGhx;`Z{M(6or&VL=21K*El`1tVv0F)POkW!;3|@ss34T|d-kFyxL}MDMa>#{ z^48tp9>*p0+!55-BNlfJ_SfsHom+!P=160^ovJlrnngtqD)-kKpg}qBo@u_%SUihmgC}nwEb;l?VBv9IAB?+C%jxD;8tk-=2eK(HMag? zDxlx!1LeQsgqU%f(P3H(wG5OS-`4TPf)l^?xE)(-g1m+SEt>1R^gIPnYHn^GQ<(ME zym#(7i`Y@d6Dvcgp;H_Y)E$1inyI*&IruAea5zVPb1rs_ksD2oWMHxgqKvXY zRY3adlMjY$e1=2SO8t1MZP;u}39vp}^AH_O=TzN8KpJXcLI*(OsdK)iz|p@&CFtan zQztdr{-e_b@7X8T3hKuHG|a6uJXR&i4%-7nGK6;EoZMa+I~{`|<_-^d7*cUXP38MJBY}a1TMFg%y=x@A(Lzyp123Dh>Z9oee{1Gm-4$q-k-MX81z30P4 z&)%ygbH)QJby5|R=Cjt*lUOZB#Jks)BWg(CCX8k2;sk$K-TA~w#cZXtoex+qgOQS_ zbgsF(e^{<|BBqc~PV3z-6zYvH)Z>bCJIb1%e+;8g1!7?OMmL2-lH@5j#vOiuI_J*V zUKfXV)#olHHR)49hVJg}KWDt&u2t^hd_K7fpF+THF`R;?I)c|%h9g>2<-DqQONHWd zONRzGrw2jZ1x!|~&G^pWd)Q>+X!gz|O1xmngLj+$BQ+SMZ`wou@1YWv=acl}2QMv} zj*w;m>OfHWs;pEvHi8CjtPQw7Sq#XRpqJ+;-6=@$+Nv3P`JXd@j>J)7+aXQm@WjWYX)qE7^#`}-JnG99KbREfn9w;wn251PQV+e!8p_+8 z$V0Mked*fPl1G<$Jta2<%%)IclLn^Hu~n0GkdfJD4)#djbjncbJGLV3G@Jf|7wk4= z$Ml}}4d{tLr-)p}B@>z9MFLS0n~g}pkQGkT!{IWYWJ;v0u?RQoeoEGG(OOS%8#ba0QORtTIq{A z-?Y9ZCnqO0aQ$mb3%x}lf*Fi}ulY}!qJq~lwy*|IzNW$hqcF1c?e~C0_u$1;1RB2U z^Xu`ZWl%?dIt$CG;(B(lNB}zDB4T|5Jb6M1tLCSwd>NaY2aUVAp^ZJJ310|&IKMB>Uudf!bmIwdUlNnXt7aXv$?jZTfDObr5nI}+_uD?Ee!A89GrG=ag_n}&|K2q9*z zOOe}pjnqYtHy+9JYcx!AU4}B?T)jKix9_W3D4lCdiwwi?Teo&?DgVJ`|3QoOS_{7) zA)I~P-PhsMEL5pW1_OLgM-{arXn_u;Fj7%ZQX%*Gj{$Pqj8B?K> zK$*&^-;_`T!%m4+=2x)0q;mggPS3!&VB$L_O^N-m+d-U00U@kW;ic8TN-z0up)=IW zeQvE^IhLiz*jXdrA5ELPg(l3*eF1CJXr!?TpPAxPbODX((Fc2YbQqiDFDatE8B_*s zems?rk=R2+rp_>$|7>0D6yc;Wsj6V36)a4toZ@`A1Lb}`fpm|2~4O1jO z;$EM;I-+^HimPyMfZDJo2qz#a)Lp`GrNxGZaDP1f2HYGmlsICjbXj{T0aMQo{bT`C z50?)9#?bYT!*x7G@xsfJl9!J#ZwqTp=D4T>nOX0Cx!nKkLJgIiQSB!GU;G?*+prxq z*h`GQ@zT>V$naQl^F>I3f~7^GY$nb5n%gdQ2P^6Ssm^l5Vt4$?T~U}9W9Gr=7_vB7 z6q=Cg5duGMD+Zh#l;dG|+gw=4Yiu)j&# zAUpSp00SG)e&{*%65>u>9c40x36Y6HoDF@^CFCUUzceGSiF=9 z*V6AY`5;28e%0bYaoedUN~+z*Es6`L|FNY)U%1zU4O;ZQ-}IHW=8duneRBy{+CYZs+8# zVzbQ3A#peq@Zj`(Q*2rWLBrq-L4ZafKXXEVg#maF(`^g9vaBG{&bX^8b(vsrfq?{o z+x|}e3qb(&)kX~47{p&Tsw9ONThOTM%op6&fgP-*;yP`Ce=9`QXr+*+_fKZry)#1s zv@a=lVaq^mBal4Wy&L+LD&sb~)QdiRX>ijnaLMjkz(TU<+x7XJyo%L)c!a=FQchkT zJ|XArN)J4HzW!?=!6M*SG<;?bdgj8TC4Xr*nyNt}V6&mod^hHfd^bpezy6vyB^;o} zKn2n|ccLw9CnRhW47zvyP6I4yO$|FszFP(+7ud4Kepc(rj?R(199qC~`;vF*voRp) z_j{(VUH!D%Hs?)!lO0M5DGGOpJ5^(iHk;|L>bBru@ef)BSyzH-4-=>3Xnc<*<4uS8(pEoZq23sM4Agn!y$M{{?l87}D-ByS zHDanoK_G1RDH;qFe7mihoyMprVXD6!Ydm|<8*FV!&dH2B-9ZD&j zKsnbUWozwn62^7f1cCiZmO-QPN70EAH0cDIMS0T(A1O7+`Yk2-$-Z#zx{!tT-^Tbpg1wTMI!}TDQGWYQ)U5dR;_bJSYM?zPsYkzrUTRc zV(obC^DPG)M}?Tb3GLw&hGHi%MZeQHI=w;VeAg3O!{|%2DarS*y2c59|B~^{h3O`$ z59S1cdt!fei_5^@F30&cFyC_K|8SxlJIR4iM%-}xaT0&G$Fc77cLrDjakQzYKYEus zCPUy?exdQfBr;Aa1I-RYMyl*Iu}2^<#2!H!NLf)6sNCCcIGrR;Mo5ZV2q|u`@q-9v zYEA_tgoBtnVgE7uv;GI;1fAnz%ggR*MSb&52F8aqvH)U+HCg5OHG|mvrZsijsQ>sW zPWOOzd)pR`_@5szwQS~kj*ft!jm;~3!C3-TLY{wKqBTR+NB0!r3a>{Ek@*ZJBONH+yc{Th7Nz8+75Hkb`~N<-0CVEIhhR6^A%P5=%E8u+ z>N~t36CZa>1_fLG0xZ>dc7jULz+f?yK{3Ob38L%96dq}%l3+3(zTcb`Nl9$11-0b5 z(beP_$gqOw50d)D6FD8@M<1}LMx?9rp676yC`%T=H&}cg{QR8lrfXq|Lb9mfT`kr& zZF;Ex?opqP>M)nOWE;xif?!WM*&2|sk2L=zwqVZ{VA#LCqxtfYP&Jhd7qijJLg~{1 ze}QZ)7laM{FZ`d?Ix@G7ydlE*2-Jx7?U^e^xK=-{%(`4-ntEnsL1RF|Wuy0nOn$%X`bYAKkmv5*r`&?L0P!FMk%EmcbB8y-ypqXQ`>IrrWrk%UxTr z4>~~~RRSMQr!}~2*OF59{YkP@*~tC!+_H0MN>3C@^r}iDXv&BexcO1Ly=5vgPOP+> zQI0vT?bK*ufo0-H?VT{kM%@IOa-eQv{PTYG`^IdpERC-Bjal80nk~+IA{1W)L!AR) zc}QJlK{S*Ro%!tO0o&7j*PdT4rK!cET}gODwUDch?6k+heR7X zWE0+`F5-N1wIUFG)(X^)=aaG`g!(x&%0c7Et~WCtu(P1x5K9;?#SW*;Q`_#er)E}v zno|*T;9$U=RP$_(uuD1@SlrJ;a%~$AIvisuCP9+2+ZK2)8{-NgyT-+Sg8jSq@5(t5 zsrQ9X^i|S5t)P<^-SzuIGxCrQCI~P!cuYNMgJT(P+*>q%Ptq?!}yP=<-Q zM~9;%d3o*{`k)!~d2-hmk_Xq(17ZJ;#^H=cbB7qYX4}ZZNKdNy9PdG6UHduSLx<_= zkNFU*Ha5uJ9uQmwf#*5*@|pgN^3o|D+vahT^Lj;u3z)~FH40K3F4HL*aK&-<^>#ma zA<)?Ss`rn4wKfyfl;8yVj^&g$P{N6yqDz`>6fvhiULu~bBpr5q3=UVJhL4zu{&iUJ zahAgLA0`(5i%_g<|9Ft%Cchu{MA#FcPk>$;&gGCbb2y&L75KblbCF$t5wu`=`h>m~ zed?u{KU|?KBl-8Y5~^dwgoOEwZ>(}r*OT1nc+B?fC($_~2F1~kj||}l!&Py z_Q8SUMF1E#L#NlJH0l=VFuqYV;15WF(MJr~?2`+wx_2X}$;*k=f;hgMCyNb5AH;)p zc7834tyK*6_xrcFr7cvkR@^D#`F*HuFAVckZkj(5cznMb{2dx3sV^m<5sOU52nFjg ze`n{@y8qpf2~{&nU?g2H26Ho1;Y2=U6BG0kzYEjBxW`yCqa7c`Y1jc<%C8rWU%yG! z9pq1(G@+A}2f2ToEFFE|;PiH5iD1+6tD1B32Q*-5=yVcnJ5o9vQYWfG*a+aI=2qH!uTVY;yQ*N;9QG}X;4IFt!BIcQrT(kjNj<(o5v*)%#+Ac;(> z?6q{pgrE!4GmzDP)4&PMd#WI$VOwQa^7vB8$LXt?umwlY5o-g0hVXW!UXV{(l}RM@3owl@zoU z!hiE}aMB|#{>y(}I4qDDZ58zPsam$t>k>BIjvn8_ z(z+&h4l@kjy7Npc^^}$Z&+E&hCw|6t&3^kcD4}G`pgm%bDB;|-hnr`jOPxgBB5v)kjqirA+YO^=O;g;0lcs!4awGiW3YTOIwSMjweL5bNfk{*jOvgvyH zwI1QO|B~cmDU#PT@@Ls=iIRtjy}C^Y*xc&tj1(p7%6oINbj2Jgq7Asbg~OJ?M-68iXD9v&;`dq_H4i>e@Q&N z2&UJW+EMT1=6T-KeUmc$>_YN!(NSEe(fOlitoS6Yt5c#1erPF(nXrt`H}>U=dpRPz z*P_ZcYCiqyCb*R>&|a)En+-sVAFJ~-N1ev=hyOUsQcpLJEeLn^^;%(7a@4AbDv4;{T1DKgH^Qk z3&YO9mDR4dn=h{U9~oOm?GpM3v)GO9*i@ZExdS|^Vic-kp^-1eY>udfpDi_SWRxZ6 zHa7jQ^}-Urt+ugoQWOXG%grSD$U5zFD{;Hne|x8wh_{DSo#)@=+`N}UZyF_LQ}5&E zWmgbm8BXc4Y*C`_U)Y^~RG($kz}BfJ>1C<#!LSx3kKQJ!a9Op^@S{wavrQgSM{Sv1 zUV7`#YQiZBZUvVL-Ri%igC~4$nl0via1?*vIxDrC5OsTNWXoD4Pu?&Zp~1#xrW>JQ z`p{_1?J{05&u@!1;ltb=u@sC!=E%v!?Hq*9fslm~GfTpFHKaMZ=1P!hdkK+b_ z?;cLer|VO-zT(3BYkA-zf#!{GWXT?_Qt{>Mtw%d*AjbUsQ{^^~=G{eCkdl*Etj3o?ppKB>_LFTDH=S-cwmCo!VS6u&E z0)MSlO4lp#sLOIqpQo69dvyDZ6Yd+w^IBG%@n-V@>7$22DY&u_hI*vtA68UVSrZ2$S>8& zn(kTLVJ0UCr;OC7z4h;aE-^ud_vMRu#*d_Az7ij5IhZ$7cjJ|L;}@q})6}~zXb4d6 zea2-J+GI2w^X!(h7*pR8J%Y%KV{xmvI3-1T)mx-GYEg?B= ziOF!JoAAL_hBFzg`smaBq3TBUMHVlcDW&&Uz*p{vRg|AnhdsM_hk^bw*_5q#xb=8~ z&F;#5Vs5QDVJ&KVn!;K_dy9=`Q-l7grV2`@4ysLbVN_85e`OV~fQ3Z;sAae%NJgb4l>EpSGjc-|qouV|8ZQ2>C=u1z69N+D&{fwSE3d;Q*UW z|8!=ST;0+G5e2a#UiK@L>0Hu#(|MRf8;NNUAv|!D+2?wrDK2&A(dDn<-HBK3mVMlJ z)Xuc9D&(W5K7ddGcN>>%*d^y`iY_X>96S<0qZ>^rh*0`SouJ+@!UsXz!jg5$V z-F%7SvbDo?JFb$IsuvPQLsVxk(>vi=P)Nyw=Vtaj^ohzDlNcaJiHm1oG(2*YGjUMp zpt$>mo5XsO&mhZm9PuzjmE|}7k>^}f2ySDquf>QDIk)6MV1M{1ma*B$RR!H?qgAO! zB=VGcFZWU7?!-oFxub28FsqLx*E#tl)^Hxb9eGKn zP}P*ga!)WYnmnYyOv00?Sle4&KCUQyQ2cM<+D@(PTQzm<2ShCpK`t@18litN*o%8n zJV}dTt7C8Rb_?$-`_|DThuv2qT`qk#*12uIgpVx%TFxgs(uHN+QeFb{kH2C;G@T+RQAu zJKpku3Xt@ffj;yWI4Rf=PphI1PD&Ru#!FPS+$!6c3|Q52#3lY}cS*LkbM#+uEt5H# ze?Y6Yn{eh?n!#?|iG~0Y5;xs$~{5FXfm6IQj(ye6iH22wcD`dr;_EPS8qxc z@A|s(vG{wm)MG*}RC6O`<(f@j$ z&zp08zu*5jrxSXgagXb|?)x*IU5zW1w72IeT&+HptjjhVPATtR%RT;5mCxzW)X(jeCg;m}%BAo0 z)^lJiNrtgBxZ#o_qL;hoEOX#aVr5;QxOxLDR-{wQcfa@8OwEyd0T$5}A|;%<;w$Q& zZoQvWP83SMyqw3l#3DmoBmyEYJhY1!d2qBqx>kZivLSn%=hEegMS=l>p@E;wC>5+P zJLZ>_Su<(S`J%cEN8ylCOb;30(6l+ZD2+iwnH=b21G z$2wwOCW6m$`#fSTw%M!4=No%nGZuE4xpB*`&pZdY-0GQjUI0uHmbacA$?9A%>Gp*lvcyODmcL8xzAC@H* z-kCc)b4NI25KwkFI@U^JhS|c6EHR*Nrm)$fhUBsS)tmLaO1Mrgg>ya9g}Tf(aLt-e zJaJsFT#(8QljBo}l}t&dNQMmH0WL@D^h4+l<-fuu+v0N+3Zp7&+Pgv?w|s~VZwZcR zOg?xrDLAM!{FHIi6F!d*l{Pa)ti^vCSt}WBvD`b@ADZQ7T;$p_@9==-ooyaH`el4& z6Uru~Th+`WIY9IpUt6fZXHRH)pS`rKM44Nu9Mzvf-PAtYr>KFE_h;TRfn#&wu`mWOz&sdxjZjBOIzz zztM7os%BO|S@>ZVo6 z^OWR>PkWBpWzO2Q!MiUci?7Y(0peU$@&@1*>*~h3R3>Jku9%_|s5Qa$@g?nvoZ{D$ zv94rmX)`a?HI-F4m$P<@i-s%CW{ED;I#FUdRfQj+j%8grJ#*{VC4`ySpnuWP zQ}X@~zqQX*E%vEc#N+ka_D)s{pGR|Cmh%LXDu4uV`{Maq&lVh91iQY642 zg4{fMOd2-p5V28I(JGo$@ca>74|mV<`e4_R-S(w2!be!uSdKYVSy6Ch!m$y#NQB1G z2lk;58e7=6!Wv|jB%Gh;a@R9MgWD-NN3baK{IA!(v2)F?9LxgV-+m3p0rrXG4A?qm z&|#^ORy7p+#nM#>a!CkV3#jON_~&a&?aqHalUV1?-g%dkhaFVD=&$Ju327)F@V#%5 zC?`06k9d)L<~3ys4q$+myA}0?Uh@;-HgkLS?92~IoBAhxj!3`Pv~nIws_iELFwVY7 z{v97rOHI1wdsyFPR$gp@oOQtzKx$l;-5aM&)PWv7XBCrn$MqlRkM>_=pk@GZ@iN{Y zHDRn3m?`9%T1v9vXNOEh_JT1U(~^sCH<3E)oS>ha#|}A}!aKo+nkHV#b8=j0Q!;0pfP1-b!A+kt~oiABTqE=Jkp3bT60h=U`kb)xybve zyIs%Z4fZ^G2wy6wJg=ymeATiSZhV56CSXcdb41w8^b(1w?ctF%Y+18~gwKhVZLTJj zYIORWqRN^{PR&VRTK z?U_0uU?5iFb^ZWB_wL{q?%lDMjkFTX+{%7R?e_OjE`8Zv#gxojzb;tpym$PFo`#-y z!z2|-Wb9OmdI z1XDvXK#Z&+l0;K#m5t|y9@omI-+{(=V&g{Z7Qdc(ue!nON107bT+V%u#?@k7qT3sG z+e0PEL$ne#0e#cE3|g9jC)KhT|MI$-Gue~6eFyU1)Te~hlz(XZ-F5V!Vp4FCS6R@W zqVo#{n|e2XY};0zRH(hiaeWWc&yVe*2H{{5WFBOeube6|i#6{h^&Pqk!o-X3SwOTL zov)F}kCO&GenzJk_6Fr=d!p|B^?8?eK;;RWNsTAA74|ms@!flLxc78=ywHbvsmYQm z6ct2E^H&oMHcOd5JR--$KBuHcIFAr@bXH4I5a%MPt6V01meTy0I#6QruI<=!K&HRP zj6!XQdd6frsBR6+2nAk7?nTx}7&0)W4Avob4&lHSwNB;wXq!n=0Gh|XgWy|~X zPggsMi<;;Cy$kLL%Q5qsLaHEAsiBJe@z+ROz%yKO4Cm7KO^*)E%V>pwKed{(T!-({rL@9(43c~hr@CEx}`B5D-6z|?<+ndt?V7_mw`waUL-{D5l? zD`(8*E8X*I<($o)8sXLUqI;JkIjA`Brs9Bpwq(mm$-Hd!oe4dC`a#s?c=SFI-kkJq$lp!-7u$eLE*krIWj*UootQ^Is9q&n_Jp8 zD*hs=$zm#$PUa_~0Wo!Ld(Yn`j9N*^nb$6OFui{0_>WC*MeTj|r3`ZA(7(FURKv%2 z=bq8kH$^%%%`P_^lD3A2($FEYDaM8v>c392V4Mbi^YoaZYmEdbu@e3DKx)i{4`|tJ z28x8}-y%V*>|Qyh+R|*KTJ<@2Y2W};+ecs1@eCIm&yhq zBQ5`eraf=k?tXn>vUA)pP9EoSDgDB0{# zwjLMN@&uzB9_4W%Cz083`*wpf+8r!OLh_^>2q)zL+=Ik^#x^vgi%>%h5i#O9LrtD* z-tcfdoYc4BU^+^J%Tcb?CAW^tI02aN-7<5XR%W`GI}yDF(#mqavzHdfhJZ#6i*9H`?-ob$M+t4-onQxwj-}PR?UW_6bv$rwPGQF zCSBErSr3O8MU9{iTbO1zSLQv?#!NieVRd(G@BJOQo`T1A2{$*(47$#n{kg;{T)b6M zHzJ%ZAzB(Vi`Jihsl+w;>-pvn=N{<5yHrZk&syDq&5=+-M~c%`d&}b z=5s&%=O$~9H=AQnRn~BFhDX7@d3lvqA%c0_lmb(GTB$>7$F96X1jvY{MgL`9Q_|GP z6E#b&X?ZT*wSnt2U+ENuzMYMedivL;f7Fm9enN^HN&@|O`gJq0ivi;=6|CrACSCos zAREx(db)9ZC~|$$vUI<$g!EBzHeEb70fKWUGyO)|Ea=Mh7dFzq5$^j|*_MaCLH}H$ zY;g9vO{C%ajq{gbvt;N0V}J(vlb#+(!!~qe5vn$sh6!2Rs=89k@Ut3d6}Y;*9N#=i zBwhDg(A~9&8&Uqj(~2&-d9)U13h~is4Id!dP+j-Z_eZP8aF$&>p_8Ru%NMX~!~6WE zl!3nswfk{btCQD-($W7$$yt~q#tLGFvyr86S%o4VLYE{mpctT6m2KI}<vZKF6r<{Bu@y= z*Zx{zWbK!2kVwSx7Ln@t>l6?V9g%)VF)8 znjxo2d1KIL)82DgmsE+QEmvlfAvA_hJ>|r86u%ygpSKk&Sk_h8Xo~oX&Uf*>`>Q_# z92dnWs~hpgo5T#7f+T1Oo^ZNZVwcsn^ILSYC|~0Lw06}gL(JUCEU|j4LeP$zI=0*z zy|2*$q>Oges7XGEh7vEEfpvtip^NR6udrnt-JGi2t4(4bxli2=#?FXRLp#a;b>QP= zy+=dFy|}Dx9drerFckZD5hP5`28Lq=@}-b6bP@0uEc1ZN-w=$NDkwM2_c<35&2w=4 z?m1p1O}1K*vVtPpJ&`~VeV29lJN|}uoXM3LMm#iBZYqyWe>60^eq*(XrM~_Bl!GT_ zE*&0t^J`pe$mgxMj}zh#Q!u1Pku1$3hM}3vi(xe;hVeKySr<>GhfN9-F^>#wTxG52 zm0hTPEAxc=I~e)djZp2nwu-k0tC$N2^Akxkrp1Wnl7wxzQ>D(1D2vz-0q=`SK0Of71pD^cI-n@5~wk zGjwsZ_>1*dc24qsZ)vp6y=Qc6dSk=V<$m7o%1Lida#KPkHlB#_5N#@%sTVne-#1-5 zSLH88=mBL=I$YL8j!Q^Y`r6OdfWne$JTZe$YWLkHpPehglG=Ug`3k!>oC$1n^SZ!^ zQarCh;f~gO2xVfET0_`|-@>1mhx!arwLVj4YNn3v&3ja6dAbC%x?=A&Oj>5- zV>L-QDaT|zqiUEgBsyszB~qs^a)i)3>6hi3rQ@0|6wrlIO59JeFIZeuFRyuv*M)LE zJ>59E$U*+!WD=Ndk+BI{6 zgerQ8X!!UX9H8eg{kn&HtfO%L->1%p3Chz9|KXpBc%AVl^(R%ho>sYGZeU;LvtSpn zk5&U4AE1(nzeWlgvqiMIVRHjjAL5%JkcwV746Q>h4)nzKM4xEy; za(|ojzBW9|HJ++7dRfZG)lH*JP=uqNoii&3EN4CUYHYot=r;&ex1F20xGamPiy=t4 zkVY2+3Xa62%)cWZ$CWZxa`Ld?Fv^{2`Mon21yrtB=Emhpe{QWjP%4~I0R1z@PKgg| z-2Xjs|MYW1IH>FWuU|%N4|4L=r>XltO~vz)!-IGw`N5R}1UZf*EtT;YJKJ8y@e${} z3aNg2R?lvd*=V!}jqYy@q6=iH^1QCf^Ew9v{4bcw^ArgMb=kNq%k>&1<3iF`TW4h@ z>+WzA_84uuQB=UbB*_WaQg{J*_>R(0snSp{o+u%A^bGC9Q(61dR{y|pQ41ER#J&+` zjaJdQsr7kozP>nm%-XlmR-36~J8Mp2k&dln(Q(pljp8%ZmCWjQrVPj67O@lo(=Jwg zD@&pD57a|pqq$aAXS$y28uh^HKvYr7|Eh*H!q)qu`ETDGOD#vPbp}jI+Ya+>Y21e+ zGgJC{?(FZy`@ehe=q7or#Q2k%aoPUEjM7r*^qEcSmPFPz}8hJ?sX5&L@1?~56xPs0ojhv1?XjZXBLyzkE3;5O}^ zXSzqV`C8Pz--;9g%>@d+LL4!j^iZ32MLSO}*f}i2o#bSOi*j46CiQG*v@oe&j#vCVGw_={o=s0C{e?T1aobt(H=M6_ zk2^U0!}#u@;a1#?HYH7JLs1&bc%9)!x2`b1ZMf<#aT(r1(+zKJ0x_G%)Bu zwezA2^X)ADtdkHK15e@1GRarMBM4tyOG?01)C{L9)3w%jJ$f|BakW@ZGA>Pvpj$A; z={#;9fb5A~Ia;@4%hDoodekfe;Ux}i)%^WL^VgH!-kE873@Awvp=NKrmaNagKQ_56 z+^dkm^d*H(8@fdWWCH}!Kf&=poX9_*Nq8;bzZp*Awg$jY8X8=418-r`FQO-2hw$=WaG6*O%LOgj91!S38?-BsQURLm`nG$fA2A@hZ(9&>j+;u3Xr9 zQk!dK>$GLA54f8}v<*B;HUS^t^-8bPye&+0mt*_GZXM883Wx3)h^%33U${_+3MyYEP9@ct!XXFn?aZa>>*@JRwK! znWQR5T_asHN1JUnN8YRbLYJ@T4aEhwQ@jt;-ojIoQ^XA52=oehsrP>b`G|@mt0XFJ zr=`KbmO)QeJFY1qV5qm>ICNn2zKzK&1ZQ5jsqMkL!OEusCf&vO#jqX)Wo zS%R=EQE3|);CxunT79=}u zI+|nM9V=k3tTnO3Uet?ADi0_W(nDo#dl{{Qt5Z8;1)j{*5S?sq-R$mBqC8q(yZxJ| z@l8dUZr{1}QAIkfR&Cs-31#s|c3q*36kNbSi-p*O4W%?vy0Zve673-|qYPIJP$)+C z%f_a&5{qPY&z~cAu%xDsk=weVt2LZlzM#zv=GrwJp{?e71YDiifOh%h&ye+(qn5c8 z%JDtwUE?r=Bc_;+<5?IRAQ&*uhz($nM}!Uk{g>u6u>mfqOlZ3>U8}>_GJj^xB%KG> zv;r_O)$;UGPQ!4yqP&{Jv9EzA_dVWPeAMBqwyv0^oLUa+FY~)wxQe^Q7i)~3^mc;7 zXr1xnRg>Hz1;==D>^#?31R4*o+ZlJWgtgD5vdDK~OZ3nA(ed`|mGYavOnn)_NxZRt z|M#K&zgnc@>+KD`_5S#>ZSO_Baj`d~8|K>hN0c^2Hb{i!3Tv|?WTHc+nX3q|BJUq3 z2OH2A_L4u5z<)VvvomK`BqWb}p0nMvjQeIowiVa;jCP)?lzB&&tWrx=*v6E4^44F4 z9G&{0cKh>tBO^E~XD+*XPWt|>9Dkq2#5cXi^v3OZ@!Zc!es`oDD?rZOLbQ5Dg^4Ie z$L!P0$$$RjU<3o+Svh7C-IaIXc9O`T4Vk5zUzVi{CRFD9@3NKr58;(HNlx@l(X~NZ z>f&Dd)!x{%L|W2q|F(t+L#&nZj!#eTel}VD=Z_!3@|SMB`}XDQ*Moc^SFdfI)-Uii zHfW&_HYgLVkfSoYBECTaxBd!du=(bYC8!A3(*Fs%Tlhq)w@ZHH)+MN0uM2YTQP=al z;<1VA{KVkfqy^;>1xjq`iqP)pN{6@s-_Eu!ynPsNQ?|{V#hqX3Wj}ZOrnhm=lJY-T z#(HZu{?7Q2XTF?p4U zjT6fK)c=ia(tSfu8Fx;QV`WwPO}owMIMiU4yj=b8ug<7DhC;$FZdwyyRGH}ZY_dl_ z8c(XxX1o*kd}(Nry;qpLkB-ZNg|{j!^UBnH>K0L%p3#cQQllE3cI6k4^C-HbMXaSg ze_!i-dRtT8F*wjHDX7^le($bdU!3neF}PN)K2g_=<3j=$@6v|rn2kjsbX$45^1{2) zRYK`x)S{MQ>bhbVcWXa&GO+buvRPiZSGRbeOkG!mygvG)tF2j0rMzmXPz3#9njMh?TJ% zV&*oIN;G-Ms@#1=&t ztLRHl3zMp-%BlXupUROA>IrlZ6xyx1I6_U*<<_z%23k*C+7dW?E^Sp!kz~s18Fc^3 zyjkf%g9hp;^i&Nj0M?Qy2m7La6VBQ(z1HfSy`bOy&DSuisMu39e(jVl_RjuRVxppnTS>kQwPJhurV=u znFBr9gnWU~%~b^5m1iTI>?$JjwLb4J5l-c#4!<4a=4na~1n4Lyey(&-$Wfjpzga`t z@lB1uGnaQd1~pC#*4|o`%9rr%_S$2WA(|e$LQ2!U^2=O(Iq%6-u_|-!#n2d@ zvzgywvqtU=eB^iYTu8R5$gL`Opvb5^D_Uvpj&s9{rDTO{2akQTNR0D%d^PRa2LCfp zTn4^2Qiz)ABr7y#oz*M$)o8Jt09y(L+U$8u#!Srcrw~OzgIP^TgM?j$db^x;n~3$g z!M&MxO+329*=flyHnv$*Os$9^xjWcTox8mvCf`51HqEuIM&QJWmO~yPTQuZl>erF& z0wtCKowV3;2-FN9FtM!}u`zav6S7A@0v6_NcSl7+mbyE~MiyQ6kZMQVr$pX(ZgA;i z%jNk^&K=o=gSaS z<0CvCKR@qRk38jbNlz+NC6Q{r6_(_It0@f|a*XMpa7CsfRLPd&k_GK5Of;fJ^e|Ng z&LD~0xF<+me9m()o9Y6UeTO~Le~pqJH*-_s2~gYJyL-Cq&#is_>m4lUT4L9ASJj1W zN0F8WKL(}d!VbxNBuve=BZ{;ctdRT|6Xe;W-ad6B*I7c^^KQvh`{eJH;?W}RIPHVU z4s4KN^L}%uxi@atQ zTmO*irWkTA0FW+jUfw61kF(X5v%R9qrlTxJP&(g#V@M>y*|;0~l^(X%97uE3+PUyO z;S4e$*$@JQY=$Nt12J@3WIdrx%PrCB?iPBUhS`Ls395;E@(9x1?PAWh>~aBc)}X@^ zgB=9T6&?bLjLIbisV1l}0V5GS=gonML{w8GeP=a+tSD(#nD|(V30ljESkKGQCbZEc zKthil2Vy+Cx#$j9BOyyfS319>Dm@}CBKi5=&W6oj6K}NFs5_@8HA?UixlxVd#76Lg z?4>x;-XLO0!c?0-}%B3v0aF1t?g{SSHsPwq6 zH)1y^i3lD0*4Y_wZmV*?rXO8<|A^} zCH*M#%Dk(xFD$pvoJVib^id0PC9{ZU1K&stV(Y=)^pYnm>;Nd z)dRS&KdRKSf#3qx+71Iz-@x6(Sj02LRXp!w7AA|--8-@)k|~?xJP+cSw(Lp=G2p!A z+N6S#m)HF-9gqD&}*$qD#S;NgXIEB4XkoKMcrCN85iOT=g- z%Y8%Una^3%Jf#2$Kv|vyl~A`WKmXuP+_QWW+~+FmrElJGhe{KBNI!A;cVCnizo{9s&hhtV z&G?%q{D>mheAN#|b1l&gSO>C48i-c3c8y>FPvjDPG7@MbU@#jXo}A@Xq3dojUt3ps zXp~#m1b6U9M|NeZ(=LNccXanK_~;q=^zgQ2?@L90=x z&`4H6PSO!a&V#0iNthJ~t<9E${1^Kek>#~-eUD_0R&GsOfX9?QX4%p4loSvT#AYaW z&aT@i5+$`UdUIgBWD(Tlya-BeaP+_V5q?U90Zg23h3(Nm<2l4R`L^l~bC0g#5;HGv zuZ0?b=IF}cJfgSVO`VfAsb|YO9=P$pt?y4(=7hr85ZF}nnXCL^FveW_Mz@XQ=M7D> zg-J)T95q>AH%~9BN23KF7DZ6+0ywC77<^(d)*Ql3}1^P#2#2zOCjB#`lEBrkdj zH{=fEXcd%B&>eCB5{v9;$&XbalgcoMKT$eCw|5N8p?nztzoAR`sug#w#5{x#=phD1 z;Ke?c9{!U}Pc~wB3h+ouGVMTAXOcM?U|+&fMLX4%){=t+Azuc=2gR(VUq&Q9-UK=E zZGvvd=*Qf>3yYMmKr5*UuL4EzWD$iaa?10_E|_|Y)Er_TV+O10blc_Hb=${&biVa{5KHMN#zjnAXz;1Uhx5ZH%A%?+W(EX5fL-b z-OJmG+?F0{ze=5)t@E*sggg`&Fex>`L(EWv8{1=fN5{H<0uS%VxFc$ZF*gt!qcRpD zv!Ryov6P%=Ew|EAAm>(oblu$Z;J_|nI&M7KrUdjE z172i2Wne(j9awaIz8 z!L~DRfGY^yVy{fS2_xI)7qo`5b}I86$U`frXHbdB_BseJQPF zO#ByaD8~ph1%8n9% z)`b)2x&NQLr_2vC4C;r^Bge3gGN%kD9$?NAv)ni5x;qhLH*hVdIt==;-CCeB}aaLZ%Zl z;@+kZz(w%^LMY_)Okx7w(g?|J-QaC8(cN?+ss#9$N(59|%CopP7QN%bB0Vu^&yk7) ztTucK1fEze`ZyEXEiw)7=zb0zjQPQIYIs6? z1Q>W&rl|}Ep)EkYObSJ2yFm-*>)yjJ;B4=_EC8?PFNx2jXqBv74s|!br@Ef+q z#0!aNY?+vk1R-TpEc1PID#Vd~zE-^z*)Y~gS_5E*xQHylxMZ=MbOa1hiDVf_Fc^zK zM59RYfqs<{Frz$48+C%lI`vlSv{-~LrD&5w`KxVCwAj{#q}50)2R0$VMT)3sB!{17 z(H-!>h!aR=pvD%=NT-ZTbceq!c>S^EUNa50=UtW4t0+=4ewYXh{4Z36uQS1>X~0qZ zqWT=5DP3Wg>GJ)mrGDMi3IT=+5XBS{v0VVXn6?b5jtE~95mU=<>m_I~N1AAu@KdPc zsAm|#uX4pwtRmDAwIoFqp3%rC5<6%Em(~g-J{Y9$UxmeV^z!USQkNGY5+dHF8qw7b zyt0=xGrdu?z=5Q|;h`iN5VRH~1lKRZQY{iP)r0&T0nmBw9^Mx7)1^pvfLN=Rw4ViF zc!>y#myCeI>dAWM0Nhg~u_q%|#z%%G>2j!qjVZOUXQSAM%xC-uniR^M6|L|w_DAR- zN3`Wjc|4Cj6T1;M_j{7oV*RA2; z9LH=+eMAXwYzD|#N@fP?MH2va8<|L>LY?3~)u3xG03H=cJ8Q2~fe^WGV%To~S37bt zkmH)m`umm;1AGi0mM7$#U%<#>C zG7i$^6&1Y8CN?tBkq9m%%ue6V74waZe&HR7A3L|TmEcvu#zP&(ztx6IakP5z$IYb0 zG}p_50Wo9}@CLy^hQ>zp7KHl;5N@G7LL>^Q&KYuW5(z;Fq@( ziVqMj$k|pMe;drl(@bx+B!UFm4nU9-@QkW`lqLi1!@u``R2m}p zO|2XLx(0qw;0JRa5~IKdM?loQNxpoUx*H&;f0_;-#orS0+`K2Erz&>DpCXMF!KR- zlHjMQ6wpS{D=4_F%@{i>f6Nqmw4q)R&&p6Esu1+M_B(x#FAlCBI!3!vrWz;{&QjSy zvY3Pm1~CHY=VKQn$Kekm+zD&GC(w^8E)1(}vm^IiWDHaz=!n6~V3&MVUKfkuV4@C~ zl@R4uwimz}$@06(D?_O>Nk3Wy#nk{?os?E+pS}Wo^x+<^&zot@nVMw=G0eaaZ+WDI zVu>p)gF4_zHsBelrz|Ftoxb6LqezCXK1pJx9K&|tb%+y6KmIf)Iyj`=MbsX}90V$& z2bWV8+@@C<46XS{afyJ#hv!ItFd1ZrvIbNDQ-CX8zLNeKQpmywom%L4QfZNEUZ#4P zg5GdG=^hcDAOH&WLE^8it#AUekvJFKPy7h-3CuuBDfEm_vvH9NJzkVABMeGr&w$N% zV~}fA&}|%kT$UI?^gr@r5634uJ|6+c(L;$!D`AW5l-v;y(*<;ql~7z{01e{Tdn7S< z%qPJIF$7}(3uxS@Oh73AM?AN<1O?e)81zrraiq@2c#Ni>=M~6=8kC+u?cAwE148F(mK`YdpD^kD<-HCdTJNgiXI%f9K{QBs7+?= z*Z{R>98e9;U`iJ13*{XE%+R2P{98@4nSg@khI3f%FwTfW809s8j|HhqAT@E32vhtY zn26)X8OM+nsi12J;`bqpNI{kH20oy;�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 -Powder Averaged CoRh₂O₄ · Sunny documentation

     diff --git a/dev/examples/spinw/08_Kagome_AFM.html b/dev/examples/spinw/08_Kagome_AFM.html deleted file mode 100644 index e870aa863..000000000 --- a/dev/examples/spinw/08_Kagome_AFM.html +++ /dev/null @@ -1,30 +0,0 @@ - -Tutorial 8 - Kagome Antiferromagnet · Sunny documentation
    GitHub

    Download this example as Jupyter notebook or Julia script.

    Tutorial 8 - Kagome Antiferromagnet

    This is a Sunny port of SpinW Tutorial 8, originally authored by Bjorn Fak and Sandor Toth. The goal is to calculate the linear spin wave theory spectrum for the $\sqrt{3} \times \sqrt{3}$ order of a Kagome antiferromagnet.

    Load Packages

    using Sunny, GLMakie

    Build a Crystal with $P\overline{3}$ space group,

    a = 1
-latvecs = lattice_vectors(a, a, 10a, 90, 90, 120)
-crystal = Crystal(latvecs, [[1/2,0,0]], 147)
    Crystal
-Spacegroup 'P -3' (147)
-Lattice params a=1, b=1, c=10, α=90°, β=90°, γ=120°
-Cell volume 8.66
-Class 1:
-   1. [1/2, 0, 0]
-   2. [0, 1/2, 0]
-   3. [1/2, 1/2, 0]
-

    Build a System with antiferrogmanetic nearest neighbor exchange $J=1$.

    S = 1
-sys = System(crystal, (3,3,1), [SpinInfo(1; S, g=2)], :dipole)
-J = 1.0
-set_exchange!(sys, J, Bond(2,3,[0,0,0]))

    Initialize to an energy minimizing magnetic structure, for which nearest-neighbor spins are at 120° angles.

    q = -[1/3, 1/3, 0]
-axis = [0,0,1]
-set_spiral_order_on_sublattice!(sys, 1; q, axis, S0=[cos(0),sin(0),0])
-set_spiral_order_on_sublattice!(sys, 2; q, axis, S0=[cos(0),sin(0),0])
-set_spiral_order_on_sublattice!(sys, 3; q, axis, S0=[cos(2π/3),sin(2π/3),0])
-plot_spins(sys; dims=2)
    Example block output

    Check energy. Each site participates in 4 bonds with energy $JS^2\cos(2π/3)$. Factor of 1/2 avoids double counting.

    @assert energy_per_site(sys) ≈ (4/2)*J*S^2*cos(2π/3)

    Define a path in reciprocal space.

    points_rlu = [[-1/2, 0, 0], [0, 0, 0], [1/2, 1/2, 0]]
-density = 100
-path, xticks = reciprocal_space_path(crystal, points_rlu, density);

    Calculate discrete intensities

    swt = SpinWaveTheory(sys)
-formula = intensity_formula(swt, :perp; kernel=delta_function_kernel)
-disp, intensity = intensities_bands(swt, path, formula);

    Plot over a restricted color range from [0,1e-2]. Note that the intensities of the flat band at zero-energy are off-scale.

    fig = Figure()
-ax = Axis(fig[1,1]; xlabel="Momentum (r.l.u.)", ylabel="Energy (meV)", xticks, xticklabelrotation=π/6)
-ylims!(ax, -1e-1, 2.3)
-for i in axes(disp, 2)
-    lines!(ax, 1:length(disp[:,i]), disp[:,i]; color=intensity[:,i], colorrange=(0,1e-2))
-end
-fig
    Example block output
    diff --git a/dev/examples/spinw/15_Ba3NbFe3Si2O14.html b/dev/examples/spinw/15_Ba3NbFe3Si2O14.html deleted file mode 100644 index 03dd99159..000000000 --- a/dev/examples/spinw/15_Ba3NbFe3Si2O14.html +++ /dev/null @@ -1,49 +0,0 @@ - -Tutorial 15 - Ba₃NbFe₃Si₂O₁₄ · Sunny documentation
    GitHub

    Download this example as Jupyter notebook or Julia script.

    Tutorial 15 - Ba₃NbFe₃Si₂O₁₄

    This is a Sunny port of SpinW Tutorial 15, originally authored by Sandor Toth. The goal is to calculate the linear spin wave theory spectrum for Ba₃NbFe₃Si₂O₁₄.

    Load packages

    using Sunny, GLMakie

    Build a Crystal for Ba₃NbFe₃Si₂O₁₄ using the crystal structure from Marty et al., Phys. Rev. Lett. 101, 247201 (2008).

    a = b = 8.539 # (Å)
-c = 5.2414
-latvecs = lattice_vectors(a, b, c, 90, 90, 120)
-types = ["Fe","Nb","Ba","Si","O","O","O"]
-positions = [[0.24964,0,0.5],[0,0,0],[0.56598,0,0],[2/3,1/3,0.5220],[2/3,1/3,0.2162],[0.5259,0.7024,0.3536],[0.7840,0.9002,0.7760]]
-langasite = Crystal(latvecs, positions, 150; types)
-crystal = subcrystal(langasite, "Fe")
-view_crystal(crystal, 7)
    Example block output

    Create a System with a lattice size of $(1,1,7)$. The magnetic structure of Ba₃NbFe₃Si₂O₁₄ was determined to have the ordering wavevector $𝐐=(0,0,1/7)$ and hence the magnetic unit cell has 7 sites.

    latsize = (1,1,7)
-S = 5/2
-seed = 5
-sys = System(crystal, latsize, [SpinInfo(1; S, g=2)], :dipole)
    System [Dipole mode]
-Lattice (1×1×7)×3
-Energy per site 0
-

    Set exchange interactions as parametrized in Loire et al., Phys. Rev. Lett. 106, 207201 (2011)

    J₁ = 0.85
-J₂ = 0.24
-J₃ = 0.053
-J₄ = 0.017
-J₅ = 0.24
-set_exchange!(sys, J₁, Bond(3, 2, [1,1,0]))
-set_exchange!(sys, J₄, Bond(1, 1, [0,0,1]))
-set_exchange!(sys, J₂, Bond(1, 3, [0,0,0]))

    The final two exchanges define the chirality of the magnetic structure. The crystal chirality, $\epsilon_T$, the chirality of each triangle, $ϵ_D$ and the sense of rotation of the spin helices along $c$, $ϵ_{H}$. The three chiralities are related by $ϵ_T=ϵ_D ϵ_H$. We now assign $J_3$ and $J_5$ according to the crystal chirality.

    ϵD = -1
-ϵH = +1
-ϵT = ϵD * ϵH
-
-if ϵT == -1
-    set_exchange!(sys, J₃, Bond(2, 3, [-1,-1,1]))
-    set_exchange!(sys, J₅, Bond(3, 2, [1,1,1]))
-elseif ϵT == 1
-    set_exchange!(sys, J₅, Bond(2, 3, [-1,-1,1]))
-    set_exchange!(sys, J₃, Bond(3, 2, [1,1,1]))
-else
-    throw("Provide a valid chirality")
-end

    Whilst Sunny provides tools to optimize the ground state automatically, in this case we already know the model ground state. Set the spiral magnetic order using set_spiral_order_on_sublattice!. It takes an ordering wavevector q, an axis of rotation for the spins axis, and the initial spin S0 for each sublattice.

    q = [0, 0, 1/7]
-axis = [0,0,1]
-set_spiral_order_on_sublattice!(sys, 1; q, axis, S0=[1, 0, 0])
-set_spiral_order_on_sublattice!(sys, 2; q, axis, S0=[-1/2, -sqrt(3)/2, 0])
-set_spiral_order_on_sublattice!(sys, 3; q, axis, S0=[-1/2, +sqrt(3)/2, 0])
-
-plot_spins(sys; color=[s[1] for s in sys.dipoles])
    Example block output

    Define a path in reciprocal space, $[0,1,-1+\xi]$ for $\xi = 0 \dots 3$.

    points_rlu = [[0,1,-1],[0,1,-1+1],[0,1,-1+2],[0,1,-1+3]];
-density = 100
-path, xticks = reciprocal_space_path(crystal, points_rlu, density);

    Calculate broadened intensities

    swt = SpinWaveTheory(sys)
-γ = 0.15 # width in meV
-broadened_formula = intensity_formula(swt, :perp; kernel=lorentzian(γ))
-energies = collect(0:0.01:6)  # 0 < ω < 6 (meV).
-is = intensities_broadened(swt, path, energies, broadened_formula);

    Plot

    fig = Figure()
-ax = Axis(fig[1,1]; xlabel="Momentum (r.l.u.)", ylabel="Energy (meV)", xticks, xticklabelrotation=π/6)
-heatmap!(ax, 1:size(is,1), energies, is, colorrange=(0,5))
-fig
    Example block output
    diff --git a/dev/examples/spinw/08_Kagome_AFM-08bb7e3d.png b/dev/examples/spinw/SW08_Kagome_AFM-08bb7e3d.png similarity index 100% rename from dev/examples/spinw/08_Kagome_AFM-08bb7e3d.png rename to dev/examples/spinw/SW08_Kagome_AFM-08bb7e3d.png diff --git a/dev/examples/spinw/08_Kagome_AFM-a51d5723.png b/dev/examples/spinw/SW08_Kagome_AFM-a51d5723.png similarity index 100% rename from dev/examples/spinw/08_Kagome_AFM-a51d5723.png rename to dev/examples/spinw/SW08_Kagome_AFM-a51d5723.png diff --git a/dev/examples/spinw/SW08_Kagome_AFM.html b/dev/examples/spinw/SW08_Kagome_AFM.html new file mode 100644 index 000000000..91150547c --- /dev/null +++ b/dev/examples/spinw/SW08_Kagome_AFM.html @@ -0,0 +1,30 @@ + +SW8 - Kagome Antiferromagnet · Sunny documentation
    GitHub

    Download this example as Jupyter notebook or Julia script.

    SW8 - Kagome Antiferromagnet

    This is a Sunny port of SpinW Tutorial 8, originally authored by Bjorn Fak and Sandor Toth. The goal is to calculate the linear spin wave theory spectrum for the $\sqrt{3} \times \sqrt{3}$ order of a Kagome antiferromagnet.

    Load Packages

    using Sunny, GLMakie

    Build a Crystal with $P\overline{3}$ space group,

    a = 1
+latvecs = lattice_vectors(a, a, 10a, 90, 90, 120)
+crystal = Crystal(latvecs, [[1/2,0,0]], 147)
    Crystal
+Spacegroup 'P -3' (147)
+Lattice params a=1, b=1, c=10, α=90°, β=90°, γ=120°
+Cell volume 8.66
+Class 1:
+   1. [1/2, 0, 0]
+   2. [0, 1/2, 0]
+   3. [1/2, 1/2, 0]
+

    Build a System with antiferrogmanetic nearest neighbor exchange $J=1$.

    S = 1
+sys = System(crystal, (3,3,1), [SpinInfo(1; S, g=2)], :dipole)
+J = 1.0
+set_exchange!(sys, J, Bond(2,3,[0,0,0]))

    Initialize to an energy minimizing magnetic structure, for which nearest-neighbor spins are at 120° angles.

    q = -[1/3, 1/3, 0]
+axis = [0,0,1]
+set_spiral_order_on_sublattice!(sys, 1; q, axis, S0=[cos(0),sin(0),0])
+set_spiral_order_on_sublattice!(sys, 2; q, axis, S0=[cos(0),sin(0),0])
+set_spiral_order_on_sublattice!(sys, 3; q, axis, S0=[cos(2π/3),sin(2π/3),0])
+plot_spins(sys; dims=2)
    Example block output

    Check energy. Each site participates in 4 bonds with energy $JS^2\cos(2π/3)$. Factor of 1/2 avoids double counting.

    @assert energy_per_site(sys) ≈ (4/2)*J*S^2*cos(2π/3)

    Define a path in reciprocal space.

    points_rlu = [[-1/2, 0, 0], [0, 0, 0], [1/2, 1/2, 0]]
+density = 100
+path, xticks = reciprocal_space_path(crystal, points_rlu, density);

    Calculate discrete intensities

    swt = SpinWaveTheory(sys)
+formula = intensity_formula(swt, :perp; kernel=delta_function_kernel)
+disp, intensity = intensities_bands(swt, path, formula);

    Plot over a restricted color range from [0,1e-2]. Note that the intensities of the flat band at zero-energy are off-scale.

    fig = Figure()
+ax = Axis(fig[1,1]; xlabel="Momentum (r.l.u.)", ylabel="Energy (meV)", xticks, xticklabelrotation=π/6)
+ylims!(ax, -1e-1, 2.3)
+for i in axes(disp, 2)
+    lines!(ax, 1:length(disp[:,i]), disp[:,i]; color=intensity[:,i], colorrange=(0,1e-2))
+end
+fig
    Example block output
    diff --git a/dev/examples/spinw/15_Ba3NbFe3Si2O14-0135a936.png b/dev/examples/spinw/SW15_Ba3NbFe3Si2O14-0135a936.png similarity index 100% rename from dev/examples/spinw/15_Ba3NbFe3Si2O14-0135a936.png rename to dev/examples/spinw/SW15_Ba3NbFe3Si2O14-0135a936.png diff --git a/dev/examples/spinw/15_Ba3NbFe3Si2O14-7b15c415.png b/dev/examples/spinw/SW15_Ba3NbFe3Si2O14-7b15c415.png similarity index 100% rename from dev/examples/spinw/15_Ba3NbFe3Si2O14-7b15c415.png rename to dev/examples/spinw/SW15_Ba3NbFe3Si2O14-7b15c415.png diff --git a/dev/examples/spinw/15_Ba3NbFe3Si2O14-9b66d42a.png b/dev/examples/spinw/SW15_Ba3NbFe3Si2O14-9b66d42a.png similarity index 100% rename from dev/examples/spinw/15_Ba3NbFe3Si2O14-9b66d42a.png rename to dev/examples/spinw/SW15_Ba3NbFe3Si2O14-9b66d42a.png diff --git a/dev/examples/spinw/SW15_Ba3NbFe3Si2O14.html b/dev/examples/spinw/SW15_Ba3NbFe3Si2O14.html new file mode 100644 index 000000000..d5e40690a --- /dev/null +++ b/dev/examples/spinw/SW15_Ba3NbFe3Si2O14.html @@ -0,0 +1,49 @@ + +SW15 - Ba₃NbFe₃Si₂O₁₄ · Sunny documentation
    GitHub

    Download this example as Jupyter notebook or Julia script.

    SW15 - Ba₃NbFe₃Si₂O₁₄

    This is a Sunny port of SpinW Tutorial 15, originally authored by Sandor Toth. The goal is to calculate the linear spin wave theory spectrum for Ba₃NbFe₃Si₂O₁₄.

    Load packages

    using Sunny, GLMakie

    Build a Crystal for Ba₃NbFe₃Si₂O₁₄ using the crystal structure from Marty et al., Phys. Rev. Lett. 101, 247201 (2008).

    a = b = 8.539 # (Å)
+c = 5.2414
+latvecs = lattice_vectors(a, b, c, 90, 90, 120)
+types = ["Fe","Nb","Ba","Si","O","O","O"]
+positions = [[0.24964,0,0.5],[0,0,0],[0.56598,0,0],[2/3,1/3,0.5220],[2/3,1/3,0.2162],[0.5259,0.7024,0.3536],[0.7840,0.9002,0.7760]]
+langasite = Crystal(latvecs, positions, 150; types)
+crystal = subcrystal(langasite, "Fe")
+view_crystal(crystal, 7)
    Example block output

    Create a System with a lattice size of $(1,1,7)$. The magnetic structure of Ba₃NbFe₃Si₂O₁₄ was determined to have the ordering wavevector $𝐐=(0,0,1/7)$ and hence the magnetic unit cell has 7 sites.

    latsize = (1,1,7)
+S = 5/2
+seed = 5
+sys = System(crystal, latsize, [SpinInfo(1; S, g=2)], :dipole)
    System [Dipole mode]
+Lattice (1×1×7)×3
+Energy per site 0
+

    Set exchange interactions as parametrized in Loire et al., Phys. Rev. Lett. 106, 207201 (2011)

    J₁ = 0.85
+J₂ = 0.24
+J₃ = 0.053
+J₄ = 0.017
+J₅ = 0.24
+set_exchange!(sys, J₁, Bond(3, 2, [1,1,0]))
+set_exchange!(sys, J₄, Bond(1, 1, [0,0,1]))
+set_exchange!(sys, J₂, Bond(1, 3, [0,0,0]))

    The final two exchanges define the chirality of the magnetic structure. The crystal chirality, $\epsilon_T$, the chirality of each triangle, $ϵ_D$ and the sense of rotation of the spin helices along $c$, $ϵ_{H}$. The three chiralities are related by $ϵ_T=ϵ_D ϵ_H$. We now assign $J_3$ and $J_5$ according to the crystal chirality.

    ϵD = -1
+ϵH = +1
+ϵT = ϵD * ϵH
+
+if ϵT == -1
+    set_exchange!(sys, J₃, Bond(2, 3, [-1,-1,1]))
+    set_exchange!(sys, J₅, Bond(3, 2, [1,1,1]))
+elseif ϵT == 1
+    set_exchange!(sys, J₅, Bond(2, 3, [-1,-1,1]))
+    set_exchange!(sys, J₃, Bond(3, 2, [1,1,1]))
+else
+    throw("Provide a valid chirality")
+end

    Whilst Sunny provides tools to optimize the ground state automatically, in this case we already know the model ground state. Set the spiral magnetic order using set_spiral_order_on_sublattice!. It takes an ordering wavevector q, an axis of rotation for the spins axis, and the initial spin S0 for each sublattice.

    q = [0, 0, 1/7]
+axis = [0,0,1]
+set_spiral_order_on_sublattice!(sys, 1; q, axis, S0=[1, 0, 0])
+set_spiral_order_on_sublattice!(sys, 2; q, axis, S0=[-1/2, -sqrt(3)/2, 0])
+set_spiral_order_on_sublattice!(sys, 3; q, axis, S0=[-1/2, +sqrt(3)/2, 0])
+
+plot_spins(sys; color=[s[1] for s in sys.dipoles])
    Example block output

    Define a path in reciprocal space, $[0,1,-1+\xi]$ for $\xi = 0 \dots 3$.

    points_rlu = [[0,1,-1],[0,1,-1+1],[0,1,-1+2],[0,1,-1+3]];
+density = 100
+path, xticks = reciprocal_space_path(crystal, points_rlu, density);

    Calculate broadened intensities

    swt = SpinWaveTheory(sys)
+γ = 0.15 # width in meV
+broadened_formula = intensity_formula(swt, :perp; kernel=lorentzian(γ))
+energies = collect(0:0.01:6)  # 0 < ω < 6 (meV).
+is = intensities_broadened(swt, path, energies, broadened_formula);

    Plot

    fig = Figure()
+ax = Axis(fig[1,1]; xlabel="Momentum (r.l.u.)", ylabel="Energy (meV)", xticks, xticklabelrotation=π/6)
+heatmap!(ax, 1:size(is,1), energies, is, colorrange=(0,5))
+fig
    Example block output
    diff --git a/dev/index.html b/dev/index.html index cff258465..6fc92f047 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Overview · Sunny documentation
    GitHub

    Overview

    Sunny is a Julia package for modeling atomic-scale magnetism. It provides powerful tools to study equilibrium and non-equilibrium magnetic phenomena. In particular, it allows estimation of dynamical structure factor intensities, $\mathcal{S}(𝐪,ω)$, to support quantitative modeling of experimental scattering data.

    Features include:

    • Generalized spin dynamics using SU(N) coherent states.
    • Ability to specify a crystal from a .cif file or its spacegroup symmetry.
    • Interactive visualizations of the 3D crystals and magnetic ordering.
    • Symmetry analysis to classify allowed interaction terms, and to propagate them by symmetry.
    • Single-ion anisotropy at arbitrary order, which can be specified using Stevens operators or as a polynomial of spin operators.
    • Monte Carlo sampling of spin configurations in thermal equilibrium, and optimization tools.
    • Measurements of dynamical correlations. At low temperature, one can use linear spin wave theory and its multi-boson generalization. This generalizes to finite temperatures using the classical dynamics, which allows for strongly nonlinear effects.
    • Long-range dipole-dipole interactions accelerated with the fast Fourier transform (FFT).
    • Support for comparison with experimental data: form factor, dipole factor, temperature-dependent classical-to-quantum factors, intensity binning, etc.
    +Overview · Sunny documentation
    GitHub

    Overview

    Sunny is a Julia package for modeling atomic-scale magnetism. It provides powerful tools to study equilibrium and non-equilibrium magnetic phenomena. In particular, it allows estimation of dynamical structure factor intensities, $\mathcal{S}(𝐪,ω)$, to support quantitative modeling of experimental scattering data.

    Features include:

    • Generalized spin dynamics using SU(N) coherent states.
    • Ability to specify a crystal from a .cif file or its spacegroup symmetry.
    • Interactive visualizations of the 3D crystals and magnetic ordering.
    • Symmetry analysis to classify allowed interaction terms, and to propagate them by symmetry.
    • Single-ion anisotropy at arbitrary order, which can be specified using Stevens operators or as a polynomial of spin operators.
    • Monte Carlo sampling of spin configurations in thermal equilibrium, and optimization tools.
    • Measurements of dynamical correlations. At low temperature, one can use linear spin wave theory and its multi-boson generalization. This generalizes to finite temperatures using the classical dynamics, which allows for strongly nonlinear effects.
    • Long-range dipole-dipole interactions accelerated with the fast Fourier transform (FFT).
    • Support for comparison with experimental data: form factor, dipole factor, temperature-dependent classical-to-quantum factors, intensity binning, etc.
    diff --git a/dev/library.html b/dev/library.html index 5008e0ebb..845bc8d3c 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
    diff --git a/dev/parallelism.html b/dev/parallelism.html index 201519c18..3e01b68dc 100644 --- a/dev/parallelism.html +++ b/dev/parallelism.html @@ -1,5 +1,5 @@ -Parallelizing Calculations · Sunny documentation
    GitHub

    Parallelizing Calculations

    Calculating structure factors with classical dynamics is computationally expensive, and Sunny does not currently parallelize these calculations at a fine-grained level. However, Julia provides facilities that allow users to run multiple simulations in parallel with only a little extra effort. We will look at two approaches to doing this: multithreading and Julia's Distributed package. We'll present these approaches in a series of code snippets that can be copied and pasted into your preferred Julia development environment.

    Review of the serial workflow

    The serial approach to calculating a structure factor, covered in FeI₂ at Finite Temperature, involves thermalizing a spin System and then calling add_sample!. add_sample! uses the state of the System as an initial condition for the calculation of a dynamical trajectory. The correlations of the trajectory are calculated and accumulated into a running average of the $𝒮(𝐪,ω)$. This sequence is repeated to generate additional samples.

    To illustrate, we'll set up a a simple model: a spin-1 antiferromagnet on an FCC crystal. 

    using Sunny, GLMakie
+Parallelizing Calculations · Sunny documentation
    GitHub
    Parallelizing Calculations
    Calculating structure factors with classical dynamics is computationally expensive, and Sunny does not currently parallelize these calculations at a fine-grained level. However, Julia provides facilities that allow users to run multiple simulations in parallel with only a little extra effort. We will look at two approaches to doing this: multithreading and Julia's Distributed package. We'll present these approaches in a series of code snippets that can be copied and pasted into your preferred Julia development environment.
    Review of the serial workflow
    The serial approach to calculating a structure factor, covered in the FeI₂ tutorial, involves thermalizing a spin System and then calling add_sample!. add_sample! uses the state of the System as an initial condition for the calculation of a dynamical trajectory. The correlations of the trajectory are calculated and accumulated into a running average of the $𝒮(𝐪,ω)$. This sequence is repeated to generate additional samples.
    To illustrate, we'll set up a a simple model: a spin-1 antiferromagnet on an FCC crystal. 
    using Sunny, GLMakie
 
 function make_system(cryst; J, dims, seed=nothing)
     sys = System(cryst, dims, [SpinInfo(1, S=1, g=2)], :dipole; seed)
@@ -63,4 +63,4 @@
     end
 
     return sc
-end
    Finally, merge the results into a summary SampledCorrelations.
    sc = merge_correlations(scs)
    
+end

    Finally, merge the results into a summary SampledCorrelations.

    sc = merge_correlations(scs)
    diff --git a/dev/renormalization.html b/dev/renormalization.html index 0e22c632d..3b379032c 100644 --- a/dev/renormalization.html +++ b/dev/renormalization.html @@ -1,5 +1,5 @@ -Interaction Strength Renormalization · Sunny documentation
    GitHub

    Interaction Strength Renormalization

    A unique feature of Sunny is its support for building classical models where quantum spin is represented as an $N$-level system, rather than just an expected dipole. This generalization can be important when modeling quantum spin Hamiltonians that include, e.g., a single-ion anisotropy, or a biquadratic coupling between sites. Sunny also supports constraining quantum spin to the space of pure dipoles; in this case, Sunny will automatically perform an interaction strength renormalization that maximizes accuracy.

    Local operators

    A quantum spin-$S$ state has $N = 2S + 1$ levels. Each local spin operator $\hat{S}^{\{x,y,z\}}$ is faithfully represented as an $N×N$ matrix. These matrices can be accessed using spin_matrices for a given label $S$. For example, the Pauli matrices are associated with $S = 1/2$.

    When $S > 1/2$, it is possible to construct multipole moments beyond the spin-dipole. For example,

    S = spin_matrices(3/2)
+Interaction Strength Renormalization · Sunny documentation
    GitHub
    Interaction Strength Renormalization
    A unique feature of Sunny is its support for building classical models where quantum spin is represented as an $N$-level system, rather than just an expected dipole. This generalization can be important when modeling quantum spin Hamiltonians that include, e.g., a single-ion anisotropy, or a biquadratic coupling between sites. Sunny also supports constraining quantum spin to the space of pure dipoles; in this case, Sunny will automatically perform an interaction strength renormalization that maximizes accuracy.
    Local operators
    A quantum spin-$S$ state has $N = 2S + 1$ levels. Each local spin operator $\hat{S}^{\{x,y,z\}}$ is faithfully represented as an $N×N$ matrix. These matrices can be accessed using spin_matrices for a given label $S$. For example, the Pauli matrices are associated with $S = 1/2$.
    When $S > 1/2$, it is possible to construct multipole moments beyond the spin-dipole. For example,
    S = spin_matrices(3/2)
 @assert S[3] ≈ diagm([3/2, 1/2, -1/2, -3/2])
 @assert S[3]^2 ≈ diagm([9/4, 1/4, 1/4, 9/4])
    If the operator -S[3]^2 is passed to set_onsite_coupling!, it would set an easy-axis anisotropy in the $\hat{z}$ direction.
    Any Hermitian operator can be expanded in the basis of Stevens operators $\hat{\mathcal{O}}_{k,q}$ up to a constant shift. To see this expansion, use print_stevens_expansion:
    print_stevens_expansion((S[1]^2 + S[2]^2)) # Prints -(1/3)𝒪₂₀ + 5/2
    Alternatively, the same operator could have been constructed directly from stevens_matrices:
    O = stevens_matrices(3/2)
 @assert S[1]^2 + S[2]^2 ≈ -O[2, 0]/3 + (5/2)*I
    See below for an explicit definition of Stevens operators as polynomials of the spin operators.
    Renormalization procedure for :dipole mode
    Sunny will typically operate in one of two modes: :SUN or :dipole. The former faithfully represents quantum spin as an SU(N) coherent-state which, for our purposes, is an $N$-component complex vector. In contrast, :dipole mode constrains the coherent-state to the space of pure dipoles. Here, Sunny will automatically renormalize the magnitude of each Stevens operator to achieve maximal consistency with :SUN mode. This procedure was derived in D. Dahlbom et al., [arXiv:2304.03874].
    By way of illustration, consider a quantum operator $\hat{\mathcal{H}}_{\mathrm{local}}$ giving a single-ion anisotropy for one site. In Stevens operators,
    \[\hat{\mathcal H}_{\mathrm{local}} = \sum_{k, q} A_{k,q} \hat{\mathcal{O}}_{k,q},\]
    for some coefficients $A_{k,q}$.
    In :SUN mode, Sunny will faithfully represent $\hat{\mathcal H}_{\mathrm{local}}$ as an $N×N$ matrix. In :dipole mode, the expected energy $\langle \hat{\mathcal H}_{\mathrm{local}} \rangle$ must somehow be approximated as a function of the expected dipole $\mathbf{s}$.
    One approach is to formally take $S \to \infty$, and this yields the traditional classical limit of a spin system. In this, limit spin operators commute, and expectation values of polynomials become polynomials of expectation values. For example, $\langle \hat{S}^\alpha \hat{S}^\beta\rangle \to \langle \hat{S}^\alpha \rangle \langle \hat{S}^\beta\rangle$, because any corrections are damped by the factor $S^{-1} \to 0$. The expectation of a Stevens operator $\langle \hat{\mathcal{O}}_{k,q} \rangle$ becomes a Stevens function $\mathcal{O}_{k,q}(\mathbf{s})$, i.e., a polynomial of expected dipole $\mathbf{s} = \langle \hat{\mathbf{S}} \rangle$.
    In a real magnetic compound, however, the spin magnitude $S$ is not necessarily large. To obtain a better approximation, one should avoid the assumption $S \to \infty$. Our approach is to start with the full dynamics of SU(N) coherent states, and then constrain it to the space of pure dipole states $|\mathbf{s}\rangle$. The latter are defined such that expectation values,
    \[\langle \mathbf{s}| \hat{\mathbf{S}} | \mathbf{s}\rangle = \mathbf{s},\]
    have magnitude $|\mathbf{s}| = S$, which is maximal.
    For pure dipole states, expectations can be computed exactly,
    \[\langle \mathbf{s}| \hat{\mathcal{O}} | \mathbf{s}\rangle = c_k \mathcal{O}_{k,q}(\mathbf{s}).\]
    The right-hand side involves a renormalization of the Stevens functions, where
    \[\begin{align*}
@@ -49,4 +49,4 @@
 \hat{\mathcal{O}}_{6,\pm2} & =\phi_{\pm}(\hat{S}_{+}^{2}\pm\hat{S}_{-}^{2})(33\hat{S}_{z}^{4}-(18X+123)\hat{S}_{z}^{2}+X^{2}+10X+102)+\mathrm{h.c.}\\
 \hat{\mathcal{O}}_{6,\pm1} & =\phi_{\pm}(\hat{S}_{+}\pm\hat{S}_{-})(33\hat{S}_{z}^{5}-(30X-15)\hat{S}_{z}^{3}+(5X^{2}-10X+12)\hat{S}_{z})+\mathrm{h.c.}\\
 \hat{\mathcal{O}}_{6,0} & =231\hat{S}_{z}^{6}-(315X-735)\hat{S}_{z}^{4}+(105X^{2}-525X+294)\hat{S}_{z}^{2}-5X^{3}+40X^{2}-60X
-\end{align*}\]
    Computer-generated tables of Stevens operators with $k > 6$ are available from C. Rudowicz and C. Y. Chung, J. Phys.: Condens. Matter 16, 5825 (2004), but these typically do not appear in magnetic simulations.
    The case $k=1$ gives the dipole operators,
    \[(\hat{\mathcal{O}}_{1,1}, \hat{\mathcal{O}}_{1,0}, \hat{\mathcal{O}}_{1,-1}) = (\hat{S}_{x}, \hat{S}_{z}, \hat{S}_{y}).\]
    The case $k=2$ gives the quadrupole operators,
    \[(\hat{\mathcal{O}}_{2,2}, \dots, \hat{\mathcal{O}}_{2,-2}) = \left(\hat{S}_x^2 - \hat{S}_y^2, \frac{\hat{S}_x \hat{S}_z + \hat{S}_z \hat{S}_x}{2}, 2\hat{S}_z^2-\hat{S}_x^2-\hat{S}_y^2, \frac{\hat{S}_y \hat{S}_z + \hat{S}_z \hat{S}_y}{2}, \hat{S}_x \hat{S}_y + \hat{S}_y \hat{S}_x\right).\]
    For each $k$ value, the set of operators $\hat{\mathcal{O}}_{k,q'}$ for $q' = -k, \dots, k$ form an irreducible representation of the group of rotations O(3). That is, rotation will transform $\hat{\mathcal{O}}_{k,q}$ into a linear combination of $\hat{\mathcal{O}}_{k,q'}$ where $q'$ varies but $k$ remains fixed. 
    In taking the large-$S$ limit, each dipole operator is replaced by its expectation value $\mathbf{s} = \langle \hat{\mathbf{S}} \rangle$, and only leading-order terms are retained. The operator $\hat{\mathcal{O}}_{k,q}$ becomes a homogeneous polynomial $O_{k,q}(\mathbf{s})$ of order $k$ in the spin components. One can see these polynomials by constructing stevens_matrices with the argument S = Inf. Due to the normalization constraint, each dipole can be expressed in polar angles, $(\theta, \phi)$. Then the Stevens functions $O_{k,q}(\mathbf{s})$ correspond to the spherical harmonic functions $Y_l^m(\theta, \phi)$ where $l=k$ and $m=q$; this correspondence is valid up to $k$ and $q$-dependent rescaling factors.
    
+\end{align*}\]
    Computer-generated tables of Stevens operators with $k > 6$ are available from C. Rudowicz and C. Y. Chung, J. Phys.: Condens. Matter 16, 5825 (2004), but these typically do not appear in magnetic simulations.
    The case $k=1$ gives the dipole operators,
    \[(\hat{\mathcal{O}}_{1,1}, \hat{\mathcal{O}}_{1,0}, \hat{\mathcal{O}}_{1,-1}) = (\hat{S}_{x}, \hat{S}_{z}, \hat{S}_{y}).\]
    The case $k=2$ gives the quadrupole operators,
    \[(\hat{\mathcal{O}}_{2,2}, \dots, \hat{\mathcal{O}}_{2,-2}) = \left(\hat{S}_x^2 - \hat{S}_y^2, \frac{\hat{S}_x \hat{S}_z + \hat{S}_z \hat{S}_x}{2}, 2\hat{S}_z^2-\hat{S}_x^2-\hat{S}_y^2, \frac{\hat{S}_y \hat{S}_z + \hat{S}_z \hat{S}_y}{2}, \hat{S}_x \hat{S}_y + \hat{S}_y \hat{S}_x\right).\]
    For each $k$ value, the set of operators $\hat{\mathcal{O}}_{k,q'}$ for $q' = -k, \dots, k$ form an irreducible representation of the group of rotations O(3). That is, rotation will transform $\hat{\mathcal{O}}_{k,q}$ into a linear combination of $\hat{\mathcal{O}}_{k,q'}$ where $q'$ varies but $k$ remains fixed. 
    In taking the large-$S$ limit, each dipole operator is replaced by its expectation value $\mathbf{s} = \langle \hat{\mathbf{S}} \rangle$, and only leading-order terms are retained. The operator $\hat{\mathcal{O}}_{k,q}$ becomes a homogeneous polynomial $O_{k,q}(\mathbf{s})$ of order $k$ in the spin components. One can see these polynomials by constructing stevens_matrices with the argument S = Inf. Due to the normalization constraint, each dipole can be expressed in polar angles, $(\theta, \phi)$. Then the Stevens functions $O_{k,q}(\mathbf{s})$ correspond to the spherical harmonic functions $Y_l^m(\theta, \phi)$ where $l=k$ and $m=q$; this correspondence is valid up to $k$ and $q$-dependent rescaling factors.
    diff --git a/dev/search_index.js b/dev/search_index.js index 677263bf7..e3ec0f803 100644 --- a/dev/search_index.js +++ b/dev/search_index.js @@ -1,3 +1,3 @@ var documenterSearchIndex = {"docs": -[{"location":"parallelism.html#Parallelizing-Calculations","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"","category":"section"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"Calculating structure factors with classical dynamics is computationally expensive, and Sunny does not currently parallelize these calculations at a fine-grained level. However, Julia provides facilities that allow users to run multiple simulations in parallel with only a little extra effort. We will look at two approaches to doing this: multithreading and Julia's Distributed package. We'll present these approaches in a series of code snippets that can be copied and pasted into your preferred Julia development environment.","category":"page"},{"location":"parallelism.html#Review-of-the-serial-workflow","page":"Parallelizing Calculations","title":"Review of the serial workflow","text":"","category":"section"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"The serial approach to calculating a structure factor, covered in FeI₂ at Finite Temperature, involves thermalizing a spin System and then calling add_sample!. add_sample! uses the state of the System as an initial condition for the calculation of a dynamical trajectory. The correlations of the trajectory are calculated and accumulated into a running average of the 𝒮(𝐪ω). This sequence is repeated to generate additional samples.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"To illustrate, we'll set up a a simple model: a spin-1 antiferromagnet on an FCC crystal. ","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"using Sunny, GLMakie\n\nfunction make_system(cryst; J, dims, seed=nothing)\n sys = System(cryst, dims, [SpinInfo(1, S=1, g=2)], :dipole; seed)\n set_exchange!(sys, J, Bond(1,1,[1,0,0]))\n return sys\nend\n\nJ = 1.0 # meV \ncryst = Sunny.fcc_primitive_crystal()\nsys = make_system(cryst; J, dims=(10,10,2))","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"To thermalize and generate equilibrium samples, we'll need a Langevin integrator. ","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"kT = 0.5 # meV\nΔt = 0.05/J\nintegrator = Langevin(Δt; kT, λ=0.1)","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"Finally, call dynamical_correlations to configure a SampledCorrelations.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"sc = dynamical_correlations(sys; Δt=0.1, nω=100, ωmax=10.0)","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"The serial calculation can now be performed as follows:","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"nsamples = 10\n\n# Thermalize the system\nfor _ in 1:5000 # Sufficient number of steps to thermalize\n step!(sys, integrator)\nend\n\nfor _ in 1:nsamples\n # Generate new sample by running Langevin dynamics\n for _ in 1:1000 # Sufficient number of steps to decorrelate\n step!(sys, integrator)\n end\n # Add the sample to the correlation data\n add_sample!(sc, sys)\nend","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"This will take a second or two on a modern workstation, resulting in a single SampledCorrelations that contains 10 samples.","category":"page"},{"location":"parallelism.html#Multithreading-approach","page":"Parallelizing Calculations","title":"Multithreading approach","text":"","category":"section"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"To use threads in Julia, you must launch your Julia environment appropriately.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"From the command line, launch Julia with julia --threads=N, where N is the number of threads. If you don't know how many threads you'd like, you can let Julia decide with --threads=auto.\nJupyter notebook users will need to to set up a multithreaded Julia kernel and restart into this kernel. The kernel can be created inside Julia with the following:","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":" using IJulia\n IJulia.installkernel(\"Julia Multithreaded\",\n env=Dict(\"JULIA_NUM_THREADS\" => \"auto\"))","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"VSCode users should open their settings and search for Julia: Additional Args. There will be link called Edit in settings.json. Click on this, add \"--threads=auto\" to the list julia.additionalArgs, and start a new REPL.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"Before going further, make sure that Threads.nthreads() returns a number greater than 1.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"We will use multithreading in a very simple way, essentially employing a distributed memory approach to avoid conflicts around memory access. First preallocate a number of systems and correlations.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"npar = Threads.nthreads()\nsystems = [make_system(cryst; J, dims=(10,10,2), seed=i) for i in 1:npar]\nscs = [dynamical_correlations(sys; Δt=0.1, nω=100, ωmax=10.0) for _ in 1:npar]","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"warning: Dealing with memory constraints\nIf you have many threads available and are working with a large system, you may not have enough memory to store all these systems and correlations. In that case, simply reduce npar to a small enough value that you can make the necessary allocations.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"When the Threads.@threads macro is applied before a for loop, the iterations of the loop will execute in parallel using the available threads. We will put the entire thermalization and sampling process inside the loop, with each thread acting on a unique System and SampledCorrelations.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"Threads.@threads for id in 1:npar\n integrator = Langevin(Δt; kT, λ=0.1)\n for _ in 1:5000\n step!(systems[id], integrator)\n end\n for _ in 1:nsamples\n for _ in 1:1000\n step!(systems[id], integrator)\n end\n add_sample!(scs[id], systems[id])\n end\nend","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"You may find this takes a little bit longer than the serial example, but, at the end of it, you will have generated npar correlation objects, each with 10 samples. We can merge these into a summary SampledCorrelations with 10*npar samples with merge_correlations:","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"sc = merge_correlations(scs)","category":"page"},{"location":"parallelism.html#Using-Distributed","page":"Parallelizing Calculations","title":"Using Distributed","text":"","category":"section"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"Julia also provides a distributed memory approach to parallelism through the standard library package Distributed. This works by launching independent Julia environments on different \"processes.\" An advantage of this approach is that it scales naturally to clusters since the processes are easily distributed across many different compute nodes. A disadvantage, especially when working on a single computer, is the increased memory overhead associated with launching all these environments.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"We begin by importing the package,","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"using Distributed","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"and launching some new processes. It is often sensible to create as many processes as there are cores.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"ncores = length(Sys.cpu_info())\naddprocs(ncores)","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"You can think of each process as a separate computer running a fresh Julia environment, so we'll need to import Sunny and define our function in each of these environments. This is easily achieved with the @everywhere macro.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"@everywhere using Sunny\n\n@everywhere function make_system(cryst; J, dims, seed=nothing)\n sys = System(cryst, dims, [SpinInfo(1, S=1, g=2)], :dipole; seed)\n set_exchange!(sys, J, Bond(1,1,[1,0,0]))\n return sys\nend","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"A simple way to perform work on these processes is to use the parallel map function, pmap. This will apply a function to each element of some iterable, such as a list of numbers, and return a list of the results. It is a parallel map because these function calls may occur at the same time on different Julia processes. The pmap function takes care of distributing the work among the different processes and retrieving the results.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"In the example below, we give pmap a list of RNG seeds to iterate over, and we define the function that will be applied to each of these seeds in a do block. The contents of this block are essentially the same as what we put inside our parallel for loop in the multithreading example. The main difference is that the Systems and SampledCorrelations are not created in advance of the parallelization but are instead created inside each Julia process. The do block returns a SampledCorrelations, and the output of all the parallel computations are collected into list of SampledCorrelations called scs.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"scs = pmap(1:ncores) do seed\n sys = make_system(Sunny.fcc_primitive_crystal(); J=1.0, dims=(10,10,2), seed)\n sc = dynamical_correlations(sys; Δt=0.1, nω=100, ωmax=10.0)\n integrator = Langevin(Δt; kT, λ=0.1)\n\n for _ in 1:5000 # Thermalize\n step!(sys, integrator)\n end\n for _ in 1:nsamples \n for _ in 1:1000 \n step!(sys, integrator)\n end\n add_sample!(sc, sys)\n end\n\n return sc\nend","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"Finally, merge the results into a summary SampledCorrelations.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"sc = merge_correlations(scs)","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"EditURL = \"../../../examples/fei2_tutorial.jl\"","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"Download this example as Jupyter notebook or Julia script.","category":"page"},{"location":"examples/fei2_tutorial.html#Case-Study:-FeI","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"","category":"section"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"FeI₂ is an effective spin-1 material with strong single-ion anisotropy. Quadrupolar fluctuations give rise to a single-ion bound state that cannot be described by a dipole-only model. This tutorial illustrates how to use the linear spin wave theory of SU(3) coherent states (i.e. 2-flavor bosons) to model the magnetic behavior in FeI₂. The original study was performed in Bai et al., Nature Physics 17, 467–472 (2021).","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"The Fe atoms are arranged in stacked triangular layers. The effective spin Hamiltonian takes the form,","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"mathcalH=sum_(ij) 𝐒_i J_ij 𝐒_j - Dsum_i left(S_i^zright)^2","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"where the set of exchange matrices J_ij between bonded sites (ij) includes competing ferromagnetic and antiferromagnetic interactions. This model also includes a strong easy axis anisotropy, D 0.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"We will formulate this Hamiltonian in Sunny and then calculate its dynamic structure factor.","category":"page"},{"location":"examples/fei2_tutorial.html#Get-Julia-and-Sunny","page":"Case Study: FeI₂","title":"Get Julia and Sunny","text":"","category":"section"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"Sunny is implemented in Julia. This is a relatively new programming language that allows for interactive development (like Python or Matlab) while also providing high numerical efficiency (like C++ or Fortran). New Julia users may wish to take a look at our Getting Started with Julia guide. Sunny requires Julia 1.9 or later.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"From the Julia prompt, load Sunny. For plotting, one can choose either GLMakie (a pop-up window) or WGLMakie (inline plots for a Jupyter notebook or VSCode).","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"using Sunny, GLMakie","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"If these packages are not yet installed, Julia should offer to install them using its built-in package management system. If old versions are installed, you may need to update them to run this tutorial.","category":"page"},{"location":"examples/fei2_tutorial.html#Crystals","page":"Case Study: FeI₂","title":"Crystals","text":"","category":"section"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"A Crystal describes the crystallographic unit cell and will usually be loaded from a .cif file. Here, we instead build a crystal by listing all atoms and their types.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"a = b = 4.05012 # Lattice constants for triangular lattice\nc = 6.75214 # Spacing in the z-direction\n\nlatvecs = lattice_vectors(a, b, c, 90, 90, 120) # A 3x3 matrix of lattice vectors that\n # define the conventional unit cell\npositions = [[0, 0, 0], [1/3, 2/3, 1/4], [2/3, 1/3, 3/4]] # Positions of atoms in fractions\n # of lattice vectors\ntypes = [\"Fe\", \"I\", \"I\"]\nFeI2 = Crystal(latvecs, positions; types)","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"Observe that Sunny inferred the space group, 'P -3 m 1' (164) and labeled the atoms according to their point group symmetries.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"Only the Fe atoms are magnetic, so we discard the I ions using subcrystal.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"cryst = subcrystal(FeI2, \"Fe\")","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"Observe that cryst retains the spacegroup symmetry of the full FeI₂ crystal. This information will be used, for example, to propagate exchange interactions between symmetry-equivalent bonds.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"In a running Julia environment, the crystal can be viewed interactively using view_crystal.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"view_crystal(cryst, 8.0)","category":"page"},{"location":"examples/fei2_tutorial.html#Symmetry-analysis","page":"Case Study: FeI₂","title":"Symmetry analysis","text":"","category":"section"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"The command print_symmetry_table provides a list of all the symmetry-allowed interactions up to a cutoff distance.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"print_symmetry_table(cryst, 8.0)","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"The allowed g-tensor is expressed as a 3×3 matrix in the free coefficients A, B, ... The allowed single-ion anisotropy is expressed as a linear combination of Stevens operators. The latter correspond to polynomials of the spin operators, as we will describe below.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"The allowed exchange interactions are given as a 3×3 matrix for representative bonds. The notation Bond(i, j, n) indicates a bond between atom indices i and j, with cell offset n. In the general case, it will be necessary to associate atom indices with their positions in the unit cell; these can be viewed with display(cryst). Note that the order of the pair (i j) is significant if the exchange tensor contains antisymmetric Dzyaloshinskii–Moriya (DM) interactions.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"In the case of FeI₂, Bond(1, 1, [1,0,0]) is one of the 6 nearest-neighbor Fe-Fe bonds on a triangular lattice layer, and Bond(1, 1, [0,0,1]) is an Fe-Fe bond between layers.","category":"page"},{"location":"examples/fei2_tutorial.html#Building-a-spin-System","page":"Case Study: FeI₂","title":"Building a spin System","text":"","category":"section"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"In constructing a spin System, we must provide several additional details about the spins.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"sys = System(cryst, (4, 4, 4), [SpinInfo(1, S=1, g=2)], :SUN, seed=2)","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"This system includes 444 unit cells, i.e. 64 Fe atoms, each with spin S=1 and a g-factor of 2. Quantum mechanically, spin S=1 involves a superposition of 2S+1=3 distinct angular momentum states. In :SUN mode, this superposition will be modeled explicitly using the formalism of SU(3) coherent states, which captures both dipolar and quadrupolar fluctuations. For the more traditional dipole dynamics, use :dipole mode instead.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"Next we will use set_exchange! to assign interaction to bonds. Sunny will automatically propagate each interaction to all symmetry-equivalent bonds in the unit cell. The FeI₂ interactions below follow Bai et al.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"J1pm = -0.236\nJ1pmpm = -0.161\nJ1zpm = -0.261\nJ2pm = 0.026\nJ3pm = 0.166\nJ′0pm = 0.037\nJ′1pm = 0.013\nJ′2apm = 0.068\n\nJ1zz = -0.236\nJ2zz = 0.113\nJ3zz = 0.211\nJ′0zz = -0.036\nJ′1zz = 0.051\nJ′2azz = 0.073\n\nJ1xx = J1pm + J1pmpm\nJ1yy = J1pm - J1pmpm\nJ1yz = J1zpm\n\nset_exchange!(sys, [J1xx 0.0 0.0;\n 0.0 J1yy J1yz;\n 0.0 J1yz J1zz], Bond(1,1,[1,0,0]))\nset_exchange!(sys, [J2pm 0.0 0.0;\n 0.0 J2pm 0.0;\n 0.0 0.0 J2zz], Bond(1,1,[1,2,0]))\nset_exchange!(sys, [J3pm 0.0 0.0;\n 0.0 J3pm 0.0;\n 0.0 0.0 J3zz], Bond(1,1,[2,0,0]))\nset_exchange!(sys, [J′0pm 0.0 0.0;\n 0.0 J′0pm 0.0;\n 0.0 0.0 J′0zz], Bond(1,1,[0,0,1]))\nset_exchange!(sys, [J′1pm 0.0 0.0;\n 0.0 J′1pm 0.0;\n 0.0 0.0 J′1zz], Bond(1,1,[1,0,1]))\nset_exchange!(sys, [J′2apm 0.0 0.0;\n 0.0 J′2apm 0.0;\n 0.0 0.0 J′2azz], Bond(1,1,[1,2,1]))","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"The function set_onsite_coupling! assigns a single-ion anisotropy. The argument can be constructed using spin_matrices or stevens_matrices. Here we use Julia's anonymous function syntax to assign an easy-axis anisotropy along the direction hatz.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"D = 2.165\nset_onsite_coupling!(sys, S -> -D*S[3]^2, 1)","category":"page"},{"location":"examples/fei2_tutorial.html#Calculating-structure-factor-intensities","page":"Case Study: FeI₂","title":"Calculating structure factor intensities","text":"","category":"section"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"In the remainder of this tutorial, we will examine Sunny's tools for calculating the dynamical structure factor using a multi-boson generalization of linear spin wave theory (LSWT). This theory describes non-interacting quasi-particle excitations that hybridize dipolar and quadrupolar modes.","category":"page"},{"location":"examples/fei2_tutorial.html#Finding-the-ground-state","page":"Case Study: FeI₂","title":"Finding the ground state","text":"","category":"section"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"Begin with a random configuration and use minimize_energy! to find a configuration of the SU(3) coherent states (i.e. spin dipoles and quadrupoles) that locally minimizes energy.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"randomize_spins!(sys)\nminimize_energy!(sys)","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"A positive number above indicates that the procedure has converged to a local energy minimum. The configuration, however, may still have defects. This can be checked by visualizing the spins, colored according to their z-components.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"plot_spins(sys; color=[s[3] for s in sys.dipoles])","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"A different understanding of the magnetic ordering can be obtained by moving to Fourier space. The 'instant' structure factor 𝒮(𝐪) is an experimental observable. To investigate 𝒮(𝐪) as true 3D data, Sunny provides instant_correlations and related functions. Here, however, we will use print_wrapped_intensities, which gives average intensities for the individual Bravais sublattices (in effect, all wavevectors are wrapped to the first Brillouin zone).","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"print_wrapped_intensities(sys)","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"The result will likely be approximately consistent with the known zero-field energy-minimizing magnetic structure of FeI₂, which is single-Q (two-up, two-down antiferromagnetic order). Mathematically, spontaneous symmetry breaking should select one of Q = 0 -14 14, 14 0 14, or -141414, associated with the three-fold rotational symmetry of the crystal spacegroup. In nature, however, one will frequently encounter competing \"domains\" associated with the three possible orientations of the ground state.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"If the desired ground state is already known, as with FeI₂, it could be entered by hand using set_dipole!. Alternatively, in the case of FeI₂, we could repeatedly employ the above randomization and minimization procedure until a defect-free configuration is found. Some systems will have more complicated ground states, which can be much more challenging to find. For this, Sunny provides experimental support for powerful simulated annealing via parallel tempering, but that is outside the scope of this tutorial.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"Here, let's break the three-fold symmetry of FeI₂ by hand. Given one or more desired Q modes, Sunny can suggest a magnetic supercell with appropriate periodicity. Let's arbitrarily select one of the three possible ordering wavevectors, Q = 0 -14 14. Sunny suggests a corresponding magnetic supercell in units of the crystal lattice vectors.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"suggest_magnetic_supercell([[0, -1/4, 1/4]])","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"The system returned by reshape_supercell is smaller, and is sheared relative to the original system. This makes it much easier to find the global energy minimum.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"sys_min = reshape_supercell(sys, [1 0 0; 0 2 1; 0 -2 1])\nrandomize_spins!(sys_min)\nminimize_energy!(sys_min);\nnothing #hide","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"Plot the system again, now including \"ghost\" spins out to 12Å","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"plot_spins(sys_min; color=[s[3] for s in sys_min.dipoles], ghost_radius=12)","category":"page"},{"location":"examples/fei2_tutorial.html#Linear-spin-wave-theory","page":"Case Study: FeI₂","title":"Linear spin wave theory","text":"","category":"section"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"Now that we have found the ground state for a magnetic supercell, we can immediately proceed to perform zero-temperature calculations using linear spin wave theory. We begin by instantiating a SpinWaveTheory type using the supercell.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"swt = SpinWaveTheory(sys_min)","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"Select a sequence of wavevectors that will define a piecewise linear interpolation in reciprocal lattice units (RLU).","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"q_points = [[0,0,0], [1,0,0], [0,1,0], [1/2,0,0], [0,1,0], [0,0,0]];\nnothing #hide","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"The function reciprocal_space_path will linearly sample a path between the provided q-points with a given density. The xticks return value provides labels for use in plotting.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"density = 50\npath, xticks = reciprocal_space_path(cryst, q_points, density);\nnothing #hide","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"The dispersion function defines the quasiparticle excitation energies ω_i(𝐪) for each point 𝐪 along the reciprocal space path.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"disp = dispersion(swt, path);\nnothing #hide","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"In addition to the band energies ω_i(𝐪), Sunny can calculate the inelastic neutron scattering intensity I_i(𝐪) for each band i according to an intensity_formula. We choose to apply a polarization correction (1 - 𝐪𝐪) by setting the mode argument to :perp. Selecting delta_function_kernel specifies that we want the energy and intensity of each band individually.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"formula = intensity_formula(swt, :perp; kernel=delta_function_kernel)","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"The function intensities_bands uses linear spin wave theory to calculate both the dispersion and intensity data for the provided path.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"disp, intensity = intensities_bands(swt, path, formula);\nnothing #hide","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"These can be plotted in GLMakie.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"fig = Figure()\nax = Axis(fig[1,1]; xlabel=\"Momentum (r.l.u.)\", ylabel=\"Energy (meV)\", xticks, xticklabelrotation=π/6)\nylims!(ax, 0.0, 7.5)\nxlims!(ax, 1, size(disp, 1))\ncolorrange = extrema(intensity)\nfor i in axes(disp, 2)\n lines!(ax, 1:length(disp[:,i]), disp[:,i]; color=intensity[:,i], colorrange)\nend\nfig","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"To make comparisons with inelastic neutron scattering (INS) data, it is helpful to employ an empirical broadening kernel, e.g., a lorentzian.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"γ = 0.15 # width in meV\nbroadened_formula = intensity_formula(swt, :perp; kernel=lorentzian(γ))","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"The intensities_broadened function requires an energy range in addition to the 𝐪-space path.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"energies = collect(0:0.01:10) # 0 < ω < 10 (meV).\nis1 = intensities_broadened(swt, path, energies, broadened_formula);\nnothing #hide","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"A real FeI₂ sample will exhibit competing magnetic domains associated with spontaneous symmetry breaking of the 6-fold rotational symmetry of the triangular lattice. Note that the wavevectors 𝐪 and -𝐪 are equivalent in the structure factor, which leaves three distinct domain orientations, which are related by 120° rotations about the z-axis. Rather than rotating the spin configuration directly, on can rotate the 𝐪-space path. Below, we use rotation_in_rlu to average the intensities over all three possible orientations.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"R = rotation_in_rlu(cryst, [0, 0, 1], 2π/3)\nis2 = intensities_broadened(swt, [R*q for q in path], energies, broadened_formula)\nis3 = intensities_broadened(swt, [R*R*q for q in path], energies, broadened_formula)\nis_averaged = (is1 + is2 + is3) / 3\n\nfig = Figure()\nax = Axis(fig[1,1]; xlabel=\"Momentum (r.l.u.)\", ylabel=\"Energy (meV)\", xticks, xticklabelrotation=π/6)\nheatmap!(ax, 1:size(is_averaged, 1), energies, is_averaged)\nfig","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"This result can be directly compared to experimental neutron scattering data from Bai et al.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"(The publication figure accidentally used a non-standard coordinate system to label the wave vectors.)","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"To get this agreement, the use of SU(3) coherent states is essential. In other words, we needed a theory of multi-flavored bosons. The lower band has large quadrupolar character, and arises from the strong easy-axis anisotropy of FeI₂. By setting mode = :SUN, the calculation captures this coupled dipole-quadrupole dynamics.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"An interesting exercise is to repeat the same study, but using mode = :dipole instead of :SUN. That alternative choice would constrain the coherent state dynamics to the space of dipoles only.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"The full dynamical spin structure factor (DSSF) can be retrieved as a 33 matrix with the dssf function, for a given path of 𝐪-vectors.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"disp, is = dssf(swt, path);\nnothing #hide","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"The first output disp is identical to that obtained from dispersion. The second output is contains a list of 33 matrix of intensities. For example, is[q,n][2,3] yields the (yz) component of the structure factor intensity for nth mode at the qth wavevector in the path.","category":"page"},{"location":"examples/fei2_tutorial.html#What's-next?","page":"Case Study: FeI₂","title":"What's next?","text":"","category":"section"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"The multi-boson linear spin wave theory, applied above, can be understood as the quantization of a certain generalization of the Landau-Lifshitz spin dynamics. Rather than dipoles, this dynamics takes places on the space of SU(N) coherent states.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"The full SU(N) coherent state dynamics, with appropriate quantum correction factors, can be useful to model finite temperature scattering data. In particular, it captures certain anharmonic effects due to thermal fluctuations. This is the subject of our FeI₂ at Finite Temperature tutorial.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"The classical dynamics is also a good starting point to study non-equilibrium phenomena. Empirical noise and damping terms can be used to model coupling to a thermal bath. This yields a Langevin dynamics of SU(N) coherent states. Our CP² Skyrmion Quench tutorial shows how this dynamics gives rise to the formation of novel topological defects in a temperature quench.","category":"page"},{"location":"examples/fei2_tutorial.html","page":"Case Study: FeI₂","title":"Case Study: FeI₂","text":"Relative to LSWT calculations, it can take much more time to estimate mathcalS(𝐪ω) intensities using classical dynamics simulation. See the SunnyTutorials notebooks for examples of \"production-scale\" simulations.","category":"page"},{"location":"structure-factor.html#Structure-Factor-Calculations","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"","category":"section"},{"location":"structure-factor.html#Overview","page":"Structure Factor Calculations","title":"Overview","text":"","category":"section"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"The dynamical structure factor is of fundamental importance for characterizing a magnetic system, and facilitates quantitative comparison between theory and experimental scattering data.","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"Consider, for example, a two-point dynamical spin correlation function, s^α(𝐱+Δ𝐱 t+Δt) s^β(𝐱 t). Here s^α(𝐱 t) represents the time dynamics of a spin dipole component α at position 𝐱, and brackets represent an average over equilibrium initial conditions and over (𝐱 t). The dynamical structure factor is defined as the Fourier transform of this two-point correlation in both space and time, up to an overall scaling factor. Using the convolution theorem, the result is,","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"𝒮^αβ(𝐪 ω) = frac1V s^α(𝐪 ω)^ast s^β(𝐪 ω) ","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"with V the system volume. We will restrict attention to lattice systems with periodic boundaries.","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"Consider a crystal unit cell defined by three lattice vectors 𝐚_1 𝐚_2 𝐚_3, and linear system sizes L_1 L_2 L_3 measured in unit cells. The allowed momentum vectors take on discrete values 𝐪 = sum_α=1^3 m_α 𝐛_α L_α, where m_α are an integers and the reciprocal lattice vectors 𝐛_α are defined to satisfy 𝐚_α 𝐛_β = 2π δ_αβ. For a Bravais lattice, 𝐪 will be periodic in the first Brillouin zone, i.e., under any shift 𝐪 𝐪 𝐛_α. More generally, consider a non-Bravais lattice such that each unit cell may contain multiple spins. By partitioning spins s_j(𝐱t) according to their sublattice index j, the relevant momenta 𝐪 remain discretized as above, but now periodicity in the first Brillouin zone is lost. The structure factor may be written as a phase-average over the displacements between sublattices 𝐫_jk,","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"𝒮^αβ(𝐪 ω) = _jk e^i 𝐫_jk 𝐪 𝒮^αβ_jk(𝐪 ω) ","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"From a theoretical perspective, the quantity","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"𝒮^αβ_jk(𝐪 ω) = frac1V s_j^α(𝐪 ω)^ast s_k^β(𝐪 ω)","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"is fundamental. For each sublattice j, the data s_j^α(𝐪 ω) can be efficiently obtained by fast Fourier tranformation of a real space configuration s_j^α(𝐱 t). Internally, Sunny will calculate and store the discrete 𝒮^αβ_jk(𝐪 ω) correlation data, and use this to construct 𝒮^αβ(𝐪ω) intensities that can be compared with experiment.","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"Calculating this structure factor involves several steps, with various possible settings. Sunny provides a number of tools to facilitate this calculation and to extract information from the results. These tools are briefly outlined below. Please see the Examples for a \"real life\" use case. Detailed function information is available in the Library API.","category":"page"},{"location":"structure-factor.html#Estimating-stucture-factors-with-classical-dynamics","page":"Structure Factor Calculations","title":"Estimating stucture factors with classical dynamics","text":"","category":"section"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"Classical dynamics may be used to estimate structure factor data by analyzing the spin-spin correlations of dynamical trajectories. This is fundamentally a Monte Carlo approach, as the trajectories must be started from an initial spin configuration that is sampled at thermal equilibrium. (Note that it is not possible to estimate a true T=0 dynamical structure factor using this method, but the temperature may be very low.) Samples are accumulated into a SampledCorrelations, from which intensity information may be extracted. The user does not typically build their own SampledCorrelations but instead initializes one by calling either dynamical_correlations or instant_correlations, as described below.","category":"page"},{"location":"structure-factor.html#Estimating-a-dynamical-structure-factor:-𝒮(𝐪,ω)","page":"Structure Factor Calculations","title":"Estimating a dynamical structure factor: 𝒮(𝐪ω)","text":"","category":"section"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"A SampledCorrelations for estimating the dynamical structure factor, 𝒮^αβ(𝐪ω), may be created by calling dynamical_correlations. This requires three keyword arguments. These will determine the dynamics used to calculate samples and, consequently, the ω information that will be available. ","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"Δt: Determines the step size used for simulating the dynamics. A smaller number will require proportionally more calculation time. While a smaller Δt will enable the resolution of higher energies, Δt is typically selected to ensure numerical stability rather than to maximize the largest ω value. A safe choice is to use the smaller value of Δt = 0.1/(J* S^2) or Δt = 0.1/(D * S), where S is magnetic moment of the largest local spin (as specified in SpinInfo), J is the parameter governing the largest bilinear interaction (e.g. exchange), and D is the parameter governing the largest single-site term of the Hamiltonian (e.g., anisotropy or Zeeman term).\nωmax: Sets the maximum resolved energy. Note that this is not independent of Δt. If ωmax too large, Sunny will throw an error and ask you to choose a smaller Δt. \nnω: Determines the number of energy bins to resolve. A larger number will require more calculation time.","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"A sample may be added by calling add_sample!(sc, sys). The input sys must be a spin configuration in good thermal equilibrium, e.g., using the continuous Langevin dynamics or using single spin flip trials with LocalSampler. The statistical quality of the 𝒮^αβ(𝐪ω) can be improved by repeatedly generating decorrelated spin configurations in sys and calling add_sample! on each configuration.","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"The outline of typical use case might look like this:","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"# Make a `SampledCorrelations`\nsc = dynamical_correlations(sys; Δt=0.05, ωmax=10.0, nω=100) \n\n# Add samples\nfor _ in 1:nsamples\n decorrelate_system(sys) # Perform some type of Monte Carlo simulation\n add_sample!(sc, sys) # Use spins to calculate trajectory and accumulate new sample of 𝒮(𝐪,ω)\nend","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"The calculation may be configured in a number of ways; see the dynamical_correlations documentation for a list of all keywords.","category":"page"},{"location":"structure-factor.html#Estimating-an-instantaneous-(\"static\")-structure-factor:-𝒮(𝐪)","page":"Structure Factor Calculations","title":"Estimating an instantaneous (\"static\") structure factor: 𝒮(𝐪)","text":"","category":"section"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"Sunny provides two methods for calculating instantaneous, or static, structure factors: 𝒮^αβ(𝐪). The first involves calculating spatial spin-spin correlations at single time slices. The second involves calculating a dynamic structure factor first and integrating out the ω information. The advantage of the latter approach is that it enables application of an ω-dependent classical-to-quantum rescaling of structure factor intensities, a method that should be preferred whenever comparing results to experimental data or spin wave calculations. A disadvantage of this approach is that it is computationally more expensive. There are also many cases when it is not straightforward to calculate a meaningful dynamics, as when working with Ising spins. In this section we will discuss how to calculate instantaneous structure factors from static spin configurations. Information about calculating instantaneous data from a dynamical correlations can be found in the following section.","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"The basic usage for the instantaneous case is very similar to the dynamic case, except one calls instant_correlations instead of dynamical_correlations to configure a SampledCorrelations. Note that there are no required keywords as there is no need to specify any dynamics. instant_correlations will return a SampledCorrelations containing no data. Samples may be added by calling add_sample!(sc, sys), where sc is the SampledCorrelations. When performing a finite-temperature calculation, it is important to ensure that the spin configuration in the sys represents a good equilibrium sample, as in the dynamical case. Note, however, that we recommend calculating instantaneous correlations at finite temperature calculations by using full dynamics (i.e., using dynamical_correlations) and then integrating out the energy axis. An approach to doing this is described in the next section.","category":"page"},{"location":"structure-factor.html#Extracting-information-from-sampled-correlation-data","page":"Structure Factor Calculations","title":"Extracting information from sampled correlation data","text":"","category":"section"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"The basic function for extracting information from a SampledCorrelations at a particular wave vector, 𝐪, is intensities_interpolated. It takes a SampledCorrelations, a list of wave vectors, and an intensity_formula. The intensity_formula specifies how to contract and correct correlation data to arrive at a physical intensity. A simple example is formula = intensity_formula(sc, :perp), which will instruct Sunny apply polarization corrections: sum_αβ(I-q_α q_β) 𝒮^αβ(𝐪ω). An intensity at the wave vector 𝐪 = (𝐛_2 + 𝐛_3)2 may then be retrieved with intensities_interpolated(sf, [[0.0, 0.5, 0.5]], formula) . intensities_interpolated returns a list of nω elements at each wavevector. The corresponding ω values can be retrieved by calling available_energies on sf.","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"Since Sunny only calculates the structure factor on a finite lattice when performing classical simulations, it is important to realize that exact information is only available at a discrete set of wave vectors. Specifically, for each axis index i, we will get information at q_i = fracnL_i, where n runs from (frac-L_i2+1) to fracL_i2 and L_i is the linear dimension of the lattice used for the calculation. If you request a wave vector that does not fall into this set, Sunny will automatically round to the nearest 𝐪 that is available. If intensities_interpolated is given the keyword argument interpolation=:linear, Sunny will use trilinear interpolation to determine a result at the requested wave vector. ","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"To retrieve the intensities at all wave vectors for which there is exact data, first call the function available_wave_vectors to generate a list of qs. This takes an optional keyword argument bzsize, which must be given a tuple of three integers specifying the number of Brillouin zones to calculate, e.g., bzsize=(2,2,2). The resulting list of wave vectors may then be passed to intensities_interpolated.","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"Alternatively, intensities_binned can be used to place the exact data into histogram bins for comparison with experiment.","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"The convenience function reciprocal_space_path returns a list of wavevectors sampled along a path that connects specified 𝐪 points. This list can be used as an input to intensities. Another convenience method, reciprocal_space_shell will generate points on a sphere of a given radius. This is useful for powder averaging. ","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"A number of arguments for intensity_formula are available which modify the calculation of structure factor intensity. It is generally recommended to provide a value of kT corresponding to the temperature of sampled configurations. Given kT, Sunny will include an energy- and temperature-dependent classical-to-quantum rescaling of intensities in the formula.","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"To retrieve intensity data from a instantaneous structure factor, use instant_intensities_interpolated, which accepts similar arguments to intensities_interpolated. This function may also be used to calculate instantaneous information from a dynamical correlation data, i.e. from a SampledCorrelations created with dynamical_correlations. Note that it is important to supply a value to kT to reap the benefits of this approach over simply calculating a static structure factor at the outset. ","category":"page"},{"location":"writevtk.html#ParaView-Rendering","page":"ParaView Rendering","title":"ParaView Rendering","text":"","category":"section"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"The 4D correlation data produced by Sunny is too high-dimensional to visualize directly. This page describes how to export 3D slices of correlation data from Sunny to the Visual ToolKit (VTK) format, which is compatible with the ParaView visualization software. ParaView supports volumetric rendering:","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"","category":"page"},{"location":"writevtk.html#Simulation-data","page":"ParaView Rendering","title":"Simulation data","text":"","category":"section"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"First, generate some correlation data in Sunny. We will use a 2D lattice, since the correlation data S(Q_xQ_yomega) is 3D and can be exported in its entirety. The following code sets up the system, thermalizes it, and records the correlation data in a SampledCorrelations called dsf.","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"using Sunny\n\n# Single layer 12x12 periodic square lattice\nlatsize = (12,12,1)\n\nlatvecs = lattice_vectors(8.,8.,12.,90,100,90)\npositions = [[0,0,0]]\ntypes = [\"Cu\"]\nformfactors = [FormFactor(\"Cu2\")]\nxtal = Crystal(latvecs, positions; types)\n\nsys = System(xtal, latsize, [SpinInfo(1, S=1/2, g=2)], :SUN; seed=1)\n\nJ = 10.\nset_exchange!(sys, J, Bond(1,1,[1,0,0]))\nset_exchange!(sys, J, Bond(1,1,[0,1,0]))\n\nΔt = 0.01\nkT = 0.5\nlangevin = Langevin(Δt; λ=0.5, kT)\nrandomize_spins!(sys)\nfor i in 1:10_000 # Long enough to reach equilibrium\n step!(sys, langevin)\nend \n\nωmax=10.\n\ndsf = dynamical_correlations(sys\n ;Δt=Δt\n ,nω=48\n ,ωmax=ωmax\n ,process_trajectory=:symmetrize)\n\nnsamples = 10\nfor _ in 1:nsamples\n for _ in 1:1000 \n step!(sys, langevin)\n end\n add_sample!(dsf, sys)\nend","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"The default histogram BinningParameters are already integrated over the z direction because the system is 2D:","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"unit_resolution_binning_parameters(dsf)","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"⊡ 12 bins from -0.042 to +0.958 along [+1.27 dx] (Δ = 0.065)\n⊡ 12 bins from -0.042 to +0.958 along [+1.27 dy] (Δ = 0.065)\n∫ Integrated from +0.000 to +0.000 along [-0.33 dx +1.88 dz] (Δ = 0.524)\n⊡ 48 bins from -0.107 to +10.134 along [+1.00 dE] (Δ = 0.213)","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"The histogram is very oblong; it's approximately 1x1x10. To make it a nicer shape, we will rescale the energy axis to be be fractions of ωmax:","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"params = unit_resolution_binning_parameters(dsf)\nscale_factor = ωmax\nparams.binend[4] /= scale_factor\nparams.binstart[4] /= scale_factor\nparams.binwidth[4] /= scale_factor\nparams.covectors[4,:] ./= scale_factor","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"Doing this changes the last axis of the histogram to fit in [0,1]:","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"⊡ 49 bins from -0.011 to +1.013 along [+0.10 dE] (Δ = 0.213)","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"Now that our histogram is a cube, we compute the intensity in the histogram bins using the usual intensities_binned:","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"formula = intensity_formula(dsf,:trace)\nsignal, counts = intensities_binned(dsf, params; formula)\nintensity = signal ./ counts","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"Now that we have our intensity data and the binning parameters, we can export to VTK format using export_vtk and move to ParaView for the visualization.","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"# Importing WriteVTK enables Sunny's export-to-VTK functions\nimport WriteVTK\n\n# [1,2,4] specifies that the (x,y,z) axes in ParaView are (Qx,Qy,ω)\nexport_vtk(\"square_lattice\", params, intensity; dims_kept = [1,2,4])\n# Writes a file square_lattice.vti in the current directory","category":"page"},{"location":"writevtk.html#Loading-in-ParaView","page":"ParaView Rendering","title":"Loading in ParaView","text":"","category":"section"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"In ParaView, use File > Open to open square_lattice.vti. This will add the file to the Pipeline Browser with a closed eye icon, indicating that the data is ready to be loaded.","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"In the Properties panel, both bin_centers and data will be selected for import by default. Uncheck bin_centers because we don't need that information for the visualization. Click the green Apply button to load the data.","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"By default, only the outline of the data is shown in the 3D viewport. Since we adjusted the energy axis, the outline is a 1x1x1 cube. Optionally enable the axes grid under \"View\", and customize using the adjacent edit button.","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"To enable the volumetric render:","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"Select \"Volume\" from the \"Representation\" drop-down menu under \"Display\".\nThe \"Coloring\" drop-down should automatically select data because it's the only data loaded.\nOpen the Color Map Editor to adjust the opacity of the fog, which may be too faint to see by default.","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"Depending on your computer and your dataset size, the volumetric rendering may be slow, but our dataset is relatively small, so the render should be fast.","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"If nothing shows up at first, don't despair. Often, there are Bragg-like peaks in the correlation data which outshine everything else. To see this, enable Display Data Histogram in the Color Map Editor panel. To zoom in on the lower-intensity data, click and drag the right side handle of the opacity transfer function box to the middle a few times.","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"After suitable color mapping, the dispersion curve should become visible:","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"","category":"page"},{"location":"writevtk.html#Experiment-data","page":"ParaView Rendering","title":"Experiment data","text":"","category":"section"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"Note that since only the data and binning parameters are required for exporting to VTK, experiment data can be exported in the same way. For example, to visualize S(Q_xQ_yQ_z), do this:","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"# Load 4D histogram data from Mantid\nparams, signal = load_nxs(\"experiment_data.nxs\")\n\n# Integrate out the energy axis so we are 3D\nintegrate_axes!(params; axes = 4)\nsignal = sum(signal; dims = 4)\n\n# Export to ParaView\nexport_vtk(\"experiment_data_as_vtk\", params, signal)","category":"page"},{"location":"examples/ising2d.html","page":"Classical Ising model","title":"Classical Ising model","text":"EditURL = \"../../../examples/ising2d.jl\"","category":"page"},{"location":"examples/ising2d.html","page":"Classical Ising model","title":"Classical Ising model","text":"Download this example as Jupyter notebook or Julia script.","category":"page"},{"location":"examples/ising2d.html#Classical-Ising-model","page":"Classical Ising model","title":"Classical Ising model","text":"","category":"section"},{"location":"examples/ising2d.html","page":"Classical Ising model","title":"Classical Ising model","text":"This tutorial illustrates simulation of the classical 2D Ising model.","category":"page"},{"location":"examples/ising2d.html","page":"Classical Ising model","title":"Classical Ising model","text":"using Sunny, GLMakie","category":"page"},{"location":"examples/ising2d.html","page":"Classical Ising model","title":"Classical Ising model","text":"Sunny expects a 3D Crystal unit cell. To model a square lattice, we create an orthogonal unit cell where the z-spacing is distinct from the x and y spacing.","category":"page"},{"location":"examples/ising2d.html","page":"Classical Ising model","title":"Classical Ising model","text":"a = 1\nlatvecs = lattice_vectors(a,a,10a,90,90,90)\ncrystal = Crystal(latvecs, [[0,0,0]])","category":"page"},{"location":"examples/ising2d.html","page":"Classical Ising model","title":"Classical Ising model","text":"Create a System of spins with linear size L in the x and y directions, and only one layer in the z direction. The option :dipole means that the system will store Heisenberg spins, as opposed to SU(N) coherent states. Polarize the initial spin configuration using polarize_spins!. Following the Ising convention, we will restrict these spins to the z-axis and give them magnitude S=1.","category":"page"},{"location":"examples/ising2d.html","page":"Classical Ising model","title":"Classical Ising model","text":"By default, Sunny uses physical units, e.g. magnetic field in tesla. Here we specify an alternative Units system, so that the Zeeman coupling between the spin dipole 𝐬 and an external field 𝐁 has the dimensionless form -𝐁𝐬.","category":"page"},{"location":"examples/ising2d.html","page":"Classical Ising model","title":"Classical Ising model","text":"L = 128\nsys = System(crystal, (L,L,1), [SpinInfo(1, S=1, g=1)], :dipole, units=Units.theory, seed=0)\npolarize_spins!(sys, (0,0,1))","category":"page"},{"location":"examples/ising2d.html","page":"Classical Ising model","title":"Classical Ising model","text":"Use set_exchange! to include a ferromagnetic Heisenberg interaction along nearest-neighbor bonds. The Bond below connects two spins displaced by one lattice constant in the x-direction. This interaction will be propagated to all nearest-neighbors bonds in the system, consistent with the symmetries of the square lattice.","category":"page"},{"location":"examples/ising2d.html","page":"Classical Ising model","title":"Classical Ising model","text":"set_exchange!(sys, -1.0, Bond(1,1,(1,0,0)))","category":"page"},{"location":"examples/ising2d.html","page":"Classical Ising model","title":"Classical Ising model","text":"If an external field is desired, it can be set using set_external_field!.","category":"page"},{"location":"examples/ising2d.html","page":"Classical Ising model","title":"Classical Ising model","text":"B = 0\nset_external_field!(sys, (0,0,B))","category":"page"},{"location":"examples/ising2d.html","page":"Classical Ising model","title":"Classical Ising model","text":"The critical temperature for the Ising model is known analytically.","category":"page"},{"location":"examples/ising2d.html","page":"Classical Ising model","title":"Classical Ising model","text":"Tc = 2/log(1+√2)","category":"page"},{"location":"examples/ising2d.html","page":"Classical Ising model","title":"Classical Ising model","text":"Use a LocalSampler to perform nsweeps Monte Carlo sweeps. A sweep consists of, on average, one trial update per spin in the system. Each proposed update is accepted or rejected according to the Metropolis acceptance probability. As its name suggests, the propose_flip function will only propose pure spin flips, 𝐬 rightarrow -𝐬.","category":"page"},{"location":"examples/ising2d.html","page":"Classical Ising model","title":"Classical Ising model","text":"nsweeps = 4000\nsampler = LocalSampler(kT=Tc, propose=propose_flip)\nfor i in 1:nsweeps\n step!(sys, sampler)\nend","category":"page"},{"location":"examples/ising2d.html","page":"Classical Ising model","title":"Classical Ising model","text":"Plot the Ising spins by extracting the z-component of the dipoles","category":"page"},{"location":"examples/ising2d.html","page":"Classical Ising model","title":"Classical Ising model","text":"heatmap(reshape([s.z for s in sys.dipoles], (L,L)))","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"EditURL = \"../../../examples/powder_averaging.jl\"","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"Download this example as Jupyter notebook or Julia script.","category":"page"},{"location":"examples/powder_averaging.html#Powder-Averaged-CoRhO","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"","category":"section"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"This tutorial illustrates the calculation of the powder-averaged structure factor by performing an orientational average. We consider a simple model of the diamond-cubic crystal CoRh₂O₄, with parameters extracted from Ge et al., Phys. Rev. B 96, 064413.","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"using Sunny, GLMakie","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"Construct a diamond Crystal in the conventional (non-primitive) cubic unit cell. Sunny will populate all eight symmetry-equivalent sites when given the international spacegroup number 227 (\"Fd-3m\") and the appropriate setting. For this spacegroup, there are two conventional translations of the unit cell, and it is necessary to disambiguate through the setting keyword argument. (On your own: what happens if setting is omitted?)","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"a = 8.5031 # (Å)\nlatvecs = lattice_vectors(a, a, a, 90, 90, 90)\ncryst = Crystal(latvecs, [[0,0,0]], 227, setting=\"1\")","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"In a running Julia environment, the crystal can be viewed interactively using view_crystal.","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"view_crystal(cryst, 8.0)","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"Construct a System with an antiferromagnetic nearest neighbor interaction J. Because the diamond crystal is bipartite, the ground state will have unfrustrated Néel order. Selecting latsize=(1,1,1) is sufficient because the ground state is periodic over each cubic unit cell. By passing an explicit seed, the system's random number generator will give repeatable results.","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"latsize = (2, 2, 2)\nseed = 0\nS = 3/2\nJ = 7.5413*meV_per_K # (~ 0.65 meV)\nsys = System(cryst, latsize, [SpinInfo(1; S, g=2)], :dipole; seed=0)\nset_exchange!(sys, J, Bond(1, 3, [0,0,0]))","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"In the ground state, each spin is exactly anti-aligned with its 4 nearest-neighbors. Because every bond contributes an energy of -JS^2, the energy per site is -2JS^2. In this calculation, a factor of 1/2 avoids double-counting the bonds. Due to lack of frustration, direct energy minimization is successful in finding the ground state.","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"randomize_spins!(sys)\nminimize_energy!(sys)\n\n@assert energy_per_site(sys) ≈ -2J*S^2","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"Plotting the spins confirms the expected Néel order. Note that the overall, global rotation of dipoles is arbitrary.","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"s0 = sys.dipoles[1,1,1,1]\nplot_spins(sys; color=[s'*s0 for s in sys.dipoles])","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"For numerical efficiency, it will be helpful to work with the smallest possible magnetic supercell. Here, it is the primitive unit cell, which contains just two sites. The variable shape below defines the primitive lattice vectors cryst.prim_latvecs in units of the conventional lattice vectors. This result is used as input to reshape_supercell. The energy per site remains the same, which verifies that the magnetic supercell is valid.","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"shape = cryst.latvecs \\ cryst.prim_latvecs\nsys_prim = reshape_supercell(sys, shape)\n@assert energy_per_site(sys_prim) ≈ -2J*S^2","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"Now estimate 𝒮(𝐪ω) with SpinWaveTheory and an intensity_formula. The mode :perp contracts with a dipole factor to return the unpolarized intensity. The formula also employs lorentzian broadening. The isotropic FormFactor for Cobalt(2+) dampens intensities at large 𝐪.","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"swt = SpinWaveTheory(sys_prim)\nη = 0.4 # (meV)\nkernel = lorentzian(η)\nformfactors = [FormFactor(\"Co2\")]\nformula = intensity_formula(swt, :perp; kernel, formfactors)","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"For the \"single crystal\" result, we may use reciprocal_space_path to construct a path that connects high-symmetry points in reciprocal space. The intensities_broadened function collects intensities along this path for the given set of energy values.","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"qpoints = [[0.0, 0.0, 0.0], [0.5, 0.0, 0.0], [0.5, 0.5, 0.0], [0.0, 0.0, 0.0]]\npath, xticks = reciprocal_space_path(cryst, qpoints, 50)\nenergies = collect(0:0.01:6)\nis = intensities_broadened(swt, path, energies, formula)\n\nfig = Figure()\nax = Axis(fig[1,1]; aspect=1.4, ylabel=\"ω (meV)\", xlabel=\"𝐪 (r.l.u.)\",\n xticks, xticklabelrotation=π/10)\nheatmap!(ax, 1:size(is, 1), energies, is, colormap=:gnuplot2)\nfig","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"A powder measurement effectively involves an average over all possible crystal orientations. We use the function reciprocal_space_shell to sample n wavevectors on a sphere of a given radius (inverse angstroms), and then calculate the spherically-averaged intensity.","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"radii = 0.01:0.02:3 # (1/Å)\noutput = zeros(Float64, length(radii), length(energies))\nfor (i, radius) in enumerate(radii)\n n = 300\n qs = reciprocal_space_shell(cryst, radius, n)\n is = intensities_broadened(swt, qs, energies, formula)\n output[i, :] = sum(is, dims=1) / size(is, 1)\nend\n\nfig = Figure()\nax = Axis(fig[1,1]; xlabel=\"Q (Å⁻¹)\", ylabel=\"ω (meV)\")\nheatmap!(ax, radii, energies, output, colormap=:gnuplot2)\nfig","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"This result can be compared to experimental neutron scattering data from Fig. 5 of Ge et al.","category":"page"},{"location":"examples/powder_averaging.html","page":"Powder Averaged CoRh₂O₄","title":"Powder Averaged CoRh₂O₄","text":"","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"EditURL = \"../../../examples/out_of_equilibrium.jl\"","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"Download this example as Jupyter notebook or Julia script.","category":"page"},{"location":"examples/out_of_equilibrium.html#CP-Skyrmion-Quench","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"","category":"section"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"This example demonstrates Sunny's ability to simulate the out-of-equilibrium dynamics of generalized spin systems. We will implement the model Hamiltonian of Zhang et al., Nature Communications 14, 3626 (2023), which supports a novel type of topological defect, a CP² skyrmion, that involves both the dipolar and quadrupolar parts of a quantum spin.","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"Beginning from an initial high-temperature state, a disordered gas of CP² skyrmions can be formed by rapidly quenching to low temperature. To model the coupled dynamics of dipoles and quadrupoles, Sunny uses a recently developed generalization of the Landau-Lifshitz spin dynamics, Dahlbom et al., Phys. Rev. B 106, 235154 (2022).","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"using Sunny, GLMakie","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"The Hamiltonian we will implement,","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"mathcalH = sum_langle ij rangle J_ij( hatS_i^x hatS_j^x + hatS_i^y hatS_j^y + DeltahatS_i^z hatS_j^z) - hsum_ihatS_i^z + Dsum_i(hatS_i^z)^2","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"contains competing ferromagnetic nearest-neightbor and antiferromagnetic next-nearest-neighbor exchange terms on a triangular lattice. Both exchanges exhibit anisotropy on the z-term. Additionally, there is an external magnetic field, h, and easy-plane single-ion anisotropy, D 0. We begin by implementing the Crystal.","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"lat_vecs = lattice_vectors(1.0, 1.0, 2.0, 90, 90, 120)\nbasis_vecs = [[0,0,0]]\ncryst = Crystal(lat_vecs, basis_vecs)","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"The crystal is then used to create a spin System. All parameters in this model system are dimensionless, so we select \"theory\" units and set the g-factor to one.","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"L = 40\ndims = (L, L, 1)\nsys = System(cryst, dims, [SpinInfo(1, S=1, g=1)], :SUN; seed=101, units=Units.theory)","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"We proceed to implement each term of the Hamiltonian, selecting our parameters so that the system occupies a region of the phase diagram that supports skyrmions. The exchange interactions are set as follows.","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"J1 = -1 # Nearest-neighbor ferromagnetic\nJ2 = (2.0/(1+√5)) # Tune competing exchange to set skyrmion scale length\nΔ = 2.6 # Exchange anisotropy\n\nex1 = J1 * [1.0 0.0 0.0;\n 0.0 1.0 0.0;\n 0.0 0.0 Δ]\nex2 = J2 * [1.0 0.0 0.0;\n 0.0 1.0 0.0;\n 0.0 0.0 Δ]\nset_exchange!(sys, ex1, Bond(1, 1, [1, 0, 0]))\nset_exchange!(sys, ex2, Bond(1, 1, [1, 2, 0]))","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"Next we add the external field,","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"h = 15.5\nfield = set_external_field!(sys, [0.0 0.0 h])","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"and finally an easy-plane single-ion anisotropy,","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"D = 19.0\nset_onsite_coupling!(sys, S -> D*S[3]^2, 1)","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"Initialize system to an infinite temperature (fully randomized) initial condition.","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"randomize_spins!(sys)","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"We are now ready to simulate the quenching process using a generalized Langevin spin dynamics. If we were working with spin dipoles only, then Langevin dynamics would be the usual Landau-Lifshitz spin dynamics, augmented with damping and noise terms. In the present study, we are instead working with quantum spin-1 (an (N=3)-level system that includes both dipoles and quadrupoles). Here, Langevin captures the coupled dipole-quadrupole dynamics using the formalism of SU(N) coherent states.","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"Selecting kT = 0 in the Langevin dynamics will effective disable the noise term. Then the parameter λ effectively determines the damping time-scale.","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"Δt = 0.2/D # Integration time step (inverse meV). Typically this will be\n # inversely proportional to the largest energy scale in the\n # system. We can use a fairly large time-step here because\n # accuracy isn't critical.\nkT = 0 # Target equilibrium temperature (meV)\nλ = 0.1 # Magnitude of coupling to thermal bath (dimensionless)\nintegrator = Langevin(Δt; kT, λ)","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"Finally we run the dynamics. We will record the state of the system at three different times during the quenching process by copying the coherents field of the System.","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"τs = [4., 16, 256] # Times to record snapshots\nframes = [] # Empty array to store snapshots\nfor i in eachindex(τs)\n dur = i == 1 ? τs[1] : τs[i] - τs[i-1] # Determine the length of time to simulate\n numsteps = round(Int, dur/Δt)\n for _ in 1:numsteps # Perform the integration\n step!(sys, integrator)\n end\n push!(frames, copy(sys.coherents)) # Save a snapshot spin configuration\nend","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"To visualize the state of the system contained in each snapshot, we will calculate and plot the skyrmion density on each plaquette of our lattice. The function plot_triangular_plaquettes is not part of the core Sunny package, but rather something you could define yourself. We are using the definition in plotting2d.jl from the Sunny examples/extra directory.","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"include(pkgdir(Sunny, \"examples\", \"extra\", \"plotting2d.jl\"))\n\nfunction sun_berry_curvature(z₁, z₂, z₃)\n z₁, z₂, z₃ = normalize.((z₁, z₂, z₃))\n n₁ = z₁ ⋅ z₂\n n₂ = z₂ ⋅ z₃\n n₃ = z₃ ⋅ z₁\n return angle(n₁ * n₂ * n₃)\nend\n\nplot_triangular_plaquettes(sun_berry_curvature, frames; resolution=(1800,600),\n offset_spacing=10, texts = [\"\\tt = \"*string(τ) for τ in τs], text_offset = (0.0, 6.0)\n)","category":"page"},{"location":"examples/out_of_equilibrium.html","page":"CP² Skyrmion Quench","title":"CP² Skyrmion Quench","text":"The times are given in hbarJ_1. The white background corresponds to a quantum paramagnetic state, where the local spin exhibits a strong quadrupole moment and little or no dipole moment. Observe that the process has generated a number of well-formed skyrmions of both positive (red) and negative (blue) charge in addition to a number of other metastable spin configurations. A full-sized version of this figure is available in Dahlbom et al..","category":"page"},{"location":"library.html#Library-API","page":"Library API","title":"Library API","text":"","category":"section"},{"location":"library.html","page":"Library API","title":"Library API","text":"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).","category":"page"},{"location":"library.html","page":"Library API","title":"Library API","text":"","category":"page"},{"location":"library.html","page":"Library API","title":"Library API","text":"Sunny.plot_spins\nSunny.view_crystal\nSunny.export_vtk","category":"page"},{"location":"library.html","page":"Library API","title":"Library API","text":"Modules = [Sunny]\nPrivate = false","category":"page"},{"location":"library.html#Sunny.Site","page":"Library API","title":"Sunny.Site","text":"(cell1, cell2, cell3, i) :: Site\n\nFour 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).\n\nThis 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!.\n\nNote 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.\n\n\n\n\n\n","category":"type"},{"location":"library.html#Sunny.Units","page":"Library API","title":"Sunny.Units","text":"Units.meV\nUnits.theory\n\nThe 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.\n\nSee also meV_per_K\n\n\n\n\n\n","category":"constant"},{"location":"library.html#Sunny.meV_per_K","page":"Library API","title":"Sunny.meV_per_K","text":"meV_per_K = 0.086173332621451774\n\nA physical constant. Useful for converting kelvin into the default energy units, meV.\n\n\n\n\n\n","category":"constant"},{"location":"library.html#Sunny.BinningParameters","page":"Library API","title":"Sunny.BinningParameters","text":"BinningParameters(binstart,binend,binwidth;covectors = I(4))\nBinningParameters(binstart,binend;numbins,covectors = I(4))\n\nDescribes 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.\n\nThe 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.\n\nThe convention for the binning scheme is that:\n\nThe left edge of the first bin starts at binstart\nThe bin width is binwidth\nThe last bin contains binend\nThere are no \"partial bins;\" the last bin may contain values greater than binend. C.f. count_bins.\n\nA value can be binned by computing its bin index:\n\ncoords = covectors * value\nbin_ix = 1 .+ floor.(Int64,(coords .- binstart) ./ binwidth)\n\n\n\n\n\n","category":"type"},{"location":"library.html#Sunny.Bond","page":"Library API","title":"Sunny.Bond","text":"Bond(i, j, n)\n\nRepresents a bond between atom indices i and j. n is a vector of three integers specifying unit cell displacement in terms of lattice vectors.\n\n\n\n\n\n","category":"type"},{"location":"library.html#Sunny.Crystal","page":"Library API","title":"Sunny.Crystal","text":"An object describing a crystallographic unit cell and its space group symmetry. Constructors are as follows:\n\nCrystal(filename; symprec=1e-5)\n\nReads the crystal from a .cif file located at the path filename. The optional parameter symprec controls the precision tolerance for spacegroup symmetries.\n\nCrystal(latvecs, positions; types=nothing, symprec=1e-5)\n\nConstructs 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.\n\nCrystal(latvecs, positions, spacegroup_number; types=nothing, setting=nothing, symprec=1e-5)\n\nBuilds 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.\n\nCurrently, 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.\n\nExamples\n\n# Read a Crystal from a .cif file\nCrystal(\"filename.cif\")\n\n# Build an FCC crystal using the primitive unit cell. The spacegroup number\n# 225 is inferred.\nlatvecs = [1 1 0;\n 1 0 1;\n 0 1 1] / 2\npositions = [[0, 0, 0]]\nCrystal(latvecs, positions)\n\n# Build a CsCl crystal (two cubic sublattices). By providing distinct type\n# strings, the spacegroup number 221 is inferred.\nlatvecs = lattice_vectors(1, 1, 1, 90, 90, 90)\npositions = [[0,0,0], [0.5,0.5,0.5]]\ntypes = [\"Na\", \"Cl\"]\ncryst = Crystal(latvecs, positions; types)\n\n# Build a diamond cubic crystal from its spacegroup number 227. This\n# spacegroup has two possible settings (\"1\" or \"2\"), which determine an\n# overall unit cell translation.\nlatvecs = lattice_vectors(1, 1, 1, 90, 90, 90)\npositions = [[1, 1, 1] / 4]\ncryst = Crystal(latvecs, positions, 227; setting=\"1\")\n\nSee also lattice_vectors.\n\n\n\n\n\n","category":"type"},{"location":"library.html#Sunny.FormFactor-Tuple{String}","page":"Library API","title":"Sunny.FormFactor","text":"FormFactor(ion::String; g_lande=2)\n\nThe 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.\n\nThe parameter ion must be one of the following strings:\n\nAm2, Am3, Am4, Am5, Am6, Am7, Au1, Au2, Au3, Au4, Au5, Ce2, Co0, Co1, Co2, Co3,\nCo4, Cr0, Cr1, Cr2, Cr3, Cr4, Cu0, Cu1, Cu2, Cu3, Cu4, Dy2, Dy3, Er2, Er3, Eu2,\nEu3, Fe0, Fe1, Fe2, Fe3, Fe4, Gd2, Gd3, Hf2, Hf3, Ho2, Ho3, Ir0a, Ir0b, Ir0c,\nIr1a, Ir1b, Ir2, Ir3, Ir4, Ir5, Ir6, Mn0, Mn1, Mn2, Mn3, Mn4, Mo0, Mo1, Nb0,\nNb1, Nd2, Nd3, Ni0, Ni1, Ni2, Ni3, Ni4, Np3, Np4, Np5, Np6, Os0a, Os0b, Os0c,\nOs1a, Os1b, Os2, Os3, Os4, Os5, Os6, Os7, Pd0, Pd1, Pr3, Pt1, Pt2, Pt3, Pt4,\nPt5, Pt6, Pu3, Pu4, Pu5, Pu6, Re0a, Re0b, Re0c, Re1a, Re1b, Re2, Re3, Re4, Re5,\nRe6, Rh0, Rh1, Ru0, Ru1, Sc0, Sc1, Sc2, Sm2, Sm3, Ta2, Ta3, Ta4, Tb2, Tb3, Tc0,\nTc1, Ti0, Ti1, Ti2, Ti3, Tm2, Tm3, U3, U4, U5, V0, V1, V2, V3, V4, W0a, W0b,\nW0c, W1a, W1b, W2c, W3, W4, W5, Y0, Yb2, Yb3, Zr0, Zr1\n\nThe trailing number denotes ionization state. For example, \"Fe0\" denotes a neutral iron atom, while \"Fe2\" denotes Fe²⁺. If multiple electronic configurations are possible, they will be distinguished by a trailing letter (a, b, ...). Omitting this letter will print an informative error,\n\nFormFactor(\"Ir0\")\n\nERROR: Disambiguate form factor according to electronic configuration:\n \"Ir0a\" -- 6s⁰5d⁹\n \"Ir0b\" -- 6s¹5d⁸\n \"Ir0c\" -- 6s²5d⁷\n\nThe form factor is approximated as\n\nF(s) = j_0(s) + frac2-gg j_2(s) s^2,\n\ninvolving the Landé g-factor. The j_l(s) are radial integrals associated with the lth Bessel function of the magnetic dipole, where s = k4π, and k is the magnitude of momentum transfer. \n\nThe 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,\n\nj_0(s) = A e^-as^2 + B e^-bs^2 + C e^-cs^2 + D e^-ds^2 + E \nj_l(s) = (A e^-as^2 + B e^-bs^2 + C e^-cs^2 + D e^-ds^2 + E) s^2\n\nReferences:\n\nhttps://www.ill.eu/sites/ccsl/ffacts/ffachtml.html\nJ. Brown, The Neutron Data Booklet, 2nd ed., Sec. 2.5 Magnetic Form Factors (2003)\nK. Kobayashi, T. Nagao, M. Ito, Acta Cryst. A, 67 pp 473–480 (2011)\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.ImplicitMidpoint","page":"Library API","title":"Sunny.ImplicitMidpoint","text":"ImplicitMidpoint(Δt::Float64; atol=1e-12) where N\n\nEnergy-conserving spin dynamics. One call to the step! function will advance a System by Δt units of time.\n\nUses 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.\n\n\n\n\n\n","category":"type"},{"location":"library.html#Sunny.Langevin","page":"Library API","title":"Sunny.Langevin","text":"Langevin(Δt::Float64; λ::Float64, kT::Float64)\n\nSpin 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.\n\nAssuming 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.\n\nAn alternative approach to sampling is LocalSampler, which may be preferred when the allowed spin values become effective discrete (e.g. Ising spins).\n\n\n\n\n\n","category":"type"},{"location":"library.html#Sunny.LocalSampler","page":"Library API","title":"Sunny.LocalSampler","text":"LocalSampler(; kT, nsweeps=1.0, propose=propose_uniform)\n\nMonte 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.\n\nAssuming ergodicity, the LocalSampler will sample from thermal equilibrium for the target temperature kT. \n\nThe 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.\n\nThe returned object stores fields ΔE and Δs, which represent the cumulative change to the net energy and dipole, respectively.\n\nAn 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!).\n\n\n\n\n\n","category":"type"},{"location":"library.html#Sunny.SampledCorrelations","page":"Library API","title":"Sunny.SampledCorrelations","text":"SampledCorrelations\n\nBasic data type for storing sampled correlation data. A SampleCorrelations is initialized by calling either dynamical_correlations or instant_correlations.\n\n\n\n\n\n","category":"type"},{"location":"library.html#Sunny.SpinInfo","page":"Library API","title":"Sunny.SpinInfo","text":"SpinInfo(atom::Int; S, g=2)\n\nCharacterizes 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.\n\n\n\n\n\n","category":"type"},{"location":"library.html#Sunny.SpinWaveTheory","page":"Library API","title":"Sunny.SpinWaveTheory","text":"SpinWaveTheory(sys, energy_ϵ::Float64=1e-8)\n\nConstructs an object to perform linear spin wave theory. Use it with dispersion and dssf functions.\n\nThe 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.\n\n\n\n\n\n","category":"type"},{"location":"library.html#Sunny.System-Tuple{Crystal, Tuple{Int64, Int64, Int64}, Vector{SpinInfo}, Symbol}","page":"Library API","title":"Sunny.System","text":"System(crystal::Crystal, latsize, infos, mode; units=Units.meV, seed::Int)\n\nConstruct 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.\n\nThe 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. \n\nMode :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.\n\nThe default units system of (meV, Å, tesla) can be overridden by with the units parameter; see Units. \n\nAn optional seed may be provided to achieve reproducible random number generation.\n\nAll spins are initially polarized in the z-direction.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.add_sample!-Tuple{SampledCorrelations, System}","page":"Library API","title":"Sunny.add_sample!","text":"add_sample!(sc::SampledCorrelations, sys::System)\n\nadd_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. \n\nThis 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!.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.available_energies-Tuple{SampledCorrelations}","page":"Library API","title":"Sunny.available_energies","text":"available_energies(sc::SampledCorrelations; negative_energies=false)\n\nReturn 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.available_wave_vectors-Tuple{SampledCorrelations}","page":"Library API","title":"Sunny.available_wave_vectors","text":"available_wave_vectors(sc::SampledCorrelations; bzsize=(1,1,1))\n\nReturns all wave vectors for which sc contains exact values. bsize specifies the number of Brillouin zones to be included.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.axes_bincenters-Tuple{Any, Any, Any}","page":"Library API","title":"Sunny.axes_bincenters","text":"axes_bincenters(params::BinningParameters)\n\nReturns tick marks which label the bins of the histogram described by BinningParameters by their bin centers.\n\nThe following alternative syntax can be used to compute bin centers for a single axis:\n\naxes_bincenters(binstart,binend,binwidth)\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.broaden_energy-Tuple{SampledCorrelations, Any, Function}","page":"Library API","title":"Sunny.broaden_energy","text":"broaden_energy(sc::SampledCorrelations, vals, kernel::Function; negative_energies=false)\n\nPerforms 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:\n\nnewvals = broaden_energy(sc, vals, (ω, ω₀) -> lorentzian(ω-ω₀, 0.2))\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.count_bins-Tuple{Any, Any, Any}","page":"Library API","title":"Sunny.count_bins","text":"count_bins(binstart,binend,binwidth)\n\nReturns the number of bins in the binning scheme implied by binstart, binend, and binwidth. To count the bins in a BinningParameters, use params.numbins.\n\nThis function defines how partial bins are handled, so it should be used preferentially over computing the number of bins manually.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.dispersion-Tuple{SpinWaveTheory, Any}","page":"Library API","title":"Sunny.dispersion","text":"dispersion(swt::SpinWaveTheory, qs)\n\nComputes 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.\n\nThe 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.dmvec-Tuple{Any}","page":"Library API","title":"Sunny.dmvec","text":"dmvec(D)\n\nAntisymmetric matrix representation of the Dzyaloshinskii-Moriya pseudo-vector,\n\n [ 0 D[3] -D[2]\n -D[3] 0 D[1]\n D[2] -D[1] 0 ]\n\nUseful in the context of set_exchange!.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.dssf-Tuple{SpinWaveTheory, Any}","page":"Library API","title":"Sunny.dssf","text":"dssf(swt::SpinWaveTheory, qs)\n\nGiven a SpinWaveTheory object, computes the dynamical spin structure factor,\n\n 𝒮^αβ(𝐤 ω) = 1(2πN)dt _𝐫 expi(ωt - 𝐤𝐫) S^α(𝐫 t)S^β(0 0)\n\nusing the result from linear spin-wave theory,\n\n 𝒮^αβ(𝐤 ω) = _n A_n^αβ(𝐤)^2 δω-ω_n(𝐤)\n\nqs 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.\n\nThe 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 β.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.dynamical_correlations-Union{Tuple{System{N}}, Tuple{N}} where N","page":"Library API","title":"Sunny.dynamical_correlations","text":"dynamical_correlations(sys::System; Δt, nω, ωmax, \n process_trajectory=:none, observables=nothing, correlations=nothing)\n\nCreates 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.\n\nThree keywords are required to specify the dynamics used for the trajectory calculation.\n\nΔ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.\nωmax: The maximum energy, ω, that will be resolved.\nnω: The number of energy bins to calculated between 0 and ωmax.\n\nAdditional keyword options are the following:\n\nobservables: 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.\ncorrelations: 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)].\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.eachsite-Tuple{System}","page":"Library API","title":"Sunny.eachsite","text":"eachsite(sys::System)\n\nAn iterator over all Sites in the system. \n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.enable_dipole_dipole!-Union{Tuple{System{N}}, Tuple{N}} where N","page":"Library API","title":"Sunny.enable_dipole_dipole!","text":"enable_dipole_dipole!(sys::System)\n\nEnables long-range dipole-dipole interactions,\n\n -(μ_04π) _ij (3 (𝐌_j𝐫_ij)(𝐌_i𝐫_ij) - 𝐌_i𝐌_j) 𝐫_ij^3\n\nwhere 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.energy-Union{Tuple{System{N}}, Tuple{N}} where N","page":"Library API","title":"Sunny.energy","text":"energy(sys::System)\n\nThe total system energy. See also energy_per_site.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.energy_per_site-Union{Tuple{System{N}}, Tuple{N}} where N","page":"Library API","title":"Sunny.energy_per_site","text":"energy_per_site(sys::System)\n\nThe total system energy divided by the number of sites.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.generate_mantid_script_from_binning_parameters-Tuple{Any}","page":"Library API","title":"Sunny.generate_mantid_script_from_binning_parameters","text":"generate_mantid_script_from_binning_parameters(params::BinningParameters)\n\nGenerate a Mantid script which bins data according to the given BinningParameters.\n\nwarning: Units\nTake 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.global_position-Tuple{System, Any}","page":"Library API","title":"Sunny.global_position","text":"global_position(sys::System, site::Site)\n\nPosition of a Site in global coordinates.\n\nTo precompute a full list of positions, one can use eachsite as below:\n\npos = [global_position(sys, site) for site in eachsite(sys)]\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.instant_correlations-Tuple{System}","page":"Library API","title":"Sunny.instant_correlations","text":"instant_correlations(sys::System; process_trajectory=:none, observables=nothing, correlations=nothing)\n\nCreates 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.\n\nImportant 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.\n\nThe following optional keywords are available:\n\nobservables: 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.\ncorrelations: 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)].\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.instant_intensities_interpolated-Tuple{SampledCorrelations, Any, Any}","page":"Library API","title":"Sunny.instant_intensities_interpolated","text":"instant_intensities_interpolated(sc::SampledCorrelations, qs; kwargs...)\n\nReturn 𝒮(𝐪) 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.integrate_axes!-Tuple{BinningParameters}","page":"Library API","title":"Sunny.integrate_axes!","text":"integrate_axes!(params::BinningParameters; axes)\n\nIntegrate over one or more axes of the histogram by setting the number of bins in that axis to 1. Examples:\n\nintegrate_axes!(params; axes = [2,3])\nintegrate_axes!(params; axes = 2)\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.integrated_lorentzian-Tuple{Float64}","page":"Library API","title":"Sunny.integrated_lorentzian","text":"integrated_lorentzian(η)\n\nReturns x mapsto atan(xη)π for use with intensities_binned.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.intensities_bands-Tuple{SpinWaveTheory, Any, Sunny.SpinWaveIntensityFormula}","page":"Library API","title":"Sunny.intensities_bands","text":"dispersion, intensities = intensities_bands(swt::SpinWaveTheory, ks, formula::SpinWaveIntensityFormula)\n\nComputes 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.:\n\nformula = intensity_formula(swt, :perp, formula; kernel = delta_function_kernel)\n\nor else the bands will be broadened, and their intensity can not be computed.\n\nThe 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.intensities_binned-Tuple{SampledCorrelations, BinningParameters, Sunny.ClassicalIntensityFormula}","page":"Library API","title":"Sunny.intensities_binned","text":"intensity, counts = intensities_binned(sc::SampledCorrelations, params::BinningParameters, formula; integrated_kernel)\n\nGiven 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.\n\nThe BinningParameters are expected to accept (q,ω) in R.L.U. for the (possibly reshaped) crystal associated with sc.\n\nThis 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.\n\nIf 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 ω.\n\nCurrently, 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].\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.intensities_broadened-Tuple{SpinWaveTheory, Any, Any, Any}","page":"Library API","title":"Sunny.intensities_broadened","text":"intensities_broadened(swt::SpinWaveTheory, ks, ωvals, formula)\n\nComputes 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.:\n\nformula = intensity_formula(swt, :perp; kernel = lorentzian(0.05))\n\nor else the intensity at ωvals which are not exactly on the dispersion curve can not be calculated.\n\nThe 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.\n\nNote that ks is an array of wave vectors of arbitrary dimension. Each element k of ks must be a 3-wavevector in absolute units.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.intensities_interpolated-Tuple{SampledCorrelations, Any, Sunny.ClassicalIntensityFormula}","page":"Library API","title":"Sunny.intensities_interpolated","text":"intensities_interpolated(sc::SampledCorrelations, qs, formula:ClassicalIntensityFormula; interpolation=nothing, negative_energies=false)\n\nThe 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.\n\ninterpolation: 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.\nnegative_energies: If set to true, Sunny will return the periodic extension of the energy axis. Most users will not want this.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.intensity_formula-Tuple{Function, SampledCorrelations, AbstractVector{Int64}}","page":"Library API","title":"Sunny.intensity_formula","text":"formula = intensity_formula(sc::SampledCorrelations)\n\nEstablish 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.\n\nintensity_formula(sc,...; kT = Inf, formfactors = ...)\n\nThere are keyword arguments providing temperature and form factor corrections:\n\nkT: 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.\nformfactors: 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).\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.intensity_formula-Tuple{Function, SampledCorrelations, Any}","page":"Library API","title":"Sunny.intensity_formula","text":"A custom intensity formula can be specifed by providing a function intensity = f(q,ω,correlations) and specifying which correlations it requires:\n\nintensity_formula(f,sc::SampledCorrelations, required_correlations; kwargs...)\n\nThe function is intended to be specified using do notation. For example, this custom formula sums the off-diagonal correlations:\n\nrequired = [(:Sx,:Sy),(:Sy,:Sz),(:Sx,:Sz)]\nintensity_formula(sc,required,return_type = ComplexF64) do k, ω, off_diagonal_correlations\n sum(off_diagonal_correlations)\nend\n\nIf your custom formula returns a type other than Float64, use the return_type keyword argument to flag this.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.intensity_formula-Tuple{Function, SpinWaveTheory, AbstractVector{Int64}}","page":"Library API","title":"Sunny.intensity_formula","text":"formula = intensity_formula(swt::SpinWaveTheory; kernel = ...)\n\nEstablish a formula for computing the scattering intensity by diagonalizing the hamiltonian H(q) using Linear Spin Wave Theory.\n\nIf kernel = delta_function_kernel, then the resulting formula can be used with intensities_bands.\n\nIf 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.:\n\nkernel = Δω -> ...\n\nor a function of both the energy transfer ω and of Δω, e.g.:\n\nkernel = (ω,Δω) -> ...\n\nThe integral of a properly normalized kernel function over all Δω is one.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.intensity_formula-Tuple{SpinWaveTheory, Symbol}","page":"Library API","title":"Sunny.intensity_formula","text":"intensity_formula([swt or sc], contraction_mode::Symbol)\n\nSunny has several built-in formulas that can be selected by setting contraction_mode to one of these values:\n\n:trace (default), which yields operatornametr 𝒮(qω) = _α 𝒮^αα(qω)\n:perp, which contracts 𝒮^αβ(qω) with the dipole factor δ_αβ - q_αq_β, returning the unpolarized intensity.\n:full, which will return all elements 𝒮^αβ(𝐪ω) without contraction.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.lattice_params-Tuple{StaticArraysCore.SMatrix{3, 3, Float64, 9}}","page":"Library API","title":"Sunny.lattice_params","text":"lattice_params(latvecs::Mat3)\n\nCompute the lattice parameters (a b c α β γ) for the three lattice vectors provided as columns of latvecs. The inverse mapping is lattice_vectors.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.lattice_vectors-NTuple{6, Any}","page":"Library API","title":"Sunny.lattice_vectors","text":"lattice_vectors(a, b, c, α, β, γ)\n\nReturn the lattice vectors, as columns of the 33 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.load_nxs-Tuple{Any}","page":"Library API","title":"Sunny.load_nxs","text":"params, signal = load_nxs(filename)\n\nGiven the name of a Mantid-exported MDHistoWorkspace file, load the BinningParameters and the signal from that file.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.lorentzian-Tuple{Any, Any}","page":"Library API","title":"Sunny.lorentzian","text":"lorentzian(x, η)\n\nReturns η(π(x^2 + η^2)).\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.magnetic_moment-Tuple{System, Any}","page":"Library API","title":"Sunny.magnetic_moment","text":"magnetic_moment(sys::System, site::Site)\n\nGet the magnetic moment for a Site. This is the spin dipole multiplied by the Bohr magneton and the local g-tensor.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.merge_correlations-Union{Tuple{Array{SampledCorrelations{N}, 1}}, Tuple{N}} where N","page":"Library API","title":"Sunny.merge_correlations","text":"merge_correlations(scs::Vector{SampledCorrelations)\n\nAccumulate a list of SampledCorrelations into a single, summary SampledCorrelations. Useful for reducing the results of parallel computations.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.minimize_energy!-Union{Tuple{System{N}}, Tuple{N}} where N","page":"Library API","title":"Sunny.minimize_energy!","text":"minimize_energy!(sys::System{N}; maxiters=100, subiters=20,\n method=Optim.ConjugateGradient(), kwargs...) where N\n\nOptimizes 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.polarize_spins!-Union{Tuple{N}, Tuple{System{N}, Any}} where N","page":"Library API","title":"Sunny.polarize_spins!","text":"polarize_spins!(sys::System, dir)\n\nPolarize all spins in the system along the direction dir.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.position_to_site-Tuple{System, Any}","page":"Library API","title":"Sunny.position_to_site","text":"position_to_site(sys::System, r)\n\nConverts 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.\n\nExample\n\n# Find the `site` at the center of a unit cell which is displaced by four\n# multiples of the first lattice vector\nsite = position_to_site(sys, [4.5, 0.5, 0.5])\n\n# Print the dipole at this site\nprintln(sys.dipoles[site])\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.powder_average_binned-Tuple{SampledCorrelations, Any, Sunny.ClassicalIntensityFormula}","page":"Library API","title":"Sunny.powder_average_binned","text":"powder_average_binned(sc::SampledCorrelations, radial_binning_parameters; formula\n ω_binning_parameters, integrated_kernel = nothing, bzsize = nothing)\n\nThis 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.\n\nRadial binning parameters are specified as tuples (start,end,bin_width), e.g. radial_binning_parameters = (0,6π,6π/55).\n\nEnergy broadening is supported in the same way as intensities_binned, and this function accepts the same kind of intensity_formula.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.primitive_cell_shape-Tuple{Crystal}","page":"Library API","title":"Sunny.primitive_cell_shape","text":"primitive_cell_shape(cryst::Crystal)\n\nReturns 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.\n\nExamples\n\n# Valid if `cryst` has not been reshaped\n@assert cryst.prim_latvecs ≈ cryst.latvecs * primitive_cell_shape(cryst)\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.print_bond-Tuple{Crystal, Bond}","page":"Library API","title":"Sunny.print_bond","text":"print_bond(cryst::Crystal, bond::Bond; b_ref::Bond)\n\nPrints 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, ...\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.print_site-Tuple{Any, Any}","page":"Library API","title":"Sunny.print_site","text":"print_site(cryst, i; R=I)\n\nPrint 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.print_stevens_expansion-Tuple{AbstractMatrix}","page":"Library API","title":"Sunny.print_stevens_expansion","text":"function print_stevens_expansion(op)\n\nPrints 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.\n\nExamples\n\nS = spin_matrices(2)\nprint_stevens_expansion(S[1]^4 + S[2]^4 + S[3]^4)\n# Prints: (1/20)𝒪₄₀ + (1/4)𝒪₄₄ + 102/5\n\nS = spin_matrices(Inf)\nprint_stevens_expansion(S[1]^4 + S[2]^4 + S[3]^4)\n# Prints: (1/20)𝒪₄₀ + (1/4)𝒪₄₄ + (3/5)𝒮⁴\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.print_suggested_frame-Tuple{Crystal, Int64}","page":"Library API","title":"Sunny.print_suggested_frame","text":"print_suggested_frame(cryst, i; digits=4)\n\nPrint 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.print_symmetry_table-Tuple{Crystal, Any}","page":"Library API","title":"Sunny.print_symmetry_table","text":"print_symmetry_table(cryst::Crystal, max_dist)\n\nPrint 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.print_wrapped_intensities-Union{Tuple{System{N}}, Tuple{N}} where N","page":"Library API","title":"Sunny.print_wrapped_intensities","text":"print_wrapped_intensities(sys::System; nmax=10)\n\nFor 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 -12 and 12 in reciprocal lattice units (RLU). The output from this function will typically be used as input to suggest_magnetic_supercell.\n\nBecause 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.propose_delta-Tuple{Any}","page":"Library API","title":"Sunny.propose_delta","text":"propose_delta(magnitude)\n\nGenerate 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. \n\nIn :SUN mode, the procedure is analogous, but now involving Gaussian perturbations to each of the N complex components of an SU(N) coherent state.\n\nIn the limit of very large magnitude, this function coincides with propose_uniform.\n\nFor use with LocalSampler.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.propose_flip-Union{Tuple{N}, Tuple{System{N}, Any}} where N","page":"Library API","title":"Sunny.propose_flip","text":"propose_flip\n\nFunction 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.propose_uniform","page":"Library API","title":"Sunny.propose_uniform","text":"propose_uniform\n\nFunction 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.\n\n\n\n\n\n","category":"function"},{"location":"library.html#Sunny.randomize_spins!-Union{Tuple{System{N}}, Tuple{N}} where N","page":"Library API","title":"Sunny.randomize_spins!","text":"randomize_spins!(sys::System)\n\nRandomizes all spins under appropriate the uniform distribution.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.reciprocal_space_path-Tuple{Crystal, Any, Any}","page":"Library API","title":"Sunny.reciprocal_space_path","text":"reciprocal_space_path(cryst::Crystal, qs, density)\n\nReturns 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.\n\nSpecial 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.reciprocal_space_path_bins-Tuple{Any, Any, Any, Vararg{Any}}","page":"Library API","title":"Sunny.reciprocal_space_path_bins","text":"reciprocal_space_path_bins(sc,qs,density,args...;kwargs...)\n\nTakes 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.\n\nAlso 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.).\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.reciprocal_space_shell-Tuple{Crystal, Any, Any}","page":"Library API","title":"Sunny.reciprocal_space_shell","text":"reciprocal_space_shell(cryst::Crystal, radius, n)\n\nSample n points on the reciprocal space sphere with a given radius (units of inverse length).\n\nExamples\n\n# Sample wavevectors on the sphere at fixed density\nreciprocal_space_shell(cryst, r, 4π*r^2*density)\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.reference_bonds-Tuple{Crystal, Float64}","page":"Library API","title":"Sunny.reference_bonds","text":"reference_bonds(cryst::Crystal, max_dist)\n\nReturns 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).\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.remove_periodicity!-Union{Tuple{N}, Tuple{System{N}, Any}} where N","page":"Library API","title":"Sunny.remove_periodicity!","text":"remove_periodicity!(sys::System, dims)\n\nRemove periodic interactions along the dimensions where dims is true. The system must support inhomogeneous interactions via to_inhomogeneous.\n\nExample\n\n# Remove periodic boundaries along the 1st and 3rd dimensions\nremove_periodicity!(sys::System, (true, false, true))\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.repeat_periodically-Union{Tuple{N}, Tuple{System{N}, Tuple{Int64, Int64, Int64}}} where N","page":"Library API","title":"Sunny.repeat_periodically","text":"repeat_periodically(sys::System{N}, counts::NTuple{3,Int}) where N\n\nCreates a System identical to sys but repeated a given number of times in each dimension, specified by the tuple counts.\n\nSee also reshape_supercell.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.reshape_supercell-Union{Tuple{N}, Tuple{System{N}, Any}} where N","page":"Library API","title":"Sunny.reshape_supercell","text":"reshape_supercell(sys::System, shape)\n\nMaps an existing System to a new one that has the shape and periodicity of a requested supercell. The columns of the 33 integer matrix shape represent the supercell lattice vectors measured in units of the original crystal lattice vectors.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.resize_supercell-Union{Tuple{N}, Tuple{System{N}, Tuple{Int64, Int64, Int64}}} where N","page":"Library API","title":"Sunny.resize_supercell","text":"resize_supercell(sys::System{N}, latsize::NTuple{3,Int}) where N\n\nCreates a System with a given number of conventional unit cells in each lattice vector direction. Interactions and other settings will be inherited from sys.\n\nConvenience function for:\n\nreshape_supercell(sys, [latsize[1] 0 0; 0 latsize[2] 0; 0 0 latsize[3]])\n\nSee also reshape_supercell.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.rotate_operator-Tuple{LinearAlgebra.Hermitian{ComplexF64, Matrix{ComplexF64}}, Any}","page":"Library API","title":"Sunny.rotate_operator","text":"rotate_operator(A, R)\n\nRotates the local quantum operator A according to the 33 rotation matrix R.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.rotation_in_rlu-Tuple{Crystal, Any, Any}","page":"Library API","title":"Sunny.rotation_in_rlu","text":"rotation_in_rlu(cryst::Crystal, axis, angle)\n\nReturns a 33 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_coherent!-Union{Tuple{N}, Tuple{System{N}, Any, Any}} where N","page":"Library API","title":"Sunny.set_coherent!","text":"set_coherent!(sys::System, Z, site::Site)\n\nSet a coherent spin state at a Site using the N complex amplitudes in Z.\n\nFor 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 z-direction, and subsequent components represent states with decreasing angular momentum along this axis (m = S S-1 -S).\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_dipole!-Union{Tuple{N}, Tuple{System{N}, Any, Any}} where N","page":"Library API","title":"Sunny.set_dipole!","text":"set_dipole!(sys::System, dir, site::Site)\n\nPolarize the spin at a Site along the direction dir.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_exchange!-Union{Tuple{N}, Tuple{System{N}, Any, Bond}} where N","page":"Library API","title":"Sunny.set_exchange!","text":"set_exchange!(sys::System, J, bond::Bond)\n\nSets a 3×3 spin-exchange matrix J along bond, yielding a pairwise interaction energy 𝐒_iJ 𝐒_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.\n\nThe 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).\n\nFor more general interactions, such as biquadratic, use set_pair_coupling! instead.\n\nExamples\n\n# An explicit exchange matrix\nJ1 = [2 3 0;\n -3 2 0;\n 0 0 2]\nset_exchange!(sys, J1, bond)\n\n# An equivalent Heisenberg + DM exchange \nJ2 = 2*I + dmvec([0,0,3])\nset_exchange!(sys, J2, bond)\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_exchange_at!-Union{Tuple{N}, Tuple{System{N}, Any, Union{NTuple{4, Int64}, CartesianIndex{4}}, Union{NTuple{4, Int64}, CartesianIndex{4}}}} where N","page":"Library API","title":"Sunny.set_exchange_at!","text":"set_exchange_at!(sys::System, J, site1::Site, site2::Site; offset=nothing)\n\nSets 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.\n\nIf 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.\n\nFor more general interactions, such as biquadratic, use set_pair_coupling_at! instead.\n\nSee also set_exchange!.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_external_field!-Tuple{System, Any}","page":"Library API","title":"Sunny.set_external_field!","text":"set_external_field!(sys::System, B::Vec3)\n\nSets the external field B that couples to all spins.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_external_field_at!-Tuple{System, Any, Any}","page":"Library API","title":"Sunny.set_external_field_at!","text":"set_external_field_at!(sys::System, B::Vec3, site::Site)\n\nSets a Zeeman coupling between a field B and a single spin. Site includes a unit cell and a sublattice index.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_onsite_coupling!-Tuple{System, Any, Int64}","page":"Library API","title":"Sunny.set_onsite_coupling!","text":"set_onsite_coupling!(sys::System, op, i::Int)\n\nSet 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.\n\nExamples\n\n# An easy axis anisotropy in the z-direction\nset_onsite_coupling!(sys, S -> -D*S[3]^3, i)\n\n# The unique quartic single-ion anisotropy for a site with cubic point group\n# symmetry\nset_onsite_coupling!(sys, S -> 20*(S[1]^4 + S[2]^4 + S[3]^4), i)\n\n# An equivalent expression of this quartic anisotropy, up to a constant shift\nO = stevens_matrices(spin_label(sys, i))\nset_onsite_coupling!(sys, O[4,0] + 5*O[4,4], i)\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_onsite_coupling_at!-Tuple{System, Any, Union{NTuple{4, Int64}, CartesianIndex{4}}}","page":"Library API","title":"Sunny.set_onsite_coupling_at!","text":"set_onsite_coupling_at!(sys::System, op, site::Site)\n\nSets the single-ion anisotropy operator op for a single Site, ignoring crystal symmetry. The system must support inhomogeneous interactions via to_inhomogeneous.\n\nSee also set_onsite_coupling!.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_pair_coupling!-Union{Tuple{N}, Tuple{System{N}, AbstractMatrix, Any}} where N","page":"Library API","title":"Sunny.set_pair_coupling!","text":"set_pair_coupling!(sys::System, op, bond)\n\nSets 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.\n\nExamples\n\n# Bilinear+biquadratic exchange involving 3×3 matrices J1 and J2\nset_pair_coupling!(sys, (Si, Sj) -> Si'*J1*Sj + (Si'*J2*Sj)^2, bond)\n\n# Equivalent expression using an appropriate fixed matrix representation\nS = spin_matrices(1/2)\nSi, Sj = to_product_space(S, S)\nset_pair_coupling!(sys, Si'*J1*Sj + (Si'*J2*Sj)^2, bond)\n\nSee also spin_matrices, to_product_space.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_pair_coupling_at!-Union{Tuple{N}, Tuple{System{N}, AbstractMatrix, Union{NTuple{4, Int64}, CartesianIndex{4}}, Union{NTuple{4, Int64}, CartesianIndex{4}}}} where N","page":"Library API","title":"Sunny.set_pair_coupling_at!","text":"set_pair_coupling_at!(sys::System, op, bond)\n\nSets 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.\n\nThe system must support inhomogeneous interactions via to_inhomogeneous.\n\nIf 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_spiral_order!-Tuple{Any}","page":"Library API","title":"Sunny.set_spiral_order!","text":"set_spiral_order!(sys; q, axis, S0)\n\nInitializes 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.\n\nExample\n\n# Spiral order for a wavevector propagating in the direction of the first\n# reciprocal lattice vector (i.e., orthogonal to the lattice vectors ``𝐚_2``\n# and ``𝐚_3``), repeating with a period of 10 lattice constants, and spiraling\n# about the ``ẑ``-axis. The spin at the origin will point in the direction\n# ``𝐒_0 = ŷ + ẑ``. Here, ``(x̂, ŷ, ẑ)`` are the axes of Cartesian coordinate\n# system in the global frame.\nset_spiral_order!(sys; q=[1/10, 0, 0], axis=[0, 0, 1], S0=[0, 1, 1])\n\nSee also set_spiral_order_on_sublattice!.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_spiral_order_on_sublattice!-Tuple{Any, Any}","page":"Library API","title":"Sunny.set_spiral_order_on_sublattice!","text":"set_spiral_order_on_sublattice!(sys, i; q, axis, S0)\n\nInitializes 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.\n\nThis function is not available for systems with reshaped unit cells.\n\nSee also set_spiral_order!.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_vacancy_at!-Union{Tuple{N}, Tuple{System{N}, Any}} where N","page":"Library API","title":"Sunny.set_vacancy_at!","text":"set_vacancy_at!(sys::System, site::Site)\n\nMake a single site nonmagnetic. Site includes a unit cell and a sublattice index.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.slice_2D_binning_parameters-Tuple{Vector{Float64}, Any, Any, Int64, Any}","page":"Library API","title":"Sunny.slice_2D_binning_parameters","text":"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)\n\nCreates BinningParameters which make a cut along one dimension of Q-space.\n\nThe 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.\n\nThe binning in the transverse directions is defined in the following way, which sets their normalization and orthogonality properties:\n\ncut_covector = normalize(cut_to_q - cut_from_q)\ntransverse_covector = normalize(plane_normal × cut_covector)\ncotransverse_covector = normalize(transverse_covector × cut_covector)\n\nIn other words, the axes are orthonormal with respect to the Euclidean metric.\n\nIf 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.\n\nThe four axes of the resulting histogram are:\n\nAlong the cut\nFist transverse Q direction\nSecond transverse Q direction\nEnergy\n\nThis function can be used without reference to a SampledCorrelations using this alternate syntax to manually specify the bin centers for the energy axis:\n\nslice_2D_binning_parameter(ω_bincenters, cut_from, cut_to,...)\n\nwhere ω_bincenters specifies the energy axis, and both cut_from and cut_to are arbitrary covectors, in any units.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.spin_label-Tuple{System, Int64}","page":"Library API","title":"Sunny.spin_label","text":"spin_label(sys::System, i::Int)\n\nIf atom i carries a single spin-S moment, then returns the half-integer label S. Otherwise, throws an error.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.spin_matrices-Tuple{Any}","page":"Library API","title":"Sunny.spin_matrices","text":"spin_matrices(S)\n\nReturns a triple of NN spin matrices, where N = 2S+1. These are the generators of SU(2) in the spin-S representation.\n\nIf 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.\n\nExample\n\nS = spin_matrices(3/2)\n@assert S'*S ≈ (3/2)*(3/2+1)*I\n@assert S[1]*S[2] - S[2]*S[1] ≈ im*S[3]\n\nS = spin_matrices(Inf)\n@assert S[1]*S[2] - S[2]*S[1] == 0\n\nSee also print_stevens_expansion.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.step!","page":"Library API","title":"Sunny.step!","text":"step!(sys::System, dynamics)\n\nAdvance 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.\n\n\n\n\n\n","category":"function"},{"location":"library.html#Sunny.stevens_matrices-Tuple{Any}","page":"Library API","title":"Sunny.stevens_matrices","text":"stevens_matrices(S)\n\nReturns 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 NN matrix where ``N = 2S\n\n1``. Linear combinations of Stevens operators can be used as a \"physical\n\nbasis\" for decomposing local observables. To see this decomposition, use print_stevens_expansion.\n\nIf S == Inf, then symbolic operators will be returned. In this infinite dimensional limit, the Stevens operators become homogeneous polynomials of commuting spin operators.\n\nExample\n\nO = stevens_matrices(2)\nS = spin_matrices(2)\n\nA = (1/20)O[4,0] + (1/4)O[4,4] + (102/5)I\nB = S[1]^4 + S[2]^4 + S[3]^4\n@assert A ≈ B\n\nSee also spin_matrices and Interaction Strength Renormalization.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.subcrystal-Union{Tuple{N}, Tuple{Crystal, Vararg{String, N}}} where N","page":"Library API","title":"Sunny.subcrystal","text":"subcrystal(cryst, types) :: Crystal\n\nFilters sublattices of a Crystal by atom types, keeping the space group unchanged.\n\nsubcrystal(cryst, classes) :: Crystal\n\nFilters sublattices of Crystal by equivalence classes, keeping the space group unchanged.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.suggest_magnetic_supercell-Tuple{Any}","page":"Library API","title":"Sunny.suggest_magnetic_supercell","text":"suggest_magnetic_supercell(qs; tol=1e-12, maxsize=100)\n\nSuggests 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.\n\nPrints a 33 matrix of integers that is suitable for use in reshape_supercell.\n\nExamples\n\n# A magnetic supercell for a single-Q structure. Will print\nq1 = [0, -1/4, 1/4]\nsuggest_magnetic_supercell([q1]) # [1 0 0; 0 2 1; 0 -2 1]\n\n# A larger magnetic supercell for a double-Q structure\nq2 = [1/4, 0, 1/4]\nsuggest_magnetic_supercell([q1, q2]) # [1 2 2; -1 2 -2; -1 2 2]\n\n# If given incommensurate wavevectors, find an approximate supercell that\n# is exactly commensurate for nearby wavevectors.\nsuggest_magnetic_supercell([[0, 0, 1/√5], [0, 0, 1/√7]]; tol=1e-2)\n\n# This prints [1 0 0; 0 1 0; 0 0 16], which becomes commensurate under the\n# approximations `1/√5 ≈ 7/16` and `1/√7 ≈ 3/8`.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.symmetry_equivalent_bonds-Tuple{System, Bond}","page":"Library API","title":"Sunny.symmetry_equivalent_bonds","text":"symmetry_equivalent_bonds(sys::System, bond::Bond)\n\nGiven 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).\n\nExample\n\nfor (site1, site2, offset) in symmetry_equivalent_bonds(sys, bond)\n @assert site1 < site2\n set_exchange_at!(sys, J, site1, site2; offset)\nend\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.to_inhomogeneous-Union{Tuple{System{N}}, Tuple{N}} where N","page":"Library API","title":"Sunny.to_inhomogeneous","text":"to_inhomogeneous(sys::System)\n\nReturns a copy of the system that allows for inhomogeneous interactions, which can be set using set_onsite_coupling_at!, set_exchange_at!, and set_vacancy_at!.\n\nInhomogeneous systems do not support symmetry-propagation of interactions or system reshaping.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.to_product_space-Tuple{Any, Any, Vararg{Any}}","page":"Library API","title":"Sunny.to_product_space","text":"to_product_space(A, B, Cs...)\n\nGiven 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.unit_resolution_binning_parameters-Tuple{Any, Any, Vararg{Any}}","page":"Library API","title":"Sunny.unit_resolution_binning_parameters","text":"unit_resolution_binning_parameters(sc::SampledCorrelations)\n\nCreate 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.\n\nThis 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:\n\nunit_resolution_binning_parameters(ω_bincenters,latsize,[reciprocal lattice vectors])\n\nThe last argument may be a 3x3 matrix specifying the reciprocal lattice vectors, or a Crystal.\n\nLastly, binning parameters for a single axis may be specifed by their bin centers:\n\n(binstart,binend,binwidth) = unit_resolution_binning_parameters(bincenters::Vector{Float64})\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.@mix_proposals-Tuple","page":"Library API","title":"Sunny.@mix_proposals","text":"@mix_proposals weight1 propose1 weight2 propose2 ...\n\nMacro to generate a proposal function that randomly selects among the provided functions according to the provided probability weights. For use with LocalSampler.\n\nExample\n\n# A proposal function that proposes a spin flip 40% of the time, and a\n# Gaussian perturbation 60% of the time.\n@mix_proposals 0.4 propose_flip 0.6 propose_delta(0.2)\n\n\n\n\n\n","category":"macro"},{"location":"library.html#Optional-Makie-extensions","page":"Library API","title":"Optional Makie extensions","text":"","category":"section"},{"location":"library.html","page":"Library API","title":"Library API","text":"The following will be enabled through a package extension if either GLMakie or WGLMakie is loaded.","category":"page"},{"location":"library.html","page":"Library API","title":"Library API","text":"plot_spins\nview_crystal","category":"page"},{"location":"library.html#Sunny.plot_spins","page":"Library API","title":"Sunny.plot_spins","text":"plot_spins(sys::System; arrowscale=1.0, color=:red, colorfn=nothing,\n colormap=:viridis, colorrange=nothing, show_cell=true, orthographic=false,\n ghost_radius=0, dims=3\n\nPlot the spin configuration defined by sys. Optional parameters are:\n\narrowscale: Scale all arrows by dimensionless factor.\ncolor: Arrow colors. May be symbolic or numeric. If scalar, will be shared among all sites.\ncolorfn: Function that dynamically maps from a site index to a numeric color value. Useful for animations.\ncolormap, colorrange: Used to populate colors from numbers following Makie conventions.\nshow_cell: Show original crystallographic unit cell.\northographic: Use camera with orthographic projection.\nghost_radius: Show translucent periodic images up to a given distance (length units).\ndims: Spatial dimensions of system (1, 2, or 3).\n\nCalling notify on the return value will animate the figure.\n\n\n\n\n\n","category":"function"},{"location":"library.html#Sunny.view_crystal","page":"Library API","title":"Sunny.view_crystal","text":"view_crystal(crystal::Crystal, max_dist::Real; show_axis=true, orthographic=false)\n\nAn interactive crystal viewer, with bonds up to max_dist.\n\n\n\n\n\n","category":"function"},{"location":"library.html#Optional-WriteVTK-extensions","page":"Library API","title":"Optional WriteVTK extensions","text":"","category":"section"},{"location":"library.html","page":"Library API","title":"Library API","text":"The following will be enabled through a package extension if WriteVTK is loaded.","category":"page"},{"location":"library.html","page":"Library API","title":"Library API","text":"export_vtk","category":"page"},{"location":"library.html#Sunny.export_vtk","page":"Library API","title":"Sunny.export_vtk","text":"export_vtk(filename,params::BinningParameters,data)\n\nExport 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.\n\nAt least one axis of the BinningParameters must be integrated over, since VTK does not support 4D data. See integrate_axes!.\n\n\n\n\n\n","category":"function"},{"location":"examples/contributed/MgCr2O4-tutorial.html#MgCr2O4-at-Finite-Temperature","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Author: Martin Mourigal
    Date: September 9, 2022 (Updated by October 28, 2023 using Sunny 0.5.5)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"In this tutorial, we will walk through an example in Sunny and calculate the spin dynamical properties of the Heisenberg pyrochlore antiferromagnet and apply this knowledge to MgCr2O4 and ZnCr2O4, which are known to approximate this model. Relevant publications include:","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"[1] P. H. Conlon and J. T. Chalker, Phys. Rev. Lett. 102, 237206 (2009)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"[2] P. H. Conlon and J. T. Chalker, Phys. Rev. B 81, 224413 (2010)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"[3] X. Bai, J. A. M. Paddison, et al. Phys. Rev. Lett. 122, 097201 (2019)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#Setting-up-Julia","page":"MgCr2O4 at Finite Temperature","title":"Setting up Julia","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"To run the examples in the tutorial, you will need a working installation of the Julia programming language and the Sunny package. Some useful references for getting started are:","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Getting started with Julia for Sunny\nSunny Docs","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"We will begin by loading the relevant packages.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"using Sunny # The main package\nusing GLMakie # Plotting package","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#Setting-up-the-crystal-structure","page":"MgCr2O4 at Finite Temperature","title":"Setting up the crystal structure","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Before specifying the interactions of our system, we first must set up the crystal. We will begin by specifying the pyrochlore lattice (illustrated below) in the manner that is typical of theorists.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Picture Credits: Theory of Quantum Matter Unit, OIST","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#\"Theorist\"-Method","page":"MgCr2O4 at Finite Temperature","title":"\"Theorist\" Method","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"In this approach, we directly define the lattice vectors and specify the position of each atom in fractional coordinates.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"latvecs = lattice_vectors(8.3342, 8.3342, 8.3342, 90, 90, 90)\npositions = [[0.875, 0.625, 0.375],\n [0.625, 0.125, 0.625],\n [0.875, 0.875, 0.125],\n [0.625, 0.875, 0.375],\n [0.875, 0.125, 0.875],\n [0.625, 0.625, 0.125],\n [0.875, 0.375, 0.625],\n [0.625, 0.375, 0.875],\n [0.375, 0.625, 0.875],\n [0.125, 0.125, 0.125],\n [0.375, 0.875, 0.625],\n [0.125, 0.875, 0.875],\n [0.375, 0.125, 0.375],\n [0.125, 0.625, 0.625],\n [0.375, 0.375, 0.125],\n [0.125, 0.375, 0.375]];\ntypes = [\"B\" for _ in positions]\nxtal_pyro = Crystal(latvecs, positions; types) # We will call this crystal the Theoretical Pyrochlore","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Crystal\nHM symbol 'F d -3 m' (227)\nLattice params a=8.334, b=8.334, c=8.334, α=90°, β=90°, γ=90°\nCell volume 578.9\nType 'B', Wyckoff 16c (point group '.-3m'):\n 1. [7/8, 5/8, 3/8]\n 2. [5/8, 1/8, 5/8]\n 3. [7/8, 7/8, 1/8]\n 4. [5/8, 7/8, 3/8]\n 5. [7/8, 1/8, 7/8]\n 6. [5/8, 5/8, 1/8]\n 7. [7/8, 3/8, 5/8]\n 8. [5/8, 3/8, 7/8]\n 9. [3/8, 5/8, 7/8]\n 10. [1/8, 1/8, 1/8]\n 11. [3/8, 7/8, 5/8]\n 12. [1/8, 7/8, 7/8]\n 13. [3/8, 1/8, 3/8]\n 14. [1/8, 5/8, 5/8]\n 15. [3/8, 3/8, 1/8]\n 16. [1/8, 3/8, 3/8]\n","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"To examine the result interactively, we can call view_crystal.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"view_crystal(xtal_pyro, 3.2)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#\"Experimentalist\"-Method-#1-(Incorrect)","page":"MgCr2O4 at Finite Temperature","title":"\"Experimentalist\" Method #1 (Incorrect)","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"A real crystal is more complicated than this, however, and we will now construct the system using the actual CIF file of MgCr2O4 from ICSD. This can be done by copying over the data from a CIF file by hand, but this can be dangerous, as shown below.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"latvecs = lattice_vectors(8.3342, 8.3342, 8.3342, 90, 90, 90)\npositions = [[0.1250, 0.1250, 0.1250],\n [0.5000, 0.5000, 0.5000],\n [0.2607, 0.2607, 0.2607]]\ntypes = [\"Mg\",\"Cr\",\"O\"]\nxtal_mgcro_1 = Crystal(latvecs, positions; types)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Crystal\nHM symbol 'R 3 m' (160)\nLattice params a=8.334, b=8.334, c=8.334, α=90°, β=90°, γ=90°\nCell volume 578.9\nType 'Mg', Wyckoff 3a (point group '3m'):\n 1. [1/8, 1/8, 1/8]\nType 'Cr', Wyckoff 3a (point group '3m'):\n 2. [1/2, 1/2, 1/2]\nType 'O', Wyckoff 3a (point group '3m'):\n 3. [0.2607, 0.2607, 0.2607]\n","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Sunny returned a valid crystal, but it did get right space group for MgCr2O4. This can be fixed by modifying the input to include the space group and the setting.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#\"Experimentalist\"-Method-#2-(Correct)","page":"MgCr2O4 at Finite Temperature","title":"\"Experimentalist\" Method #2 (Correct)","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"As above, we will define the crystal structure of MgCr2O4 by copying the info from a CIF file, but we will also specify the space group and setting explicitly.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"latvecs = lattice_vectors(8.3342, 8.3342, 8.3342, 90, 90, 90)\npositions = [[0.1250, 0.1250, 0.1250],\n [0.5000, 0.5000, 0.5000],\n [0.2607, 0.2607, 0.2607]]\ntypes = [\"Mg\",\"Cr\",\"O\"]\nspacegroup = 227 # Space Group Number\nsetting = \"2\" # Space Group setting\nxtal_mgcro_2 = Crystal(latvecs, positions, spacegroup; types, setting)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Crystal\nHM symbol 'F d -3 m' (227)\nLattice params a=8.334, b=8.334, c=8.334, α=90°, β=90°, γ=90°\nCell volume 578.9\nType 'Mg', Wyckoff 8b (point group '-43m'):\n 1. [1/8, 1/8, 1/8]\n 2. [5/8, 5/8, 1/8]\n 3. [7/8, 3/8, 3/8]\n 4. [3/8, 7/8, 3/8]\n 5. [5/8, 1/8, 5/8]\n 6. [1/8, 5/8, 5/8]\n 7. [3/8, 3/8, 7/8]\n 8. [7/8, 7/8, 7/8]\nType 'Cr', Wyckoff 16c (point group '.-3m'):\n 9. [1/2, 0, 0]\n 10. [3/4, 1/4, 0]\n 11. [0, 1/2, 0]\n 12. [1/4, 3/4, 0]\n 13. [3/4, 0, 1/4]\n 14. [1/2, 1/4, 1/4]\n 15. [1/4, 1/2, 1/4]\n 16. [0, 3/4, 1/4]\n 17. [0, 0, 1/2]\n 18. [1/4, 1/4, 1/2]\n 19. [1/2, 1/2, 1/2]\n 20. [3/4, 3/4, 1/2]\n 21. [1/4, 0, 3/4]\n 22. [0, 1/4, 3/4]\n 23. [3/4, 1/2, 3/4]\n 24. [1/2, 3/4, 3/4]\nType 'O', Wyckoff 32e (point group '.3m'):\n 25. [0.7393, 0.0107, 0.0107]\n 26. [0.5107, 0.2393, 0.0107]\n 27. [0.2393, 0.5107, 0.0107]\n 28. [0.0107, 0.7393, 0.0107]\n 29. [0.5107, 0.0107, 0.2393]\n 30. [0.7393, 0.2393, 0.2393]\n 31. [0.0107, 0.5107, 0.2393]\n 32. [0.2393, 0.7393, 0.2393]\n 33. [0.2607, 0.2607, 0.2607]\n 34. [0.4893, 0.4893, 0.2607]\n 35. [0.7607, 0.7607, 0.2607]\n 36. [0.9893, 0.9893, 0.2607]\n 37. [0.4893, 0.2607, 0.4893]\n 38. [0.2607, 0.4893, 0.4893]\n 39. [0.9893, 0.7607, 0.4893]\n 40. [0.7607, 0.9893, 0.4893]\n 41. [0.2393, 0.0107, 0.5107]\n 42. [0.0107, 0.2393, 0.5107]\n 43. [0.7393, 0.5107, 0.5107]\n 44. [0.5107, 0.7393, 0.5107]\n 45. [0.0107, 0.0107, 0.7393]\n 46. [0.2393, 0.2393, 0.7393]\n 47. [0.5107, 0.5107, 0.7393]\n 48. [0.7393, 0.7393, 0.7393]\n 49. [0.7607, 0.2607, 0.7607]\n 50. [0.9893, 0.4893, 0.7607]\n 51. [0.2607, 0.7607, 0.7607]\n 52. [0.4893, 0.9893, 0.7607]\n 53. [0.9893, 0.2607, 0.9893]\n 54. [0.7607, 0.4893, 0.9893]\n 55. [0.4893, 0.7607, 0.9893]\n 56. [0.2607, 0.9893, 0.9893]\n","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"This result is correct, but at this point we might as well import the CIF file directly, which we now proceed to do.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#\"Experimentalist\"-Method-#3-(Correct-–-if-your-CIF-file-is)","page":"MgCr2O4 at Finite Temperature","title":"\"Experimentalist\" Method #3 (Correct – if your CIF file is)","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"To import a CIF file, simply give the path to Crystal. One may optionally specify a precision parameter to apply to the symmetry analysis.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"cif = pkgdir(Sunny, \"examples\", \"longer_examples\", \"MgCr2O4_160953_2009.cif\")\nxtal_mgcro_3 = Crystal(cif; symprec=0.001)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Crystal\nHM symbol 'F d -3 m' (227)\nLattice params a=8.333, b=8.333, c=8.333, α=90°, β=90°, γ=90°\nCell volume 578.6\nType 'Mg1', Wyckoff 8b (point group '-43m'):\n 1. [1/8, 1/8, 1/8]\n 2. [5/8, 5/8, 1/8]\n 3. [7/8, 3/8, 3/8]\n 4. [3/8, 7/8, 3/8]\n 5. [5/8, 1/8, 5/8]\n 6. [1/8, 5/8, 5/8]\n 7. [3/8, 3/8, 7/8]\n 8. [7/8, 7/8, 7/8]\nType 'Cr1', Wyckoff 16c (point group '.-3m'):\n 9. [1/2, 0, 0]\n 10. [3/4, 1/4, 0]\n 11. [0, 1/2, 0]\n 12. [1/4, 3/4, 0]\n 13. [3/4, 0, 1/4]\n 14. [1/2, 1/4, 1/4]\n 15. [1/4, 1/2, 1/4]\n 16. [0, 3/4, 1/4]\n 17. [0, 0, 1/2]\n 18. [1/4, 1/4, 1/2]\n 19. [1/2, 1/2, 1/2]\n 20. [3/4, 3/4, 1/2]\n 21. [1/4, 0, 3/4]\n 22. [0, 1/4, 3/4]\n 23. [3/4, 1/2, 3/4]\n 24. [1/2, 3/4, 3/4]\nType 'O1', Wyckoff 32e (point group '.3m'):\n 25. [0.7388, 0.0112, 0.0112]\n 26. [0.5112, 0.2388, 0.0112]\n 27. [0.2388, 0.5112, 0.0112]\n 28. [0.0112, 0.7388, 0.0112]\n 29. [0.5112, 0.0112, 0.2388]\n 30. [0.7388, 0.2388, 0.2388]\n 31. [0.0112, 0.5112, 0.2388]\n 32. [0.2388, 0.7388, 0.2388]\n 33. [0.2612, 0.2612, 0.2612]\n 34. [0.4888, 0.4888, 0.2612]\n 35. [0.7612, 0.7612, 0.2612]\n 36. [0.9888, 0.9888, 0.2612]\n 37. [0.4888, 0.2612, 0.4888]\n 38. [0.2612, 0.4888, 0.4888]\n 39. [0.9888, 0.7612, 0.4888]\n 40. [0.7612, 0.9888, 0.4888]\n 41. [0.2388, 0.0112, 0.5112]\n 42. [0.0112, 0.2388, 0.5112]\n 43. [0.7388, 0.5112, 0.5112]\n 44. [0.5112, 0.7388, 0.5112]\n 45. [0.0112, 0.0112, 0.7388]\n 46. [0.2388, 0.2388, 0.7388]\n 47. [0.5112, 0.5112, 0.7388]\n 48. [0.7388, 0.7388, 0.7388]\n 49. [0.7612, 0.2612, 0.7612]\n 50. [0.9888, 0.4888, 0.7612]\n 51. [0.2612, 0.7612, 0.7612]\n 52. [0.4888, 0.9888, 0.7612]\n 53. [0.9888, 0.2612, 0.9888]\n 54. [0.7612, 0.4888, 0.9888]\n 55. [0.4888, 0.7612, 0.9888]\n 56. [0.2612, 0.9888, 0.9888]\n","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Finally, we wish to restrict attention to the magnetic atoms in the unit cell while maintaining symmetry information for the full crystal, which is required to determine the correct exchange and g-factor anisotropies. This can be achieved with the subcrystal function.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"xtal_mgcro = subcrystal(xtal_mgcro_2,\"Cr\")","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Crystal\nHM symbol 'F d -3 m' (227)\nLattice params a=8.334, b=8.334, c=8.334, α=90°, β=90°, γ=90°\nCell volume 578.9\nType 'Cr', Wyckoff 16c (point group '.-3m'):\n 1. [1/2, 0, 0]\n 2. [3/4, 1/4, 0]\n 3. [0, 1/2, 0]\n 4. [1/4, 3/4, 0]\n 5. [3/4, 0, 1/4]\n 6. [1/2, 1/4, 1/4]\n 7. [1/4, 1/2, 1/4]\n 8. [0, 3/4, 1/4]\n 9. [0, 0, 1/2]\n 10. [1/4, 1/4, 1/2]\n 11. [1/2, 1/2, 1/2]\n 12. [3/4, 3/4, 1/2]\n 13. [1/4, 0, 3/4]\n 14. [0, 1/4, 3/4]\n 15. [3/4, 1/2, 3/4]\n 16. [1/2, 3/4, 3/4]\n","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#Making-a-System-and-assigning-interactions","page":"MgCr2O4 at Finite Temperature","title":"Making a System and assigning interactions","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html#Making-a-System","page":"MgCr2O4 at Finite Temperature","title":"Making a System","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Before assigning any interactions, we first have to set up a System using our Crystal.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"dims = (6, 6, 6) # Supercell dimensions\nspininfos = [SpinInfo(1, S=3/2, g=2)] # Specify spin information, note that all sites are symmetry equivalent\nsys_pyro = System(xtal_pyro, dims, spininfos, :dipole) # Make a system in dipole (Landau-Lifshitz) mode on pyrochlore lattice\nsys_mgcro = System(xtal_mgcro, dims, spininfos, :dipole); # Same on MgCr2O4 crystal","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"To understand what interactions we may assign to this system, we have to understand the the symmetry properties of the crystal, which we turn to next.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#Symmetry-analysis-for-exchange-and-single-ion-anisotropies","page":"MgCr2O4 at Finite Temperature","title":"Symmetry analysis for exchange and single-ion anisotropies","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"print_symmetry_table reports all the exchange interactions, single-site anisotropies, and g-factors allowed on our crystal. It takes a Cyrstal and a distance. We'll look at both the \"theorist's\" pyrochlore lattice,","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"print_symmetry_table(xtal_pyro, 5.9)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Atom 1\nType 'B', position [7/8, 5/8, 3/8], multiplicity 16\nAllowed g-tensor: [ A B -B\n B A B\n -B B A]\nAllowed anisotropy in Stevens operators:\n c₁*(𝒪[2,-2]+2𝒪[2,-1]-2𝒪[2,1]) +\n c₂*(7𝒪[4,-3]+2𝒪[4,-2]-𝒪[4,-1]+𝒪[4,1]+7𝒪[4,3]) + c₃*(𝒪[4,0]+5𝒪[4,4]) +\n c₄*(-11𝒪[6,-6]-8𝒪[6,-3]+𝒪[6,-2]-8𝒪[6,-1]+8𝒪[6,1]-8𝒪[6,3]) + c₅*(𝒪[6,0]-21𝒪[6,4]) + c₆*((9/5)𝒪[6,-6]+(24/5)𝒪[6,-5]+𝒪[6,-2]+(8/5)𝒪[6,-1]-(8/5)𝒪[6,1]-(24/5)𝒪[6,5])\n\nSunny.Bond(1, 3, [0, 0, 0])\nDistance 2.94658466788246, coordination 6\nConnects 'B' at [7/8, 5/8, 3/8] to 'B' at [7/8, 7/8, 1/8]\nAllowed exchange matrix:[ A -D D\n D B C\n -D C B]\nAllowed DM vector: [0 -D -D]\n\nSunny.Bond(1, 2, [0, 0, 0])\nDistance 5.10363435357589, coordination 12\nConnects 'B' at [7/8, 5/8, 3/8] to 'B' at [5/8, 1/8, 5/8]\nAllowed exchange matrix:[ A C-E D-F\n C+E B -C+E\n D+F -C-E A]\nAllowed DM vector: [E F -E]\n\nSunny.Bond(2, 6, [0, 0, 0])\nDistance 5.89316933576492, coordination 6\nConnects 'B' at [5/8, 1/8, 5/8] to 'B' at [5/8, 5/8, 1/8]\nAllowed exchange matrix:[A D D\n D B C\n D C B]\n\nSunny.Bond(1, 5, [0, 0, 0])\nDistance 5.89316933576492, coordination 6\nConnects 'B' at [7/8, 5/8, 3/8] to 'B' at [7/8, 1/8, 7/8]\nAllowed exchange matrix:[ A D -D\n D B C\n -D C B]\n\n","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"and for the the MgCrO4 crystal,","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"print_symmetry_table(xtal_mgcro, 6.0)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Atom 1\nType 'Cr', position [1/2, 0, 0], multiplicity 16\nAllowed g-tensor: [A B B\n B A B\n B B A]\nAllowed anisotropy in Stevens operators:\n c₁*(𝒪[2,-2]+2𝒪[2,-1]+2𝒪[2,1]) +\n c₂*(-7𝒪[4,-3]-2𝒪[4,-2]+𝒪[4,-1]+𝒪[4,1]+7𝒪[4,3]) + c₃*(𝒪[4,0]+5𝒪[4,4]) +\n c₄*(-11𝒪[6,-6]-8𝒪[6,-3]+𝒪[6,-2]-8𝒪[6,-1]-8𝒪[6,1]+8𝒪[6,3]) + c₅*(𝒪[6,0]-21𝒪[6,4]) + c₆*((9/5)𝒪[6,-6]+(24/5)𝒪[6,-5]+𝒪[6,-2]+(8/5)𝒪[6,-1]+(8/5)𝒪[6,1]+(24/5)𝒪[6,5])\n\nSunny.Bond(1, 2, [0, 0, 0])\nDistance 2.94658466788246, coordination 6\nConnects 'Cr' at [1/2, 0, 0] to 'Cr' at [3/4, 1/4, 0]\nAllowed exchange matrix:[A C -D\n C A -D\n D D B]\nAllowed DM vector: [-D D 0]\n\nSunny.Bond(1, 7, [0, 0, 0])\nDistance 5.10363435357589, coordination 12\nConnects 'Cr' at [1/2, 0, 0] to 'Cr' at [1/4, 1/2, 1/4]\nAllowed exchange matrix:[ A C-E D-F\n C+E B -C+E\n D+F -C-E A]\nAllowed DM vector: [E F -E]\n\nSunny.Bond(1, 3, [0, 0, 0])\nDistance 5.89316933576492, coordination 6\nConnects 'Cr' at [1/2, 0, 0] to 'Cr' at [0, 1/2, 0]\nAllowed exchange matrix:[A D C\n D A C\n C C B]\n\nSunny.Bond(1, 3, [1, 0, 0])\nDistance 5.89316933576492, coordination 6\nConnects 'Cr' at [1/2, 0, 0] to 'Cr' at [1, 1/2, 0]\nAllowed exchange matrix:[A D C\n D A C\n C C B]\n\n","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Note that the exchange anisotropies allowed on the the pyrochlore lattice are slightly different from those on the MgCr2O4 cyrstal due to the role of Mg and O in the bonds. Also note that Sunny has correctly identified the two inequivalent bonds 3a and 3b having the same length. A question may arises to know which bond is J3a and which is J3b, let's plot the structure.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"view_crystal(xtal_mgcro, 5.9)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"The crystal viewer shows that the second interaction – cyan color with distance of 5.89Å – is in fact the one hopping through a chromium site, meaning it is J3a! We will need to be careful with that later.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#Building-the-exchange-interactions-for-our-system","page":"MgCr2O4 at Finite Temperature","title":"Building the exchange interactions for our system","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"We begin by setting the scale of our exchange interactions on each bond.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"J1 = 3.27 # value of J1 in meV from Bai's PRL paper\nJ_pyro = [1.00,0.000,0.000,0.000]*J1 # pure nearest neighbor pyrochlore\nJ_mgcro = [1.00,0.0815,0.1050,0.085]*J1; # further neighbor pyrochlore relevant for MgCr2O4\n# val_J_mgcro = [1.00,0.000,0.025,0.025]*val_J1; # this is a funny setting from Conlon-Chalker","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"These values are then assigned to their corresponding bonds with set_exchange!.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"# === Assign exchange interactions to pyrochlore system ===\nset_exchange!(sys_pyro, J_pyro[1], Bond(1, 3, [0,0,0])) # J1\nset_exchange!(sys_pyro, J_pyro[2], Bond(1, 2, [0,0,0])) # J2\nset_exchange!(sys_pyro, J_pyro[3], Bond(2, 6, [0,0,0])) # J3a\nset_exchange!(sys_pyro, J_pyro[4], Bond(1, 5, [0,0,0])) # J3b\n\n# === Assign exchange interactions to MgCr2O4 system ===\nset_exchange!(sys_mgcro, J_mgcro[1], Bond(1, 2, [0,0,0])) # J1\nset_exchange!(sys_mgcro, J_mgcro[2], Bond(1, 7, [0,0,0])) # J2\nset_exchange!(sys_mgcro, J_mgcro[3], Bond(1, 3, [0,0,0])) # J3a -- Careful here!\nset_exchange!(sys_mgcro, J_mgcro[4], Bond(1, 3, [1,0,0])); # J3b -- And here!","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"We will not be assigning any single-ion anisotropies, so we have finished specifying our models. For good measure, we will set both systems to a random (infinite temperature) initial condition.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"randomize_spins!(sys_pyro)\nrandomize_spins!(sys_mgcro);","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#Cooling-our-System-amd-calculating-the-instantaneous-and-dynamic-structure-factors-at-the-final-temperature","page":"MgCr2O4 at Finite Temperature","title":"Cooling our System amd calculating the instantaneous and dynamic structure factors at the final temperature","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"We begin by thermalizing our system at a particular temperature. We will accomplish this by running Langevin dynamics. To do this, we must set up a Langevin integrator.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Δt = 0.05 # Integration time step in meV^-1\nλ = 0.1 # Phenomenological damping parameter\nkT = 1.8 # Desired temperature in meV\nlangevin = Langevin(Δt; λ, kT); # Construct integrator","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"We can now thermalize our systems by running the integrator.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"for _ in 1:2000\n step!(sys_pyro, langevin)\n step!(sys_mgcro, langevin)\nend","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"As a sanity check, we'll plot the real-space spin configurations of both systems after themalization. First the pyrochlore,","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"plot_spins(sys_pyro)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"and then the MgCr2O4,","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"plot_spins(sys_mgcro)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#Instantaneous-Structure-Factor","page":"MgCr2O4 at Finite Temperature","title":"Instantaneous Structure Factor","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Next we can examine the instantaneous structure factor.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"isf_pyro = instant_correlations(sys_pyro)\nisf_mgcro = instant_correlations(sys_mgcro);","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"These are currently empty. Let's add correlation data from 10 trajectories.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"for _ in 1:10\n # Run dynamics to decorrelate\n for _ in 1:500\n step!(sys_pyro, langevin)\n step!(sys_mgcro, langevin)\n end\n # Add samples\n add_sample!(isf_pyro, sys_pyro)\n add_sample!(isf_mgcro, sys_mgcro)\nend","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"To retrieve the intensities, we set up a formula and call intensities_interpolated on an array of wave vectors.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"qvals = -4.0:0.025:4.0\nqs = [(qa, qb, 0) for qa in qvals, qb in qvals] # Wave vectors to query\n\nformula_pyro = intensity_formula(isf_pyro, :perp)\nformula_mgcro = intensity_formula(isf_mgcro, :perp)\nSq_pyro = instant_intensities_interpolated(isf_pyro, qs, formula_pyro)\nSq_mgcro = instant_intensities_interpolated(isf_mgcro, qs, formula_mgcro);","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Finally, we can plot the results.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"fig = Figure(; resolution=(1200,500))\naxparams = (aspect = true, xticks=-4:4, yticks=-4:4, titlesize=20,\n xlabel = \"𝐪a (2π a⁻¹)\", ylabel = \"𝐪b (2π b⁻¹)\", xlabelsize = 18, ylabelsize=18,)\nax_pyro = Axis(fig[1,1]; title=\"Pyrochlore\", axparams...)\nax_mgcro = Axis(fig[1,3]; title=\"MgCr2O4\", axparams...)\nhm = heatmap!(ax_pyro, qvals, qvals, Sq_pyro)\nColorbar(fig[1,2], hm)\nhm = heatmap!(ax_mgcro, qvals, qvals, Sq_mgcro)\nColorbar(fig[1,4], hm)\nfig","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#Dynamical-Structure-Factor","page":"MgCr2O4 at Finite Temperature","title":"Dynamical Structure Factor","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"We can also estimate the dynamical structure factor.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"sc_pyro = dynamical_correlations(sys_pyro; Δt, ωmax = 10.0, nω = 100)\nsc_mgcro = dynamical_correlations(sys_mgcro; Δt, ωmax = 10.0, nω = 100);","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Next we add some sample trajectories.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"for _ in 1:3\n # Run dynamics to decorrelate\n for _ in 1:500\n step!(sys_pyro, langevin)\n step!(sys_mgcro, langevin)\n end\n # Add samples\n add_sample!(sc_pyro, sys_pyro)\n add_sample!(sc_mgcro, sys_mgcro)\nend","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"We can now examine the structure factor intensities along a path in momentum space.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"fig = Figure(; resolution=(1200,900))\naxsqw = (xticks=-4:4, yticks=0:2:10, ylabel=\"E (meV)\", ylabelsize=18, xlabelsize=18, )\n\nqbs = 0.0:0.5:1.5 # Determine q_b for each slice\nfor (i, qb) in enumerate(qbs)\n path, _ = reciprocal_space_path(xtal_pyro, [[-4.0, qb, 0.0],[4.0, qb, 0.0]], 40) # Generate a path of wave\n # vectors through the BZ\n formula = intensity_formula(sc_pyro, :perp; kT) # Temperature keyword enables intensity rescaling\n Sqω_pyro = intensities_interpolated(sc_pyro, path, formula)\n\n ax = Axis(fig[fldmod1(i,2)...]; xlabel = \"q = (x, $qb, 0)\", axsqw...)\n ωs = available_energies(sc_pyro)\n heatmap!(ax, [p[1] for p in path], ωs, Sqω_pyro; colorrange=(0.0, 4.0))\nend\nfig","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"And let's take a look at the same slices for MgCr2O4.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"fig = Figure(; resolution=(1200,900))\n\nqbs = 0.0:0.5:1.5\nfor (i, qb) in enumerate(qbs)\n path, _ = reciprocal_space_path(xtal_mgcro, [[-4.0, qb, 0.0],[4.0, qb, 0.0]], 40) # Generate a path of wave\n # vectors through the BZ\n formula = intensity_formula(sc_mgcro, :perp; kT) # Temperature keyword enables intensity rescaling\n Sqω_mgcro = intensities_interpolated(sc_mgcro, path, formula)\n\n ax = Axis(fig[fldmod1(i,2)...]; xlabel = \"q = (x, $qb, 0)\", axsqw...)\n ωs = available_energies(sc_mgcro)\n heatmap!(ax, [p[1] for p in path], ωs, Sqω_mgcro; colorrange=(0.0, 4.0))\nend\nfig","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#Instantaneous-structure-factor-from-a-dynamical-structure-factor","page":"MgCr2O4 at Finite Temperature","title":"Instantaneous structure factor from a dynamical structure factor","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Finally, we note that the instant structure factor can be calculated from the dynamical structure factor. We simply call instant_intensities rather than intensities. This will calculate the instantaneous structure factor from from 𝒮(𝐪ω) by integrating out ω . An advantage of doing this (as opposed to using instant_correlations) is that Sunny is able to apply a temperature- and energy-dependent intensity rescaling before integrating out the dynamical information. The results of this approach are more suitable for comparison with experimental data.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"qvals = -4.0:0.05:4.0\nqs = [(qa, qb, 0) for qa in qvals, qb in qvals] # Wave vectors to query\n\nformula_pyro = intensity_formula(sc_pyro, :perp; kT) # Temperature keyword enables intensity rescaling\nformula_mgcro = intensity_formula(sc_mgcro, :perp; kT) # Temperature keyword enables intensity rescaling\n\nSq_pyro = instant_intensities_interpolated(sc_pyro, qs, formula_pyro)\nSq_mgcro = instant_intensities_interpolated(sc_mgcro, qs, formula_mgcro);","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"We can plot the results below. It is useful to compare these to the plot above generated with an instant_correlations.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"fig = Figure(; resolution=(1200,500))\nax_pyro = Axis(fig[1,1]; title=\"Pyrochlore\", axparams...)\nax_mgcro = Axis(fig[1,3]; title=\"MgCr2O4\", axparams...)\nhm = heatmap!(ax_pyro, qvals, qvals, Sq_pyro)\nColorbar(fig[1,2], hm)\nhm = heatmap!(ax_mgcro, qvals, qvals, Sq_mgcro)\nColorbar(fig[1,4], hm)\nfig","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html#Powder-Averaged-CoRhO-at-Finite-Temperature","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"","category":"section"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Inspired by: Ge et al., Phys. Rev. B 96, 064413 (2017)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Authors: Martin Mourigal, David Dahlbom","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Date: October 28, 2023 (Sunny 0.5.5)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Goal: This script is to calculate the temperature dependence of the magnon excitations in the spin-3/2 Heisenberg Diamond Antiferromagnet and compare to powder-averaged results obtained for the compound CoRh₂O₄","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html#Load-pacakges.","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Load pacakges.","text":"","category":"section"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"using Sunny, GLMakie, ProgressMeter, Statistics, Random, Brillouin\ncif_path = pkgdir(Sunny, \"examples\", \"longer_examples\", \"CoRh2O4_#109301.cif\");","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html#Define-custom-functions.","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Define custom functions.","text":"","category":"section"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"The function quench! randomizes the spins of a given System, fixes a target temperature, and lets the system relax at this temperature for nrelax integration steps.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"function quench!(sys, integrator; kTtarget, nrelax)\n randomize_spins!(sys);\n integrator.kT = kTtarget;\n prog = Progress(nrelax; dt=10.0, desc=\"Quenched and now relaxing: \", color=:green);\n for _ in 1:nrelax\n step!(sys, integrator)\n next!(prog)\n end\nend","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"quench! (generic function with 1 method)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"dwell! takes a System, sets a target temperature, and has the system dwell at this temperature for ndwell integration steps.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"function dwell!(sys, integrator; kTtarget, ndwell)\n integrator.kT = kTtarget;\n prog = Progress(ndwell; dt=10.0, desc=\"Dwelling: \", color=:green);\n for _ in 1:ndwell\n step!(sys, integrator)\n next!(prog)\n end\nend","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"dwell! (generic function with 1 method)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"anneal! takes a temperature schedule and cools the System through it, with ndwell steps of the integrator at each temperature in the schedule. Returns the energy at the end of the dwell for each scheduled temperature.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"function anneal!(sys, integrator; kTschedule, ndwell)\n nspins = prod(size(sys.dipoles));\n ensys = zeros(length(kTschedule))\n prog = Progress(ndwell*length(kTschedule); dt=10.0, desc=\"Annealing: \", color=:red);\n for (i, kT) in enumerate(kTschedule)\n integrator.kT = kT\n for _ in 1:ndwell\n step!(sys, integrator)\n next!(prog)\n end\n ensys[i] = energy(sys)\n end\n return ensys/nspins\nend","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"anneal! (generic function with 1 method)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"sample_sf! samples a structure factor, which may be either an instant or dynamical structure factor. The integrator is run ndecorr times before each one of the samples is taken.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"function sample_sf!(sf, sys, integrator; nsamples, ndecorr)\n prog = Progress(nsamples*ndecorr; dt=10.0, desc=\"Sampling SF: \", color=:red);\n for _ in 1:nsamples\n for _ in 1:ndecorr\n step!(sys, integrator)\n next!(prog)\n end\n add_sample!(sf, sys) # Accumulate the newly sampled structure factor into `sf`\n end\nend","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"sample_sf! (generic function with 1 method)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"powder_average powder averages a structure factor. Works for both instant and dynamical structure factors. To prevent smearing, removes Bragg peaks before introducing energy broadening. Bragg peaks are added back at ω=0 after broadening.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"function powder_average(sc, rs, npts, formula; η=0.1)\n prog = Progress(length(rs); dt=10., desc=\"Powder Averaging: \", color=:blue)\n ωs = available_energies(sc)\n output = zeros(Float64, length(rs), length(ωs))\n for (i, r) in enumerate(rs)\n qs = reciprocal_space_shell(sc.crystal, r, npts)\n vals = intensities_interpolated(sc, qs, formula)\n bragg_idxs = findall(x -> x > maximum(vals)*0.9, vals)\n bragg_vals = vals[bragg_idxs]\n vals[bragg_idxs] .= 0\n vals = broaden_energy(sc, vals, (ω,ω₀)->lorentzian(ω-ω₀, η))\n vals[bragg_idxs] .= bragg_vals\n output[i,:] .= mean(vals, dims=1)[1,:]\n next!(prog)\n end\n return output\nend","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"powder_average (generic function with 1 method)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html#System-Definition-for-CoRhO","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"System Definition for CoRh₂O₄","text":"","category":"section"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Define the crystal structure of CoRh₂O₄ in the conventional cell.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"xtal = Crystal(cif_path; symprec=1e-4)\nmagxtal = subcrystal(xtal,\"Co1\")\nview_crystal(magxtal, 6.0)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Print the symmetry-allowed interactions.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"print_symmetry_table(magxtal, 4.0)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Atom 1\nType 'Co1', position [0, 0, 0], multiplicity 8\nAllowed g-tensor: [A 0 0\n 0 A 0\n 0 0 A]\nAllowed anisotropy in Stevens operators:\n c₁*(𝒪[4,0]+5𝒪[4,4]) +\n c₂*(𝒪[6,0]-21𝒪[6,4])\n\nSunny.Bond(1, 3, [0, 0, 0])\nDistance 3.6784429025744, coordination 4\nConnects 'Co1' at [0, 0, 0] to 'Co1' at [1/4, 1/4, 1/4]\nAllowed exchange matrix:[A B B\n B A B\n B B A]\n\n","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Assign local Hilbert space","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"S = 3/2\nlhs = [SpinInfo(1; S, g=2)]\nformfactors = [FormFactor(\"Co2\")];","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Create System and randomize it","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"sunmode = :dipole\nlatsize = (10,10,10)\nsys = System(magxtal, latsize, lhs, sunmode; seed=1)\nrandomize_spins!(sys)\nplot_spins(sys)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Define exchange interactions.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"scaleJ = 0.63\nvalJ1 = 1.00*scaleJ\nset_exchange!(sys, valJ1, Bond(1, 3, [0, 0, 0]));","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html#Thermalize-system-to-an-ordered,-yet-finite-temperature,-state","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Thermalize system to an ordered, yet finite temperature, state","text":"","category":"section"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Define Langevin Integrator and Initialize it","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Δt0 = 0.05/abs(scaleJ*S); ## Time steps in Langevin\nλ0 = 0.1; ## Langevin damping, usually 0.05 or 0.1 is good.\nkT0 = 0.01*abs(scaleJ*S); ## Initialize at some temperature\nintegrator = Langevin(Δt0; λ=λ0, kT=kT0);","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Thermalization Option 1: Quench the system from infinite temperature to a target temperature. Note: this may lead to a poorly thermalized sample","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"quench!(sys, integrator; kTtarget=kT0, nrelax=10000);","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Option 2: Anneal (according to a temperature schedule) then dwell once we've reach base temperature. (Uncomment to execute.)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"# kTs = [abs(scaleJ)*valS*100 * 0.9^k for k in 0:100]\n# anneal!(sys,integrator;kTschedule=kTs,ndwell=500)\n# dwell!(sys,integrator;kTtarget=kTs[end],ndwell=2000)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Plot the resulting spin system to check ordering in real space","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"plot_spins(sys)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html#Calculation-of-Neutron-Scattering-Responses","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Calculation of Neutron Scattering Responses","text":"","category":"section"},{"location":"examples/contributed/CoRh2O4-tutorial.html#Fourier-transformed-instantaneous-two-point-correlation-functions","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Fourier transformed instantaneous two-point correlation functions","text":"","category":"section"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Calculate the instantaneous/equal-time structure factor.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"eqsf = instant_correlations(sys)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"SampledCorrelations (6.252 MiB)\n[S(q) | 0 sample]\nLattice: (10, 10, 10)×8\n6 correlations in Dipole mode:\n╔ ⬤ ⬤ ⬤ Sx\n║ ⋅ ⬤ ⬤ Sy\n╚ ⋅ ⋅ ⬤ Sz\n","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"If desired, add additional samples by decorrelating and then re-calculating the eqsf.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"nsamples = 1\nndecorr = 1000\n@time sample_sf!(eqsf, sys, integrator; nsamples=nsamples, ndecorr=ndecorr);","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":" 0.966485 seconds (1.89 M allocations: 118.815 MiB, 6.25% gc time, 50.12% compilation time)\n","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Project onto a constant Q-Slice in momentum space.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"nQpts = 200\nQxpts = range(-10.0, 10.0, length=nQpts)\nQypts = range(-10.0, 10.0, length=nQpts)\nqz = 1.0\nQpts = [[qx, qy, qz] for qx in Qxpts, qy in Qypts]\ninstant_formula = intensity_formula(eqsf, :perp; formfactors)\niq = instant_intensities_interpolated(eqsf, Qpts, instant_formula);","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Plot the resulting I(Q)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"heatmap(Qxpts, Qypts, iq;\n colorrange = (0, maximum(iq)/20),\n axis = (\n xlabel=\"Momentum Transfer Qx (r.l.u)\", xlabelsize=16,\n ylabel=\"Momentum Transfer Qy (r.l.u)\", ylabelsize=16,\n aspect=true,\n )\n)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html#Dynamical-and-energy-integrated-two-point-correlation-functions","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Dynamical and energy-integrated two-point correlation functions","text":"","category":"section"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Calculate the time traces and Fourier transform: Dynamical Structure Factor (first sample).","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"ωmax = 6.0 # Maximum energy to resolve\nnω = 100 # Number of energies to resolve\nsc = dynamical_correlations(sys; Δt=Δt0, nω=nω, ωmax=ωmax, process_trajectory=:symmetrize)\n@time add_sample!(sc, sys) # Add a sample trajectory","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":" 5.471269 seconds (14.33 M allocations: 291.526 MiB, 0.75% gc time, 0.02% compilation time)\n","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"If desired, add additional decorrelated samples.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"nsamples = 10\nndecorr = 1000\n@time sample_sf!(sc, sys, integrator; nsamples=nsamples, ndecorr=ndecorr);","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Sampling SF: 27%|██████████▎ | ETA: 0:00:33\u001b[KSampling SF: 49%|██████████████████▊ | ETA: 0:00:25\u001b[KSampling SF: 68%|█████████████████████████▉ | ETA: 0:00:17\u001b[KSampling SF: 84%|████████████████████████████████ | ETA: 0:00:09\u001b[KSampling SF: 100%|██████████████████████████████████████| Time: 0:00:53\u001b[K\n 59.070784 seconds (143.58 M allocations: 2.866 GiB, 0.56% gc time, 0.24% compilation time)\n","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Can use the Brillouin package for help on determining high symmetry points","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"kp = irrfbz_path(227,[[1,0,0], [0,1,0], [0,0,1]])\nkpc = cartesianize(kp)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"KPath{3} (6 points, 2 paths, 8 points in paths):\n points: :U => [1.570796, 6.283185, 1.570796]\n :W => [3.141593, 6.283185, 0.0]\n :K => [4.712389, 4.712389, 0.0]\n :Γ => [0.0, 0.0, 0.0]\n :L => [3.141593, 3.141593, 3.141593]\n :X => [0.0, 6.283185, 0.0]\n paths: [:Γ, :X, :U]\n [:K, :Γ, :L, :W, :X]\n basis: [-6.283185, 6.283185, 6.283185]\n [6.283185, -6.283185, 6.283185]\n [6.283185, 6.283185, -6.283185]","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Project onto a constant QE-Slice in momentum-energy space.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"densQpts = 50\nsymQpts = [[0.75, 0.75, 0.00], # List of wave vectors that define a path\n [0.00, 0.00, 0.00],\n [0.50, 0.50, 0.50],\n [0.50, 1.00, 0.00],\n [0.00, 1.00, 0.00],\n [0.25, 1.00, 0.25],\n [0.00, 1.00, 0.00],\n [0.00,-4.00, 0.00]]\n(Qpts, xticks) = reciprocal_space_path(magxtal, symQpts, densQpts)\nformula = intensity_formula(sc, :perp; formfactors, kT=integrator.kT)\niqw = intensities_interpolated(sc, Qpts, formula);","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"If desired, broaden the sc in energy.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"η = 0.1 ## Lorentzian energy broadening parameter\niqwc = broaden_energy(sc, iqw, (ω, ω₀) -> lorentzian(ω-ω₀, η));","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"If desired, calculated the energy-integrated structure factor","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"iqt = instant_intensities_interpolated(sc, Qpts, formula);","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Plot the resulting I(Q,W).","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"ωs = available_energies(sc)\nheatmap(1:size(iqwc, 1), ωs, iqwc;\n colorrange = (0, maximum(iqwc)/20000.0),\n axis = (;\n xlabel=\"Momentum Transfer (r.l.u)\",\n ylabel=\"Energy Transfer (meV)\",\n xticks,\n xticklabelrotation=π/5,\n aspect = 1.4,\n )\n)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Projection into a powder-averaged neutron scattering intensity .","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Qmax = 3.5\nnQpts = 100\nQpow = range(0, Qmax, nQpts)\nnpoints = 100\npqw = powder_average(sc, Qpow, npoints, formula; η);","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Powder Averaging: 78%|█████████████████████████▊ | ETA: 0:00:03\u001b[KPowder Averaging: 100%|█████████████████████████████████| Time: 0:00:12\u001b[K\n","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Plot resulting Ipow(|Q|,W).","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"heatmap(Qpow, ωs, pqw;\n axis = (\n xlabel=\"|Q| (Å⁻¹)\",\n ylabel=\"Energy Transfer (meV)\",\n aspect = 1.4,\n ),\n colorrange = (0, 40.0)\n)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html#Calculation-of-temperature-dependent-powder-average-spectrum","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Calculation of temperature-dependent powder average spectrum","text":"","category":"section"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Define a temperature schedule","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"kTs = [60 40 25 20 15 12 10 4] * Sunny.meV_per_K\npqw_res = []\nfor kT in kTs\n dwell!(sys, integrator; kTtarget=kT, ndwell=1000);\n sc_loc = dynamical_correlations(sys; Δt=Δt0, nω, ωmax, process_trajectory=:symmetrize);\n add_sample!(sc_loc, sys)\n formula = intensity_formula(sc, :perp; formfactors, kT)\n push!(pqw_res, powder_average(sc_loc, Qpow, npoints, formula; η))\nend","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"┌ Warning: Assignment to `formula` in soft scope is ambiguous because a global variable by the same name exists: `formula` will be treated as a new local. Disambiguate by using `local formula` to suppress this warning or `global formula` to assign to the existing global variable.\n└ @ ~/Research/SunnyContributed/contributed-docs/build/CoRh2O4-tutorial.md:7\nPowder Averaging: 83%|███████████████████████████▍ | ETA: 0:00:02\u001b[KPowder Averaging: 100%|█████████████████████████████████| Time: 0:00:12\u001b[K\nPowder Averaging: 83%|███████████████████████████▍ | ETA: 0:00:02\u001b[KPowder Averaging: 100%|█████████████████████████████████| Time: 0:00:12\u001b[K\nPowder Averaging: 83%|███████████████████████████▍ | ETA: 0:00:02\u001b[KPowder Averaging: 100%|█████████████████████████████████| Time: 0:00:12\u001b[K\nPowder Averaging: 83%|███████████████████████████▍ | ETA: 0:00:02\u001b[KPowder Averaging: 100%|█████████████████████████████████| Time: 0:00:12\u001b[K\nPowder Averaging: 81%|██████████████████████████▊ | ETA: 0:00:02\u001b[KPowder Averaging: 100%|█████████████████████████████████| Time: 0:00:12\u001b[K\nPowder Averaging: 83%|███████████████████████████▍ | ETA: 0:00:02\u001b[KPowder Averaging: 100%|█████████████████████████████████| Time: 0:00:12\u001b[K\nPowder Averaging: 81%|██████████████████████████▊ | ETA: 0:00:02\u001b[KPowder Averaging: 100%|█████████████████████████████████| Time: 0:00:12\u001b[K\nPowder Averaging: 87%|████████████████████████████▊ | ETA: 0:00:02\u001b[KPowder Averaging: 100%|█████████████████████████████████| Time: 0:00:11\u001b[K\n","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Plot the resulting Ipow(|Q|,W) as a function of temperature, to compare with Fig.6 of https://arxiv.org/abs/1706.05881","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"fig = Figure(; resolution=(1200,600))\nfor i in 1:8\n r, c = fldmod1(i, 4)\n ax = Axis(fig[r, c];\n title = \"kT = \"*string(round(kTs[9-i], digits=3))*\" (meV)\",\n xlabel = r == 2 ? \"|Q| (Å⁻¹)\" : \"\",\n ylabel = c == 1 ? \"Energy Transfer (meV)\" : \"\",\n aspect = 1.4,\n )\n heatmap!(ax, Qpow, ωs, pqw_res[9-i]; colorrange = (0, 20.0))\nend\nfig","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/spinw/08_Kagome_AFM.html","page":"Tutorial 8 - Kagome Antiferromagnet","title":"Tutorial 8 - Kagome Antiferromagnet","text":"EditURL = \"../../../../examples/spinw_ports/08_Kagome_AFM.jl\"","category":"page"},{"location":"examples/spinw/08_Kagome_AFM.html","page":"Tutorial 8 - Kagome Antiferromagnet","title":"Tutorial 8 - Kagome Antiferromagnet","text":"Download this example as Jupyter notebook or Julia script.","category":"page"},{"location":"examples/spinw/08_Kagome_AFM.html#Tutorial-8-Kagome-Antiferromagnet","page":"Tutorial 8 - Kagome Antiferromagnet","title":"Tutorial 8 - Kagome Antiferromagnet","text":"","category":"section"},{"location":"examples/spinw/08_Kagome_AFM.html","page":"Tutorial 8 - Kagome Antiferromagnet","title":"Tutorial 8 - Kagome Antiferromagnet","text":"This is a Sunny port of SpinW Tutorial 8, originally authored by Bjorn Fak and Sandor Toth. The goal is to calculate the linear spin wave theory spectrum for the sqrt3 times sqrt3 order of a Kagome antiferromagnet.","category":"page"},{"location":"examples/spinw/08_Kagome_AFM.html","page":"Tutorial 8 - Kagome Antiferromagnet","title":"Tutorial 8 - Kagome Antiferromagnet","text":"Load Packages","category":"page"},{"location":"examples/spinw/08_Kagome_AFM.html","page":"Tutorial 8 - Kagome Antiferromagnet","title":"Tutorial 8 - Kagome Antiferromagnet","text":"using Sunny, GLMakie","category":"page"},{"location":"examples/spinw/08_Kagome_AFM.html","page":"Tutorial 8 - Kagome Antiferromagnet","title":"Tutorial 8 - Kagome Antiferromagnet","text":"Build a Crystal with Poverline3 space group,","category":"page"},{"location":"examples/spinw/08_Kagome_AFM.html","page":"Tutorial 8 - Kagome Antiferromagnet","title":"Tutorial 8 - Kagome Antiferromagnet","text":"a = 1\nlatvecs = lattice_vectors(a, a, 10a, 90, 90, 120)\ncrystal = Crystal(latvecs, [[1/2,0,0]], 147)","category":"page"},{"location":"examples/spinw/08_Kagome_AFM.html","page":"Tutorial 8 - Kagome Antiferromagnet","title":"Tutorial 8 - Kagome Antiferromagnet","text":"Build a System with antiferrogmanetic nearest neighbor exchange J=1.","category":"page"},{"location":"examples/spinw/08_Kagome_AFM.html","page":"Tutorial 8 - Kagome Antiferromagnet","title":"Tutorial 8 - Kagome Antiferromagnet","text":"S = 1\nsys = System(crystal, (3,3,1), [SpinInfo(1; S, g=2)], :dipole)\nJ = 1.0\nset_exchange!(sys, J, Bond(2,3,[0,0,0]))","category":"page"},{"location":"examples/spinw/08_Kagome_AFM.html","page":"Tutorial 8 - Kagome Antiferromagnet","title":"Tutorial 8 - Kagome Antiferromagnet","text":"Initialize to an energy minimizing magnetic structure, for which nearest-neighbor spins are at 120° angles.","category":"page"},{"location":"examples/spinw/08_Kagome_AFM.html","page":"Tutorial 8 - Kagome Antiferromagnet","title":"Tutorial 8 - Kagome Antiferromagnet","text":"q = -[1/3, 1/3, 0]\naxis = [0,0,1]\nset_spiral_order_on_sublattice!(sys, 1; q, axis, S0=[cos(0),sin(0),0])\nset_spiral_order_on_sublattice!(sys, 2; q, axis, S0=[cos(0),sin(0),0])\nset_spiral_order_on_sublattice!(sys, 3; q, axis, S0=[cos(2π/3),sin(2π/3),0])\nplot_spins(sys; dims=2)","category":"page"},{"location":"examples/spinw/08_Kagome_AFM.html","page":"Tutorial 8 - Kagome Antiferromagnet","title":"Tutorial 8 - Kagome Antiferromagnet","text":"Check energy. Each site participates in 4 bonds with energy JS^2cos(2π3). Factor of 1/2 avoids double counting.","category":"page"},{"location":"examples/spinw/08_Kagome_AFM.html","page":"Tutorial 8 - Kagome Antiferromagnet","title":"Tutorial 8 - Kagome Antiferromagnet","text":"@assert energy_per_site(sys) ≈ (4/2)*J*S^2*cos(2π/3)","category":"page"},{"location":"examples/spinw/08_Kagome_AFM.html","page":"Tutorial 8 - Kagome Antiferromagnet","title":"Tutorial 8 - Kagome Antiferromagnet","text":"Define a path in reciprocal space.","category":"page"},{"location":"examples/spinw/08_Kagome_AFM.html","page":"Tutorial 8 - Kagome Antiferromagnet","title":"Tutorial 8 - Kagome Antiferromagnet","text":"points_rlu = [[-1/2, 0, 0], [0, 0, 0], [1/2, 1/2, 0]]\ndensity = 100\npath, xticks = reciprocal_space_path(crystal, points_rlu, density);\nnothing #hide","category":"page"},{"location":"examples/spinw/08_Kagome_AFM.html","page":"Tutorial 8 - Kagome Antiferromagnet","title":"Tutorial 8 - Kagome Antiferromagnet","text":"Calculate discrete intensities","category":"page"},{"location":"examples/spinw/08_Kagome_AFM.html","page":"Tutorial 8 - Kagome Antiferromagnet","title":"Tutorial 8 - Kagome Antiferromagnet","text":"swt = SpinWaveTheory(sys)\nformula = intensity_formula(swt, :perp; kernel=delta_function_kernel)\ndisp, intensity = intensities_bands(swt, path, formula);\nnothing #hide","category":"page"},{"location":"examples/spinw/08_Kagome_AFM.html","page":"Tutorial 8 - Kagome Antiferromagnet","title":"Tutorial 8 - Kagome Antiferromagnet","text":"Plot over a restricted color range from [0,1e-2]. Note that the intensities of the flat band at zero-energy are off-scale.","category":"page"},{"location":"examples/spinw/08_Kagome_AFM.html","page":"Tutorial 8 - Kagome Antiferromagnet","title":"Tutorial 8 - Kagome Antiferromagnet","text":"fig = Figure()\nax = Axis(fig[1,1]; xlabel=\"Momentum (r.l.u.)\", ylabel=\"Energy (meV)\", xticks, xticklabelrotation=π/6)\nylims!(ax, -1e-1, 2.3)\nfor i in axes(disp, 2)\n lines!(ax, 1:length(disp[:,i]), disp[:,i]; color=intensity[:,i], colorrange=(0,1e-2))\nend\nfig","category":"page"},{"location":"renormalization.html#Interaction-Strength-Renormalization","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"","category":"section"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"A unique feature of Sunny is its support for building classical models where quantum spin is represented as an N-level system, rather than just an expected dipole. This generalization can be important when modeling quantum spin Hamiltonians that include, e.g., a single-ion anisotropy, or a biquadratic coupling between sites. Sunny also supports constraining quantum spin to the space of pure dipoles; in this case, Sunny will automatically perform an interaction strength renormalization that maximizes accuracy.","category":"page"},{"location":"renormalization.html#Local-operators","page":"Interaction Strength Renormalization","title":"Local operators","text":"","category":"section"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"A quantum spin-S state has N = 2S + 1 levels. Each local spin operator hatS^xyz is faithfully represented as an NN matrix. These matrices can be accessed using spin_matrices for a given label S. For example, the Pauli matrices are associated with S = 12.","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"When S 12, it is possible to construct multipole moments beyond the spin-dipole. For example,","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"S = spin_matrices(3/2)\n@assert S[3] ≈ diagm([3/2, 1/2, -1/2, -3/2])\n@assert S[3]^2 ≈ diagm([9/4, 1/4, 1/4, 9/4])","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"If the operator -S[3]^2 is passed to set_onsite_coupling!, it would set an easy-axis anisotropy in the hatz direction.","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"Any Hermitian operator can be expanded in the basis of Stevens operators hatmathcalO_kq up to a constant shift. To see this expansion, use print_stevens_expansion:","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"print_stevens_expansion((S[1]^2 + S[2]^2)) # Prints -(1/3)𝒪₂₀ + 5/2","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"Alternatively, the same operator could have been constructed directly from stevens_matrices:","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"O = stevens_matrices(3/2)\n@assert S[1]^2 + S[2]^2 ≈ -O[2, 0]/3 + (5/2)*I","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"See below for an explicit definition of Stevens operators as polynomials of the spin operators.","category":"page"},{"location":"renormalization.html#Renormalization-procedure-for-:dipole-mode","page":"Interaction Strength Renormalization","title":"Renormalization procedure for :dipole mode","text":"","category":"section"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"Sunny will typically operate in one of two modes: :SUN or :dipole. The former faithfully represents quantum spin as an SU(N) coherent-state which, for our purposes, is an N-component complex vector. In contrast, :dipole mode constrains the coherent-state to the space of pure dipoles. Here, Sunny will automatically renormalize the magnitude of each Stevens operator to achieve maximal consistency with :SUN mode. This procedure was derived in D. Dahlbom et al., [arXiv:2304.03874].","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"By way of illustration, consider a quantum operator hatmathcalH_mathrmlocal giving a single-ion anisotropy for one site. In Stevens operators,","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"hatmathcal H_mathrmlocal = sum_k q A_kq hatmathcalO_kq","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"for some coefficients A_kq.","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"In :SUN mode, Sunny will faithfully represent hatmathcal H_mathrmlocal as an NN matrix. In :dipole mode, the expected energy langle hatmathcal H_mathrmlocal rangle must somehow be approximated as a function of the expected dipole mathbfs.","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"One approach is to formally take S to infty, and this yields the traditional classical limit of a spin system. In this, limit spin operators commute, and expectation values of polynomials become polynomials of expectation values. For example, langle hatS^alpha hatS^betarangle to langle hatS^alpha rangle langle hatS^betarangle, because any corrections are damped by the factor S^-1 to 0. The expectation of a Stevens operator langle hatmathcalO_kq rangle becomes a Stevens function mathcalO_kq(mathbfs), i.e., a polynomial of expected dipole mathbfs = langle hatmathbfS rangle.","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"In a real magnetic compound, however, the spin magnitude S is not necessarily large. To obtain a better approximation, one should avoid the assumption S to infty. Our approach is to start with the full dynamics of SU(N) coherent states, and then constrain it to the space of pure dipole states mathbfsrangle. The latter are defined such that expectation values,","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"langle mathbfs hatmathbfS mathbfsrangle = mathbfs","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"have magnitude mathbfs = S, which is maximal.","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"For pure dipole states, expectations can be computed exactly,","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"langle mathbfs hatmathcalO mathbfsrangle = c_k mathcalO_kq(mathbfs)","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"The right-hand side involves a renormalization of the Stevens functions, where","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"beginalign*\nc_1 = 1 \nc_2 = 1-frac12S^-1 \nc_3 = 1-frac32S^-1+frac12S^-2 \nc_4 = 1-3S^-1+frac114S^-2-frac34S^-3 \nc_5 = 1-5S^-1+frac354S^-2-frac254S^-3+frac32S^-4 \nc_6 = 1-frac152S^-1+frac854S^-2-frac2258S^-3+frac1378S^-4-frac154S^-5 \nvdots\nendalign*","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"Constrained to the space of dipoles, the expected local energy becomes","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"E_mathrmlocal(mathbfs) = langle mathbfs hatmathcal H_mathrmlocal mathbfsrangle = sum_k q c_k A_kq mathcalO_kq(mathbfs)","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"It can be shown that SU(N) dynamics reduces to the usual Landau-Lifshitz dynamics of dipoles, but involving E_mathrmlocal(mathbfs) as the classical Hamiltonian. Through the renormalization factors c_k, Sunny avoids the large-S assumption, and gives a more accurate result.","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"Renormalization also applies to the coupling between different sites. In Sunny, couplings will often be expressed as a polynomial of spin operators using set_pair_coupling!, but any such coupling can be decomposed as sum of tensor products of Stevens operators. Without loss of generality, consider a single coupling between two Stevens operators hatmathcalH_mathrmcoupling = hatmathcalO_kq otimes hatmathcalO_kq along a bond connecting sites i and j. Upon constraining to pure dipole states mathbfs_irangle and mathbfs_jrangle, the expected energy takes the form E_mathrmcoupling = c_k c_k mathcalO_kq(mathbfs_i) mathcalO_kq(mathbfs_j), which now involves a product of renormalized Stevens functions. ","category":"page"},{"location":"renormalization.html#Use-:dipole_large_S-mode-to-disable-renormalization","page":"Interaction Strength Renormalization","title":"Use :dipole_large_S mode to disable renormalization","text":"","category":"section"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"Although we generally recommend the above renormalization procedure, there are circumstances where it is not desirable. Examples include reproducing a model-system study, or describing a micromagnetic system for which the Stoinfty limit is a good approximation. To simulate dipoles without interaction strength renormalization, construct a System using the mode :dipole_large_S. Symbolic operators in the large-S limit can be constructed by passing Inf to either spin_matrices or stevens_matrices.","category":"page"},{"location":"renormalization.html#Definition-of-Stevens-operators","page":"Interaction Strength Renormalization","title":"Definition of Stevens operators","text":"","category":"section"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"The Stevens operators hatmathcalO_kq are defined as polynomials of angular momentum operators hatS_xyz in some spin-S representation.","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"Using","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"beginalign*\nX = mathbfhatS cdot mathbfhatS = S (S+1) \nhatS_pm = hatS_x pm i hatS_y \nphi_+ = frac14quad phi_- = frac14 i\nendalign*","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"the relevant Stevens operators are defined as,","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"beginalign*\nhatmathcalO_00 =1\n\nhatmathcalO_1pm1 =phi_pm(hatS_+pmhatS_-)+mathrmhc\nhatmathcalO_10 =hatS_z\n\nhatmathcalO_2pm2 =phi_pm(hatS_+^2pmhatS_-^2)+mathrmhc\nhatmathcalO_2pm1 =phi_pm(hatS_+pmhatS_-)hatS_z+mathrmhc\nhatmathcalO_20 =3hatS_z^2-X\n\nhatmathcalO_3pm3 =phi_pm(hatS_+^3pmhatS_-^3)+mathrmhc\nhatmathcalO_3pm2 =phi_pm(hatS_+^2pmhatS_-^2)hatS_z+mathrmhc\nhatmathcalO_3pm1 =phi_pm(hatS_+pmhatS_-)(5hatS_z^2-X-12)+mathrmhc\nhatmathcalO_30 =5hatS_z^3-(3X-1)hatS_z\n\nhatmathcalO_4pm4 =phi_pm(hatS_+^4pmhatS_-^4)+mathrmhc\nhatmathcalO_4pm3 =phi_pm(hatS_+^3pmhatS_-^3)hatS_z+mathrmhc\nhatmathcalO_4pm2 =phi_pm(hatS_+^2pmhatS_-^2)(7hatS_z^2-(X+5))+mathrmhc\nhatmathcalO_4pm1 =phi_pm(hatS_+pmhatS_-)(7hatS_z^3-(3X+1)hatS_z)+mathrmhc\nhatmathcalO_40 =35hatS_z^4-(30X-25)hatS_z^2+(3X^2-6X)\n\nhatmathcalO_5pm5 =phi_pm(hatS_+^5pmhatS_-^5)+mathrmhc\nhatmathcalO_5pm4 =phi_pm(hatS_+^4pmhatS_-^4)hatS_z+mathrmhc\nhatmathcalO_5pm3 =phi_pm(hatS_+^3pmhatS_-^3)(9hatS_z^2-(X+332))+mathrmhc\nhatmathcalO_5pm2 =phi_pm(hatS_+^2pmhatS_-^2)(3hatS_z^3-(X+6)hatS_z)+mathrmhc\nhatmathcalO_5pm1 =phi_pm(hatS_+pmhatS_-)(21hatS_z^4-14XhatS_z^2+(X^2-X+32))+mathrmhc\nhatmathcalO_50 =63hatS_z^5-(70X-105)hatS_z^3+(15X^2-50X+12)hatS_z\n\nhatmathcalO_6pm6 =phi_pm(hatS_+^6pmhatS_-^6)+mathrmhc\nhatmathcalO_6pm5 =phi_pm(hatS_+^5pmhatS_-^5)hatS_z+mathrmhc\nhatmathcalO_6pm4 =phi_pm(hatS_+^4pmhatS_-^4)(11hatS_z^2-X-38)+mathrmhc\nhatmathcalO_6pm3 =phi_pm(hatS_+^3pmhatS_-^3)(11hatS_z^3-(3X+59)hatS_z)+mathrmhc\nhatmathcalO_6pm2 =phi_pm(hatS_+^2pmhatS_-^2)(33hatS_z^4-(18X+123)hatS_z^2+X^2+10X+102)+mathrmhc\nhatmathcalO_6pm1 =phi_pm(hatS_+pmhatS_-)(33hatS_z^5-(30X-15)hatS_z^3+(5X^2-10X+12)hatS_z)+mathrmhc\nhatmathcalO_60 =231hatS_z^6-(315X-735)hatS_z^4+(105X^2-525X+294)hatS_z^2-5X^3+40X^2-60X\nendalign*","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"Computer-generated tables of Stevens operators with k 6 are available from C. Rudowicz and C. Y. Chung, J. Phys.: Condens. Matter 16, 5825 (2004), but these typically do not appear in magnetic simulations.","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"The case k=1 gives the dipole operators,","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"(hatmathcalO_11 hatmathcalO_10 hatmathcalO_1-1) = (hatS_x hatS_z hatS_y)","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"The case k=2 gives the quadrupole operators,","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"(hatmathcalO_22 dots hatmathcalO_2-2) = left(hatS_x^2 - hatS_y^2 frachatS_x hatS_z + hatS_z hatS_x2 2hatS_z^2-hatS_x^2-hatS_y^2 frachatS_y hatS_z + hatS_z hatS_y2 hatS_x hatS_y + hatS_y hatS_xright)","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"For each k value, the set of operators hatmathcalO_kq for q = -k dots k form an irreducible representation of the group of rotations O(3). That is, rotation will transform hatmathcalO_kq into a linear combination of hatmathcalO_kq where q varies but k remains fixed. ","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"In taking the large-S limit, each dipole operator is replaced by its expectation value mathbfs = langle hatmathbfS rangle, and only leading-order terms are retained. The operator hatmathcalO_kq becomes a homogeneous polynomial O_kq(mathbfs) of order k in the spin components. One can see these polynomials by constructing stevens_matrices with the argument S = Inf. Due to the normalization constraint, each dipole can be expressed in polar angles, (theta phi). Then the Stevens functions O_kq(mathbfs) correspond to the spherical harmonic functions Y_l^m(theta phi) where l=k and m=q; this correspondence is valid up to k and q-dependent rescaling factors.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"EditURL = \"../../../examples/fei2_classical.jl\"","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"Download this example as Jupyter notebook or Julia script.","category":"page"},{"location":"examples/fei2_classical.html#FeI-at-Finite-Temperature","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"","category":"section"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"using Sunny, LinearAlgebra, GLMakie","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"In our previous Case Study: FeI₂, we used linear spin wave theory (LSWT) to calculate the dynamical structure factor. Here, we perform a similar calculation using classical spin dynamics. Because we are interested in the coupled dynamics of spin dipoles and quadrupoles, we employ a classical dynamics of SU(3) coherent states that generalizes the Landau-Lifshitz equation.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"Compared to LSWT, simulations using classical dynamics are much slower, and are limited in k-space resolution. However, they make it is possible to capture nonlinear effects associated with finite temperature fluctuations. Classical dynamics are also appealing for studying out-of-equilibrium systems (e.g., relaxation of spin glasses), or systems with quenched inhomogeneities that require large simulation volumes.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"In this tutorial, we show how to study the finite temperature dynamics of FeI₂ using the classical approach. It is important to stress that the estimation of S(𝐪ω) with classical dynamics is fundamentally a Monte Carlo calculation: sample spin configurations are drawn from thermal equilibrium and used as initial conditions for generating dissipationless trajectories. The correlations of these trajectories are then averaged and used to calculate scattering intensities. It is therefore important to ensure that the initial spin configurations are sampled appropriately and that sufficient statistics are collected. We will demonstrate one approach here.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"As an overview, we will:","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"Identify the ground state\nMeasure correlation data describing the excitations around that ground state\nUse the correlation data to compute scattering intensities","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"As the implementation of the FeI₂ model is already covered in detail in the LSWT tutorial, we will not repeat it below. Instead, we will assume that you already have defined a sys in the same way with lattice dimensions 444.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"a = b = 4.05012#hide\nc = 6.75214#hide\nlatvecs = lattice_vectors(a, b, c, 90, 90, 120)#hide\npositions = [[0,0,0], [1/3, 2/3, 1/4], [2/3, 1/3, 3/4]]#hide\ntypes = [\"Fe\", \"I\", \"I\"]#hide\nFeI2 = Crystal(latvecs, positions; types)#hide\ncryst = subcrystal(FeI2, \"Fe\")#hide\nsys = System(cryst, (4,4,4), [SpinInfo(1,S=1,g=2)], :SUN, seed=2)#hide\nJ1pm = -0.236#hide\nJ1pmpm = -0.161#hide\nJ1zpm = -0.261#hide\nJ2pm = 0.026#hide\nJ3pm = 0.166#hide\nJ′0pm = 0.037#hide\nJ′1pm = 0.013#hide\nJ′2apm = 0.068#hide\nJ1zz = -0.236#hide\nJ2zz = 0.113#hide\nJ3zz = 0.211#hide\nJ′0zz = -0.036#hide\nJ′1zz = 0.051#hide\nJ′2azz = 0.073#hide\nJ1xx = J1pm + J1pmpm#hide\nJ1yy = J1pm - J1pmpm#hide\nJ1yz = J1zpm#hide\nset_exchange!(sys, [J1xx 0.0 0.0; 0.0 J1yy J1yz; 0.0 J1yz J1zz], Bond(1,1,[1,0,0]))#hide\nset_exchange!(sys, [J2pm 0.0 0.0; 0.0 J2pm 0.0; 0.0 0.0 J2zz], Bond(1,1,[1,2,0]))#hide\nset_exchange!(sys, [J3pm 0.0 0.0; 0.0 J3pm 0.0; 0.0 0.0 J3zz], Bond(1,1,[2,0,0]))#hide\nset_exchange!(sys, [J′0pm 0.0 0.0; 0.0 J′0pm 0.0; 0.0 0.0 J′0zz], Bond(1,1,[0,0,1]))#hide\nset_exchange!(sys, [J′1pm 0.0 0.0; 0.0 J′1pm 0.0; 0.0 0.0 J′1zz], Bond(1,1,[1,0,1]))#hide\nset_exchange!(sys, [J′2apm 0.0 0.0; 0.0 J′2apm 0.0; 0.0 0.0 J′2azz], Bond(1,1,[1,2,1]))#hide\nD = 2.165#hide\nset_onsite_coupling!(sys, S -> -D*S[3]^2, 1)#hide\nsys","category":"page"},{"location":"examples/fei2_classical.html#Finding-a-ground-state","page":"FeI₂ at Finite Temperature","title":"Finding a ground state","text":"","category":"section"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"Sunny uses the Langevin dynamics of SU(N) coherent states to sample spin configurations from the thermal equlibrium. One first constructs a Langevin integrator. This requires a time step, temperature, and a phenomenological damping parameter λ that sets the coupling to the thermal bath.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"Δt = 0.05/D # Should be inversely proportional to the largest energy scale\n # in the system. For FeI2, this is the easy-axis anisotropy,\n # `D = 2.165` (meV). The prefactor 0.05 is relatively small,\n # and achieves high accuracy.\nkT = 0.2 # Temperature of the thermal bath (meV).\nλ = 0.1 # This value is typically good for Monte Carlo sampling,\n # independent of system details.\n\nlangevin = Langevin(Δt; kT, λ);\nnothing #hide","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"Langevin dynamics can be used to search for a magnetically ordered state. For this, the temperature kT must be below the ordering temperature, but large enough that the dynamical sampling procedure can overcome local energy barriers and eliminate defects.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"randomize_spins!(sys)\nfor _ in 1:20_000\n step!(sys, langevin)\nend","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"Although thermal fluctuations are present, the correct antiferromagnetic order (2 up, 2 down) is apparent.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"plot_spins(sys; color=[s[3] for s in sys.dipoles])","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"For other systems, it can be much harder to find the magnetic ordering in an unbiased way, and more complicated sampling procedures may be necessary.","category":"page"},{"location":"examples/fei2_classical.html#Calculating-Thermal-Averaged-Correlations-\\langle-S{\\alpha\\beta}(𝐪,ω)\\rangle","page":"FeI₂ at Finite Temperature","title":"Calculating Thermal-Averaged Correlations langle S^alphabeta(𝐪ω)rangle","text":"","category":"section"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"Our aim is to study the classical spin dynamics for states sampled in thermal equilibrium. To minimize finite size effects, and achieve sufficient momentum space resolution, we should significantly enlarge the system volume. The function resize_supercell takes new dimensions as multiples of the unit cell lattice vectors.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"sys_large = resize_supercell(sys, (16,16,4)) # 16x16x4 copies of the original unit cell\nplot_spins(sys_large; color=[s[3] for s in sys_large.dipoles])","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"Now we will re-thermalize the system to a configuration just above the ordering temperature. Sunny expects energies in meV by default, so we use meV_per_K to convert from kelvin.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"kT = 3.5 * meV_per_K # 3.5K ≈ 0.30 meV\nlangevin.kT = kT\nfor _ in 1:10_000\n step!(sys_large, langevin)\nend","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"The next step is to collect correlation data S^alphabeta. This will involve sampling spin configurations from thermal equilibrium, and then integrating the Hamiltonian dynamics of SU(N) coherent states to collect Fourier-space information about normal modes. Quantization of these modes yields the magnons, and the associated dynamical spin-spin correlations can be compared with neutron scattering intensities S^alphabeta(qomega). Because this a real-space calculation, data is only available for discrete q modes (the resolution scales like inverse system size).","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"To store the correlation data, we initialize a SampledCorrelations object by calling dynamical_correlations. It requires three keyword arguments: an integration step size, a target number of ωs to retain, and a maximum energy ω to resolve. For the time step, twice the value used for the Langevin integrator is usually a good choice.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"sc = dynamical_correlations(sys_large; Δt=2Δt, nω=120, ωmax=7.5)","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"The function add_sample! will collect data by running a dynamical trajectory starting from the current system configuration.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"add_sample!(sc, sys_large) # Accumulate the sample into `sc`","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"To collect additional data, it is required to re-sample the spin configuration from the thermal distribution. For efficiency, the dynamics should be run long enough that consecutive samples are uncorrelated.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"for _ in 1:2\n for _ in 1:1000 # Enough steps to decorrelate spins\n step!(sys_large, langevin)\n end\n add_sample!(sc, sys_large) # Accumulate the sample into `sc`\nend","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"Now, sc has more samples included:","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"sc","category":"page"},{"location":"examples/fei2_classical.html#Computing-Scattering-Intensities","page":"FeI₂ at Finite Temperature","title":"Computing Scattering Intensities","text":"","category":"section"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"With the thermally-averaged correlation data langle S^alphabeta(qomega)rangle in hand, we now need to specify how to extract a scattering intensity from this information. This is done by constructing an intensity_formula. By way of example, we will use a formula which computes the trace of the structure factor and applies a classical-to-quantum temperature-dependent rescaling kT.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"formula = intensity_formula(sc, :trace; kT)","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"Recall that langle S^alphabeta(qomega)rangle is only available at certain discrete q values, due to the finite lattice size. There are two basic approaches to handling this discreteness. The first approach is to interpolate between the available data using intensities_interpolated. For example, we can plot single-q slices at (0,0,0) and (π,π,π) using this method:","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"qs = [[0, 0, 0], [0.5, 0.5, 0.5]]\nis = intensities_interpolated(sc, qs, formula; interpolation = :round)\n\nωs = available_energies(sc)\nfig = lines(ωs, is[1,:]; axis=(xlabel=\"meV\", ylabel=\"Intensity\"), label=\"(0,0,0)\")\nlines!(ωs, is[2,:]; label=\"(π,π,π)\")\naxislegend()\nfig","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"The resolution in energy can be improved by increasing nω (and decreasing Δt), and the general accuracy can be improved by collecting additional samples from the thermal equilibrium.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"For real calculations, one often wants to apply further corrections and more accurate formulas. Here, we apply FormFactor corrections appropriate for Fe2 magnetic ions, and a dipole polarization correction :perp.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"formfactors = [FormFactor(\"Fe2\"; g_lande=3/2)]\nnew_formula = intensity_formula(sc, :perp; kT, formfactors = formfactors)","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"Frequently, one wants to extract energy intensities along lines that connect special wave vectors–a so-called \"spaghetti plot\". The function reciprocal_space_path creates an appropriate horizontal axis for this plot by linearly sampling between provided q-points with a given sample density. The number of sample points between two wavevectors q1 and q2 is given by dist*density where dist = norm(cryst.recipvecs * (q1 - q2)) is measured in the global frame.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"points = [[0, 0, 0], # List of wave vectors that define a path\n [1, 0, 0],\n [0, 1, 0],\n [1/2, 0, 0],\n [0, 1, 0],\n [0, 0, 0]]\ndensity = 40\npath, xticks = reciprocal_space_path(cryst, points, density);\nnothing #hide","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"Again using intensities_interpolated, we can evaluate the (interpolated) intensity at each point on the path. Since scattering intensities are only available at a certain discrete (Qomega) points, the intensity on the path can be calculated by interpolating between these discrete points:","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"is_interpolated = intensities_interpolated(sc, path, new_formula;\n interpolation = :linear, # Interpolate between available wave vectors\n);\n# Add artificial broadening\nis_interpolated_broadened = broaden_energy(sc, is, (ω, ω₀)->lorentzian(ω-ω₀, 0.05));\nnothing #hide","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"The second approach to handle the discreteness of the data is to bin the intensity at the discrete points into the bins of a histogram. First, the five sub-histograms are set up using reciprocal_space_path_bins in analogy to reciprocal_space_path.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"cut_width = 0.3\ndensity = 15\nparamsList, markers, ranges = reciprocal_space_path_bins(sc,points,density,cut_width);\nnothing #hide","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"Then, the intensity data is computed using intensities_binned for each sub-histogram:","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"total_bins = ranges[end][end]\nenergy_bins = paramsList[1].numbins[4]\nis_binned = zeros(Float64,total_bins,energy_bins)\nintegrated_kernel = integrated_lorentzian(0.05) # Lorentzian broadening\nfor k in eachindex(paramsList)\n bin_data, counts = intensities_binned(sc,paramsList[k], new_formula;\n integrated_kernel = integrated_kernel\n )\n is_binned[ranges[k],:] = bin_data[:,1,1,:] ./ counts[:,1,1,:]\nend","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"The graph produced by interpolating (top) is similar to the one produced by binning (bottom):","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"fig = Figure()\nax_top = Axis(fig[1,1],ylabel = \"meV\",xticklabelrotation=π/8,xticklabelsize=12;xticks)\nax_bottom = Axis(fig[2,1],ylabel = \"meV\",xticks = (markers, string.(points)),xticklabelrotation=π/8,xticklabelsize=12)\n\nheatmap!(ax_top,1:size(is_interpolated,1), ωs, is_interpolated;\n colorrange=(0.0,0.07),\n)\n\nheatmap!(ax_bottom,1:size(is_binned,1), ωs, is_binned;\n colorrange=(0.0,0.05),\n)\n\nfig","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"Note that we have clipped the colors in order to make the higher-energy excitations more visible.","category":"page"},{"location":"examples/fei2_classical.html#Unconventional-RLU-Systems-and-Constant-Energy-Cuts","page":"FeI₂ at Finite Temperature","title":"Unconventional RLU Systems and Constant Energy Cuts","text":"","category":"section"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"Often it is useful to plot cuts across multiple wave vectors but at a single energy. We'll pick an energy,","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"ωidx = 60\ntarget_ω = ωs[ωidx]","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"and take a constant-energy cut at that energy. The most straightforward way is to make a plot whose axes are aligned with the conventional reciprocal lattice of the crystal. This is accomplished using unit_resolution_binning_parameters:","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"params = unit_resolution_binning_parameters(sc)\nparams.binstart[1:2] .= -1 # Expand plot range slightly\n\n# Set energy integration range\nomega_width = 0.3\nparams.binstart[4] = target_ω - (omega_width/2)\nparams.binend[4] = target_ω # `binend` should be inside (e.g. at the center) of the range\nparams.binwidth[4] = omega_width\n\nintegrate_axes!(params, axes = 3) # Integrate out z direction entirely\n\nparams","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"In each of the following plots, black dashed lines represent (direct) lattice vectors. Since these plots are in reciprocal space, direct lattice vectors are represented as covectors (i.e. coordinate grids) instead of as arrows.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"is, counts = intensities_binned(sc,params,new_formula)\n\nfig = Figure()\nax = Axis(fig[1,1];\n title=\"Δω=0.3 meV (Binned)\", aspect=true,\n xlabel = \"[H, 0, 0]\",\n ylabel = \"[0, K, 0]\"\n)\nbcs = axes_bincenters(params)\nhm = heatmap!(ax,bcs[1],bcs[2],is[:,:,1,1] ./ counts[:,:,1,1])\nfunction add_lines!(ax,params)#hide\n bes = Sunny.axes_binedges(params)#hide\n hrange = range(-2,2,length=17)#hide\n linesegments!(ax,[(Point2f(params.covectors[1,1:3] ⋅ [h,-10,0],params.covectors[2,1:3] ⋅ [h,-10,0]),Point2f(params.covectors[1,1:3] ⋅ [h,10,0],params.covectors[2,1:3] ⋅ [h,10,0])) for h = hrange],linestyle=:dash,color=:black)#hide\n krange = range(-2,2,length=17)#hide\n linesegments!(ax,[(Point2f(params.covectors[1,1:3] ⋅ [-10,k,0],params.covectors[2,1:3] ⋅ [-10,k,0]),Point2f(params.covectors[1,1:3] ⋅ [10,k,0],params.covectors[2,1:3] ⋅ [10,k,0])) for k = krange],linestyle=:dash,color=:black)#hide\n xlims!(ax,bes[1][1],bes[1][end])#hide\n ylims!(ax,bes[2][1],bes[2][end])#hide\nend#hide\nadd_lines!(ax,params)\nColorbar(fig[1,2], hm);\nfig","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"In the above plot, the dashed-line (direct) lattice vectors are clearly orthogonal. However, we know that in real space, the lattice vectors a and b are not orthogonal, but rather point along the edges of a hexagon (see lower left corner):","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"

    ","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"Thus, plotting the direct lattice vectors as orthogonal (even in reciprocal space) is somewhat misleading. Worse yet, the [H,0,0] by [0,K,0] plot apparently loses the 6-fold symmetry of the crystal! Lastly, if one works out the components of the real-space metric with respect to the axes of the plot, one finds that there are non-zero off-diagonal entries,","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"latvecs = sys.crystal.latvecs\nmetric = latvecs' * I(3) * latvecs","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"so real-space rotations and angles map into reciprocal space rotations angles in a complicated way.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"To resolve these important issues, we want to use axes which are orthogonal (i.e. they diagonalize the metric and solve all of the problems just mentioned). The canonical choice is to use the combination frac12a + b of lattice vectors (equiv. a^* - frac12b^*), which is orthogonal to a:","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"(latvecs * [1/2,1,0]) ⋅ (latvecs * [1,0,0]) == 0","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"This new vector frac12a+b is visibly orthogonal to a in real space:","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"f = Figure()#hide\nax = Axis(f[1,1])#hide\narrows!(ax,[Point2f(0,0),Point2f(latvecs[1:2,1] ./ 2)],[Vec2f(latvecs[1:2,1] ./ 2), Vec2f(latvecs[1:2,2])],arrowcolor = :blue,arrowsize = 30.,linewidth = 5.,linecolor = :blue)#hide\narrows!(ax,[Point2f(0,0)],[Vec2f(latvecs[1:2,:] * [1/2,1,0])],arrowcolor = :red,arrowsize = 30.,linewidth = 5.,linecolor = :red, linestyle = :dash)#hide\nscatter!(ax,[Point2f(latvecs[1:2,:] * [a,b,0]) for a in -1:1, b in -1:1][:],color = :black)#hide\nannotations!(ax,[\"0\",\"0+b\",\"0+a\", \"a/2\", \"b\"],[Point2f(0,-0.3),Point2f(latvecs[1:2,2]) .- Vec2f(0,0.3),Point2f(latvecs[1:2,1]) .- Vec2f(0,0.3),Point2f(latvecs[1:2,1] ./ 4) .- Vec2f(0,0.3),Point2f(latvecs[1:2,1] ./ 2) .+ Vec2f(latvecs[1:2,2] ./ 2) .+ Vec2f(0.3,0.3)],color=[:black,:black,:black,:blue,:blue])#hide\nf#hide","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"To use \"projection onto the new vector\" as a histogram axis, only a single change is needed to the binning parameters. The second covector (previously b) must be swapped out for frac12a + b (recall that reciprocal space covectors, such as those used in BinningParameters correspond to direct space vectors).","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"params.covectors[2,1:3] = [1/2,1,0] # [1/2,1,0] times [a;b;c] is (a/2 + b)\nparams#hide","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"The second axis of the histogram now agrees with what is conventionally labelled as [H,-H/2,0].","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"warning: Length of the new vector\nNote that, although frac12a+b is orthogonal to a, it is not the same length as a. Instead, it is sqrt(3/4) times as long. Note the unsymmetrical axes labels in the plots that follow as a direct result of this!","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"# Zoom out horizontal axis\nparams.binstart[1], params.binend[1] = -2, 2\n\n# Adjust vertical axis bounds to account for\n# length of a/2 + b\nparams.binstart[2], params.binend[2] = -2 * sqrt(3/4), 2 * sqrt(3/4)\n\n# Re-compute in the new coordinate system\nis, counts = intensities_binned(sc,params,new_formula)\n\nfig = Figure(; resolution=(1200,500))#hide\nax_right = Axis(fig[1,3];#hide\n title=\"ω≈$(round(target_ω, digits=2)) meV with Δω=0.3 meV (Binned)\", aspect=true,#hide\n xlabel = \"[H, -1/2H, 0]\"#hide\n)#hide\nbcs = axes_bincenters(params)#hide\nhm_right = heatmap!(ax_right,bcs[1],bcs[2],is[:,:,1,1] ./ counts[:,:,1,1])#hide\nadd_lines!(ax_right,params)\nColorbar(fig[1,4], hm_right);#hide\nnothing #hide","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"For comparison purposes, we will make the same plot using intensities_interpolated to emulate zero-width bins. This time, it's more convenient to think in terms of reciprocal vectors a^* and b^*. Now, our coordinate transformation consists of establishing a new, orthogonal basis to specify our wave vectors: a^* - frac12b^*, b^* and c^*. Writing this in matrix form allows us to sample a rectilinear grid of wave vectors in this frame. Finally, we'll convert these back into the original RLU system for input into Sunny.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"# New basis matrix\nA = [1 0 0\n -1/2 1 0\n 0 0 1]\n\n# Define our grid of wave vectors\nnpoints = 60\nas = range(-2, 2, npoints)\nbs = range(-3/√3, 3/√3, npoints)\nqs_ortho = [[a, b, 0] for a in as, b in bs]\n\n# Convert to original RLU system for input to Sunny\nqs = [A * q for q in qs_ortho]\n\n# Use interpolation to get intensities\nis = intensities_interpolated(sc, qs, new_formula; interpolation=:linear)\n\nax_left = Axis(fig[1,2];#hide\n title=\"ω≈$(round(ωs[ωidx], digits=2)) meV (Interpolated)\", aspect=true,#hide\n xlabel = \"[H, -1/2H, 0]\", ylabel = \"[0, K, 0]\"#hide\n)#hide\nhm_left = heatmap!(ax_left, as, bs, is[:,:,ωidx])#hide\nadd_lines!(ax_left,params)\nColorbar(fig[1,1], hm_left);#hide\nfig","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"Now, not only are the dashed-line lattice vectors no longer misleadingly orthogonal, but the six-fold symmetry has been restored as well! Further, the metric has been diagonalized:","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"metric = (latvecs * inv(A'))' * I(3) * (latvecs * inv(A'))","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"Finally, we note that instantaneous structure factor data, 𝒮(𝐪), can be obtained from a dynamic structure factor with instant_intensities_interpolated. Here we'll reuse the grid of wave vectors we generated above.","category":"page"},{"location":"examples/fei2_classical.html","page":"FeI₂ at Finite Temperature","title":"FeI₂ at Finite Temperature","text":"is_static = instant_intensities_interpolated(sc, qs, new_formula; interpolation = :linear)\n\nhm = heatmap(as, bs, is_static;\n axis=(\n title=\"Instantaneous Structure Factor\",\n xlabel = \"[H, -1/2H, 0]\",\n ylabel = \"[0, K, 0]\",\n aspect=true\n )\n)\nColorbar(hm.figure[1,2], hm.plot)\nhm","category":"page"},{"location":"versions.html#Version-History","page":"Version History","title":"Version History","text":"","category":"section"},{"location":"versions.html#v0.5.6","page":"Version History","title":"v0.5.6","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Animated spin dynamics is now possible. Call notify on the result of plot_spins to trigger redrawing of the frame. The argument colorfn to plot_spins supports animation of colors.\nGeneral pair couplings are now supported in set_pair_coupling! and set_pair_coupling_at!. :SUN supports interactions of any order, but :dipole mode is limited to bilinear and biquadratic coupling of the spin.\nTo perform a calculation with dipoles in the large-S limit, use the new mode :dipole_large_S when constructing a System.\nDeprecate the option biquad to set_exchange!. Use instead set_pair_coupling!, which generalizes beyond the scalar biquadratic.\nDeprecate spin_operators, stevens_operators, large_S_spin_operators and large_S_stevens_operators. Use instead spin_matrices and stevens_matrices, which require a specific spin-S label. To infer this, one can use spin_label.\nRemove unused option energy_tol in SpinWaveTheory.","category":"page"},{"location":"versions.html#v0.5.5","page":"Version History","title":"v0.5.5","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"reshape_supercell now allows reshaping to multiples of the primitive unit cell, which can speed up certain calculations. This is illustrated in the CoRh₂O₄ powder averaging tutorial.\nresize_supercell now allows all resizings.\nAdded energy_per_site.\nset_spiral_order_on_sublattice! cannot work on reshaped systems.\nVarious bug fixes. In particular, an intensity_formula with :full will now uniformly calculate a 3x3 matrix of complex numbers.","category":"page"},{"location":"versions.html#v0.5.4","page":"Version History","title":"v0.5.4","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Various enhancements to view_crystal. Atoms are now labeled by index, and bonds support interactive inspection (GLMakie only). Font sizes work correctly on Makie v0.20-beta. If using Makie v0.19 on a high-resolution display, pass rescale=1.5 to enlarge font sizes.\nThe function suggest_magnetic_supercell now requires only a list of wavevectors, and will return a 33 matrix that can be programmatically passed to reshape_supercell. The new tolerance parameter tol allows suggest_magnetic_supercell to approximate incommensurate wavevectors with nearby commensurate ones.\nNew functions set_spiral_order! and set_spiral_order_on_sublattice! can be used to initialize a spiral, single-Q order.\nSunny now retains all constant energy shifts that have been introduced by anisotropy operators.\nFix export_vtk functionality.","category":"page"},{"location":"versions.html#v0.5.3","page":"Version History","title":"v0.5.3","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Add large_S_spin_operators and large_S_stevens_operators to support single-ion anisotropies in dipole mode without renormalization. Set large_S=true in set_exchange! to avoid renormalization of biquadratics.\nview_crystal has been rewritten in Makie.\nplot_spins now expects ghost_radius in physical length units.\nSpinWaveTheory will (currently) error if provided a system with enable_dipole_dipole!.","category":"page"},{"location":"versions.html#v0.5.2","page":"Version History","title":"v0.5.2","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Form factors for 5d transition ions.\nDownload links for notebooks and scripts on each doc example\nVarious bug fixes.","category":"page"},{"location":"versions.html#v0.5.1","page":"Version History","title":"v0.5.1","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Fix binning edge cases.\nplot_spins accepts resolution argument.","category":"page"},{"location":"versions.html#v0.5.0","page":"Version History","title":"v0.5.0","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"New features.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Support for Linear Spin Wave Theory in :dipole and :SUN modes. (Thanks Hao Zhang!)","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"New function minimize_energy! to efficiently find an optimal configuration of spin dipoles or SU(N) coherent states.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Major refactors and enhancements to intensity calculations. This new interface allows unification between LSWT and classical spin dynamics calculations. This interface allows: Custom observables as local quantum operators, better support for linebroadening, and automatic binning to facilitate comparison with experimental data. See intensity_formula for documentation. Use load_nxs to load experimental neutron scattering data.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Breaking changes.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Require Julia 1.9.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Replace set_anisotropy! with a new function set_onsite_coupling! (and similarly set_onsite_coupling_at!). The latter expects an explicit matrix representation for the local Hamiltonian. This can be constructed, e.g., as a linear combination of stevens_operators, or as a polynomial of spin_operators. To understand the mapping between these two, the new function print_stevens_expansion acts on an arbitrary local operator.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Remove set_biquadratic!. Instead, use an optional keyword argument biquad to set_exchange!.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Rename DynamicStructureFactor to dynamical_correlations. Similarly, replace InstantStructureFactor with instant_correlations. The return type has been renamed SampledCorrelations to emphasize that the object may be holding thermodynamic samples, which are collected using add_sample!. Upon construction, the SampledCorrelations object will be empty (no initial sample).","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Remove intensities function. Instead, use one of intensities_interpolated or intensities_binned. These will require an intensity_formula, which defines a calculator (e.g., LSWT).","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Rename connected_path to reciprocal_space_path, which now returns an xticks object that can be used in plotting. Replace spherical_shell with reciprocal_space_shell that functions similarly.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Rename polarize_spin! to set_dipole! for consistency with set_coherent!. The behavior of the former function is unchanged: the spin at a given site will still be polarized along the provided direction.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Rename all_sites to eachsite consistent with Julia convention for iterators.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Rename reshape_geometry to reshape_supercell, which is the fundamental reshaping function. Rename resize_periodically to resize_supercell.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"The constructor SpinInfo now requires a g-factor or tensor as a named argument.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"The constructor FormFactor no longer accepts an atom index. Instead, the form factors are associated with site-symmetry classes in order of appearance.","category":"page"},{"location":"versions.html#v0.4.3","page":"Version History","title":"v0.4.3","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Experimental support for linear SpinWaveTheory, implemented in SU(N) mode. This module may evolve rapidly.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Implement renormalization of single-ion anisotropy and biquadratic interactions when in :dipole mode. This makes the model more faithful to the quantum mechanical Hamiltonian, but is also a breaking change.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Various improvements and bugfixes for to_inhomogeneous. Setting inhomogeneous interactions via set_exchange_at! should now infer the correct bond offset direction, or will report an ambiguity error. Ambiguities can be resolved by passing an explicit offset.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"The function remove_periodicity! disables periodicity along specified dimensions.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Rename StaticStructureFactor to InstantStructureFactor.","category":"page"},{"location":"versions.html#v0.4.2","page":"Version History","title":"v0.4.2","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Introduce LocalSampler, a framework for MCMC sampling with local spin updates.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Rename print_dominant_wavevectors to print_wrapped_intensities to reduce confusion with the physical instantaneous intensities.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"The function spherical_shell now takes a radius in physical units of inverse Å.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"New exported functions global_position, magnetic_moment, all_sites.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Remove all uses of Base.deepcopy which resolves crashes.","category":"page"},{"location":"versions.html#v0.4.1","page":"Version History","title":"v0.4.1","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"The function to_inhomogeneous creates a system that supports inhomogeneous interactions, which can be set using set_exchange_at!, etc.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"set_biquadratic! replaces set_exchange_with_biquadratic!.","category":"page"},{"location":"versions.html#v0.4.0","page":"Version History","title":"v0.4.0","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"This update includes many breaking changes, and is missing some features of 0.3.0.","category":"page"},{"location":"versions.html#Creating-a-spin-System","page":"Version History","title":"Creating a spin System","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Rename SpinSystem to System. Its constructor now has the form,","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"System(crystal, latsize, infos, mode)","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"The parameter infos is now a list of SpinInfo objects. Each defines spin angular momentum S = frac12 1 frac32 , and an optional g-factor or tensor.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"The parameter mode is one of :SUN or :dipole.","category":"page"},{"location":"versions.html#Setting-interactions","page":"Version History","title":"Setting interactions","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Interactions are now added mutably to an existing System using the following functions: set_external_field!, set_exchange!, set_onsite_coupling!, enable_dipole_dipole!.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"As a convenience, one can use dmvec(D) to convert a DM vector to a 33 antisymmetric exchange matrix.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Fully general single-ion anisotropy is now possible. The function set_onsite_coupling! expects the single ion anisotropy to be expressed as a polynomial in symbolic spin operators 𝒮, or as a linear combination of symbolic Stevens operators 𝒪. For example, an easy axis anisotropy in the direction n may be written D*(𝒮⋅n)^2.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Stevens operators 𝒪[k,q] admit polynomial expression in spin operators 𝒮[α]. Conversely, a polynomial of spin operators can be expressed as a linear combination of Stevens operators. To see this expansion use print_anisotropy_as_stevens.","category":"page"},{"location":"versions.html#Inhomogeneous-field","page":"Version History","title":"Inhomogeneous field","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"An external field can be applied to a single site with set_external_field_at!. ","category":"page"},{"location":"versions.html#Structure-factor-rewrite","page":"Version History","title":"Structure factor rewrite","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"The calculation of structure factors has been completely rewritten. For the new interface, see the FeI₂ at Finite Temperature page.","category":"page"},{"location":"versions.html#Various","page":"Version History","title":"Various","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"The \"Sampler\" interface is in flux. Langevin replaces both LangevinHeunP and LangevinSampler. Local spin-flip Monte Carlo sampling methods are temporarily broken.\nrepeat_periodically replaces extend_periodically.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Additional related functions include resize_periodically and reshape_geometry, the latter being fundamental.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"print_symmetry_table replaces print_bond_table().","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"The new function includes the list of symmetry-allowed single ion anisotropies in addition to exchange interactions.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"When reading CIF files, the field _atom_site_label is now used in place of the field _atom_site_type_symbol.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"This is required for correctness. The field _atom_site_label is guaranteed to be present, and is guaranteed to be a distinct label for each symmetry-inequivalent site. Code that explicitly referred to site labels (e.g. in calls to subcrystal) will need to be updated to use the new label.","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"EditURL = \"../../../../examples/spinw_ports/15_Ba3NbFe3Si2O14.jl\"","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"Download this example as Jupyter notebook or Julia script.","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html#Tutorial-15-BaNbFeSiO","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"","category":"section"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"This is a Sunny port of SpinW Tutorial 15, originally authored by Sandor Toth. The goal is to calculate the linear spin wave theory spectrum for Ba₃NbFe₃Si₂O₁₄.","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"Load packages","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"using Sunny, GLMakie","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"Build a Crystal for Ba₃NbFe₃Si₂O₁₄ using the crystal structure from Marty et al., Phys. Rev. Lett. 101, 247201 (2008).","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"a = b = 8.539 # (Å)\nc = 5.2414\nlatvecs = lattice_vectors(a, b, c, 90, 90, 120)\ntypes = [\"Fe\",\"Nb\",\"Ba\",\"Si\",\"O\",\"O\",\"O\"]\npositions = [[0.24964,0,0.5],[0,0,0],[0.56598,0,0],[2/3,1/3,0.5220],[2/3,1/3,0.2162],[0.5259,0.7024,0.3536],[0.7840,0.9002,0.7760]]\nlangasite = Crystal(latvecs, positions, 150; types)\ncrystal = subcrystal(langasite, \"Fe\")\nview_crystal(crystal, 7)","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"Create a System with a lattice size of (117). The magnetic structure of Ba₃NbFe₃Si₂O₁₄ was determined to have the ordering wavevector 𝐐=(0017) and hence the magnetic unit cell has 7 sites.","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"latsize = (1,1,7)\nS = 5/2\nseed = 5\nsys = System(crystal, latsize, [SpinInfo(1; S, g=2)], :dipole)","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"Set exchange interactions as parametrized in Loire et al., Phys. Rev. Lett. 106, 207201 (2011)","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"J₁ = 0.85\nJ₂ = 0.24\nJ₃ = 0.053\nJ₄ = 0.017\nJ₅ = 0.24\nset_exchange!(sys, J₁, Bond(3, 2, [1,1,0]))\nset_exchange!(sys, J₄, Bond(1, 1, [0,0,1]))\nset_exchange!(sys, J₂, Bond(1, 3, [0,0,0]))","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"The final two exchanges define the chirality of the magnetic structure. The crystal chirality, epsilon_T, the chirality of each triangle, ϵ_D and the sense of rotation of the spin helices along c, ϵ_H. The three chiralities are related by ϵ_T=ϵ_D ϵ_H. We now assign J_3 and J_5 according to the crystal chirality.","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"ϵD = -1\nϵH = +1\nϵT = ϵD * ϵH\n\nif ϵT == -1\n set_exchange!(sys, J₃, Bond(2, 3, [-1,-1,1]))\n set_exchange!(sys, J₅, Bond(3, 2, [1,1,1]))\nelseif ϵT == 1\n set_exchange!(sys, J₅, Bond(2, 3, [-1,-1,1]))\n set_exchange!(sys, J₃, Bond(3, 2, [1,1,1]))\nelse\n throw(\"Provide a valid chirality\")\nend","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"Whilst Sunny provides tools to optimize the ground state automatically, in this case we already know the model ground state. Set the spiral magnetic order using set_spiral_order_on_sublattice!. It takes an ordering wavevector q, an axis of rotation for the spins axis, and the initial spin S0 for each sublattice.","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"q = [0, 0, 1/7]\naxis = [0,0,1]\nset_spiral_order_on_sublattice!(sys, 1; q, axis, S0=[1, 0, 0])\nset_spiral_order_on_sublattice!(sys, 2; q, axis, S0=[-1/2, -sqrt(3)/2, 0])\nset_spiral_order_on_sublattice!(sys, 3; q, axis, S0=[-1/2, +sqrt(3)/2, 0])\n\nplot_spins(sys; color=[s[1] for s in sys.dipoles])","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"Define a path in reciprocal space, 01-1+xi for xi = 0 dots 3.","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"points_rlu = [[0,1,-1],[0,1,-1+1],[0,1,-1+2],[0,1,-1+3]];\ndensity = 100\npath, xticks = reciprocal_space_path(crystal, points_rlu, density);\nnothing #hide","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"Calculate broadened intensities","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"swt = SpinWaveTheory(sys)\nγ = 0.15 # width in meV\nbroadened_formula = intensity_formula(swt, :perp; kernel=lorentzian(γ))\nenergies = collect(0:0.01:6) # 0 < ω < 6 (meV).\nis = intensities_broadened(swt, path, energies, broadened_formula);\nnothing #hide","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"Plot","category":"page"},{"location":"examples/spinw/15_Ba3NbFe3Si2O14.html","page":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","title":"Tutorial 15 - Ba₃NbFe₃Si₂O₁₄","text":"fig = Figure()\nax = Axis(fig[1,1]; xlabel=\"Momentum (r.l.u.)\", ylabel=\"Energy (meV)\", xticks, xticklabelrotation=π/6)\nheatmap!(ax, 1:size(is,1), energies, is, colorrange=(0,5))\nfig","category":"page"},{"location":"index.html#Overview","page":"Overview","title":"Overview","text":"","category":"section"},{"location":"index.html","page":"Overview","title":"Overview","text":"Sunny is a Julia package for modeling atomic-scale magnetism. It provides powerful tools to study equilibrium and non-equilibrium magnetic phenomena. In particular, it allows estimation of dynamical structure factor intensities, mathcalS(𝐪ω), to support quantitative modeling of experimental scattering data.","category":"page"},{"location":"index.html","page":"Overview","title":"Overview","text":"Features include:","category":"page"},{"location":"index.html","page":"Overview","title":"Overview","text":"Generalized spin dynamics using SU(N) coherent states.\nAbility to specify a crystal from a .cif file or its spacegroup symmetry.\nInteractive visualizations of the 3D crystals and magnetic ordering.\nSymmetry analysis to classify allowed interaction terms, and to propagate them by symmetry.\nSingle-ion anisotropy at arbitrary order, which can be specified using Stevens operators or as a polynomial of spin operators.\nMonte Carlo sampling of spin configurations in thermal equilibrium, and optimization tools.\nMeasurements of dynamical correlations. At low temperature, one can use linear spin wave theory and its multi-boson generalization. This generalizes to finite temperatures using the classical dynamics, which allows for strongly nonlinear effects.\nLong-range dipole-dipole interactions accelerated with the fast Fourier transform (FFT).\nSupport for comparison with experimental data: form factor, dipole factor, temperature-dependent classical-to-quantum factors, intensity binning, etc.","category":"page"}] +[{"location":"parallelism.html#Parallelizing-Calculations","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"","category":"section"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"Calculating structure factors with classical dynamics is computationally expensive, and Sunny does not currently parallelize these calculations at a fine-grained level. However, Julia provides facilities that allow users to run multiple simulations in parallel with only a little extra effort. We will look at two approaches to doing this: multithreading and Julia's Distributed package. We'll present these approaches in a series of code snippets that can be copied and pasted into your preferred Julia development environment.","category":"page"},{"location":"parallelism.html#Review-of-the-serial-workflow","page":"Parallelizing Calculations","title":"Review of the serial workflow","text":"","category":"section"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"The serial approach to calculating a structure factor, covered in the FeI₂ tutorial, involves thermalizing a spin System and then calling add_sample!. add_sample! uses the state of the System as an initial condition for the calculation of a dynamical trajectory. The correlations of the trajectory are calculated and accumulated into a running average of the 𝒮(𝐪ω). This sequence is repeated to generate additional samples.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"To illustrate, we'll set up a a simple model: a spin-1 antiferromagnet on an FCC crystal. ","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"using Sunny, GLMakie\n\nfunction make_system(cryst; J, dims, seed=nothing)\n sys = System(cryst, dims, [SpinInfo(1, S=1, g=2)], :dipole; seed)\n set_exchange!(sys, J, Bond(1,1,[1,0,0]))\n return sys\nend\n\nJ = 1.0 # meV \ncryst = Sunny.fcc_primitive_crystal()\nsys = make_system(cryst; J, dims=(10,10,2))","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"To thermalize and generate equilibrium samples, we'll need a Langevin integrator. ","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"kT = 0.5 # meV\nΔt = 0.05/J\nintegrator = Langevin(Δt; kT, λ=0.1)","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"Finally, call dynamical_correlations to configure a SampledCorrelations.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"sc = dynamical_correlations(sys; Δt=0.1, nω=100, ωmax=10.0)","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"The serial calculation can now be performed as follows:","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"nsamples = 10\n\n# Thermalize the system\nfor _ in 1:5000 # Sufficient number of steps to thermalize\n step!(sys, integrator)\nend\n\nfor _ in 1:nsamples\n # Generate new sample by running Langevin dynamics\n for _ in 1:1000 # Sufficient number of steps to decorrelate\n step!(sys, integrator)\n end\n # Add the sample to the correlation data\n add_sample!(sc, sys)\nend","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"This will take a second or two on a modern workstation, resulting in a single SampledCorrelations that contains 10 samples.","category":"page"},{"location":"parallelism.html#Multithreading-approach","page":"Parallelizing Calculations","title":"Multithreading approach","text":"","category":"section"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"To use threads in Julia, you must launch your Julia environment appropriately.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"From the command line, launch Julia with julia --threads=N, where N is the number of threads. If you don't know how many threads you'd like, you can let Julia decide with --threads=auto.\nJupyter notebook users will need to to set up a multithreaded Julia kernel and restart into this kernel. The kernel can be created inside Julia with the following:","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":" using IJulia\n IJulia.installkernel(\"Julia Multithreaded\",\n env=Dict(\"JULIA_NUM_THREADS\" => \"auto\"))","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"VSCode users should open their settings and search for Julia: Additional Args. There will be link called Edit in settings.json. Click on this, add \"--threads=auto\" to the list julia.additionalArgs, and start a new REPL.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"Before going further, make sure that Threads.nthreads() returns a number greater than 1.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"We will use multithreading in a very simple way, essentially employing a distributed memory approach to avoid conflicts around memory access. First preallocate a number of systems and correlations.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"npar = Threads.nthreads()\nsystems = [make_system(cryst; J, dims=(10,10,2), seed=i) for i in 1:npar]\nscs = [dynamical_correlations(sys; Δt=0.1, nω=100, ωmax=10.0) for _ in 1:npar]","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"warning: Dealing with memory constraints\nIf you have many threads available and are working with a large system, you may not have enough memory to store all these systems and correlations. In that case, simply reduce npar to a small enough value that you can make the necessary allocations.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"When the Threads.@threads macro is applied before a for loop, the iterations of the loop will execute in parallel using the available threads. We will put the entire thermalization and sampling process inside the loop, with each thread acting on a unique System and SampledCorrelations.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"Threads.@threads for id in 1:npar\n integrator = Langevin(Δt; kT, λ=0.1)\n for _ in 1:5000\n step!(systems[id], integrator)\n end\n for _ in 1:nsamples\n for _ in 1:1000\n step!(systems[id], integrator)\n end\n add_sample!(scs[id], systems[id])\n end\nend","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"You may find this takes a little bit longer than the serial example, but, at the end of it, you will have generated npar correlation objects, each with 10 samples. We can merge these into a summary SampledCorrelations with 10*npar samples with merge_correlations:","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"sc = merge_correlations(scs)","category":"page"},{"location":"parallelism.html#Using-Distributed","page":"Parallelizing Calculations","title":"Using Distributed","text":"","category":"section"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"Julia also provides a distributed memory approach to parallelism through the standard library package Distributed. This works by launching independent Julia environments on different \"processes.\" An advantage of this approach is that it scales naturally to clusters since the processes are easily distributed across many different compute nodes. A disadvantage, especially when working on a single computer, is the increased memory overhead associated with launching all these environments.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"We begin by importing the package,","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"using Distributed","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"and launching some new processes. It is often sensible to create as many processes as there are cores.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"ncores = length(Sys.cpu_info())\naddprocs(ncores)","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"You can think of each process as a separate computer running a fresh Julia environment, so we'll need to import Sunny and define our function in each of these environments. This is easily achieved with the @everywhere macro.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"@everywhere using Sunny\n\n@everywhere function make_system(cryst; J, dims, seed=nothing)\n sys = System(cryst, dims, [SpinInfo(1, S=1, g=2)], :dipole; seed)\n set_exchange!(sys, J, Bond(1,1,[1,0,0]))\n return sys\nend","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"A simple way to perform work on these processes is to use the parallel map function, pmap. This will apply a function to each element of some iterable, such as a list of numbers, and return a list of the results. It is a parallel map because these function calls may occur at the same time on different Julia processes. The pmap function takes care of distributing the work among the different processes and retrieving the results.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"In the example below, we give pmap a list of RNG seeds to iterate over, and we define the function that will be applied to each of these seeds in a do block. The contents of this block are essentially the same as what we put inside our parallel for loop in the multithreading example. The main difference is that the Systems and SampledCorrelations are not created in advance of the parallelization but are instead created inside each Julia process. The do block returns a SampledCorrelations, and the output of all the parallel computations are collected into list of SampledCorrelations called scs.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"scs = pmap(1:ncores) do seed\n sys = make_system(Sunny.fcc_primitive_crystal(); J=1.0, dims=(10,10,2), seed)\n sc = dynamical_correlations(sys; Δt=0.1, nω=100, ωmax=10.0)\n integrator = Langevin(Δt; kT, λ=0.1)\n\n for _ in 1:5000 # Thermalize\n step!(sys, integrator)\n end\n for _ in 1:nsamples \n for _ in 1:1000 \n step!(sys, integrator)\n end\n add_sample!(sc, sys)\n end\n\n return sc\nend","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"Finally, merge the results into a summary SampledCorrelations.","category":"page"},{"location":"parallelism.html","page":"Parallelizing Calculations","title":"Parallelizing Calculations","text":"sc = merge_correlations(scs)","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"EditURL = \"../../../examples/01_LSWT_SU3_FeI2.jl\"","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"Download this example as Jupyter notebook or Julia script.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html#.-Multi-flavor-spin-wave-simulations-of-FeI-(Showcase)","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"","category":"section"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"FeI₂ is an effective spin-1 material with strong single-ion anisotropy. Quadrupolar fluctuations give rise to a single-ion bound state that cannot be described by a dipole-only model. This tutorial illustrates how to use the linear spin wave theory of SU(3) coherent states (i.e. 2-flavor bosons) to model the magnetic behavior in FeI₂. The original study was performed in Bai et al., Nature Physics 17, 467–472 (2021).","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"The Fe atoms are arranged in stacked triangular layers. The effective spin Hamiltonian takes the form,","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"mathcalH=sum_(ij) 𝐒_i J_ij 𝐒_j - Dsum_i left(S_i^zright)^2","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"where the set of exchange matrices J_ij between bonded sites (ij) includes competing ferromagnetic and antiferromagnetic interactions. This model also includes a strong easy axis anisotropy, D 0.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"We will formulate this Hamiltonian in Sunny and then calculate its dynamic structure factor.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html#Get-Julia-and-Sunny","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"Get Julia and Sunny","text":"","category":"section"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"Sunny is implemented in Julia. This is a relatively new programming language that allows for interactive development (like Python or Matlab) while also providing high numerical efficiency (like C++ or Fortran). New Julia users may wish to take a look at our Getting Started with Julia guide. Sunny requires Julia 1.9 or later.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"From the Julia prompt, load Sunny. For plotting, one can choose either GLMakie (a pop-up window) or WGLMakie (inline plots for a Jupyter notebook).","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"using Sunny, GLMakie","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"If these packages are not yet installed, Julia should offer to install them using its built-in package management system. If old versions are installed, you may need to update them to run this tutorial.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html#Crystals","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"Crystals","text":"","category":"section"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"A Crystal describes the crystallographic unit cell and will usually be loaded from a .cif file. Here, we instead build a crystal by listing all atoms and their types.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"a = b = 4.05012 # Lattice constants for triangular lattice\nc = 6.75214 # Spacing in the z-direction\n\nlatvecs = lattice_vectors(a, b, c, 90, 90, 120) # A 3x3 matrix of lattice vectors that\n # define the conventional unit cell\npositions = [[0, 0, 0], [1/3, 2/3, 1/4], [2/3, 1/3, 3/4]] # Positions of atoms in fractions\n # of lattice vectors\ntypes = [\"Fe\", \"I\", \"I\"]\nFeI2 = Crystal(latvecs, positions; types)","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"Observe that Sunny inferred the space group, 'P -3 m 1' (164) and labeled the atoms according to their point group symmetries.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"Only the Fe atoms are magnetic, so we discard the I ions using subcrystal.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"cryst = subcrystal(FeI2, \"Fe\")","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"Importantly, cryst retains the spacegroup symmetry of the full FeI₂ crystal. This information will be used, for example, to propagate exchange interactions between symmetry-equivalent bonds.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"In a running Julia environment, the crystal can be viewed interactively using view_crystal.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"view_crystal(cryst, 8.0)","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html#Symmetry-analysis","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"Symmetry analysis","text":"","category":"section"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"The command print_symmetry_table provides a list of all the symmetry-allowed interactions up to a cutoff distance.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"print_symmetry_table(cryst, 8.0)","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"The allowed g-tensor is expressed as a 3×3 matrix in the free coefficients A, B, ... The allowed single-ion anisotropy is expressed as a linear combination of Stevens operators. The latter correspond to polynomials of the spin operators, as we will describe below.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"The allowed exchange interactions are given as a 3×3 matrix for representative bonds. The notation Bond(i, j, n) indicates a bond between atom indices i and j, with cell offset n. In the general case, it will be necessary to associate atom indices with their positions in the unit cell; these can be viewed with display(cryst). Note that the order of the pair (i j) is significant if the exchange tensor contains antisymmetric Dzyaloshinskii–Moriya (DM) interactions.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"In the case of FeI₂, Bond(1, 1, [1,0,0]) is one of the 6 nearest-neighbor Fe-Fe bonds on a triangular lattice layer, and Bond(1, 1, [0,0,1]) is an Fe-Fe bond between layers.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html#Building-a-spin-System","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"Building a spin System","text":"","category":"section"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"In constructing a spin System, we must provide several additional details about the spins.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"sys = System(cryst, (4, 4, 4), [SpinInfo(1, S=1, g=2)], :SUN, seed=2)","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"This system includes 444 unit cells, i.e. 64 Fe atoms, each with spin S=1 and a g-factor of 2. Quantum mechanically, spin S=1 involves a superposition of 2S+1=3 distinct angular momentum states. In :SUN mode, this superposition will be modeled explicitly using the formalism of SU(3) coherent states, which captures both dipolar and quadrupolar fluctuations. For the more traditional dipole dynamics, use :dipole mode instead.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"Next we will use set_exchange! to assign interaction to bonds. Sunny will automatically propagate each interaction to all symmetry-equivalent bonds in the unit cell. The FeI₂ interactions below follow Bai et al.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"J1pm = -0.236\nJ1pmpm = -0.161\nJ1zpm = -0.261\nJ2pm = 0.026\nJ3pm = 0.166\nJ′0pm = 0.037\nJ′1pm = 0.013\nJ′2apm = 0.068\n\nJ1zz = -0.236\nJ2zz = 0.113\nJ3zz = 0.211\nJ′0zz = -0.036\nJ′1zz = 0.051\nJ′2azz = 0.073\n\nJ1xx = J1pm + J1pmpm\nJ1yy = J1pm - J1pmpm\nJ1yz = J1zpm\n\nset_exchange!(sys, [J1xx 0.0 0.0;\n 0.0 J1yy J1yz;\n 0.0 J1yz J1zz], Bond(1,1,[1,0,0]))\nset_exchange!(sys, [J2pm 0.0 0.0;\n 0.0 J2pm 0.0;\n 0.0 0.0 J2zz], Bond(1,1,[1,2,0]))\nset_exchange!(sys, [J3pm 0.0 0.0;\n 0.0 J3pm 0.0;\n 0.0 0.0 J3zz], Bond(1,1,[2,0,0]))\nset_exchange!(sys, [J′0pm 0.0 0.0;\n 0.0 J′0pm 0.0;\n 0.0 0.0 J′0zz], Bond(1,1,[0,0,1]))\nset_exchange!(sys, [J′1pm 0.0 0.0;\n 0.0 J′1pm 0.0;\n 0.0 0.0 J′1zz], Bond(1,1,[1,0,1]))\nset_exchange!(sys, [J′2apm 0.0 0.0;\n 0.0 J′2apm 0.0;\n 0.0 0.0 J′2azz], Bond(1,1,[1,2,1]))","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"The function set_onsite_coupling! assigns a single-ion anisotropy. The argument can be constructed using spin_matrices or stevens_matrices. Here we use Julia's anonymous function syntax to assign an easy-axis anisotropy along the direction hatz.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"D = 2.165\nset_onsite_coupling!(sys, S -> -D*S[3]^2, 1)","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html#Calculating-structure-factor-intensities","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"Calculating structure factor intensities","text":"","category":"section"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"In the remainder of this tutorial, we will examine Sunny's tools for calculating the dynamical structure factor using a multi-boson generalization of linear spin wave theory (LSWT). This theory describes non-interacting quasi-particle excitations that hybridize dipolar and quadrupolar modes.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html#Finding-the-ground-state","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"Finding the ground state","text":"","category":"section"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"Begin with a random configuration and use minimize_energy! to find a configuration of the SU(3) coherent states (i.e. spin dipoles and quadrupoles) that locally minimizes energy.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"randomize_spins!(sys)\nminimize_energy!(sys)","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"A positive number above indicates that the procedure has converged to a local energy minimum. The configuration, however, may still have defects. This can be checked by visualizing the spins, colored according to their z-components.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"plot_spins(sys; color=[s[3] for s in sys.dipoles])","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"A different understanding of the magnetic ordering can be obtained by moving to Fourier space. The 'instant' structure factor 𝒮(𝐪) is an experimental observable. To investigate 𝒮(𝐪) as true 3D data, Sunny provides instant_correlations and related functions. Here, however, we will use print_wrapped_intensities, which gives average intensities for the individual Bravais sublattices (in effect, all wavevectors are wrapped to the first Brillouin zone).","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"print_wrapped_intensities(sys)","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"The result will likely be approximately consistent with the known zero-field energy-minimizing magnetic structure of FeI₂, which is single-Q (two-up, two-down antiferromagnetic order). Mathematically, spontaneous symmetry breaking should select one of Q = 0 -14 14, 14 0 14, or -141414, associated with the three-fold rotational symmetry of the crystal spacegroup. In nature, however, one will frequently encounter competing \"domains\" associated with the three possible orientations of the ground state.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"If the desired ground state is already known, as with FeI₂, it could be entered by hand using set_dipole!. Alternatively, in the case of FeI₂, we could repeatedly employ the above randomization and minimization procedure until a defect-free configuration is found. Some systems will have more complicated ground states, which can be much more challenging to find. For this, Sunny provides experimental support for powerful simulated annealing via parallel tempering, but that is outside the scope of this tutorial.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"Here, let's break the three-fold symmetry of FeI₂ by hand. Given one or more desired Q modes, Sunny can suggest a magnetic supercell with appropriate periodicity. Let's arbitrarily select one of the three possible ordering wavevectors, Q = 0 -14 14. Sunny suggests a corresponding magnetic supercell in units of the crystal lattice vectors.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"suggest_magnetic_supercell([[0, -1/4, 1/4]])","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"The system returned by reshape_supercell is smaller, and is sheared relative to the original system. This makes it much easier to find the global energy minimum.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"sys_min = reshape_supercell(sys, [1 0 0; 0 2 1; 0 -2 1])\nrandomize_spins!(sys_min)\nminimize_energy!(sys_min);\nnothing #hide","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"Plot the system again, now including \"ghost\" spins out to 12Å","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"plot_spins(sys_min; color=[s[3] for s in sys_min.dipoles], ghost_radius=12)","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html#Linear-spin-wave-theory","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"Linear spin wave theory","text":"","category":"section"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"Now that we have found the ground state for a magnetic supercell, we can immediately proceed to perform zero-temperature calculations using linear spin wave theory. We begin by instantiating a SpinWaveTheory type using the supercell.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"swt = SpinWaveTheory(sys_min)","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"Select a sequence of wavevectors that will define a piecewise linear interpolation in reciprocal lattice units (RLU).","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"q_points = [[0,0,0], [1,0,0], [0,1,0], [1/2,0,0], [0,1,0], [0,0,0]];\nnothing #hide","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"The function reciprocal_space_path will linearly sample a path between the provided q-points with a given density. The xticks return value provides labels for use in plotting.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"density = 50\npath, xticks = reciprocal_space_path(cryst, q_points, density);\nnothing #hide","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"The dispersion function defines the quasiparticle excitation energies ω_i(𝐪) for each point 𝐪 along the reciprocal space path.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"disp = dispersion(swt, path);\nnothing #hide","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"In addition to the band energies ω_i(𝐪), Sunny can calculate the inelastic neutron scattering intensity I_i(𝐪) for each band i according to an intensity_formula. We choose to apply a polarization correction (1 - 𝐪𝐪) by setting the mode argument to :perp. Selecting delta_function_kernel specifies that we want the energy and intensity of each band individually.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"formula = intensity_formula(swt, :perp; kernel=delta_function_kernel)","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"The function intensities_bands uses linear spin wave theory to calculate both the dispersion and intensity data for the provided path.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"disp, intensity = intensities_bands(swt, path, formula);\nnothing #hide","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"These can be plotted in GLMakie.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"fig = Figure()\nax = Axis(fig[1,1]; xlabel=\"Momentum (r.l.u.)\", ylabel=\"Energy (meV)\", xticks, xticklabelrotation=π/6)\nylims!(ax, 0.0, 7.5)\nxlims!(ax, 1, size(disp, 1))\ncolorrange = extrema(intensity)\nfor i in axes(disp, 2)\n lines!(ax, 1:length(disp[:,i]), disp[:,i]; color=intensity[:,i], colorrange)\nend\nfig","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"To make comparisons with inelastic neutron scattering (INS) data, it is helpful to employ an empirical broadening kernel, e.g., a lorentzian.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"γ = 0.15 # width in meV\nbroadened_formula = intensity_formula(swt, :perp; kernel=lorentzian(γ))","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"The intensities_broadened function requires an energy range in addition to the 𝐪-space path.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"energies = collect(0:0.01:10) # 0 < ω < 10 (meV).\nis1 = intensities_broadened(swt, path, energies, broadened_formula);\nnothing #hide","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"A real FeI₂ sample will exhibit competing magnetic domains associated with spontaneous symmetry breaking of the 6-fold rotational symmetry of the triangular lattice. Note that the wavevectors 𝐪 and -𝐪 are equivalent in the structure factor, which leaves three distinct domain orientations, which are related by 120° rotations about the z-axis. Rather than rotating the spin configuration directly, on can rotate the 𝐪-space path. Below, we use rotation_in_rlu to average the intensities over all three possible orientations.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"R = rotation_in_rlu(cryst, [0, 0, 1], 2π/3)\nis2 = intensities_broadened(swt, [R*q for q in path], energies, broadened_formula)\nis3 = intensities_broadened(swt, [R*R*q for q in path], energies, broadened_formula)\nis_averaged = (is1 + is2 + is3) / 3\n\nfig = Figure()\nax = Axis(fig[1,1]; xlabel=\"Momentum (r.l.u.)\", ylabel=\"Energy (meV)\", xticks, xticklabelrotation=π/6)\nheatmap!(ax, 1:size(is_averaged, 1), energies, is_averaged)\nfig","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"This result can be directly compared to experimental neutron scattering data from Bai et al.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"(The publication figure accidentally used a non-standard coordinate system to label the wave vectors.)","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"To get this agreement, the use of SU(3) coherent states is essential. In other words, we needed a theory of multi-flavored bosons. The lower band has large quadrupolar character, and arises from the strong easy-axis anisotropy of FeI₂. By setting mode = :SUN, the calculation captures this coupled dipole-quadrupole dynamics.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"An interesting exercise is to repeat the same study, but using mode = :dipole instead of :SUN. That alternative choice would constrain the coherent state dynamics to the space of dipoles only.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"The full dynamical spin structure factor (DSSF) can be retrieved as a 33 matrix with the dssf function, for a given path of 𝐪-vectors.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"disp, is = dssf(swt, path);\nnothing #hide","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"The first output disp is identical to that obtained from dispersion. The second output is contains a list of 33 matrix of intensities. For example, is[q,n][2,3] yields the (yz) component of the structure factor intensity for nth mode at the qth wavevector in the path.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html#What's-next?","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"What's next?","text":"","category":"section"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"The multi-boson linear spin wave theory, applied above, can be understood as the quantization of a certain generalization of the Landau-Lifshitz spin dynamics. Rather than dipoles, this dynamics takes places on the space of SU(N) coherent states.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"The full SU(N) coherent state dynamics, with appropriate quantum correction factors, can be useful to model finite temperature scattering data. In particular, it captures certain anharmonic effects due to thermal fluctuations. See our generalized spin dynamics tutorial.","category":"page"},{"location":"examples/01_LSWT_SU3_FeI2.html","page":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","title":"1. Multi-flavor spin wave simulations of FeI₂ (Showcase)","text":"The classical dynamics is also a good starting point to study non-equilibrium phenomena. Empirical noise and damping terms can be used to model coupling to a thermal bath. This yields a Langevin dynamics of SU(N) coherent states. Our dynamical SU(N) quench tutorial illustrates how a temperature quench can give rise to novel liquid phase of CP² skyrmions.","category":"page"},{"location":"structure-factor.html#Structure-Factor-Calculations","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"","category":"section"},{"location":"structure-factor.html#Overview","page":"Structure Factor Calculations","title":"Overview","text":"","category":"section"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"The dynamical structure factor is of fundamental importance for characterizing a magnetic system, and facilitates quantitative comparison between theory and experimental scattering data.","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"Consider, for example, a two-point dynamical spin correlation function, s^α(𝐱+Δ𝐱 t+Δt) s^β(𝐱 t). Here s^α(𝐱 t) represents the time dynamics of a spin dipole component α at position 𝐱, and brackets represent an average over equilibrium initial conditions and over (𝐱 t). The dynamical structure factor is defined as the Fourier transform of this two-point correlation in both space and time, up to an overall scaling factor. Using the convolution theorem, the result is,","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"𝒮^αβ(𝐪 ω) = frac1V s^α(𝐪 ω)^ast s^β(𝐪 ω) ","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"with V the system volume. We will restrict attention to lattice systems with periodic boundaries.","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"Consider a crystal unit cell defined by three lattice vectors 𝐚_1 𝐚_2 𝐚_3, and linear system sizes L_1 L_2 L_3 measured in unit cells. The allowed momentum vectors take on discrete values 𝐪 = sum_α=1^3 m_α 𝐛_α L_α, where m_α are an integers and the reciprocal lattice vectors 𝐛_α are defined to satisfy 𝐚_α 𝐛_β = 2π δ_αβ. For a Bravais lattice, 𝐪 will be periodic in the first Brillouin zone, i.e., under any shift 𝐪 𝐪 𝐛_α. More generally, consider a non-Bravais lattice such that each unit cell may contain multiple spins. By partitioning spins s_j(𝐱t) according to their sublattice index j, the relevant momenta 𝐪 remain discretized as above, but now periodicity in the first Brillouin zone is lost. The structure factor may be written as a phase-average over the displacements between sublattices 𝐫_jk,","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"𝒮^αβ(𝐪 ω) = _jk e^i 𝐫_jk 𝐪 𝒮^αβ_jk(𝐪 ω) ","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"From a theoretical perspective, the quantity","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"𝒮^αβ_jk(𝐪 ω) = frac1V s_j^α(𝐪 ω)^ast s_k^β(𝐪 ω)","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"is fundamental. For each sublattice j, the data s_j^α(𝐪 ω) can be efficiently obtained by fast Fourier tranformation of a real space configuration s_j^α(𝐱 t). Internally, Sunny will calculate and store the discrete 𝒮^αβ_jk(𝐪 ω) correlation data, and use this to construct 𝒮^αβ(𝐪ω) intensities that can be compared with experiment.","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"Calculating this structure factor involves several steps, with various possible settings. Sunny provides a number of tools to facilitate this calculation and to extract information from the results. These tools are briefly outlined below. Please see the Examples for a \"real life\" use case. Detailed function information is available in the Library API.","category":"page"},{"location":"structure-factor.html#Estimating-stucture-factors-with-classical-dynamics","page":"Structure Factor Calculations","title":"Estimating stucture factors with classical dynamics","text":"","category":"section"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"Classical dynamics may be used to estimate structure factor data by analyzing the spin-spin correlations of dynamical trajectories. This is fundamentally a Monte Carlo approach, as the trajectories must be started from an initial spin configuration that is sampled at thermal equilibrium. (Note that it is not possible to estimate a true T=0 dynamical structure factor using this method, but the temperature may be very low.) Samples are accumulated into a SampledCorrelations, from which intensity information may be extracted. The user does not typically build their own SampledCorrelations but instead initializes one by calling either dynamical_correlations or instant_correlations, as described below.","category":"page"},{"location":"structure-factor.html#Estimating-a-dynamical-structure-factor:-𝒮(𝐪,ω)","page":"Structure Factor Calculations","title":"Estimating a dynamical structure factor: 𝒮(𝐪ω)","text":"","category":"section"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"A SampledCorrelations for estimating the dynamical structure factor, 𝒮^αβ(𝐪ω), may be created by calling dynamical_correlations. This requires three keyword arguments. These will determine the dynamics used to calculate samples and, consequently, the ω information that will be available. ","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"Δt: Determines the step size used for simulating the dynamics. A smaller number will require proportionally more calculation time. While a smaller Δt will enable the resolution of higher energies, Δt is typically selected to ensure numerical stability rather than to maximize the largest ω value. A safe choice is to use the smaller value of Δt = 0.1/(J* S^2) or Δt = 0.1/(D * S), where S is magnetic moment of the largest local spin (as specified in SpinInfo), J is the parameter governing the largest bilinear interaction (e.g. exchange), and D is the parameter governing the largest single-site term of the Hamiltonian (e.g., anisotropy or Zeeman term).\nωmax: Sets the maximum resolved energy. Note that this is not independent of Δt. If ωmax too large, Sunny will throw an error and ask you to choose a smaller Δt. \nnω: Determines the number of energy bins to resolve. A larger number will require more calculation time.","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"A sample may be added by calling add_sample!(sc, sys). The input sys must be a spin configuration in good thermal equilibrium, e.g., using the continuous Langevin dynamics or using single spin flip trials with LocalSampler. The statistical quality of the 𝒮^αβ(𝐪ω) can be improved by repeatedly generating decorrelated spin configurations in sys and calling add_sample! on each configuration.","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"The outline of typical use case might look like this:","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"# Make a `SampledCorrelations`\nsc = dynamical_correlations(sys; Δt=0.05, ωmax=10.0, nω=100) \n\n# Add samples\nfor _ in 1:nsamples\n decorrelate_system(sys) # Perform some type of Monte Carlo simulation\n add_sample!(sc, sys) # Use spins to calculate trajectory and accumulate new sample of 𝒮(𝐪,ω)\nend","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"The calculation may be configured in a number of ways; see the dynamical_correlations documentation for a list of all keywords.","category":"page"},{"location":"structure-factor.html#Estimating-an-instantaneous-(\"static\")-structure-factor:-𝒮(𝐪)","page":"Structure Factor Calculations","title":"Estimating an instantaneous (\"static\") structure factor: 𝒮(𝐪)","text":"","category":"section"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"Sunny provides two methods for calculating instantaneous, or static, structure factors: 𝒮^αβ(𝐪). The first involves calculating spatial spin-spin correlations at single time slices. The second involves calculating a dynamic structure factor first and integrating out the ω information. The advantage of the latter approach is that it enables application of an ω-dependent classical-to-quantum rescaling of structure factor intensities, a method that should be preferred whenever comparing results to experimental data or spin wave calculations. A disadvantage of this approach is that it is computationally more expensive. There are also many cases when it is not straightforward to calculate a meaningful dynamics, as when working with Ising spins. In this section we will discuss how to calculate instantaneous structure factors from static spin configurations. Information about calculating instantaneous data from a dynamical correlations can be found in the following section.","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"The basic usage for the instantaneous case is very similar to the dynamic case, except one calls instant_correlations instead of dynamical_correlations to configure a SampledCorrelations. Note that there are no required keywords as there is no need to specify any dynamics. instant_correlations will return a SampledCorrelations containing no data. Samples may be added by calling add_sample!(sc, sys), where sc is the SampledCorrelations. When performing a finite-temperature calculation, it is important to ensure that the spin configuration in the sys represents a good equilibrium sample, as in the dynamical case. Note, however, that we recommend calculating instantaneous correlations at finite temperature calculations by using full dynamics (i.e., using dynamical_correlations) and then integrating out the energy axis. An approach to doing this is described in the next section.","category":"page"},{"location":"structure-factor.html#Extracting-information-from-sampled-correlation-data","page":"Structure Factor Calculations","title":"Extracting information from sampled correlation data","text":"","category":"section"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"The basic function for extracting information from a SampledCorrelations at a particular wave vector, 𝐪, is intensities_interpolated. It takes a SampledCorrelations, a list of wave vectors, and an intensity_formula. The intensity_formula specifies how to contract and correct correlation data to arrive at a physical intensity. A simple example is formula = intensity_formula(sc, :perp), which will instruct Sunny apply polarization corrections: sum_αβ(I-q_α q_β) 𝒮^αβ(𝐪ω). An intensity at the wave vector 𝐪 = (𝐛_2 + 𝐛_3)2 may then be retrieved with intensities_interpolated(sf, [[0.0, 0.5, 0.5]], formula) . intensities_interpolated returns a list of nω elements at each wavevector. The corresponding ω values can be retrieved by calling available_energies on sf.","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"Since Sunny only calculates the structure factor on a finite lattice when performing classical simulations, it is important to realize that exact information is only available at a discrete set of wave vectors. Specifically, for each axis index i, we will get information at q_i = fracnL_i, where n runs from (frac-L_i2+1) to fracL_i2 and L_i is the linear dimension of the lattice used for the calculation. If you request a wave vector that does not fall into this set, Sunny will automatically round to the nearest 𝐪 that is available. If intensities_interpolated is given the keyword argument interpolation=:linear, Sunny will use trilinear interpolation to determine a result at the requested wave vector. ","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"To retrieve the intensities at all wave vectors for which there is exact data, first call the function available_wave_vectors to generate a list of qs. This takes an optional keyword argument bzsize, which must be given a tuple of three integers specifying the number of Brillouin zones to calculate, e.g., bzsize=(2,2,2). The resulting list of wave vectors may then be passed to intensities_interpolated.","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"Alternatively, intensities_binned can be used to place the exact data into histogram bins for comparison with experiment.","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"The convenience function reciprocal_space_path returns a list of wavevectors sampled along a path that connects specified 𝐪 points. This list can be used as an input to intensities. Another convenience method, reciprocal_space_shell will generate points on a sphere of a given radius. This is useful for powder averaging. ","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"A number of arguments for intensity_formula are available which modify the calculation of structure factor intensity. It is generally recommended to provide a value of kT corresponding to the temperature of sampled configurations. Given kT, Sunny will include an energy- and temperature-dependent classical-to-quantum rescaling of intensities in the formula.","category":"page"},{"location":"structure-factor.html","page":"Structure Factor Calculations","title":"Structure Factor Calculations","text":"To retrieve intensity data from a instantaneous structure factor, use instant_intensities_interpolated, which accepts similar arguments to intensities_interpolated. This function may also be used to calculate instantaneous information from a dynamical correlation data, i.e. from a SampledCorrelations created with dynamical_correlations. Note that it is important to supply a value to kT to reap the benefits of this approach over simply calculating a static structure factor at the outset. ","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"EditURL = \"../../../examples/02_LSWT_CoRh2O4.jl\"","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"Download this example as Jupyter notebook or Julia script.","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html#.-Spin-wave-simulations-of-CoRhO","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"","category":"section"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"This tutorial illustrates the conventional spin wave theory of dipoles. We consider a simple model of the diamond-cubic crystal CoRh₂O₄, with parameters extracted from Ge et al., Phys. Rev. B 96, 064413.","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"using Sunny, GLMakie","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"Construct a diamond Crystal in the conventional (non-primitive) cubic unit cell. Sunny will populate all eight symmetry-equivalent sites when given the international spacegroup number 227 (\"Fd-3m\") and the appropriate setting. For this spacegroup, there are two conventional translations of the unit cell, and it is necessary to disambiguate through the setting keyword argument. (On your own: what happens if setting is omitted?)","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"a = 8.5031 # (Å)\nlatvecs = lattice_vectors(a, a, a, 90, 90, 90)\ncryst = Crystal(latvecs, [[0,0,0]], 227, setting=\"1\")","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"In a running Julia environment, the crystal can be viewed interactively using view_crystal.","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"view_crystal(cryst, 8.0)","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"Construct a System with quantum spin S=32 constrained to the space of dipoles. Including an antiferromagnetic nearest neighbor interaction J will favor Néel order. To optimize this magnetic structure, it is sufficient to employ a magnetic lattice consisting of a single crystal unit cell, latsize=(1,1,1). Passing an explicit random number seed will ensure repeatable results.","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"latsize = (1, 1, 1)\nS = 3/2\nJ = 7.5413*meV_per_K # (~ 0.65 meV)\nsys = System(cryst, latsize, [SpinInfo(1; S, g=2)], :dipole; seed=0)\nset_exchange!(sys, J, Bond(1, 3, [0,0,0]))","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"In the ground state, each spin is exactly anti-aligned with its 4 nearest-neighbors. Because every bond contributes an energy of -JS^2, the energy per site is -2JS^2. In this calculation, a factor of 1/2 avoids double-counting the bonds. Due to lack of frustration, direct energy minimization is successful in finding the ground state.","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"randomize_spins!(sys)\nminimize_energy!(sys)\n\n@assert energy_per_site(sys) ≈ -2J*S^2","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"Plotting the spins confirms the expected Néel order. Note that the overall, global rotation of dipoles is arbitrary.","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"s0 = sys.dipoles[1,1,1,1]\nplot_spins(sys; color=[s'*s0 for s in sys.dipoles])","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"For numerical efficiency, it will be helpful to work with the smallest possible magnetic supercell. Here, it is the primitive unit cell, which contains just two sites. The variable shape below defines the primitive lattice vectors cryst.prim_latvecs in units of the conventional lattice vectors. This result is used as input to reshape_supercell. The energy per site remains the same, which verifies that the magnetic supercell is valid.","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"shape = cryst.latvecs \\ cryst.prim_latvecs\nsys_prim = reshape_supercell(sys, shape)\n@assert energy_per_site(sys_prim) ≈ -2J*S^2","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"Now estimate 𝒮(𝐪ω) with SpinWaveTheory and an intensity_formula. The mode :perp contracts with a dipole factor to return the unpolarized intensity. The formula also employs lorentzian broadening. The isotropic FormFactor for Cobalt(2+) dampens intensities at large 𝐪.","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"swt = SpinWaveTheory(sys_prim)\nη = 0.4 # (meV)\nkernel = lorentzian(η)\nformfactors = [FormFactor(\"Co2\")]\nformula = intensity_formula(swt, :perp; kernel, formfactors)","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"For the \"single crystal\" result, we may use reciprocal_space_path to construct a path that connects high-symmetry points in reciprocal space. The intensities_broadened function collects intensities along this path for the given set of energy values.","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"qpoints = [[0, 0, 0], [1/2, 0, 0], [1/2, 1/2, 0], [0, 0, 0]]\npath, xticks = reciprocal_space_path(cryst, qpoints, 50)\nenergies = collect(0:0.01:6)\nis = intensities_broadened(swt, path, energies, formula)\n\nfig = Figure()\nax = Axis(fig[1,1]; aspect=1.4, ylabel=\"ω (meV)\", xlabel=\"𝐪 (r.l.u.)\",\n xticks, xticklabelrotation=π/10)\nheatmap!(ax, 1:size(is, 1), energies, is, colormap=:gnuplot2)\nfig","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"A powder measurement effectively involves an average over all possible crystal orientations. We use the function reciprocal_space_shell to sample n wavevectors on a sphere of a given radius (inverse angstroms), and then calculate the spherically-averaged intensity.","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"radii = 0.01:0.02:3 # (1/Å)\noutput = zeros(Float64, length(radii), length(energies))\nfor (i, radius) in enumerate(radii)\n n = 300\n qs = reciprocal_space_shell(cryst, radius, n)\n is = intensities_broadened(swt, qs, energies, formula)\n output[i, :] = sum(is, dims=1) / size(is, 1)\nend\n\nfig = Figure()\nax = Axis(fig[1,1]; xlabel=\"Q (Å⁻¹)\", ylabel=\"ω (meV)\")\nheatmap!(ax, radii, energies, output, colormap=:gnuplot2)\nfig","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"This result can be compared to experimental neutron scattering data from Fig. 5 of Ge et al.","category":"page"},{"location":"examples/02_LSWT_CoRh2O4.html","page":"2. Spin wave simulations of CoRh₂O₄","title":"2. Spin wave simulations of CoRh₂O₄","text":"","category":"page"},{"location":"writevtk.html#ParaView-Rendering","page":"ParaView Rendering","title":"ParaView Rendering","text":"","category":"section"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"The 4D correlation data produced by Sunny is too high-dimensional to visualize directly. This page describes how to export 3D slices of correlation data from Sunny to the Visual ToolKit (VTK) format, which is compatible with the ParaView visualization software. ParaView supports volumetric rendering:","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"","category":"page"},{"location":"writevtk.html#Simulation-data","page":"ParaView Rendering","title":"Simulation data","text":"","category":"section"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"First, generate some correlation data in Sunny. We will use a 2D lattice, since the correlation data S(Q_xQ_yomega) is 3D and can be exported in its entirety. The following code sets up the system, thermalizes it, and records the correlation data in a SampledCorrelations called dsf.","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"using Sunny\n\n# Single layer 12x12 periodic square lattice\nlatsize = (12,12,1)\n\nlatvecs = lattice_vectors(8.,8.,12.,90,100,90)\npositions = [[0,0,0]]\ntypes = [\"Cu\"]\nformfactors = [FormFactor(\"Cu2\")]\nxtal = Crystal(latvecs, positions; types)\n\nsys = System(xtal, latsize, [SpinInfo(1, S=1/2, g=2)], :SUN; seed=1)\n\nJ = 10.\nset_exchange!(sys, J, Bond(1,1,[1,0,0]))\nset_exchange!(sys, J, Bond(1,1,[0,1,0]))\n\nΔt = 0.01\nkT = 0.5\nlangevin = Langevin(Δt; λ=0.5, kT)\nrandomize_spins!(sys)\nfor i in 1:10_000 # Long enough to reach equilibrium\n step!(sys, langevin)\nend \n\nωmax=10.\n\ndsf = dynamical_correlations(sys\n ;Δt=Δt\n ,nω=48\n ,ωmax=ωmax\n ,process_trajectory=:symmetrize)\n\nnsamples = 10\nfor _ in 1:nsamples\n for _ in 1:1000 \n step!(sys, langevin)\n end\n add_sample!(dsf, sys)\nend","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"The default histogram BinningParameters are already integrated over the z direction because the system is 2D:","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"unit_resolution_binning_parameters(dsf)","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"⊡ 12 bins from -0.042 to +0.958 along [+1.27 dx] (Δ = 0.065)\n⊡ 12 bins from -0.042 to +0.958 along [+1.27 dy] (Δ = 0.065)\n∫ Integrated from +0.000 to +0.000 along [-0.33 dx +1.88 dz] (Δ = 0.524)\n⊡ 48 bins from -0.107 to +10.134 along [+1.00 dE] (Δ = 0.213)","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"The histogram is very oblong; it's approximately 1x1x10. To make it a nicer shape, we will rescale the energy axis to be be fractions of ωmax:","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"params = unit_resolution_binning_parameters(dsf)\nscale_factor = ωmax\nparams.binend[4] /= scale_factor\nparams.binstart[4] /= scale_factor\nparams.binwidth[4] /= scale_factor\nparams.covectors[4,:] ./= scale_factor","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"Doing this changes the last axis of the histogram to fit in [0,1]:","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"⊡ 49 bins from -0.011 to +1.013 along [+0.10 dE] (Δ = 0.213)","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"Now that our histogram is a cube, we compute the intensity in the histogram bins using the usual intensities_binned:","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"formula = intensity_formula(dsf,:trace)\nsignal, counts = intensities_binned(dsf, params; formula)\nintensity = signal ./ counts","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"Now that we have our intensity data and the binning parameters, we can export to VTK format using export_vtk and move to ParaView for the visualization.","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"# Importing WriteVTK enables Sunny's export-to-VTK functions\nimport WriteVTK\n\n# [1,2,4] specifies that the (x,y,z) axes in ParaView are (Qx,Qy,ω)\nexport_vtk(\"square_lattice\", params, intensity; dims_kept = [1,2,4])\n# Writes a file square_lattice.vti in the current directory","category":"page"},{"location":"writevtk.html#Loading-in-ParaView","page":"ParaView Rendering","title":"Loading in ParaView","text":"","category":"section"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"In ParaView, use File > Open to open square_lattice.vti. This will add the file to the Pipeline Browser with a closed eye icon, indicating that the data is ready to be loaded.","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"In the Properties panel, both bin_centers and data will be selected for import by default. Uncheck bin_centers because we don't need that information for the visualization. Click the green Apply button to load the data.","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"By default, only the outline of the data is shown in the 3D viewport. Since we adjusted the energy axis, the outline is a 1x1x1 cube. Optionally enable the axes grid under \"View\", and customize using the adjacent edit button.","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"To enable the volumetric render:","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"Select \"Volume\" from the \"Representation\" drop-down menu under \"Display\".\nThe \"Coloring\" drop-down should automatically select data because it's the only data loaded.\nOpen the Color Map Editor to adjust the opacity of the fog, which may be too faint to see by default.","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"Depending on your computer and your dataset size, the volumetric rendering may be slow, but our dataset is relatively small, so the render should be fast.","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"If nothing shows up at first, don't despair. Often, there are Bragg-like peaks in the correlation data which outshine everything else. To see this, enable Display Data Histogram in the Color Map Editor panel. To zoom in on the lower-intensity data, click and drag the right side handle of the opacity transfer function box to the middle a few times.","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"After suitable color mapping, the dispersion curve should become visible:","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"","category":"page"},{"location":"writevtk.html#Experiment-data","page":"ParaView Rendering","title":"Experiment data","text":"","category":"section"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"Note that since only the data and binning parameters are required for exporting to VTK, experiment data can be exported in the same way. For example, to visualize S(Q_xQ_yQ_z), do this:","category":"page"},{"location":"writevtk.html","page":"ParaView Rendering","title":"ParaView Rendering","text":"# Load 4D histogram data from Mantid\nparams, signal = load_nxs(\"experiment_data.nxs\")\n\n# Integrate out the energy axis so we are 3D\nintegrate_axes!(params; axes = 4)\nsignal = sum(signal; dims = 4)\n\n# Export to ParaView\nexport_vtk(\"experiment_data_as_vtk\", params, signal)","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"EditURL = \"../../../examples/04_GSD_FeI2.jl\"","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"Download this example as Jupyter notebook or Julia script.","category":"page"},{"location":"examples/04_GSD_FeI2.html#.-Generalized-spin-dynamics-of-FeI-at-finite-*T*","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"","category":"section"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"using Sunny, LinearAlgebra, GLMakie","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"In the previous FeI₂ tutorial, we used multi-flavor spin wave theory to calculate the dynamical structure factor. Here, we perform a similar calculation using classical spin dynamics at finite temperature. Because we are interested in the coupled dynamics of spin dipoles and quadrupoles, we employ a classical dynamics of SU(3) coherent states that generalizes the Landau-Lifshitz equation.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"Compared to LSWT, simulations using classical dynamics are much slower, and are limited in k-space resolution. However, they make it is possible to capture nonlinear effects associated with finite temperature fluctuations. Classical dynamics are also appealing for studying out-of-equilibrium systems (e.g., relaxation of spin glasses), or systems with quenched inhomogeneities that require large simulation volumes.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"In this tutorial, we show how to study the finite temperature dynamics of FeI₂ using the classical approach. It is important to stress that the estimation of S(𝐪ω) with classical dynamics is fundamentally a Monte Carlo calculation: sample spin configurations are drawn from thermal equilibrium and used as initial conditions for generating dissipationless trajectories. The correlations of these trajectories are then averaged and used to calculate scattering intensities. It is therefore important to ensure that the initial spin configurations are sampled appropriately and that sufficient statistics are collected. We will demonstrate one approach here.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"As an overview, we will:","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"Identify the ground state\nMeasure correlation data describing the excitations around that ground state\nUse the correlation data to compute scattering intensities","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"As the implementation of the FeI₂ model is already covered in detail in the LSWT tutorial, we will not repeat it below. Instead, we will assume that you already have defined a sys in the same way with lattice dimensions 444.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"a = b = 4.05012#hide\nc = 6.75214#hide\nlatvecs = lattice_vectors(a, b, c, 90, 90, 120)#hide\npositions = [[0,0,0], [1/3, 2/3, 1/4], [2/3, 1/3, 3/4]]#hide\ntypes = [\"Fe\", \"I\", \"I\"]#hide\nFeI2 = Crystal(latvecs, positions; types)#hide\ncryst = subcrystal(FeI2, \"Fe\")#hide\nsys = System(cryst, (4,4,4), [SpinInfo(1,S=1,g=2)], :SUN, seed=2)#hide\nJ1pm = -0.236#hide\nJ1pmpm = -0.161#hide\nJ1zpm = -0.261#hide\nJ2pm = 0.026#hide\nJ3pm = 0.166#hide\nJ′0pm = 0.037#hide\nJ′1pm = 0.013#hide\nJ′2apm = 0.068#hide\nJ1zz = -0.236#hide\nJ2zz = 0.113#hide\nJ3zz = 0.211#hide\nJ′0zz = -0.036#hide\nJ′1zz = 0.051#hide\nJ′2azz = 0.073#hide\nJ1xx = J1pm + J1pmpm#hide\nJ1yy = J1pm - J1pmpm#hide\nJ1yz = J1zpm#hide\nset_exchange!(sys, [J1xx 0.0 0.0; 0.0 J1yy J1yz; 0.0 J1yz J1zz], Bond(1,1,[1,0,0]))#hide\nset_exchange!(sys, [J2pm 0.0 0.0; 0.0 J2pm 0.0; 0.0 0.0 J2zz], Bond(1,1,[1,2,0]))#hide\nset_exchange!(sys, [J3pm 0.0 0.0; 0.0 J3pm 0.0; 0.0 0.0 J3zz], Bond(1,1,[2,0,0]))#hide\nset_exchange!(sys, [J′0pm 0.0 0.0; 0.0 J′0pm 0.0; 0.0 0.0 J′0zz], Bond(1,1,[0,0,1]))#hide\nset_exchange!(sys, [J′1pm 0.0 0.0; 0.0 J′1pm 0.0; 0.0 0.0 J′1zz], Bond(1,1,[1,0,1]))#hide\nset_exchange!(sys, [J′2apm 0.0 0.0; 0.0 J′2apm 0.0; 0.0 0.0 J′2azz], Bond(1,1,[1,2,1]))#hide\nD = 2.165#hide\nset_onsite_coupling!(sys, S -> -D*S[3]^2, 1)#hide\nsys","category":"page"},{"location":"examples/04_GSD_FeI2.html#Finding-a-ground-state","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"Finding a ground state","text":"","category":"section"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"Sunny uses the Langevin dynamics of SU(N) coherent states to sample spin configurations from the thermal equlibrium. One first constructs a Langevin integrator. This requires a time step, temperature, and a phenomenological damping parameter λ that sets the coupling to the thermal bath.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"Δt = 0.05/D # Should be inversely proportional to the largest energy scale\n # in the system. For FeI2, this is the easy-axis anisotropy,\n # `D = 2.165` (meV). The prefactor 0.05 is relatively small,\n # and achieves high accuracy.\nkT = 0.2 # Temperature of the thermal bath (meV).\nλ = 0.1 # This value is typically good for Monte Carlo sampling,\n # independent of system details.\n\nlangevin = Langevin(Δt; kT, λ);\nnothing #hide","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"Langevin dynamics can be used to search for a magnetically ordered state. For this, the temperature kT must be below the ordering temperature, but large enough that the dynamical sampling procedure can overcome local energy barriers and eliminate defects.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"randomize_spins!(sys)\nfor _ in 1:20_000\n step!(sys, langevin)\nend","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"Although thermal fluctuations are present, the correct antiferromagnetic order (2 up, 2 down) is apparent.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"plot_spins(sys; color=[s[3] for s in sys.dipoles])","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"For other systems, it can be much harder to find the magnetic ordering in an unbiased way, and more complicated sampling procedures may be necessary.","category":"page"},{"location":"examples/04_GSD_FeI2.html#Calculating-Thermal-Averaged-Correlations-\\langle-S{\\alpha\\beta}(𝐪,ω)\\rangle","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"Calculating Thermal-Averaged Correlations langle S^alphabeta(𝐪ω)rangle","text":"","category":"section"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"Our aim is to study the classical spin dynamics for states sampled in thermal equilibrium. To minimize finite size effects, and achieve sufficient momentum space resolution, we should significantly enlarge the system volume. The function resize_supercell takes new dimensions as multiples of the unit cell lattice vectors.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"sys_large = resize_supercell(sys, (16,16,4)) # 16x16x4 copies of the original unit cell\nplot_spins(sys_large; color=[s[3] for s in sys_large.dipoles])","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"Now we will re-thermalize the system to a configuration just above the ordering temperature. Sunny expects energies in meV by default, so we use meV_per_K to convert from kelvin.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"kT = 3.5 * meV_per_K # 3.5K ≈ 0.30 meV\nlangevin.kT = kT\nfor _ in 1:10_000\n step!(sys_large, langevin)\nend","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"The next step is to collect correlation data S^alphabeta. This will involve sampling spin configurations from thermal equilibrium, and then integrating the Hamiltonian dynamics of SU(N) coherent states to collect Fourier-space information about normal modes. Quantization of these modes yields the magnons, and the associated dynamical spin-spin correlations can be compared with neutron scattering intensities S^alphabeta(qomega). Because this a real-space calculation, data is only available for discrete q modes (the resolution scales like inverse system size).","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"To store the correlation data, we initialize a SampledCorrelations object by calling dynamical_correlations. It requires three keyword arguments: an integration step size, a target number of ωs to retain, and a maximum energy ω to resolve. For the time step, twice the value used for the Langevin integrator is usually a good choice.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"sc = dynamical_correlations(sys_large; Δt=2Δt, nω=120, ωmax=7.5)","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"The function add_sample! will collect data by running a dynamical trajectory starting from the current system configuration.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"add_sample!(sc, sys_large) # Accumulate the sample into `sc`","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"To collect additional data, it is required to re-sample the spin configuration from the thermal distribution. For efficiency, the dynamics should be run long enough that consecutive samples are uncorrelated.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"for _ in 1:2\n for _ in 1:1000 # Enough steps to decorrelate spins\n step!(sys_large, langevin)\n end\n add_sample!(sc, sys_large) # Accumulate the sample into `sc`\nend","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"Now, sc has more samples included:","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"sc","category":"page"},{"location":"examples/04_GSD_FeI2.html#Computing-Scattering-Intensities","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"Computing Scattering Intensities","text":"","category":"section"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"With the thermally-averaged correlation data langle S^alphabeta(qomega)rangle in hand, we now need to specify how to extract a scattering intensity from this information. This is done by constructing an intensity_formula. By way of example, we will use a formula which computes the trace of the structure factor and applies a classical-to-quantum temperature-dependent rescaling kT.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"formula = intensity_formula(sc, :trace; kT)","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"Recall that langle S^alphabeta(qomega)rangle is only available at certain discrete q values, due to the finite lattice size. There are two basic approaches to handling this discreteness. The first approach is to interpolate between the available data using intensities_interpolated. For example, we can plot single-q slices at (0,0,0) and (π,π,π) using this method:","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"qs = [[0, 0, 0], [0.5, 0.5, 0.5]]\nis = intensities_interpolated(sc, qs, formula; interpolation = :round)\n\nωs = available_energies(sc)\nfig = lines(ωs, is[1,:]; axis=(xlabel=\"meV\", ylabel=\"Intensity\"), label=\"(0,0,0)\")\nlines!(ωs, is[2,:]; label=\"(π,π,π)\")\naxislegend()\nfig","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"The resolution in energy can be improved by increasing nω (and decreasing Δt), and the general accuracy can be improved by collecting additional samples from the thermal equilibrium.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"For real calculations, one often wants to apply further corrections and more accurate formulas. Here, we apply FormFactor corrections appropriate for Fe2 magnetic ions, and a dipole polarization correction :perp.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"formfactors = [FormFactor(\"Fe2\"; g_lande=3/2)]\nnew_formula = intensity_formula(sc, :perp; kT, formfactors = formfactors)","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"Frequently, one wants to extract energy intensities along lines that connect special wave vectors–a so-called \"spaghetti plot\". The function reciprocal_space_path creates an appropriate horizontal axis for this plot by linearly sampling between provided q-points with a given sample density. The number of sample points between two wavevectors q1 and q2 is given by dist*density where dist = norm(cryst.recipvecs * (q1 - q2)) is measured in the global frame.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"points = [[0, 0, 0], # List of wave vectors that define a path\n [1, 0, 0],\n [0, 1, 0],\n [1/2, 0, 0],\n [0, 1, 0],\n [0, 0, 0]]\ndensity = 40\npath, xticks = reciprocal_space_path(cryst, points, density);\nnothing #hide","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"Again using intensities_interpolated, we can evaluate the (interpolated) intensity at each point on the path. Since scattering intensities are only available at a certain discrete (Qomega) points, the intensity on the path can be calculated by interpolating between these discrete points:","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"is_interpolated = intensities_interpolated(sc, path, new_formula;\n interpolation = :linear, # Interpolate between available wave vectors\n);\n# Add artificial broadening\nis_interpolated_broadened = broaden_energy(sc, is, (ω, ω₀)->lorentzian(ω-ω₀, 0.05));\nnothing #hide","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"The second approach to handle the discreteness of the data is to bin the intensity at the discrete points into the bins of a histogram. First, the five sub-histograms are set up using reciprocal_space_path_bins in analogy to reciprocal_space_path.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"cut_width = 0.3\ndensity = 15\nparamsList, markers, ranges = reciprocal_space_path_bins(sc,points,density,cut_width);\nnothing #hide","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"Then, the intensity data is computed using intensities_binned for each sub-histogram:","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"total_bins = ranges[end][end]\nenergy_bins = paramsList[1].numbins[4]\nis_binned = zeros(Float64,total_bins,energy_bins)\nintegrated_kernel = integrated_lorentzian(0.05) # Lorentzian broadening\nfor k in eachindex(paramsList)\n bin_data, counts = intensities_binned(sc,paramsList[k], new_formula;\n integrated_kernel = integrated_kernel\n )\n is_binned[ranges[k],:] = bin_data[:,1,1,:] ./ counts[:,1,1,:]\nend","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"The graph produced by interpolating (top) is similar to the one produced by binning (bottom):","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"fig = Figure()\nax_top = Axis(fig[1,1],ylabel = \"meV\",xticklabelrotation=π/8,xticklabelsize=12;xticks)\nax_bottom = Axis(fig[2,1],ylabel = \"meV\",xticks = (markers, string.(points)),xticklabelrotation=π/8,xticklabelsize=12)\n\nheatmap!(ax_top,1:size(is_interpolated,1), ωs, is_interpolated;\n colorrange=(0.0,0.07),\n)\n\nheatmap!(ax_bottom,1:size(is_binned,1), ωs, is_binned;\n colorrange=(0.0,0.05),\n)\n\nfig","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"Note that we have clipped the colors in order to make the higher-energy excitations more visible.","category":"page"},{"location":"examples/04_GSD_FeI2.html#Unconventional-RLU-Systems-and-Constant-Energy-Cuts","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"Unconventional RLU Systems and Constant Energy Cuts","text":"","category":"section"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"Often it is useful to plot cuts across multiple wave vectors but at a single energy. We'll pick an energy,","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"ωidx = 60\ntarget_ω = ωs[ωidx]","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"and take a constant-energy cut at that energy. The most straightforward way is to make a plot whose axes are aligned with the conventional reciprocal lattice of the crystal. This is accomplished using unit_resolution_binning_parameters:","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"params = unit_resolution_binning_parameters(sc)\nparams.binstart[1:2] .= -1 # Expand plot range slightly\n\n# Set energy integration range\nomega_width = 0.3\nparams.binstart[4] = target_ω - (omega_width/2)\nparams.binend[4] = target_ω # `binend` should be inside (e.g. at the center) of the range\nparams.binwidth[4] = omega_width\n\nintegrate_axes!(params, axes = 3) # Integrate out z direction entirely\n\nparams","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"In each of the following plots, black dashed lines represent (direct) lattice vectors. Since these plots are in reciprocal space, direct lattice vectors are represented as covectors (i.e. coordinate grids) instead of as arrows.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"is, counts = intensities_binned(sc,params,new_formula)\n\nfig = Figure()\nax = Axis(fig[1,1];\n title=\"Δω=0.3 meV (Binned)\", aspect=true,\n xlabel = \"[H, 0, 0]\",\n ylabel = \"[0, K, 0]\"\n)\nbcs = axes_bincenters(params)\nhm = heatmap!(ax,bcs[1],bcs[2],is[:,:,1,1] ./ counts[:,:,1,1])\nfunction add_lines!(ax,params)#hide\n bes = Sunny.axes_binedges(params)#hide\n hrange = range(-2,2,length=17)#hide\n linesegments!(ax,[(Point2f(params.covectors[1,1:3] ⋅ [h,-10,0],params.covectors[2,1:3] ⋅ [h,-10,0]),Point2f(params.covectors[1,1:3] ⋅ [h,10,0],params.covectors[2,1:3] ⋅ [h,10,0])) for h = hrange],linestyle=:dash,color=:black)#hide\n krange = range(-2,2,length=17)#hide\n linesegments!(ax,[(Point2f(params.covectors[1,1:3] ⋅ [-10,k,0],params.covectors[2,1:3] ⋅ [-10,k,0]),Point2f(params.covectors[1,1:3] ⋅ [10,k,0],params.covectors[2,1:3] ⋅ [10,k,0])) for k = krange],linestyle=:dash,color=:black)#hide\n xlims!(ax,bes[1][1],bes[1][end])#hide\n ylims!(ax,bes[2][1],bes[2][end])#hide\nend#hide\nadd_lines!(ax,params)\nColorbar(fig[1,2], hm);\nfig","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"In the above plot, the dashed-line (direct) lattice vectors are clearly orthogonal. However, we know that in real space, the lattice vectors a and b are not orthogonal, but rather point along the edges of a hexagon (see lower left corner):","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"

    ","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"Thus, plotting the direct lattice vectors as orthogonal (even in reciprocal space) is somewhat misleading. Worse yet, the [H,0,0] by [0,K,0] plot apparently loses the 6-fold symmetry of the crystal! Lastly, if one works out the components of the real-space metric with respect to the axes of the plot, one finds that there are non-zero off-diagonal entries,","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"latvecs = sys.crystal.latvecs\nmetric = latvecs' * I(3) * latvecs","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"so real-space rotations and angles map into reciprocal space rotations angles in a complicated way.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"To resolve these important issues, we want to use axes which are orthogonal (i.e. they diagonalize the metric and solve all of the problems just mentioned). The canonical choice is to use the combination frac12a + b of lattice vectors (equiv. a^* - frac12b^*), which is orthogonal to a:","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"(latvecs * [1/2,1,0]) ⋅ (latvecs * [1,0,0]) == 0","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"This new vector frac12a+b is visibly orthogonal to a in real space:","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"f = Figure()#hide\nax = Axis(f[1,1])#hide\narrows!(ax,[Point2f(0,0),Point2f(latvecs[1:2,1] ./ 2)],[Vec2f(latvecs[1:2,1] ./ 2), Vec2f(latvecs[1:2,2])],arrowcolor = :blue,arrowsize = 30.,linewidth = 5.,linecolor = :blue)#hide\narrows!(ax,[Point2f(0,0)],[Vec2f(latvecs[1:2,:] * [1/2,1,0])],arrowcolor = :red,arrowsize = 30.,linewidth = 5.,linecolor = :red, linestyle = :dash)#hide\nscatter!(ax,[Point2f(latvecs[1:2,:] * [a,b,0]) for a in -1:1, b in -1:1][:],color = :black)#hide\nannotations!(ax,[\"0\",\"0+b\",\"0+a\", \"a/2\", \"b\"],[Point2f(0,-0.3),Point2f(latvecs[1:2,2]) .- Vec2f(0,0.3),Point2f(latvecs[1:2,1]) .- Vec2f(0,0.3),Point2f(latvecs[1:2,1] ./ 4) .- Vec2f(0,0.3),Point2f(latvecs[1:2,1] ./ 2) .+ Vec2f(latvecs[1:2,2] ./ 2) .+ Vec2f(0.3,0.3)],color=[:black,:black,:black,:blue,:blue])#hide\nf#hide","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"To use \"projection onto the new vector\" as a histogram axis, only a single change is needed to the binning parameters. The second covector (previously b) must be swapped out for frac12a + b (recall that reciprocal space covectors, such as those used in BinningParameters correspond to direct space vectors).","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"params.covectors[2,1:3] = [1/2,1,0] # [1/2,1,0] times [a;b;c] is (a/2 + b)\nparams#hide","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"The second axis of the histogram now agrees with what is conventionally labelled as [H,-H/2,0].","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"warning: Length of the new vector\nNote that, although frac12a+b is orthogonal to a, it is not the same length as a. Instead, it is sqrt(3/4) times as long. Note the unsymmetrical axes labels in the plots that follow as a direct result of this!","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"# Zoom out horizontal axis\nparams.binstart[1], params.binend[1] = -2, 2\n\n# Adjust vertical axis bounds to account for\n# length of a/2 + b\nparams.binstart[2], params.binend[2] = -2 * sqrt(3/4), 2 * sqrt(3/4)\n\n# Re-compute in the new coordinate system\nis, counts = intensities_binned(sc,params,new_formula)\n\nfig = Figure(; resolution=(1200,500))#hide\nax_right = Axis(fig[1,3];#hide\n title=\"ω≈$(round(target_ω, digits=2)) meV with Δω=0.3 meV (Binned)\", aspect=true,#hide\n xlabel = \"[H, -1/2H, 0]\"#hide\n)#hide\nbcs = axes_bincenters(params)#hide\nhm_right = heatmap!(ax_right,bcs[1],bcs[2],is[:,:,1,1] ./ counts[:,:,1,1])#hide\nadd_lines!(ax_right,params)\nColorbar(fig[1,4], hm_right);#hide\nnothing #hide","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"For comparison purposes, we will make the same plot using intensities_interpolated to emulate zero-width bins. This time, it's more convenient to think in terms of reciprocal vectors a^* and b^*. Now, our coordinate transformation consists of establishing a new, orthogonal basis to specify our wave vectors: a^* - frac12b^*, b^* and c^*. Writing this in matrix form allows us to sample a rectilinear grid of wave vectors in this frame. Finally, we'll convert these back into the original RLU system for input into Sunny.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"# New basis matrix\nA = [1 0 0\n -1/2 1 0\n 0 0 1]\n\n# Define our grid of wave vectors\nnpoints = 60\nas = range(-2, 2, npoints)\nbs = range(-3/√3, 3/√3, npoints)\nqs_ortho = [[a, b, 0] for a in as, b in bs]\n\n# Convert to original RLU system for input to Sunny\nqs = [A * q for q in qs_ortho]\n\n# Use interpolation to get intensities\nis = intensities_interpolated(sc, qs, new_formula; interpolation=:linear)\n\nax_left = Axis(fig[1,2];#hide\n title=\"ω≈$(round(ωs[ωidx], digits=2)) meV (Interpolated)\", aspect=true,#hide\n xlabel = \"[H, -1/2H, 0]\", ylabel = \"[0, K, 0]\"#hide\n)#hide\nhm_left = heatmap!(ax_left, as, bs, is[:,:,ωidx])#hide\nadd_lines!(ax_left,params)\nColorbar(fig[1,1], hm_left);#hide\nfig","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"Now, not only are the dashed-line lattice vectors no longer misleadingly orthogonal, but the six-fold symmetry has been restored as well! Further, the metric has been diagonalized:","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"metric = (latvecs * inv(A'))' * I(3) * (latvecs * inv(A'))","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"Finally, we note that instantaneous structure factor data, 𝒮(𝐪), can be obtained from a dynamic structure factor with instant_intensities_interpolated. Here we'll reuse the grid of wave vectors we generated above.","category":"page"},{"location":"examples/04_GSD_FeI2.html","page":"4. Generalized spin dynamics of FeI₂ at finite T","title":"4. Generalized spin dynamics of FeI₂ at finite T","text":"is_static = instant_intensities_interpolated(sc, qs, new_formula; interpolation = :linear)\n\nhm = heatmap(as, bs, is_static;\n axis=(\n title=\"Instantaneous Structure Factor\",\n xlabel = \"[H, -1/2H, 0]\",\n ylabel = \"[0, K, 0]\",\n aspect=true\n )\n)\nColorbar(hm.figure[1,2], hm.plot)\nhm","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"EditURL = \"../../../examples/06_CP2_Skyrmions.jl\"","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"Download this example as Jupyter notebook or Julia script.","category":"page"},{"location":"examples/06_CP2_Skyrmions.html#.-Dynamical-quench-into-CP-skyrmion-liquid","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"","category":"section"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"This example demonstrates Sunny's ability to simulate the out-of-equilibrium dynamics of generalized spin systems. We will implement the model Hamiltonian of Zhang et al., Nature Communications 14, 3626 (2023), which supports a novel type of topological defect, a CP² skyrmion, that involves both the dipolar and quadrupolar parts of a quantum spin.","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"Beginning from an initial high-temperature state, a disordered gas of CP² skyrmions can be formed by rapidly quenching to low temperature. To model the coupled dynamics of dipoles and quadrupoles, Sunny uses a recently developed generalization of the Landau-Lifshitz spin dynamics, Dahlbom et al., Phys. Rev. B 106, 235154 (2022).","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"using Sunny, GLMakie","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"The Hamiltonian we will implement,","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"mathcalH = sum_langle ij rangle J_ij( hatS_i^x hatS_j^x + hatS_i^y hatS_j^y + DeltahatS_i^z hatS_j^z) - hsum_ihatS_i^z + Dsum_i(hatS_i^z)^2","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"contains competing ferromagnetic nearest-neightbor and antiferromagnetic next-nearest-neighbor exchange terms on a triangular lattice. Both exchanges exhibit anisotropy on the z-term. Additionally, there is an external magnetic field, h, and easy-plane single-ion anisotropy, D 0. We begin by implementing the Crystal.","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"lat_vecs = lattice_vectors(1.0, 1.0, 2.0, 90, 90, 120)\nbasis_vecs = [[0,0,0]]\ncryst = Crystal(lat_vecs, basis_vecs)","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"The crystal is then used to create a spin System. All parameters in this model system are dimensionless, so we select \"theory\" units and set the g-factor to one.","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"L = 40\ndims = (L, L, 1)\nsys = System(cryst, dims, [SpinInfo(1, S=1, g=1)], :SUN; seed=101, units=Units.theory)","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"We proceed to implement each term of the Hamiltonian, selecting our parameters so that the system occupies a region of the phase diagram that supports skyrmions. The exchange interactions are set as follows.","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"J1 = -1 # Nearest-neighbor ferromagnetic\nJ2 = (2.0/(1+√5)) # Tune competing exchange to set skyrmion scale length\nΔ = 2.6 # Exchange anisotropy\n\nex1 = J1 * [1.0 0.0 0.0;\n 0.0 1.0 0.0;\n 0.0 0.0 Δ]\nex2 = J2 * [1.0 0.0 0.0;\n 0.0 1.0 0.0;\n 0.0 0.0 Δ]\nset_exchange!(sys, ex1, Bond(1, 1, [1, 0, 0]))\nset_exchange!(sys, ex2, Bond(1, 1, [1, 2, 0]))","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"Next we add the external field,","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"h = 15.5\nfield = set_external_field!(sys, [0.0 0.0 h])","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"and finally an easy-plane single-ion anisotropy,","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"D = 19.0\nset_onsite_coupling!(sys, S -> D*S[3]^2, 1)","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"Initialize system to an infinite temperature (fully randomized) initial condition.","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"randomize_spins!(sys)","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"We are now ready to simulate the quenching process using a generalized Langevin spin dynamics. If we were working with spin dipoles only, then Langevin dynamics would be the usual Landau-Lifshitz spin dynamics, augmented with damping and noise terms. In the present study, we are instead working with quantum spin-1 (an (N=3)-level system that includes both dipoles and quadrupoles). Here, Langevin captures the coupled dipole-quadrupole dynamics using the formalism of SU(N) coherent states.","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"Selecting kT = 0 in the Langevin dynamics will effective disable the noise term. Then the parameter λ effectively determines the damping time-scale.","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"Δt = 0.2/D # Integration time step (inverse meV). Typically this will be\n # inversely proportional to the largest energy scale in the\n # system. We can use a fairly large time-step here because\n # accuracy isn't critical.\nkT = 0 # Target equilibrium temperature (meV)\nλ = 0.1 # Magnitude of coupling to thermal bath (dimensionless)\nintegrator = Langevin(Δt; kT, λ)","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"Finally we run the dynamics. We will record the state of the system at three different times during the quenching process by copying the coherents field of the System.","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"τs = [4., 16, 256] # Times to record snapshots\nframes = [] # Empty array to store snapshots\nfor i in eachindex(τs)\n dur = i == 1 ? τs[1] : τs[i] - τs[i-1] # Determine the length of time to simulate\n numsteps = round(Int, dur/Δt)\n for _ in 1:numsteps # Perform the integration\n step!(sys, integrator)\n end\n push!(frames, copy(sys.coherents)) # Save a snapshot spin configuration\nend","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"To visualize the state of the system contained in each snapshot, we will calculate and plot the skyrmion density on each plaquette of our lattice. The function plot_triangular_plaquettes is not part of the core Sunny package, but rather something you could define yourself. We are using the definition in plotting2d.jl from the Sunny examples/extra directory.","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"include(pkgdir(Sunny, \"examples\", \"extra\", \"Plotting\", \"plotting2d.jl\"))\n\nfunction sun_berry_curvature(z₁, z₂, z₃)\n z₁, z₂, z₃ = normalize.((z₁, z₂, z₃))\n n₁ = z₁ ⋅ z₂\n n₂ = z₂ ⋅ z₃\n n₃ = z₃ ⋅ z₁\n return angle(n₁ * n₂ * n₃)\nend\n\nplot_triangular_plaquettes(sun_berry_curvature, frames; resolution=(1800,600),\n offset_spacing=10, texts = [\"\\tt = \"*string(τ) for τ in τs], text_offset = (0.0, 6.0)\n)","category":"page"},{"location":"examples/06_CP2_Skyrmions.html","page":"6. Dynamical quench into CP² skyrmion liquid","title":"6. Dynamical quench into CP² skyrmion liquid","text":"The times are given in hbarJ_1. The white background corresponds to a quantum paramagnetic state, where the local spin exhibits a strong quadrupole moment and little or no dipole moment. Observe that the process has generated a number of well-formed skyrmions of both positive (red) and negative (blue) charge in addition to a number of other metastable spin configurations. A full-sized version of this figure is available in Dahlbom et al..","category":"page"},{"location":"library.html#Library-API","page":"Library API","title":"Library API","text":"","category":"section"},{"location":"library.html","page":"Library API","title":"Library API","text":"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).","category":"page"},{"location":"library.html","page":"Library API","title":"Library API","text":"","category":"page"},{"location":"library.html","page":"Library API","title":"Library API","text":"Sunny.plot_spins\nSunny.view_crystal\nSunny.export_vtk","category":"page"},{"location":"library.html","page":"Library API","title":"Library API","text":"Modules = [Sunny]\nPrivate = false","category":"page"},{"location":"library.html#Sunny.Site","page":"Library API","title":"Sunny.Site","text":"(cell1, cell2, cell3, i) :: Site\n\nFour 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).\n\nThis 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!.\n\nNote 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.\n\n\n\n\n\n","category":"type"},{"location":"library.html#Sunny.Units","page":"Library API","title":"Sunny.Units","text":"Units.meV\nUnits.theory\n\nThe 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.\n\nSee also meV_per_K\n\n\n\n\n\n","category":"constant"},{"location":"library.html#Sunny.meV_per_K","page":"Library API","title":"Sunny.meV_per_K","text":"meV_per_K = 0.086173332621451774\n\nA physical constant. Useful for converting kelvin into the default energy units, meV.\n\n\n\n\n\n","category":"constant"},{"location":"library.html#Sunny.BinningParameters","page":"Library API","title":"Sunny.BinningParameters","text":"BinningParameters(binstart,binend,binwidth;covectors = I(4))\nBinningParameters(binstart,binend;numbins,covectors = I(4))\n\nDescribes 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.\n\nThe 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.\n\nThe convention for the binning scheme is that:\n\nThe left edge of the first bin starts at binstart\nThe bin width is binwidth\nThe last bin contains binend\nThere are no \"partial bins;\" the last bin may contain values greater than binend. C.f. count_bins.\n\nA value can be binned by computing its bin index:\n\ncoords = covectors * value\nbin_ix = 1 .+ floor.(Int64,(coords .- binstart) ./ binwidth)\n\n\n\n\n\n","category":"type"},{"location":"library.html#Sunny.Bond","page":"Library API","title":"Sunny.Bond","text":"Bond(i, j, n)\n\nRepresents a bond between atom indices i and j. n is a vector of three integers specifying unit cell displacement in terms of lattice vectors.\n\n\n\n\n\n","category":"type"},{"location":"library.html#Sunny.Crystal","page":"Library API","title":"Sunny.Crystal","text":"An object describing a crystallographic unit cell and its space group symmetry. Constructors are as follows:\n\nCrystal(filename; symprec=1e-5)\n\nReads the crystal from a .cif file located at the path filename. The optional parameter symprec controls the precision tolerance for spacegroup symmetries.\n\nCrystal(latvecs, positions; types=nothing, symprec=1e-5)\n\nConstructs 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.\n\nCrystal(latvecs, positions, spacegroup_number; types=nothing, setting=nothing, symprec=1e-5)\n\nBuilds 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.\n\nCurrently, 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.\n\nExamples\n\n# Read a Crystal from a .cif file\nCrystal(\"filename.cif\")\n\n# Build an FCC crystal using the primitive unit cell. The spacegroup number\n# 225 is inferred.\nlatvecs = [1 1 0;\n 1 0 1;\n 0 1 1] / 2\npositions = [[0, 0, 0]]\nCrystal(latvecs, positions)\n\n# Build a CsCl crystal (two cubic sublattices). By providing distinct type\n# strings, the spacegroup number 221 is inferred.\nlatvecs = lattice_vectors(1, 1, 1, 90, 90, 90)\npositions = [[0,0,0], [0.5,0.5,0.5]]\ntypes = [\"Na\", \"Cl\"]\ncryst = Crystal(latvecs, positions; types)\n\n# Build a diamond cubic crystal from its spacegroup number 227. This\n# spacegroup has two possible settings (\"1\" or \"2\"), which determine an\n# overall unit cell translation.\nlatvecs = lattice_vectors(1, 1, 1, 90, 90, 90)\npositions = [[1, 1, 1] / 4]\ncryst = Crystal(latvecs, positions, 227; setting=\"1\")\n\nSee also lattice_vectors.\n\n\n\n\n\n","category":"type"},{"location":"library.html#Sunny.FormFactor-Tuple{String}","page":"Library API","title":"Sunny.FormFactor","text":"FormFactor(ion::String; g_lande=2)\n\nThe 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.\n\nThe parameter ion must be one of the following strings:\n\nAm2, Am3, Am4, Am5, Am6, Am7, Au1, Au2, Au3, Au4, Au5, Ce2, Co0, Co1, Co2, Co3,\nCo4, Cr0, Cr1, Cr2, Cr3, Cr4, Cu0, Cu1, Cu2, Cu3, Cu4, Dy2, Dy3, Er2, Er3, Eu2,\nEu3, Fe0, Fe1, Fe2, Fe3, Fe4, Gd2, Gd3, Hf2, Hf3, Ho2, Ho3, Ir0a, Ir0b, Ir0c,\nIr1a, Ir1b, Ir2, Ir3, Ir4, Ir5, Ir6, Mn0, Mn1, Mn2, Mn3, Mn4, Mo0, Mo1, Nb0,\nNb1, Nd2, Nd3, Ni0, Ni1, Ni2, Ni3, Ni4, Np3, Np4, Np5, Np6, Os0a, Os0b, Os0c,\nOs1a, Os1b, Os2, Os3, Os4, Os5, Os6, Os7, Pd0, Pd1, Pr3, Pt1, Pt2, Pt3, Pt4,\nPt5, Pt6, Pu3, Pu4, Pu5, Pu6, Re0a, Re0b, Re0c, Re1a, Re1b, Re2, Re3, Re4, Re5,\nRe6, Rh0, Rh1, Ru0, Ru1, Sc0, Sc1, Sc2, Sm2, Sm3, Ta2, Ta3, Ta4, Tb2, Tb3, Tc0,\nTc1, Ti0, Ti1, Ti2, Ti3, Tm2, Tm3, U3, U4, U5, V0, V1, V2, V3, V4, W0a, W0b,\nW0c, W1a, W1b, W2c, W3, W4, W5, Y0, Yb2, Yb3, Zr0, Zr1\n\nThe trailing number denotes ionization state. For example, \"Fe0\" denotes a neutral iron atom, while \"Fe2\" denotes Fe²⁺. If multiple electronic configurations are possible, they will be distinguished by a trailing letter (a, b, ...). Omitting this letter will print an informative error,\n\nFormFactor(\"Ir0\")\n\nERROR: Disambiguate form factor according to electronic configuration:\n \"Ir0a\" -- 6s⁰5d⁹\n \"Ir0b\" -- 6s¹5d⁸\n \"Ir0c\" -- 6s²5d⁷\n\nThe form factor is approximated as\n\nF(s) = j_0(s) + frac2-gg j_2(s) s^2,\n\ninvolving the Landé g-factor. The j_l(s) are radial integrals associated with the lth Bessel function of the magnetic dipole, where s = k4π, and k is the magnitude of momentum transfer. \n\nThe 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,\n\nj_0(s) = A e^-as^2 + B e^-bs^2 + C e^-cs^2 + D e^-ds^2 + E \nj_l(s) = (A e^-as^2 + B e^-bs^2 + C e^-cs^2 + D e^-ds^2 + E) s^2\n\nReferences:\n\nhttps://www.ill.eu/sites/ccsl/ffacts/ffachtml.html\nJ. Brown, The Neutron Data Booklet, 2nd ed., Sec. 2.5 Magnetic Form Factors (2003)\nK. Kobayashi, T. Nagao, M. Ito, Acta Cryst. A, 67 pp 473–480 (2011)\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.ImplicitMidpoint","page":"Library API","title":"Sunny.ImplicitMidpoint","text":"ImplicitMidpoint(Δt::Float64; atol=1e-12) where N\n\nEnergy-conserving spin dynamics. One call to the step! function will advance a System by Δt units of time.\n\nUses 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.\n\n\n\n\n\n","category":"type"},{"location":"library.html#Sunny.Langevin","page":"Library API","title":"Sunny.Langevin","text":"Langevin(Δt::Float64; λ::Float64, kT::Float64)\n\nSpin 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.\n\nAssuming 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.\n\nAn alternative approach to sampling is LocalSampler, which may be preferred when the allowed spin values become effective discrete (e.g. Ising spins).\n\n\n\n\n\n","category":"type"},{"location":"library.html#Sunny.LocalSampler","page":"Library API","title":"Sunny.LocalSampler","text":"LocalSampler(; kT, nsweeps=1.0, propose=propose_uniform)\n\nMonte 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.\n\nAssuming ergodicity, the LocalSampler will sample from thermal equilibrium for the target temperature kT. \n\nThe 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.\n\nThe returned object stores fields ΔE and Δs, which represent the cumulative change to the net energy and dipole, respectively.\n\nAn 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!).\n\n\n\n\n\n","category":"type"},{"location":"library.html#Sunny.SampledCorrelations","page":"Library API","title":"Sunny.SampledCorrelations","text":"SampledCorrelations\n\nBasic data type for storing sampled correlation data. A SampleCorrelations is initialized by calling either dynamical_correlations or instant_correlations.\n\n\n\n\n\n","category":"type"},{"location":"library.html#Sunny.SpinInfo","page":"Library API","title":"Sunny.SpinInfo","text":"SpinInfo(atom::Int; S, g=2)\n\nCharacterizes 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.\n\n\n\n\n\n","category":"type"},{"location":"library.html#Sunny.SpinWaveTheory","page":"Library API","title":"Sunny.SpinWaveTheory","text":"SpinWaveTheory(sys, energy_ϵ::Float64=1e-8)\n\nConstructs an object to perform linear spin wave theory. Use it with dispersion and dssf functions.\n\nThe 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.\n\n\n\n\n\n","category":"type"},{"location":"library.html#Sunny.System-Tuple{Crystal, Tuple{Int64, Int64, Int64}, Vector{SpinInfo}, Symbol}","page":"Library API","title":"Sunny.System","text":"System(crystal::Crystal, latsize, infos, mode; units=Units.meV, seed::Int)\n\nConstruct 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.\n\nThe 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. \n\nMode :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.\n\nThe default units system of (meV, Å, tesla) can be overridden by with the units parameter; see Units. \n\nAn optional seed may be provided to achieve reproducible random number generation.\n\nAll spins are initially polarized in the z-direction.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.add_sample!-Tuple{SampledCorrelations, System}","page":"Library API","title":"Sunny.add_sample!","text":"add_sample!(sc::SampledCorrelations, sys::System)\n\nadd_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. \n\nThis 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!.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.available_energies-Tuple{SampledCorrelations}","page":"Library API","title":"Sunny.available_energies","text":"available_energies(sc::SampledCorrelations; negative_energies=false)\n\nReturn 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.available_wave_vectors-Tuple{SampledCorrelations}","page":"Library API","title":"Sunny.available_wave_vectors","text":"available_wave_vectors(sc::SampledCorrelations; bzsize=(1,1,1))\n\nReturns all wave vectors for which sc contains exact values. bsize specifies the number of Brillouin zones to be included.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.axes_bincenters-Tuple{Any, Any, Any}","page":"Library API","title":"Sunny.axes_bincenters","text":"axes_bincenters(params::BinningParameters)\n\nReturns tick marks which label the bins of the histogram described by BinningParameters by their bin centers.\n\nThe following alternative syntax can be used to compute bin centers for a single axis:\n\naxes_bincenters(binstart,binend,binwidth)\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.broaden_energy-Tuple{SampledCorrelations, Any, Function}","page":"Library API","title":"Sunny.broaden_energy","text":"broaden_energy(sc::SampledCorrelations, vals, kernel::Function; negative_energies=false)\n\nPerforms 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:\n\nnewvals = broaden_energy(sc, vals, (ω, ω₀) -> lorentzian(ω-ω₀, 0.2))\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.count_bins-Tuple{Any, Any, Any}","page":"Library API","title":"Sunny.count_bins","text":"count_bins(binstart,binend,binwidth)\n\nReturns the number of bins in the binning scheme implied by binstart, binend, and binwidth. To count the bins in a BinningParameters, use params.numbins.\n\nThis function defines how partial bins are handled, so it should be used preferentially over computing the number of bins manually.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.dispersion-Tuple{SpinWaveTheory, Any}","page":"Library API","title":"Sunny.dispersion","text":"dispersion(swt::SpinWaveTheory, qs)\n\nComputes 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.\n\nThe 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.dmvec-Tuple{Any}","page":"Library API","title":"Sunny.dmvec","text":"dmvec(D)\n\nAntisymmetric matrix representation of the Dzyaloshinskii-Moriya pseudo-vector,\n\n [ 0 D[3] -D[2]\n -D[3] 0 D[1]\n D[2] -D[1] 0 ]\n\nUseful in the context of set_exchange!.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.dssf-Tuple{SpinWaveTheory, Any}","page":"Library API","title":"Sunny.dssf","text":"dssf(swt::SpinWaveTheory, qs)\n\nGiven a SpinWaveTheory object, computes the dynamical spin structure factor,\n\n 𝒮^αβ(𝐤 ω) = 1(2πN)dt _𝐫 expi(ωt - 𝐤𝐫) S^α(𝐫 t)S^β(0 0)\n\nusing the result from linear spin-wave theory,\n\n 𝒮^αβ(𝐤 ω) = _n A_n^αβ(𝐤)^2 δω-ω_n(𝐤)\n\nqs 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.\n\nThe 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 β.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.dynamical_correlations-Union{Tuple{System{N}}, Tuple{N}} where N","page":"Library API","title":"Sunny.dynamical_correlations","text":"dynamical_correlations(sys::System; Δt, nω, ωmax, \n process_trajectory=:none, observables=nothing, correlations=nothing)\n\nCreates 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.\n\nThree keywords are required to specify the dynamics used for the trajectory calculation.\n\nΔ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.\nωmax: The maximum energy, ω, that will be resolved.\nnω: The number of energy bins to calculated between 0 and ωmax.\n\nAdditional keyword options are the following:\n\nobservables: 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.\ncorrelations: 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)].\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.eachsite-Tuple{System}","page":"Library API","title":"Sunny.eachsite","text":"eachsite(sys::System)\n\nAn iterator over all Sites in the system. \n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.enable_dipole_dipole!-Union{Tuple{System{N}}, Tuple{N}} where N","page":"Library API","title":"Sunny.enable_dipole_dipole!","text":"enable_dipole_dipole!(sys::System)\n\nEnables long-range dipole-dipole interactions,\n\n -(μ_04π) _ij (3 (𝐌_j𝐫_ij)(𝐌_i𝐫_ij) - 𝐌_i𝐌_j) 𝐫_ij^3\n\nwhere 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.energy-Union{Tuple{System{N}}, Tuple{N}} where N","page":"Library API","title":"Sunny.energy","text":"energy(sys::System)\n\nThe total system energy. See also energy_per_site.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.energy_per_site-Union{Tuple{System{N}}, Tuple{N}} where N","page":"Library API","title":"Sunny.energy_per_site","text":"energy_per_site(sys::System)\n\nThe total system energy divided by the number of sites.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.generate_mantid_script_from_binning_parameters-Tuple{Any}","page":"Library API","title":"Sunny.generate_mantid_script_from_binning_parameters","text":"generate_mantid_script_from_binning_parameters(params::BinningParameters)\n\nGenerate a Mantid script which bins data according to the given BinningParameters.\n\nwarning: Units\nTake 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.global_position-Tuple{System, Any}","page":"Library API","title":"Sunny.global_position","text":"global_position(sys::System, site::Site)\n\nPosition of a Site in global coordinates.\n\nTo precompute a full list of positions, one can use eachsite as below:\n\npos = [global_position(sys, site) for site in eachsite(sys)]\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.instant_correlations-Tuple{System}","page":"Library API","title":"Sunny.instant_correlations","text":"instant_correlations(sys::System; process_trajectory=:none, observables=nothing, correlations=nothing)\n\nCreates 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.\n\nImportant 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.\n\nThe following optional keywords are available:\n\nobservables: 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.\ncorrelations: 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)].\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.instant_intensities_interpolated-Tuple{SampledCorrelations, Any, Any}","page":"Library API","title":"Sunny.instant_intensities_interpolated","text":"instant_intensities_interpolated(sc::SampledCorrelations, qs; kwargs...)\n\nReturn 𝒮(𝐪) 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.integrate_axes!-Tuple{BinningParameters}","page":"Library API","title":"Sunny.integrate_axes!","text":"integrate_axes!(params::BinningParameters; axes)\n\nIntegrate over one or more axes of the histogram by setting the number of bins in that axis to 1. Examples:\n\nintegrate_axes!(params; axes = [2,3])\nintegrate_axes!(params; axes = 2)\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.integrated_lorentzian-Tuple{Float64}","page":"Library API","title":"Sunny.integrated_lorentzian","text":"integrated_lorentzian(η)\n\nReturns x mapsto atan(xη)π for use with intensities_binned.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.intensities_bands-Tuple{SpinWaveTheory, Any, Sunny.SpinWaveIntensityFormula}","page":"Library API","title":"Sunny.intensities_bands","text":"dispersion, intensities = intensities_bands(swt::SpinWaveTheory, ks, formula::SpinWaveIntensityFormula)\n\nComputes 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.:\n\nformula = intensity_formula(swt, :perp, formula; kernel = delta_function_kernel)\n\nor else the bands will be broadened, and their intensity can not be computed.\n\nThe 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.intensities_binned-Tuple{SampledCorrelations, BinningParameters, Sunny.ClassicalIntensityFormula}","page":"Library API","title":"Sunny.intensities_binned","text":"intensity, counts = intensities_binned(sc::SampledCorrelations, params::BinningParameters, formula; integrated_kernel)\n\nGiven 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.\n\nThe BinningParameters are expected to accept (q,ω) in R.L.U. for the (possibly reshaped) crystal associated with sc.\n\nThis 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.\n\nIf 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 ω.\n\nCurrently, 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].\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.intensities_broadened-Tuple{SpinWaveTheory, Any, Any, Any}","page":"Library API","title":"Sunny.intensities_broadened","text":"intensities_broadened(swt::SpinWaveTheory, ks, ωvals, formula)\n\nComputes 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.:\n\nformula = intensity_formula(swt, :perp; kernel = lorentzian(0.05))\n\nor else the intensity at ωvals which are not exactly on the dispersion curve can not be calculated.\n\nThe 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.\n\nNote that ks is an array of wave vectors of arbitrary dimension. Each element k of ks must be a 3-wavevector in absolute units.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.intensities_interpolated-Tuple{SampledCorrelations, Any, Sunny.ClassicalIntensityFormula}","page":"Library API","title":"Sunny.intensities_interpolated","text":"intensities_interpolated(sc::SampledCorrelations, qs, formula:ClassicalIntensityFormula; interpolation=nothing, negative_energies=false)\n\nThe 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.\n\ninterpolation: 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.\nnegative_energies: If set to true, Sunny will return the periodic extension of the energy axis. Most users will not want this.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.intensity_formula-Tuple{Function, SampledCorrelations, AbstractVector{Int64}}","page":"Library API","title":"Sunny.intensity_formula","text":"formula = intensity_formula(sc::SampledCorrelations)\n\nEstablish 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.\n\nintensity_formula(sc,...; kT = Inf, formfactors = ...)\n\nThere are keyword arguments providing temperature and form factor corrections:\n\nkT: 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.\nformfactors: 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).\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.intensity_formula-Tuple{Function, SampledCorrelations, Any}","page":"Library API","title":"Sunny.intensity_formula","text":"A custom intensity formula can be specifed by providing a function intensity = f(q,ω,correlations) and specifying which correlations it requires:\n\nintensity_formula(f,sc::SampledCorrelations, required_correlations; kwargs...)\n\nThe function is intended to be specified using do notation. For example, this custom formula sums the off-diagonal correlations:\n\nrequired = [(:Sx,:Sy),(:Sy,:Sz),(:Sx,:Sz)]\nintensity_formula(sc,required,return_type = ComplexF64) do k, ω, off_diagonal_correlations\n sum(off_diagonal_correlations)\nend\n\nIf your custom formula returns a type other than Float64, use the return_type keyword argument to flag this.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.intensity_formula-Tuple{Function, SpinWaveTheory, AbstractVector{Int64}}","page":"Library API","title":"Sunny.intensity_formula","text":"formula = intensity_formula(swt::SpinWaveTheory; kernel = ...)\n\nEstablish a formula for computing the scattering intensity by diagonalizing the hamiltonian H(q) using Linear Spin Wave Theory.\n\nIf kernel = delta_function_kernel, then the resulting formula can be used with intensities_bands.\n\nIf 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.:\n\nkernel = Δω -> ...\n\nor a function of both the energy transfer ω and of Δω, e.g.:\n\nkernel = (ω,Δω) -> ...\n\nThe integral of a properly normalized kernel function over all Δω is one.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.intensity_formula-Tuple{SpinWaveTheory, Symbol}","page":"Library API","title":"Sunny.intensity_formula","text":"intensity_formula([swt or sc], contraction_mode::Symbol)\n\nSunny has several built-in formulas that can be selected by setting contraction_mode to one of these values:\n\n:trace (default), which yields operatornametr 𝒮(qω) = _α 𝒮^αα(qω)\n:perp, which contracts 𝒮^αβ(qω) with the dipole factor δ_αβ - q_αq_β, returning the unpolarized intensity.\n:full, which will return all elements 𝒮^αβ(𝐪ω) without contraction.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.lattice_params-Tuple{StaticArraysCore.SMatrix{3, 3, Float64, 9}}","page":"Library API","title":"Sunny.lattice_params","text":"lattice_params(latvecs::Mat3)\n\nCompute the lattice parameters (a b c α β γ) for the three lattice vectors provided as columns of latvecs. The inverse mapping is lattice_vectors.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.lattice_vectors-NTuple{6, Any}","page":"Library API","title":"Sunny.lattice_vectors","text":"lattice_vectors(a, b, c, α, β, γ)\n\nReturn the lattice vectors, as columns of the 33 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.load_nxs-Tuple{Any}","page":"Library API","title":"Sunny.load_nxs","text":"params, signal = load_nxs(filename)\n\nGiven the name of a Mantid-exported MDHistoWorkspace file, load the BinningParameters and the signal from that file.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.lorentzian-Tuple{Any, Any}","page":"Library API","title":"Sunny.lorentzian","text":"lorentzian(x, η)\n\nReturns η(π(x^2 + η^2)).\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.magnetic_moment-Tuple{System, Any}","page":"Library API","title":"Sunny.magnetic_moment","text":"magnetic_moment(sys::System, site::Site)\n\nGet the magnetic moment for a Site. This is the spin dipole multiplied by the Bohr magneton and the local g-tensor.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.merge_correlations-Union{Tuple{Array{SampledCorrelations{N}, 1}}, Tuple{N}} where N","page":"Library API","title":"Sunny.merge_correlations","text":"merge_correlations(scs::Vector{SampledCorrelations)\n\nAccumulate a list of SampledCorrelations into a single, summary SampledCorrelations. Useful for reducing the results of parallel computations.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.minimize_energy!-Union{Tuple{System{N}}, Tuple{N}} where N","page":"Library API","title":"Sunny.minimize_energy!","text":"minimize_energy!(sys::System{N}; maxiters=100, subiters=20,\n method=Optim.ConjugateGradient(), kwargs...) where N\n\nOptimizes 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.polarize_spins!-Union{Tuple{N}, Tuple{System{N}, Any}} where N","page":"Library API","title":"Sunny.polarize_spins!","text":"polarize_spins!(sys::System, dir)\n\nPolarize all spins in the system along the direction dir.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.position_to_site-Tuple{System, Any}","page":"Library API","title":"Sunny.position_to_site","text":"position_to_site(sys::System, r)\n\nConverts 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.\n\nExample\n\n# Find the `site` at the center of a unit cell which is displaced by four\n# multiples of the first lattice vector\nsite = position_to_site(sys, [4.5, 0.5, 0.5])\n\n# Print the dipole at this site\nprintln(sys.dipoles[site])\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.powder_average_binned-Tuple{SampledCorrelations, Any, Sunny.ClassicalIntensityFormula}","page":"Library API","title":"Sunny.powder_average_binned","text":"powder_average_binned(sc::SampledCorrelations, radial_binning_parameters; formula\n ω_binning_parameters, integrated_kernel = nothing, bzsize = nothing)\n\nThis 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.\n\nRadial binning parameters are specified as tuples (start,end,bin_width), e.g. radial_binning_parameters = (0,6π,6π/55).\n\nEnergy broadening is supported in the same way as intensities_binned, and this function accepts the same kind of intensity_formula.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.primitive_cell_shape-Tuple{Crystal}","page":"Library API","title":"Sunny.primitive_cell_shape","text":"primitive_cell_shape(cryst::Crystal)\n\nReturns 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.\n\nExamples\n\n# Valid if `cryst` has not been reshaped\n@assert cryst.prim_latvecs ≈ cryst.latvecs * primitive_cell_shape(cryst)\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.print_bond-Tuple{Crystal, Bond}","page":"Library API","title":"Sunny.print_bond","text":"print_bond(cryst::Crystal, bond::Bond; b_ref::Bond)\n\nPrints 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, ...\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.print_site-Tuple{Any, Any}","page":"Library API","title":"Sunny.print_site","text":"print_site(cryst, i; R=I)\n\nPrint 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.print_stevens_expansion-Tuple{AbstractMatrix}","page":"Library API","title":"Sunny.print_stevens_expansion","text":"function print_stevens_expansion(op)\n\nPrints 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.\n\nExamples\n\nS = spin_matrices(2)\nprint_stevens_expansion(S[1]^4 + S[2]^4 + S[3]^4)\n# Prints: (1/20)𝒪₄₀ + (1/4)𝒪₄₄ + 102/5\n\nS = spin_matrices(Inf)\nprint_stevens_expansion(S[1]^4 + S[2]^4 + S[3]^4)\n# Prints: (1/20)𝒪₄₀ + (1/4)𝒪₄₄ + (3/5)𝒮⁴\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.print_suggested_frame-Tuple{Crystal, Int64}","page":"Library API","title":"Sunny.print_suggested_frame","text":"print_suggested_frame(cryst, i; digits=4)\n\nPrint 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.print_symmetry_table-Tuple{Crystal, Any}","page":"Library API","title":"Sunny.print_symmetry_table","text":"print_symmetry_table(cryst::Crystal, max_dist)\n\nPrint 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.print_wrapped_intensities-Union{Tuple{System{N}}, Tuple{N}} where N","page":"Library API","title":"Sunny.print_wrapped_intensities","text":"print_wrapped_intensities(sys::System; nmax=10)\n\nFor 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 -12 and 12 in reciprocal lattice units (RLU). The output from this function will typically be used as input to suggest_magnetic_supercell.\n\nBecause 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.propose_delta-Tuple{Any}","page":"Library API","title":"Sunny.propose_delta","text":"propose_delta(magnitude)\n\nGenerate 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. \n\nIn :SUN mode, the procedure is analogous, but now involving Gaussian perturbations to each of the N complex components of an SU(N) coherent state.\n\nIn the limit of very large magnitude, this function coincides with propose_uniform.\n\nFor use with LocalSampler.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.propose_flip-Union{Tuple{N}, Tuple{System{N}, Any}} where N","page":"Library API","title":"Sunny.propose_flip","text":"propose_flip\n\nFunction 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.propose_uniform","page":"Library API","title":"Sunny.propose_uniform","text":"propose_uniform\n\nFunction 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.\n\n\n\n\n\n","category":"function"},{"location":"library.html#Sunny.randomize_spins!-Union{Tuple{System{N}}, Tuple{N}} where N","page":"Library API","title":"Sunny.randomize_spins!","text":"randomize_spins!(sys::System)\n\nRandomizes all spins under appropriate the uniform distribution.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.reciprocal_space_path-Tuple{Crystal, Any, Any}","page":"Library API","title":"Sunny.reciprocal_space_path","text":"reciprocal_space_path(cryst::Crystal, qs, density)\n\nReturns 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.\n\nSpecial 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.reciprocal_space_path_bins-Tuple{Any, Any, Any, Vararg{Any}}","page":"Library API","title":"Sunny.reciprocal_space_path_bins","text":"reciprocal_space_path_bins(sc,qs,density,args...;kwargs...)\n\nTakes 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.\n\nAlso 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.).\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.reciprocal_space_shell-Tuple{Crystal, Any, Any}","page":"Library API","title":"Sunny.reciprocal_space_shell","text":"reciprocal_space_shell(cryst::Crystal, radius, n)\n\nSample n points on the reciprocal space sphere with a given radius (units of inverse length).\n\nExamples\n\n# Sample wavevectors on the sphere at fixed density\nreciprocal_space_shell(cryst, r, 4π*r^2*density)\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.reference_bonds-Tuple{Crystal, Float64}","page":"Library API","title":"Sunny.reference_bonds","text":"reference_bonds(cryst::Crystal, max_dist)\n\nReturns 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).\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.remove_periodicity!-Union{Tuple{N}, Tuple{System{N}, Any}} where N","page":"Library API","title":"Sunny.remove_periodicity!","text":"remove_periodicity!(sys::System, dims)\n\nRemove periodic interactions along the dimensions where dims is true. The system must support inhomogeneous interactions via to_inhomogeneous.\n\nExample\n\n# Remove periodic boundaries along the 1st and 3rd dimensions\nremove_periodicity!(sys::System, (true, false, true))\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.repeat_periodically-Union{Tuple{N}, Tuple{System{N}, Tuple{Int64, Int64, Int64}}} where N","page":"Library API","title":"Sunny.repeat_periodically","text":"repeat_periodically(sys::System{N}, counts::NTuple{3,Int}) where N\n\nCreates a System identical to sys but repeated a given number of times in each dimension, specified by the tuple counts.\n\nSee also reshape_supercell.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.reshape_supercell-Union{Tuple{N}, Tuple{System{N}, Any}} where N","page":"Library API","title":"Sunny.reshape_supercell","text":"reshape_supercell(sys::System, shape)\n\nMaps an existing System to a new one that has the shape and periodicity of a requested supercell. The columns of the 33 integer matrix shape represent the supercell lattice vectors measured in units of the original crystal lattice vectors.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.resize_supercell-Union{Tuple{N}, Tuple{System{N}, Tuple{Int64, Int64, Int64}}} where N","page":"Library API","title":"Sunny.resize_supercell","text":"resize_supercell(sys::System{N}, latsize::NTuple{3,Int}) where N\n\nCreates a System with a given number of conventional unit cells in each lattice vector direction. Interactions and other settings will be inherited from sys.\n\nConvenience function for:\n\nreshape_supercell(sys, [latsize[1] 0 0; 0 latsize[2] 0; 0 0 latsize[3]])\n\nSee also reshape_supercell.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.rotate_operator-Tuple{LinearAlgebra.Hermitian{ComplexF64, Matrix{ComplexF64}}, Any}","page":"Library API","title":"Sunny.rotate_operator","text":"rotate_operator(A, R)\n\nRotates the local quantum operator A according to the 33 rotation matrix R.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.rotation_in_rlu-Tuple{Crystal, Any, Any}","page":"Library API","title":"Sunny.rotation_in_rlu","text":"rotation_in_rlu(cryst::Crystal, axis, angle)\n\nReturns a 33 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_coherent!-Union{Tuple{N}, Tuple{System{N}, Any, Any}} where N","page":"Library API","title":"Sunny.set_coherent!","text":"set_coherent!(sys::System, Z, site::Site)\n\nSet a coherent spin state at a Site using the N complex amplitudes in Z.\n\nFor 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 z-direction, and subsequent components represent states with decreasing angular momentum along this axis (m = S S-1 -S).\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_dipole!-Union{Tuple{N}, Tuple{System{N}, Any, Any}} where N","page":"Library API","title":"Sunny.set_dipole!","text":"set_dipole!(sys::System, dir, site::Site)\n\nPolarize the spin at a Site along the direction dir.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_exchange!-Union{Tuple{N}, Tuple{System{N}, Any, Bond}} where N","page":"Library API","title":"Sunny.set_exchange!","text":"set_exchange!(sys::System, J, bond::Bond)\n\nSets a 3×3 spin-exchange matrix J along bond, yielding a pairwise interaction energy 𝐒_iJ 𝐒_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.\n\nThe 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).\n\nFor more general interactions, such as biquadratic, use set_pair_coupling! instead.\n\nExamples\n\n# An explicit exchange matrix\nJ1 = [2 3 0;\n -3 2 0;\n 0 0 2]\nset_exchange!(sys, J1, bond)\n\n# An equivalent Heisenberg + DM exchange \nJ2 = 2*I + dmvec([0,0,3])\nset_exchange!(sys, J2, bond)\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_exchange_at!-Union{Tuple{N}, Tuple{System{N}, Any, Union{NTuple{4, Int64}, CartesianIndex{4}}, Union{NTuple{4, Int64}, CartesianIndex{4}}}} where N","page":"Library API","title":"Sunny.set_exchange_at!","text":"set_exchange_at!(sys::System, J, site1::Site, site2::Site; offset=nothing)\n\nSets 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.\n\nIf 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.\n\nFor more general interactions, such as biquadratic, use set_pair_coupling_at! instead.\n\nSee also set_exchange!.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_external_field!-Tuple{System, Any}","page":"Library API","title":"Sunny.set_external_field!","text":"set_external_field!(sys::System, B::Vec3)\n\nSets the external field B that couples to all spins.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_external_field_at!-Tuple{System, Any, Any}","page":"Library API","title":"Sunny.set_external_field_at!","text":"set_external_field_at!(sys::System, B::Vec3, site::Site)\n\nSets a Zeeman coupling between a field B and a single spin. Site includes a unit cell and a sublattice index.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_onsite_coupling!-Tuple{System, Any, Int64}","page":"Library API","title":"Sunny.set_onsite_coupling!","text":"set_onsite_coupling!(sys::System, op, i::Int)\n\nSet 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.\n\nExamples\n\n# An easy axis anisotropy in the z-direction\nset_onsite_coupling!(sys, S -> -D*S[3]^3, i)\n\n# The unique quartic single-ion anisotropy for a site with cubic point group\n# symmetry\nset_onsite_coupling!(sys, S -> 20*(S[1]^4 + S[2]^4 + S[3]^4), i)\n\n# An equivalent expression of this quartic anisotropy, up to a constant shift\nO = stevens_matrices(spin_label(sys, i))\nset_onsite_coupling!(sys, O[4,0] + 5*O[4,4], i)\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_onsite_coupling_at!-Tuple{System, Any, Union{NTuple{4, Int64}, CartesianIndex{4}}}","page":"Library API","title":"Sunny.set_onsite_coupling_at!","text":"set_onsite_coupling_at!(sys::System, op, site::Site)\n\nSets the single-ion anisotropy operator op for a single Site, ignoring crystal symmetry. The system must support inhomogeneous interactions via to_inhomogeneous.\n\nSee also set_onsite_coupling!.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_pair_coupling!-Union{Tuple{N}, Tuple{System{N}, AbstractMatrix, Any}} where N","page":"Library API","title":"Sunny.set_pair_coupling!","text":"set_pair_coupling!(sys::System, op, bond)\n\nSets 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.\n\nExamples\n\n# Bilinear+biquadratic exchange involving 3×3 matrices J1 and J2\nset_pair_coupling!(sys, (Si, Sj) -> Si'*J1*Sj + (Si'*J2*Sj)^2, bond)\n\n# Equivalent expression using an appropriate fixed matrix representation\nS = spin_matrices(1/2)\nSi, Sj = to_product_space(S, S)\nset_pair_coupling!(sys, Si'*J1*Sj + (Si'*J2*Sj)^2, bond)\n\nSee also spin_matrices, to_product_space.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_pair_coupling_at!-Union{Tuple{N}, Tuple{System{N}, AbstractMatrix, Union{NTuple{4, Int64}, CartesianIndex{4}}, Union{NTuple{4, Int64}, CartesianIndex{4}}}} where N","page":"Library API","title":"Sunny.set_pair_coupling_at!","text":"set_pair_coupling_at!(sys::System, op, bond)\n\nSets 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.\n\nThe system must support inhomogeneous interactions via to_inhomogeneous.\n\nIf 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_spiral_order!-Tuple{Any}","page":"Library API","title":"Sunny.set_spiral_order!","text":"set_spiral_order!(sys; q, axis, S0)\n\nInitializes 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.\n\nExample\n\n# Spiral order for a wavevector propagating in the direction of the first\n# reciprocal lattice vector (i.e., orthogonal to the lattice vectors ``𝐚_2``\n# and ``𝐚_3``), repeating with a period of 10 lattice constants, and spiraling\n# about the ``ẑ``-axis. The spin at the origin will point in the direction\n# ``𝐒_0 = ŷ + ẑ``. Here, ``(x̂, ŷ, ẑ)`` are the axes of Cartesian coordinate\n# system in the global frame.\nset_spiral_order!(sys; q=[1/10, 0, 0], axis=[0, 0, 1], S0=[0, 1, 1])\n\nSee also set_spiral_order_on_sublattice!.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_spiral_order_on_sublattice!-Tuple{Any, Any}","page":"Library API","title":"Sunny.set_spiral_order_on_sublattice!","text":"set_spiral_order_on_sublattice!(sys, i; q, axis, S0)\n\nInitializes 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.\n\nThis function is not available for systems with reshaped unit cells.\n\nSee also set_spiral_order!.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.set_vacancy_at!-Union{Tuple{N}, Tuple{System{N}, Any}} where N","page":"Library API","title":"Sunny.set_vacancy_at!","text":"set_vacancy_at!(sys::System, site::Site)\n\nMake a single site nonmagnetic. Site includes a unit cell and a sublattice index.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.slice_2D_binning_parameters-Tuple{Vector{Float64}, Any, Any, Int64, Any}","page":"Library API","title":"Sunny.slice_2D_binning_parameters","text":"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)\n\nCreates BinningParameters which make a cut along one dimension of Q-space.\n\nThe 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.\n\nThe binning in the transverse directions is defined in the following way, which sets their normalization and orthogonality properties:\n\ncut_covector = normalize(cut_to_q - cut_from_q)\ntransverse_covector = normalize(plane_normal × cut_covector)\ncotransverse_covector = normalize(transverse_covector × cut_covector)\n\nIn other words, the axes are orthonormal with respect to the Euclidean metric.\n\nIf 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.\n\nThe four axes of the resulting histogram are:\n\nAlong the cut\nFist transverse Q direction\nSecond transverse Q direction\nEnergy\n\nThis function can be used without reference to a SampledCorrelations using this alternate syntax to manually specify the bin centers for the energy axis:\n\nslice_2D_binning_parameter(ω_bincenters, cut_from, cut_to,...)\n\nwhere ω_bincenters specifies the energy axis, and both cut_from and cut_to are arbitrary covectors, in any units.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.spin_label-Tuple{System, Int64}","page":"Library API","title":"Sunny.spin_label","text":"spin_label(sys::System, i::Int)\n\nIf atom i carries a single spin-S moment, then returns the half-integer label S. Otherwise, throws an error.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.spin_matrices-Tuple{Any}","page":"Library API","title":"Sunny.spin_matrices","text":"spin_matrices(S)\n\nReturns a triple of NN spin matrices, where N = 2S+1. These are the generators of SU(2) in the spin-S representation.\n\nIf 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.\n\nExample\n\nS = spin_matrices(3/2)\n@assert S'*S ≈ (3/2)*(3/2+1)*I\n@assert S[1]*S[2] - S[2]*S[1] ≈ im*S[3]\n\nS = spin_matrices(Inf)\n@assert S[1]*S[2] - S[2]*S[1] == 0\n\nSee also print_stevens_expansion.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.step!","page":"Library API","title":"Sunny.step!","text":"step!(sys::System, dynamics)\n\nAdvance 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.\n\n\n\n\n\n","category":"function"},{"location":"library.html#Sunny.stevens_matrices-Tuple{Any}","page":"Library API","title":"Sunny.stevens_matrices","text":"stevens_matrices(S)\n\nReturns 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 NN matrix where ``N = 2S\n\n1``. Linear combinations of Stevens operators can be used as a \"physical\n\nbasis\" for decomposing local observables. To see this decomposition, use print_stevens_expansion.\n\nIf S == Inf, then symbolic operators will be returned. In this infinite dimensional limit, the Stevens operators become homogeneous polynomials of commuting spin operators.\n\nExample\n\nO = stevens_matrices(2)\nS = spin_matrices(2)\n\nA = (1/20)O[4,0] + (1/4)O[4,4] + (102/5)I\nB = S[1]^4 + S[2]^4 + S[3]^4\n@assert A ≈ B\n\nSee also spin_matrices and Interaction Strength Renormalization.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.subcrystal-Union{Tuple{N}, Tuple{Crystal, Vararg{String, N}}} where N","page":"Library API","title":"Sunny.subcrystal","text":"subcrystal(cryst, types) :: Crystal\n\nFilters sublattices of a Crystal by atom types, keeping the space group unchanged.\n\nsubcrystal(cryst, classes) :: Crystal\n\nFilters sublattices of Crystal by equivalence classes, keeping the space group unchanged.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.suggest_magnetic_supercell-Tuple{Any}","page":"Library API","title":"Sunny.suggest_magnetic_supercell","text":"suggest_magnetic_supercell(qs; tol=1e-12, maxsize=100)\n\nSuggests 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.\n\nPrints a 33 matrix of integers that is suitable for use in reshape_supercell.\n\nExamples\n\n# A magnetic supercell for a single-Q structure. Will print\nq1 = [0, -1/4, 1/4]\nsuggest_magnetic_supercell([q1]) # [1 0 0; 0 2 1; 0 -2 1]\n\n# A larger magnetic supercell for a double-Q structure\nq2 = [1/4, 0, 1/4]\nsuggest_magnetic_supercell([q1, q2]) # [1 2 2; -1 2 -2; -1 2 2]\n\n# If given incommensurate wavevectors, find an approximate supercell that\n# is exactly commensurate for nearby wavevectors.\nsuggest_magnetic_supercell([[0, 0, 1/√5], [0, 0, 1/√7]]; tol=1e-2)\n\n# This prints [1 0 0; 0 1 0; 0 0 16], which becomes commensurate under the\n# approximations `1/√5 ≈ 7/16` and `1/√7 ≈ 3/8`.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.symmetry_equivalent_bonds-Tuple{System, Bond}","page":"Library API","title":"Sunny.symmetry_equivalent_bonds","text":"symmetry_equivalent_bonds(sys::System, bond::Bond)\n\nGiven 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).\n\nExample\n\nfor (site1, site2, offset) in symmetry_equivalent_bonds(sys, bond)\n @assert site1 < site2\n set_exchange_at!(sys, J, site1, site2; offset)\nend\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.to_inhomogeneous-Union{Tuple{System{N}}, Tuple{N}} where N","page":"Library API","title":"Sunny.to_inhomogeneous","text":"to_inhomogeneous(sys::System)\n\nReturns a copy of the system that allows for inhomogeneous interactions, which can be set using set_onsite_coupling_at!, set_exchange_at!, and set_vacancy_at!.\n\nInhomogeneous systems do not support symmetry-propagation of interactions or system reshaping.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.to_product_space-Tuple{Any, Any, Vararg{Any}}","page":"Library API","title":"Sunny.to_product_space","text":"to_product_space(A, B, Cs...)\n\nGiven 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.\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.unit_resolution_binning_parameters-Tuple{Any, Any, Vararg{Any}}","page":"Library API","title":"Sunny.unit_resolution_binning_parameters","text":"unit_resolution_binning_parameters(sc::SampledCorrelations)\n\nCreate 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.\n\nThis 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:\n\nunit_resolution_binning_parameters(ω_bincenters,latsize,[reciprocal lattice vectors])\n\nThe last argument may be a 3x3 matrix specifying the reciprocal lattice vectors, or a Crystal.\n\nLastly, binning parameters for a single axis may be specifed by their bin centers:\n\n(binstart,binend,binwidth) = unit_resolution_binning_parameters(bincenters::Vector{Float64})\n\n\n\n\n\n","category":"method"},{"location":"library.html#Sunny.@mix_proposals-Tuple","page":"Library API","title":"Sunny.@mix_proposals","text":"@mix_proposals weight1 propose1 weight2 propose2 ...\n\nMacro to generate a proposal function that randomly selects among the provided functions according to the provided probability weights. For use with LocalSampler.\n\nExample\n\n# A proposal function that proposes a spin flip 40% of the time, and a\n# Gaussian perturbation 60% of the time.\n@mix_proposals 0.4 propose_flip 0.6 propose_delta(0.2)\n\n\n\n\n\n","category":"macro"},{"location":"library.html#Optional-Makie-extensions","page":"Library API","title":"Optional Makie extensions","text":"","category":"section"},{"location":"library.html","page":"Library API","title":"Library API","text":"The following will be enabled through a package extension if either GLMakie or WGLMakie is loaded.","category":"page"},{"location":"library.html","page":"Library API","title":"Library API","text":"plot_spins\nview_crystal","category":"page"},{"location":"library.html#Sunny.plot_spins","page":"Library API","title":"Sunny.plot_spins","text":"plot_spins(sys::System; arrowscale=1.0, color=:red, colorfn=nothing,\n colormap=:viridis, colorrange=nothing, show_cell=true, orthographic=false,\n ghost_radius=0, dims=3\n\nPlot the spin configuration defined by sys. Optional parameters are:\n\narrowscale: Scale all arrows by dimensionless factor.\ncolor: Arrow colors. May be symbolic or numeric. If scalar, will be shared among all sites.\ncolorfn: Function that dynamically maps from a site index to a numeric color value. Useful for animations.\ncolormap, colorrange: Used to populate colors from numbers following Makie conventions.\nshow_cell: Show original crystallographic unit cell.\northographic: Use camera with orthographic projection.\nghost_radius: Show translucent periodic images up to a given distance (length units).\ndims: Spatial dimensions of system (1, 2, or 3).\n\nCalling notify on the return value will animate the figure.\n\n\n\n\n\n","category":"function"},{"location":"library.html#Sunny.view_crystal","page":"Library API","title":"Sunny.view_crystal","text":"view_crystal(crystal::Crystal, max_dist::Real; show_axis=true, orthographic=false)\n\nAn interactive crystal viewer, with bonds up to max_dist.\n\n\n\n\n\n","category":"function"},{"location":"library.html#Optional-WriteVTK-extensions","page":"Library API","title":"Optional WriteVTK extensions","text":"","category":"section"},{"location":"library.html","page":"Library API","title":"Library API","text":"The following will be enabled through a package extension if WriteVTK is loaded.","category":"page"},{"location":"library.html","page":"Library API","title":"Library API","text":"export_vtk","category":"page"},{"location":"library.html#Sunny.export_vtk","page":"Library API","title":"Sunny.export_vtk","text":"export_vtk(filename,params::BinningParameters,data)\n\nExport 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.\n\nAt least one axis of the BinningParameters must be integrated over, since VTK does not support 4D data. See integrate_axes!.\n\n\n\n\n\n","category":"function"},{"location":"examples/05_MC_Ising.html","page":"5. Monte Carlo sampling of the Ising model","title":"5. Monte Carlo sampling of the Ising model","text":"EditURL = \"../../../examples/05_MC_Ising.jl\"","category":"page"},{"location":"examples/05_MC_Ising.html","page":"5. Monte Carlo sampling of the Ising model","title":"5. Monte Carlo sampling of the Ising model","text":"Download this example as Jupyter notebook or Julia script.","category":"page"},{"location":"examples/05_MC_Ising.html#.-Monte-Carlo-sampling-of-the-Ising-model","page":"5. Monte Carlo sampling of the Ising model","title":"5. Monte Carlo sampling of the Ising model","text":"","category":"section"},{"location":"examples/05_MC_Ising.html","page":"5. Monte Carlo sampling of the Ising model","title":"5. Monte Carlo sampling of the Ising model","text":"This tutorial illustrates simulation of the classical 2D Ising model.","category":"page"},{"location":"examples/05_MC_Ising.html","page":"5. Monte Carlo sampling of the Ising model","title":"5. Monte Carlo sampling of the Ising model","text":"using Sunny, GLMakie","category":"page"},{"location":"examples/05_MC_Ising.html","page":"5. Monte Carlo sampling of the Ising model","title":"5. Monte Carlo sampling of the Ising model","text":"Sunny expects a 3D Crystal unit cell. To model a square lattice, we create an orthogonal unit cell where the z-spacing is distinct from the x and y spacing.","category":"page"},{"location":"examples/05_MC_Ising.html","page":"5. Monte Carlo sampling of the Ising model","title":"5. Monte Carlo sampling of the Ising model","text":"a = 1\nlatvecs = lattice_vectors(a,a,10a,90,90,90)\ncrystal = Crystal(latvecs, [[0,0,0]])","category":"page"},{"location":"examples/05_MC_Ising.html","page":"5. Monte Carlo sampling of the Ising model","title":"5. Monte Carlo sampling of the Ising model","text":"Create a System of spins with linear size L in the x and y directions, and only one layer in the z direction. The option :dipole means that the system will store Heisenberg spins, as opposed to SU(N) coherent states. Polarize the initial spin configuration using polarize_spins!. Following the Ising convention, we will restrict these spins to the z-axis and give them magnitude S=1.","category":"page"},{"location":"examples/05_MC_Ising.html","page":"5. Monte Carlo sampling of the Ising model","title":"5. Monte Carlo sampling of the Ising model","text":"By default, Sunny uses physical units, e.g. magnetic field in tesla. Here we specify an alternative Units system, so that the Zeeman coupling between the spin dipole 𝐬 and an external field 𝐁 has the dimensionless form -𝐁𝐬.","category":"page"},{"location":"examples/05_MC_Ising.html","page":"5. Monte Carlo sampling of the Ising model","title":"5. Monte Carlo sampling of the Ising model","text":"L = 128\nsys = System(crystal, (L,L,1), [SpinInfo(1, S=1, g=1)], :dipole, units=Units.theory, seed=0)\npolarize_spins!(sys, (0,0,1))","category":"page"},{"location":"examples/05_MC_Ising.html","page":"5. Monte Carlo sampling of the Ising model","title":"5. Monte Carlo sampling of the Ising model","text":"Use set_exchange! to include a ferromagnetic Heisenberg interaction along nearest-neighbor bonds. The Bond below connects two spins displaced by one lattice constant in the x-direction. This interaction will be propagated to all nearest-neighbors bonds in the system, consistent with the symmetries of the square lattice.","category":"page"},{"location":"examples/05_MC_Ising.html","page":"5. Monte Carlo sampling of the Ising model","title":"5. Monte Carlo sampling of the Ising model","text":"set_exchange!(sys, -1.0, Bond(1,1,(1,0,0)))","category":"page"},{"location":"examples/05_MC_Ising.html","page":"5. Monte Carlo sampling of the Ising model","title":"5. Monte Carlo sampling of the Ising model","text":"If an external field is desired, it can be set using set_external_field!.","category":"page"},{"location":"examples/05_MC_Ising.html","page":"5. Monte Carlo sampling of the Ising model","title":"5. Monte Carlo sampling of the Ising model","text":"B = 0\nset_external_field!(sys, (0,0,B))","category":"page"},{"location":"examples/05_MC_Ising.html","page":"5. Monte Carlo sampling of the Ising model","title":"5. Monte Carlo sampling of the Ising model","text":"The critical temperature for the Ising model is known analytically.","category":"page"},{"location":"examples/05_MC_Ising.html","page":"5. Monte Carlo sampling of the Ising model","title":"5. Monte Carlo sampling of the Ising model","text":"Tc = 2/log(1+√2)","category":"page"},{"location":"examples/05_MC_Ising.html","page":"5. Monte Carlo sampling of the Ising model","title":"5. Monte Carlo sampling of the Ising model","text":"Use a LocalSampler to perform nsweeps Monte Carlo sweeps. A sweep consists of, on average, one trial update per spin in the system. Each proposed update is accepted or rejected according to the Metropolis acceptance probability. As its name suggests, the propose_flip function will only propose pure spin flips, 𝐬 rightarrow -𝐬.","category":"page"},{"location":"examples/05_MC_Ising.html","page":"5. Monte Carlo sampling of the Ising model","title":"5. Monte Carlo sampling of the Ising model","text":"nsweeps = 4000\nsampler = LocalSampler(kT=Tc, propose=propose_flip)\nfor i in 1:nsweeps\n step!(sys, sampler)\nend","category":"page"},{"location":"examples/05_MC_Ising.html","page":"5. Monte Carlo sampling of the Ising model","title":"5. Monte Carlo sampling of the Ising model","text":"Plot the Ising spins by extracting the z-component of the dipoles","category":"page"},{"location":"examples/05_MC_Ising.html","page":"5. Monte Carlo sampling of the Ising model","title":"5. Monte Carlo sampling of the Ising model","text":"heatmap(reshape([s.z for s in sys.dipoles], (L,L)))","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html#Powder-Averaged-CoRhO-at-Finite-Temperature","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"","category":"section"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Inspired by: Ge et al., Phys. Rev. B 96, 064413 (2017)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Authors: Martin Mourigal, David Dahlbom","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Date: October 28, 2023 (Sunny 0.5.5)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Goal: This script is to calculate the temperature dependence of the magnon excitations in the spin-3/2 Heisenberg Diamond Antiferromagnet and compare to powder-averaged results obtained for the compound CoRh₂O₄","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html#Load-pacakges.","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Load pacakges.","text":"","category":"section"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"using Sunny, GLMakie, ProgressMeter, Statistics, Random, Brillouin\ncif_path = pkgdir(Sunny, \"examples\", \"longer_examples\", \"CoRh2O4_#109301.cif\");","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html#Define-custom-functions.","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Define custom functions.","text":"","category":"section"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"The function quench! randomizes the spins of a given System, fixes a target temperature, and lets the system relax at this temperature for nrelax integration steps.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"function quench!(sys, integrator; kTtarget, nrelax)\n randomize_spins!(sys);\n integrator.kT = kTtarget;\n prog = Progress(nrelax; dt=10.0, desc=\"Quenched and now relaxing: \", color=:green);\n for _ in 1:nrelax\n step!(sys, integrator)\n next!(prog)\n end\nend","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"quench! (generic function with 1 method)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"dwell! takes a System, sets a target temperature, and has the system dwell at this temperature for ndwell integration steps.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"function dwell!(sys, integrator; kTtarget, ndwell)\n integrator.kT = kTtarget;\n prog = Progress(ndwell; dt=10.0, desc=\"Dwelling: \", color=:green);\n for _ in 1:ndwell\n step!(sys, integrator)\n next!(prog)\n end\nend","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"dwell! (generic function with 1 method)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"anneal! takes a temperature schedule and cools the System through it, with ndwell steps of the integrator at each temperature in the schedule. Returns the energy at the end of the dwell for each scheduled temperature.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"function anneal!(sys, integrator; kTschedule, ndwell)\n nspins = prod(size(sys.dipoles));\n ensys = zeros(length(kTschedule))\n prog = Progress(ndwell*length(kTschedule); dt=10.0, desc=\"Annealing: \", color=:red);\n for (i, kT) in enumerate(kTschedule)\n integrator.kT = kT\n for _ in 1:ndwell\n step!(sys, integrator)\n next!(prog)\n end\n ensys[i] = energy(sys)\n end\n return ensys/nspins\nend","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"anneal! (generic function with 1 method)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"sample_sf! samples a structure factor, which may be either an instant or dynamical structure factor. The integrator is run ndecorr times before each one of the samples is taken.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"function sample_sf!(sf, sys, integrator; nsamples, ndecorr)\n prog = Progress(nsamples*ndecorr; dt=10.0, desc=\"Sampling SF: \", color=:red);\n for _ in 1:nsamples\n for _ in 1:ndecorr\n step!(sys, integrator)\n next!(prog)\n end\n add_sample!(sf, sys) # Accumulate the newly sampled structure factor into `sf`\n end\nend","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"sample_sf! (generic function with 1 method)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"powder_average powder averages a structure factor. Works for both instant and dynamical structure factors. To prevent smearing, removes Bragg peaks before introducing energy broadening. Bragg peaks are added back at ω=0 after broadening.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"function powder_average(sc, rs, npts, formula; η=0.1)\n prog = Progress(length(rs); dt=10., desc=\"Powder Averaging: \", color=:blue)\n ωs = available_energies(sc)\n output = zeros(Float64, length(rs), length(ωs))\n for (i, r) in enumerate(rs)\n qs = reciprocal_space_shell(sc.crystal, r, npts)\n vals = intensities_interpolated(sc, qs, formula)\n bragg_idxs = findall(x -> x > maximum(vals)*0.9, vals)\n bragg_vals = vals[bragg_idxs]\n vals[bragg_idxs] .= 0\n vals = broaden_energy(sc, vals, (ω,ω₀)->lorentzian(ω-ω₀, η))\n vals[bragg_idxs] .= bragg_vals\n output[i,:] .= mean(vals, dims=1)[1,:]\n next!(prog)\n end\n return output\nend","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"powder_average (generic function with 1 method)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html#System-Definition-for-CoRhO","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"System Definition for CoRh₂O₄","text":"","category":"section"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Define the crystal structure of CoRh₂O₄ in the conventional cell.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"xtal = Crystal(cif_path; symprec=1e-4)\nmagxtal = subcrystal(xtal,\"Co1\")\nview_crystal(magxtal, 6.0)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Print the symmetry-allowed interactions.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"print_symmetry_table(magxtal, 4.0)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Atom 1\nType 'Co1', position [0, 0, 0], multiplicity 8\nAllowed g-tensor: [A 0 0\n 0 A 0\n 0 0 A]\nAllowed anisotropy in Stevens operators:\n c₁*(𝒪[4,0]+5𝒪[4,4]) +\n c₂*(𝒪[6,0]-21𝒪[6,4])\n\nSunny.Bond(1, 3, [0, 0, 0])\nDistance 3.6784429025744, coordination 4\nConnects 'Co1' at [0, 0, 0] to 'Co1' at [1/4, 1/4, 1/4]\nAllowed exchange matrix:[A B B\n B A B\n B B A]\n\n","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Assign local Hilbert space","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"S = 3/2\nlhs = [SpinInfo(1; S, g=2)]\nformfactors = [FormFactor(\"Co2\")];","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Create System and randomize it","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"sunmode = :dipole\nlatsize = (10,10,10)\nsys = System(magxtal, latsize, lhs, sunmode; seed=1)\nrandomize_spins!(sys)\nplot_spins(sys)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Define exchange interactions.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"scaleJ = 0.63\nvalJ1 = 1.00*scaleJ\nset_exchange!(sys, valJ1, Bond(1, 3, [0, 0, 0]));","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html#Thermalize-system-to-an-ordered,-yet-finite-temperature,-state","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Thermalize system to an ordered, yet finite temperature, state","text":"","category":"section"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Define Langevin Integrator and Initialize it","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Δt0 = 0.05/abs(scaleJ*S); ## Time steps in Langevin\nλ0 = 0.1; ## Langevin damping, usually 0.05 or 0.1 is good.\nkT0 = 0.01*abs(scaleJ*S); ## Initialize at some temperature\nintegrator = Langevin(Δt0; λ=λ0, kT=kT0);","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Thermalization Option 1: Quench the system from infinite temperature to a target temperature. Note: this may lead to a poorly thermalized sample","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"quench!(sys, integrator; kTtarget=kT0, nrelax=10000);","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Option 2: Anneal (according to a temperature schedule) then dwell once we've reach base temperature. (Uncomment to execute.)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"# kTs = [abs(scaleJ)*valS*100 * 0.9^k for k in 0:100]\n# anneal!(sys,integrator;kTschedule=kTs,ndwell=500)\n# dwell!(sys,integrator;kTtarget=kTs[end],ndwell=2000)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Plot the resulting spin system to check ordering in real space","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"plot_spins(sys)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html#Calculation-of-Neutron-Scattering-Responses","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Calculation of Neutron Scattering Responses","text":"","category":"section"},{"location":"examples/contributed/CoRh2O4-tutorial.html#Fourier-transformed-instantaneous-two-point-correlation-functions","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Fourier transformed instantaneous two-point correlation functions","text":"","category":"section"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Calculate the instantaneous/equal-time structure factor.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"eqsf = instant_correlations(sys)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"SampledCorrelations (6.252 MiB)\n[S(q) | 0 sample]\nLattice: (10, 10, 10)×8\n6 correlations in Dipole mode:\n╔ ⬤ ⬤ ⬤ Sx\n║ ⋅ ⬤ ⬤ Sy\n╚ ⋅ ⋅ ⬤ Sz\n","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"If desired, add additional samples by decorrelating and then re-calculating the eqsf.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"nsamples = 1\nndecorr = 1000\n@time sample_sf!(eqsf, sys, integrator; nsamples=nsamples, ndecorr=ndecorr);","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":" 0.966485 seconds (1.89 M allocations: 118.815 MiB, 6.25% gc time, 50.12% compilation time)\n","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Project onto a constant Q-Slice in momentum space.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"nQpts = 200\nQxpts = range(-10.0, 10.0, length=nQpts)\nQypts = range(-10.0, 10.0, length=nQpts)\nqz = 1.0\nQpts = [[qx, qy, qz] for qx in Qxpts, qy in Qypts]\ninstant_formula = intensity_formula(eqsf, :perp; formfactors)\niq = instant_intensities_interpolated(eqsf, Qpts, instant_formula);","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Plot the resulting I(Q)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"heatmap(Qxpts, Qypts, iq;\n colorrange = (0, maximum(iq)/20),\n axis = (\n xlabel=\"Momentum Transfer Qx (r.l.u)\", xlabelsize=16,\n ylabel=\"Momentum Transfer Qy (r.l.u)\", ylabelsize=16,\n aspect=true,\n )\n)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html#Dynamical-and-energy-integrated-two-point-correlation-functions","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Dynamical and energy-integrated two-point correlation functions","text":"","category":"section"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Calculate the time traces and Fourier transform: Dynamical Structure Factor (first sample).","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"ωmax = 6.0 # Maximum energy to resolve\nnω = 100 # Number of energies to resolve\nsc = dynamical_correlations(sys; Δt=Δt0, nω=nω, ωmax=ωmax, process_trajectory=:symmetrize)\n@time add_sample!(sc, sys) # Add a sample trajectory","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":" 5.471269 seconds (14.33 M allocations: 291.526 MiB, 0.75% gc time, 0.02% compilation time)\n","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"If desired, add additional decorrelated samples.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"nsamples = 10\nndecorr = 1000\n@time sample_sf!(sc, sys, integrator; nsamples=nsamples, ndecorr=ndecorr);","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Sampling SF: 27%|██████████▎ | ETA: 0:00:33\u001b[KSampling SF: 49%|██████████████████▊ | ETA: 0:00:25\u001b[KSampling SF: 68%|█████████████████████████▉ | ETA: 0:00:17\u001b[KSampling SF: 84%|████████████████████████████████ | ETA: 0:00:09\u001b[KSampling SF: 100%|██████████████████████████████████████| Time: 0:00:53\u001b[K\n 59.070784 seconds (143.58 M allocations: 2.866 GiB, 0.56% gc time, 0.24% compilation time)\n","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Can use the Brillouin package for help on determining high symmetry points","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"kp = irrfbz_path(227,[[1,0,0], [0,1,0], [0,0,1]])\nkpc = cartesianize(kp)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"KPath{3} (6 points, 2 paths, 8 points in paths):\n points: :U => [1.570796, 6.283185, 1.570796]\n :W => [3.141593, 6.283185, 0.0]\n :K => [4.712389, 4.712389, 0.0]\n :Γ => [0.0, 0.0, 0.0]\n :L => [3.141593, 3.141593, 3.141593]\n :X => [0.0, 6.283185, 0.0]\n paths: [:Γ, :X, :U]\n [:K, :Γ, :L, :W, :X]\n basis: [-6.283185, 6.283185, 6.283185]\n [6.283185, -6.283185, 6.283185]\n [6.283185, 6.283185, -6.283185]","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Project onto a constant QE-Slice in momentum-energy space.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"densQpts = 50\nsymQpts = [[0.75, 0.75, 0.00], # List of wave vectors that define a path\n [0.00, 0.00, 0.00],\n [0.50, 0.50, 0.50],\n [0.50, 1.00, 0.00],\n [0.00, 1.00, 0.00],\n [0.25, 1.00, 0.25],\n [0.00, 1.00, 0.00],\n [0.00,-4.00, 0.00]]\n(Qpts, xticks) = reciprocal_space_path(magxtal, symQpts, densQpts)\nformula = intensity_formula(sc, :perp; formfactors, kT=integrator.kT)\niqw = intensities_interpolated(sc, Qpts, formula);","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"If desired, broaden the sc in energy.","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"η = 0.1 ## Lorentzian energy broadening parameter\niqwc = broaden_energy(sc, iqw, (ω, ω₀) -> lorentzian(ω-ω₀, η));","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"If desired, calculated the energy-integrated structure factor","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"iqt = instant_intensities_interpolated(sc, Qpts, formula);","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Plot the resulting I(Q,W).","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"ωs = available_energies(sc)\nheatmap(1:size(iqwc, 1), ωs, iqwc;\n colorrange = (0, maximum(iqwc)/20000.0),\n axis = (;\n xlabel=\"Momentum Transfer (r.l.u)\",\n ylabel=\"Energy Transfer (meV)\",\n xticks,\n xticklabelrotation=π/5,\n aspect = 1.4,\n )\n)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Projection into a powder-averaged neutron scattering intensity .","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Qmax = 3.5\nnQpts = 100\nQpow = range(0, Qmax, nQpts)\nnpoints = 100\npqw = powder_average(sc, Qpow, npoints, formula; η);","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Powder Averaging: 78%|█████████████████████████▊ | ETA: 0:00:03\u001b[KPowder Averaging: 100%|█████████████████████████████████| Time: 0:00:12\u001b[K\n","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Plot resulting Ipow(|Q|,W).","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"heatmap(Qpow, ωs, pqw;\n axis = (\n xlabel=\"|Q| (Å⁻¹)\",\n ylabel=\"Energy Transfer (meV)\",\n aspect = 1.4,\n ),\n colorrange = (0, 40.0)\n)","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html#Calculation-of-temperature-dependent-powder-average-spectrum","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Calculation of temperature-dependent powder average spectrum","text":"","category":"section"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Define a temperature schedule","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"kTs = [60 40 25 20 15 12 10 4] * Sunny.meV_per_K\npqw_res = []\nfor kT in kTs\n dwell!(sys, integrator; kTtarget=kT, ndwell=1000);\n sc_loc = dynamical_correlations(sys; Δt=Δt0, nω, ωmax, process_trajectory=:symmetrize);\n add_sample!(sc_loc, sys)\n formula = intensity_formula(sc, :perp; formfactors, kT)\n push!(pqw_res, powder_average(sc_loc, Qpow, npoints, formula; η))\nend","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"┌ Warning: Assignment to `formula` in soft scope is ambiguous because a global variable by the same name exists: `formula` will be treated as a new local. Disambiguate by using `local formula` to suppress this warning or `global formula` to assign to the existing global variable.\n└ @ ~/Research/SunnyContributed/contributed-docs/build/CoRh2O4-tutorial.md:7\nPowder Averaging: 83%|███████████████████████████▍ | ETA: 0:00:02\u001b[KPowder Averaging: 100%|█████████████████████████████████| Time: 0:00:12\u001b[K\nPowder Averaging: 83%|███████████████████████████▍ | ETA: 0:00:02\u001b[KPowder Averaging: 100%|█████████████████████████████████| Time: 0:00:12\u001b[K\nPowder Averaging: 83%|███████████████████████████▍ | ETA: 0:00:02\u001b[KPowder Averaging: 100%|█████████████████████████████████| Time: 0:00:12\u001b[K\nPowder Averaging: 83%|███████████████████████████▍ | ETA: 0:00:02\u001b[KPowder Averaging: 100%|█████████████████████████████████| Time: 0:00:12\u001b[K\nPowder Averaging: 81%|██████████████████████████▊ | ETA: 0:00:02\u001b[KPowder Averaging: 100%|█████████████████████████████████| Time: 0:00:12\u001b[K\nPowder Averaging: 83%|███████████████████████████▍ | ETA: 0:00:02\u001b[KPowder Averaging: 100%|█████████████████████████████████| Time: 0:00:12\u001b[K\nPowder Averaging: 81%|██████████████████████████▊ | ETA: 0:00:02\u001b[KPowder Averaging: 100%|█████████████████████████████████| Time: 0:00:12\u001b[K\nPowder Averaging: 87%|████████████████████████████▊ | ETA: 0:00:02\u001b[KPowder Averaging: 100%|█████████████████████████████████| Time: 0:00:11\u001b[K\n","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"Plot the resulting Ipow(|Q|,W) as a function of temperature, to compare with Fig.6 of https://arxiv.org/abs/1706.05881","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"fig = Figure(; resolution=(1200,600))\nfor i in 1:8\n r, c = fldmod1(i, 4)\n ax = Axis(fig[r, c];\n title = \"kT = \"*string(round(kTs[9-i], digits=3))*\" (meV)\",\n xlabel = r == 2 ? \"|Q| (Å⁻¹)\" : \"\",\n ylabel = c == 1 ? \"Energy Transfer (meV)\" : \"\",\n aspect = 1.4,\n )\n heatmap!(ax, Qpow, ωs, pqw_res[9-i]; colorrange = (0, 20.0))\nend\nfig","category":"page"},{"location":"examples/contributed/CoRh2O4-tutorial.html","page":"Powder Averaged CoRh₂O₄ at Finite Temperature","title":"Powder Averaged CoRh₂O₄ at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#MgCr2O4-at-Finite-Temperature","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Author: Martin Mourigal
    Date: September 9, 2022 (Updated by October 28, 2023 using Sunny 0.5.5)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"In this tutorial, we will walk through an example in Sunny and calculate the spin dynamical properties of the Heisenberg pyrochlore antiferromagnet and apply this knowledge to MgCr2O4 and ZnCr2O4, which are known to approximate this model. Relevant publications include:","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"[1] P. H. Conlon and J. T. Chalker, Phys. Rev. Lett. 102, 237206 (2009)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"[2] P. H. Conlon and J. T. Chalker, Phys. Rev. B 81, 224413 (2010)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"[3] X. Bai, J. A. M. Paddison, et al. Phys. Rev. Lett. 122, 097201 (2019)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#Setting-up-Julia","page":"MgCr2O4 at Finite Temperature","title":"Setting up Julia","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"To run the examples in the tutorial, you will need a working installation of the Julia programming language and the Sunny package. Some useful references for getting started are:","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Getting started with Julia for Sunny\nSunny Docs","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"We will begin by loading the relevant packages.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"using Sunny # The main package\nusing GLMakie # Plotting package","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#Setting-up-the-crystal-structure","page":"MgCr2O4 at Finite Temperature","title":"Setting up the crystal structure","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Before specifying the interactions of our system, we first must set up the crystal. We will begin by specifying the pyrochlore lattice (illustrated below) in the manner that is typical of theorists.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Picture Credits: Theory of Quantum Matter Unit, OIST","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#\"Theorist\"-Method","page":"MgCr2O4 at Finite Temperature","title":"\"Theorist\" Method","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"In this approach, we directly define the lattice vectors and specify the position of each atom in fractional coordinates.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"latvecs = lattice_vectors(8.3342, 8.3342, 8.3342, 90, 90, 90)\npositions = [[0.875, 0.625, 0.375],\n [0.625, 0.125, 0.625],\n [0.875, 0.875, 0.125],\n [0.625, 0.875, 0.375],\n [0.875, 0.125, 0.875],\n [0.625, 0.625, 0.125],\n [0.875, 0.375, 0.625],\n [0.625, 0.375, 0.875],\n [0.375, 0.625, 0.875],\n [0.125, 0.125, 0.125],\n [0.375, 0.875, 0.625],\n [0.125, 0.875, 0.875],\n [0.375, 0.125, 0.375],\n [0.125, 0.625, 0.625],\n [0.375, 0.375, 0.125],\n [0.125, 0.375, 0.375]];\ntypes = [\"B\" for _ in positions]\nxtal_pyro = Crystal(latvecs, positions; types) # We will call this crystal the Theoretical Pyrochlore","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Crystal\nHM symbol 'F d -3 m' (227)\nLattice params a=8.334, b=8.334, c=8.334, α=90°, β=90°, γ=90°\nCell volume 578.9\nType 'B', Wyckoff 16c (point group '.-3m'):\n 1. [7/8, 5/8, 3/8]\n 2. [5/8, 1/8, 5/8]\n 3. [7/8, 7/8, 1/8]\n 4. [5/8, 7/8, 3/8]\n 5. [7/8, 1/8, 7/8]\n 6. [5/8, 5/8, 1/8]\n 7. [7/8, 3/8, 5/8]\n 8. [5/8, 3/8, 7/8]\n 9. [3/8, 5/8, 7/8]\n 10. [1/8, 1/8, 1/8]\n 11. [3/8, 7/8, 5/8]\n 12. [1/8, 7/8, 7/8]\n 13. [3/8, 1/8, 3/8]\n 14. [1/8, 5/8, 5/8]\n 15. [3/8, 3/8, 1/8]\n 16. [1/8, 3/8, 3/8]\n","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"To examine the result interactively, we can call view_crystal.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"view_crystal(xtal_pyro, 3.2)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#\"Experimentalist\"-Method-#1-(Incorrect)","page":"MgCr2O4 at Finite Temperature","title":"\"Experimentalist\" Method #1 (Incorrect)","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"A real crystal is more complicated than this, however, and we will now construct the system using the actual CIF file of MgCr2O4 from ICSD. This can be done by copying over the data from a CIF file by hand, but this can be dangerous, as shown below.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"latvecs = lattice_vectors(8.3342, 8.3342, 8.3342, 90, 90, 90)\npositions = [[0.1250, 0.1250, 0.1250],\n [0.5000, 0.5000, 0.5000],\n [0.2607, 0.2607, 0.2607]]\ntypes = [\"Mg\",\"Cr\",\"O\"]\nxtal_mgcro_1 = Crystal(latvecs, positions; types)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Crystal\nHM symbol 'R 3 m' (160)\nLattice params a=8.334, b=8.334, c=8.334, α=90°, β=90°, γ=90°\nCell volume 578.9\nType 'Mg', Wyckoff 3a (point group '3m'):\n 1. [1/8, 1/8, 1/8]\nType 'Cr', Wyckoff 3a (point group '3m'):\n 2. [1/2, 1/2, 1/2]\nType 'O', Wyckoff 3a (point group '3m'):\n 3. [0.2607, 0.2607, 0.2607]\n","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Sunny returned a valid crystal, but it did get right space group for MgCr2O4. This can be fixed by modifying the input to include the space group and the setting.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#\"Experimentalist\"-Method-#2-(Correct)","page":"MgCr2O4 at Finite Temperature","title":"\"Experimentalist\" Method #2 (Correct)","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"As above, we will define the crystal structure of MgCr2O4 by copying the info from a CIF file, but we will also specify the space group and setting explicitly.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"latvecs = lattice_vectors(8.3342, 8.3342, 8.3342, 90, 90, 90)\npositions = [[0.1250, 0.1250, 0.1250],\n [0.5000, 0.5000, 0.5000],\n [0.2607, 0.2607, 0.2607]]\ntypes = [\"Mg\",\"Cr\",\"O\"]\nspacegroup = 227 # Space Group Number\nsetting = \"2\" # Space Group setting\nxtal_mgcro_2 = Crystal(latvecs, positions, spacegroup; types, setting)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Crystal\nHM symbol 'F d -3 m' (227)\nLattice params a=8.334, b=8.334, c=8.334, α=90°, β=90°, γ=90°\nCell volume 578.9\nType 'Mg', Wyckoff 8b (point group '-43m'):\n 1. [1/8, 1/8, 1/8]\n 2. [5/8, 5/8, 1/8]\n 3. [7/8, 3/8, 3/8]\n 4. [3/8, 7/8, 3/8]\n 5. [5/8, 1/8, 5/8]\n 6. [1/8, 5/8, 5/8]\n 7. [3/8, 3/8, 7/8]\n 8. [7/8, 7/8, 7/8]\nType 'Cr', Wyckoff 16c (point group '.-3m'):\n 9. [1/2, 0, 0]\n 10. [3/4, 1/4, 0]\n 11. [0, 1/2, 0]\n 12. [1/4, 3/4, 0]\n 13. [3/4, 0, 1/4]\n 14. [1/2, 1/4, 1/4]\n 15. [1/4, 1/2, 1/4]\n 16. [0, 3/4, 1/4]\n 17. [0, 0, 1/2]\n 18. [1/4, 1/4, 1/2]\n 19. [1/2, 1/2, 1/2]\n 20. [3/4, 3/4, 1/2]\n 21. [1/4, 0, 3/4]\n 22. [0, 1/4, 3/4]\n 23. [3/4, 1/2, 3/4]\n 24. [1/2, 3/4, 3/4]\nType 'O', Wyckoff 32e (point group '.3m'):\n 25. [0.7393, 0.0107, 0.0107]\n 26. [0.5107, 0.2393, 0.0107]\n 27. [0.2393, 0.5107, 0.0107]\n 28. [0.0107, 0.7393, 0.0107]\n 29. [0.5107, 0.0107, 0.2393]\n 30. [0.7393, 0.2393, 0.2393]\n 31. [0.0107, 0.5107, 0.2393]\n 32. [0.2393, 0.7393, 0.2393]\n 33. [0.2607, 0.2607, 0.2607]\n 34. [0.4893, 0.4893, 0.2607]\n 35. [0.7607, 0.7607, 0.2607]\n 36. [0.9893, 0.9893, 0.2607]\n 37. [0.4893, 0.2607, 0.4893]\n 38. [0.2607, 0.4893, 0.4893]\n 39. [0.9893, 0.7607, 0.4893]\n 40. [0.7607, 0.9893, 0.4893]\n 41. [0.2393, 0.0107, 0.5107]\n 42. [0.0107, 0.2393, 0.5107]\n 43. [0.7393, 0.5107, 0.5107]\n 44. [0.5107, 0.7393, 0.5107]\n 45. [0.0107, 0.0107, 0.7393]\n 46. [0.2393, 0.2393, 0.7393]\n 47. [0.5107, 0.5107, 0.7393]\n 48. [0.7393, 0.7393, 0.7393]\n 49. [0.7607, 0.2607, 0.7607]\n 50. [0.9893, 0.4893, 0.7607]\n 51. [0.2607, 0.7607, 0.7607]\n 52. [0.4893, 0.9893, 0.7607]\n 53. [0.9893, 0.2607, 0.9893]\n 54. [0.7607, 0.4893, 0.9893]\n 55. [0.4893, 0.7607, 0.9893]\n 56. [0.2607, 0.9893, 0.9893]\n","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"This result is correct, but at this point we might as well import the CIF file directly, which we now proceed to do.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#\"Experimentalist\"-Method-#3-(Correct-–-if-your-CIF-file-is)","page":"MgCr2O4 at Finite Temperature","title":"\"Experimentalist\" Method #3 (Correct – if your CIF file is)","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"To import a CIF file, simply give the path to Crystal. One may optionally specify a precision parameter to apply to the symmetry analysis.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"cif = pkgdir(Sunny, \"examples\", \"longer_examples\", \"MgCr2O4_160953_2009.cif\")\nxtal_mgcro_3 = Crystal(cif; symprec=0.001)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Crystal\nHM symbol 'F d -3 m' (227)\nLattice params a=8.333, b=8.333, c=8.333, α=90°, β=90°, γ=90°\nCell volume 578.6\nType 'Mg1', Wyckoff 8b (point group '-43m'):\n 1. [1/8, 1/8, 1/8]\n 2. [5/8, 5/8, 1/8]\n 3. [7/8, 3/8, 3/8]\n 4. [3/8, 7/8, 3/8]\n 5. [5/8, 1/8, 5/8]\n 6. [1/8, 5/8, 5/8]\n 7. [3/8, 3/8, 7/8]\n 8. [7/8, 7/8, 7/8]\nType 'Cr1', Wyckoff 16c (point group '.-3m'):\n 9. [1/2, 0, 0]\n 10. [3/4, 1/4, 0]\n 11. [0, 1/2, 0]\n 12. [1/4, 3/4, 0]\n 13. [3/4, 0, 1/4]\n 14. [1/2, 1/4, 1/4]\n 15. [1/4, 1/2, 1/4]\n 16. [0, 3/4, 1/4]\n 17. [0, 0, 1/2]\n 18. [1/4, 1/4, 1/2]\n 19. [1/2, 1/2, 1/2]\n 20. [3/4, 3/4, 1/2]\n 21. [1/4, 0, 3/4]\n 22. [0, 1/4, 3/4]\n 23. [3/4, 1/2, 3/4]\n 24. [1/2, 3/4, 3/4]\nType 'O1', Wyckoff 32e (point group '.3m'):\n 25. [0.7388, 0.0112, 0.0112]\n 26. [0.5112, 0.2388, 0.0112]\n 27. [0.2388, 0.5112, 0.0112]\n 28. [0.0112, 0.7388, 0.0112]\n 29. [0.5112, 0.0112, 0.2388]\n 30. [0.7388, 0.2388, 0.2388]\n 31. [0.0112, 0.5112, 0.2388]\n 32. [0.2388, 0.7388, 0.2388]\n 33. [0.2612, 0.2612, 0.2612]\n 34. [0.4888, 0.4888, 0.2612]\n 35. [0.7612, 0.7612, 0.2612]\n 36. [0.9888, 0.9888, 0.2612]\n 37. [0.4888, 0.2612, 0.4888]\n 38. [0.2612, 0.4888, 0.4888]\n 39. [0.9888, 0.7612, 0.4888]\n 40. [0.7612, 0.9888, 0.4888]\n 41. [0.2388, 0.0112, 0.5112]\n 42. [0.0112, 0.2388, 0.5112]\n 43. [0.7388, 0.5112, 0.5112]\n 44. [0.5112, 0.7388, 0.5112]\n 45. [0.0112, 0.0112, 0.7388]\n 46. [0.2388, 0.2388, 0.7388]\n 47. [0.5112, 0.5112, 0.7388]\n 48. [0.7388, 0.7388, 0.7388]\n 49. [0.7612, 0.2612, 0.7612]\n 50. [0.9888, 0.4888, 0.7612]\n 51. [0.2612, 0.7612, 0.7612]\n 52. [0.4888, 0.9888, 0.7612]\n 53. [0.9888, 0.2612, 0.9888]\n 54. [0.7612, 0.4888, 0.9888]\n 55. [0.4888, 0.7612, 0.9888]\n 56. [0.2612, 0.9888, 0.9888]\n","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Finally, we wish to restrict attention to the magnetic atoms in the unit cell while maintaining symmetry information for the full crystal, which is required to determine the correct exchange and g-factor anisotropies. This can be achieved with the subcrystal function.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"xtal_mgcro = subcrystal(xtal_mgcro_2,\"Cr\")","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Crystal\nHM symbol 'F d -3 m' (227)\nLattice params a=8.334, b=8.334, c=8.334, α=90°, β=90°, γ=90°\nCell volume 578.9\nType 'Cr', Wyckoff 16c (point group '.-3m'):\n 1. [1/2, 0, 0]\n 2. [3/4, 1/4, 0]\n 3. [0, 1/2, 0]\n 4. [1/4, 3/4, 0]\n 5. [3/4, 0, 1/4]\n 6. [1/2, 1/4, 1/4]\n 7. [1/4, 1/2, 1/4]\n 8. [0, 3/4, 1/4]\n 9. [0, 0, 1/2]\n 10. [1/4, 1/4, 1/2]\n 11. [1/2, 1/2, 1/2]\n 12. [3/4, 3/4, 1/2]\n 13. [1/4, 0, 3/4]\n 14. [0, 1/4, 3/4]\n 15. [3/4, 1/2, 3/4]\n 16. [1/2, 3/4, 3/4]\n","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#Making-a-System-and-assigning-interactions","page":"MgCr2O4 at Finite Temperature","title":"Making a System and assigning interactions","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html#Making-a-System","page":"MgCr2O4 at Finite Temperature","title":"Making a System","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Before assigning any interactions, we first have to set up a System using our Crystal.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"dims = (6, 6, 6) # Supercell dimensions\nspininfos = [SpinInfo(1, S=3/2, g=2)] # Specify spin information, note that all sites are symmetry equivalent\nsys_pyro = System(xtal_pyro, dims, spininfos, :dipole) # Make a system in dipole (Landau-Lifshitz) mode on pyrochlore lattice\nsys_mgcro = System(xtal_mgcro, dims, spininfos, :dipole); # Same on MgCr2O4 crystal","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"To understand what interactions we may assign to this system, we have to understand the the symmetry properties of the crystal, which we turn to next.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#Symmetry-analysis-for-exchange-and-single-ion-anisotropies","page":"MgCr2O4 at Finite Temperature","title":"Symmetry analysis for exchange and single-ion anisotropies","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"print_symmetry_table reports all the exchange interactions, single-site anisotropies, and g-factors allowed on our crystal. It takes a Cyrstal and a distance. We'll look at both the \"theorist's\" pyrochlore lattice,","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"print_symmetry_table(xtal_pyro, 5.9)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Atom 1\nType 'B', position [7/8, 5/8, 3/8], multiplicity 16\nAllowed g-tensor: [ A B -B\n B A B\n -B B A]\nAllowed anisotropy in Stevens operators:\n c₁*(𝒪[2,-2]+2𝒪[2,-1]-2𝒪[2,1]) +\n c₂*(7𝒪[4,-3]+2𝒪[4,-2]-𝒪[4,-1]+𝒪[4,1]+7𝒪[4,3]) + c₃*(𝒪[4,0]+5𝒪[4,4]) +\n c₄*(-11𝒪[6,-6]-8𝒪[6,-3]+𝒪[6,-2]-8𝒪[6,-1]+8𝒪[6,1]-8𝒪[6,3]) + c₅*(𝒪[6,0]-21𝒪[6,4]) + c₆*((9/5)𝒪[6,-6]+(24/5)𝒪[6,-5]+𝒪[6,-2]+(8/5)𝒪[6,-1]-(8/5)𝒪[6,1]-(24/5)𝒪[6,5])\n\nSunny.Bond(1, 3, [0, 0, 0])\nDistance 2.94658466788246, coordination 6\nConnects 'B' at [7/8, 5/8, 3/8] to 'B' at [7/8, 7/8, 1/8]\nAllowed exchange matrix:[ A -D D\n D B C\n -D C B]\nAllowed DM vector: [0 -D -D]\n\nSunny.Bond(1, 2, [0, 0, 0])\nDistance 5.10363435357589, coordination 12\nConnects 'B' at [7/8, 5/8, 3/8] to 'B' at [5/8, 1/8, 5/8]\nAllowed exchange matrix:[ A C-E D-F\n C+E B -C+E\n D+F -C-E A]\nAllowed DM vector: [E F -E]\n\nSunny.Bond(2, 6, [0, 0, 0])\nDistance 5.89316933576492, coordination 6\nConnects 'B' at [5/8, 1/8, 5/8] to 'B' at [5/8, 5/8, 1/8]\nAllowed exchange matrix:[A D D\n D B C\n D C B]\n\nSunny.Bond(1, 5, [0, 0, 0])\nDistance 5.89316933576492, coordination 6\nConnects 'B' at [7/8, 5/8, 3/8] to 'B' at [7/8, 1/8, 7/8]\nAllowed exchange matrix:[ A D -D\n D B C\n -D C B]\n\n","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"and for the the MgCrO4 crystal,","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"print_symmetry_table(xtal_mgcro, 6.0)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Atom 1\nType 'Cr', position [1/2, 0, 0], multiplicity 16\nAllowed g-tensor: [A B B\n B A B\n B B A]\nAllowed anisotropy in Stevens operators:\n c₁*(𝒪[2,-2]+2𝒪[2,-1]+2𝒪[2,1]) +\n c₂*(-7𝒪[4,-3]-2𝒪[4,-2]+𝒪[4,-1]+𝒪[4,1]+7𝒪[4,3]) + c₃*(𝒪[4,0]+5𝒪[4,4]) +\n c₄*(-11𝒪[6,-6]-8𝒪[6,-3]+𝒪[6,-2]-8𝒪[6,-1]-8𝒪[6,1]+8𝒪[6,3]) + c₅*(𝒪[6,0]-21𝒪[6,4]) + c₆*((9/5)𝒪[6,-6]+(24/5)𝒪[6,-5]+𝒪[6,-2]+(8/5)𝒪[6,-1]+(8/5)𝒪[6,1]+(24/5)𝒪[6,5])\n\nSunny.Bond(1, 2, [0, 0, 0])\nDistance 2.94658466788246, coordination 6\nConnects 'Cr' at [1/2, 0, 0] to 'Cr' at [3/4, 1/4, 0]\nAllowed exchange matrix:[A C -D\n C A -D\n D D B]\nAllowed DM vector: [-D D 0]\n\nSunny.Bond(1, 7, [0, 0, 0])\nDistance 5.10363435357589, coordination 12\nConnects 'Cr' at [1/2, 0, 0] to 'Cr' at [1/4, 1/2, 1/4]\nAllowed exchange matrix:[ A C-E D-F\n C+E B -C+E\n D+F -C-E A]\nAllowed DM vector: [E F -E]\n\nSunny.Bond(1, 3, [0, 0, 0])\nDistance 5.89316933576492, coordination 6\nConnects 'Cr' at [1/2, 0, 0] to 'Cr' at [0, 1/2, 0]\nAllowed exchange matrix:[A D C\n D A C\n C C B]\n\nSunny.Bond(1, 3, [1, 0, 0])\nDistance 5.89316933576492, coordination 6\nConnects 'Cr' at [1/2, 0, 0] to 'Cr' at [1, 1/2, 0]\nAllowed exchange matrix:[A D C\n D A C\n C C B]\n\n","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Note that the exchange anisotropies allowed on the the pyrochlore lattice are slightly different from those on the MgCr2O4 cyrstal due to the role of Mg and O in the bonds. Also note that Sunny has correctly identified the two inequivalent bonds 3a and 3b having the same length. A question may arises to know which bond is J3a and which is J3b, let's plot the structure.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"view_crystal(xtal_mgcro, 5.9)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"The crystal viewer shows that the second interaction – cyan color with distance of 5.89Å – is in fact the one hopping through a chromium site, meaning it is J3a! We will need to be careful with that later.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#Building-the-exchange-interactions-for-our-system","page":"MgCr2O4 at Finite Temperature","title":"Building the exchange interactions for our system","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"We begin by setting the scale of our exchange interactions on each bond.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"J1 = 3.27 # value of J1 in meV from Bai's PRL paper\nJ_pyro = [1.00,0.000,0.000,0.000]*J1 # pure nearest neighbor pyrochlore\nJ_mgcro = [1.00,0.0815,0.1050,0.085]*J1; # further neighbor pyrochlore relevant for MgCr2O4\n# val_J_mgcro = [1.00,0.000,0.025,0.025]*val_J1; # this is a funny setting from Conlon-Chalker","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"These values are then assigned to their corresponding bonds with set_exchange!.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"# === Assign exchange interactions to pyrochlore system ===\nset_exchange!(sys_pyro, J_pyro[1], Bond(1, 3, [0,0,0])) # J1\nset_exchange!(sys_pyro, J_pyro[2], Bond(1, 2, [0,0,0])) # J2\nset_exchange!(sys_pyro, J_pyro[3], Bond(2, 6, [0,0,0])) # J3a\nset_exchange!(sys_pyro, J_pyro[4], Bond(1, 5, [0,0,0])) # J3b\n\n# === Assign exchange interactions to MgCr2O4 system ===\nset_exchange!(sys_mgcro, J_mgcro[1], Bond(1, 2, [0,0,0])) # J1\nset_exchange!(sys_mgcro, J_mgcro[2], Bond(1, 7, [0,0,0])) # J2\nset_exchange!(sys_mgcro, J_mgcro[3], Bond(1, 3, [0,0,0])) # J3a -- Careful here!\nset_exchange!(sys_mgcro, J_mgcro[4], Bond(1, 3, [1,0,0])); # J3b -- And here!","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"We will not be assigning any single-ion anisotropies, so we have finished specifying our models. For good measure, we will set both systems to a random (infinite temperature) initial condition.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"randomize_spins!(sys_pyro)\nrandomize_spins!(sys_mgcro);","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#Cooling-our-System-amd-calculating-the-instantaneous-and-dynamic-structure-factors-at-the-final-temperature","page":"MgCr2O4 at Finite Temperature","title":"Cooling our System amd calculating the instantaneous and dynamic structure factors at the final temperature","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"We begin by thermalizing our system at a particular temperature. We will accomplish this by running Langevin dynamics. To do this, we must set up a Langevin integrator.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Δt = 0.05 # Integration time step in meV^-1\nλ = 0.1 # Phenomenological damping parameter\nkT = 1.8 # Desired temperature in meV\nlangevin = Langevin(Δt; λ, kT); # Construct integrator","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"We can now thermalize our systems by running the integrator.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"for _ in 1:2000\n step!(sys_pyro, langevin)\n step!(sys_mgcro, langevin)\nend","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"As a sanity check, we'll plot the real-space spin configurations of both systems after themalization. First the pyrochlore,","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"plot_spins(sys_pyro)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"and then the MgCr2O4,","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"plot_spins(sys_mgcro)","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#Instantaneous-Structure-Factor","page":"MgCr2O4 at Finite Temperature","title":"Instantaneous Structure Factor","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Next we can examine the instantaneous structure factor.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"isf_pyro = instant_correlations(sys_pyro)\nisf_mgcro = instant_correlations(sys_mgcro);","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"These are currently empty. Let's add correlation data from 10 trajectories.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"for _ in 1:10\n # Run dynamics to decorrelate\n for _ in 1:500\n step!(sys_pyro, langevin)\n step!(sys_mgcro, langevin)\n end\n # Add samples\n add_sample!(isf_pyro, sys_pyro)\n add_sample!(isf_mgcro, sys_mgcro)\nend","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"To retrieve the intensities, we set up a formula and call intensities_interpolated on an array of wave vectors.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"qvals = -4.0:0.025:4.0\nqs = [(qa, qb, 0) for qa in qvals, qb in qvals] # Wave vectors to query\n\nformula_pyro = intensity_formula(isf_pyro, :perp)\nformula_mgcro = intensity_formula(isf_mgcro, :perp)\nSq_pyro = instant_intensities_interpolated(isf_pyro, qs, formula_pyro)\nSq_mgcro = instant_intensities_interpolated(isf_mgcro, qs, formula_mgcro);","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Finally, we can plot the results.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"fig = Figure(; resolution=(1200,500))\naxparams = (aspect = true, xticks=-4:4, yticks=-4:4, titlesize=20,\n xlabel = \"𝐪a (2π a⁻¹)\", ylabel = \"𝐪b (2π b⁻¹)\", xlabelsize = 18, ylabelsize=18,)\nax_pyro = Axis(fig[1,1]; title=\"Pyrochlore\", axparams...)\nax_mgcro = Axis(fig[1,3]; title=\"MgCr2O4\", axparams...)\nhm = heatmap!(ax_pyro, qvals, qvals, Sq_pyro)\nColorbar(fig[1,2], hm)\nhm = heatmap!(ax_mgcro, qvals, qvals, Sq_mgcro)\nColorbar(fig[1,4], hm)\nfig","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#Dynamical-Structure-Factor","page":"MgCr2O4 at Finite Temperature","title":"Dynamical Structure Factor","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"We can also estimate the dynamical structure factor.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"sc_pyro = dynamical_correlations(sys_pyro; Δt, ωmax = 10.0, nω = 100)\nsc_mgcro = dynamical_correlations(sys_mgcro; Δt, ωmax = 10.0, nω = 100);","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Next we add some sample trajectories.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"for _ in 1:3\n # Run dynamics to decorrelate\n for _ in 1:500\n step!(sys_pyro, langevin)\n step!(sys_mgcro, langevin)\n end\n # Add samples\n add_sample!(sc_pyro, sys_pyro)\n add_sample!(sc_mgcro, sys_mgcro)\nend","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"We can now examine the structure factor intensities along a path in momentum space.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"fig = Figure(; resolution=(1200,900))\naxsqw = (xticks=-4:4, yticks=0:2:10, ylabel=\"E (meV)\", ylabelsize=18, xlabelsize=18, )\n\nqbs = 0.0:0.5:1.5 # Determine q_b for each slice\nfor (i, qb) in enumerate(qbs)\n path, _ = reciprocal_space_path(xtal_pyro, [[-4.0, qb, 0.0],[4.0, qb, 0.0]], 40) # Generate a path of wave\n # vectors through the BZ\n formula = intensity_formula(sc_pyro, :perp; kT) # Temperature keyword enables intensity rescaling\n Sqω_pyro = intensities_interpolated(sc_pyro, path, formula)\n\n ax = Axis(fig[fldmod1(i,2)...]; xlabel = \"q = (x, $qb, 0)\", axsqw...)\n ωs = available_energies(sc_pyro)\n heatmap!(ax, [p[1] for p in path], ωs, Sqω_pyro; colorrange=(0.0, 4.0))\nend\nfig","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"And let's take a look at the same slices for MgCr2O4.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"fig = Figure(; resolution=(1200,900))\n\nqbs = 0.0:0.5:1.5\nfor (i, qb) in enumerate(qbs)\n path, _ = reciprocal_space_path(xtal_mgcro, [[-4.0, qb, 0.0],[4.0, qb, 0.0]], 40) # Generate a path of wave\n # vectors through the BZ\n formula = intensity_formula(sc_mgcro, :perp; kT) # Temperature keyword enables intensity rescaling\n Sqω_mgcro = intensities_interpolated(sc_mgcro, path, formula)\n\n ax = Axis(fig[fldmod1(i,2)...]; xlabel = \"q = (x, $qb, 0)\", axsqw...)\n ωs = available_energies(sc_mgcro)\n heatmap!(ax, [p[1] for p in path], ωs, Sqω_mgcro; colorrange=(0.0, 4.0))\nend\nfig","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"(Image: )","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html#Instantaneous-structure-factor-from-a-dynamical-structure-factor","page":"MgCr2O4 at Finite Temperature","title":"Instantaneous structure factor from a dynamical structure factor","text":"","category":"section"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"Finally, we note that the instant structure factor can be calculated from the dynamical structure factor. We simply call instant_intensities rather than intensities. This will calculate the instantaneous structure factor from from 𝒮(𝐪ω) by integrating out ω . An advantage of doing this (as opposed to using instant_correlations) is that Sunny is able to apply a temperature- and energy-dependent intensity rescaling before integrating out the dynamical information. The results of this approach are more suitable for comparison with experimental data.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"qvals = -4.0:0.05:4.0\nqs = [(qa, qb, 0) for qa in qvals, qb in qvals] # Wave vectors to query\n\nformula_pyro = intensity_formula(sc_pyro, :perp; kT) # Temperature keyword enables intensity rescaling\nformula_mgcro = intensity_formula(sc_mgcro, :perp; kT) # Temperature keyword enables intensity rescaling\n\nSq_pyro = instant_intensities_interpolated(sc_pyro, qs, formula_pyro)\nSq_mgcro = instant_intensities_interpolated(sc_mgcro, qs, formula_mgcro);","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"We can plot the results below. It is useful to compare these to the plot above generated with an instant_correlations.","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"fig = Figure(; resolution=(1200,500))\nax_pyro = Axis(fig[1,1]; title=\"Pyrochlore\", axparams...)\nax_mgcro = Axis(fig[1,3]; title=\"MgCr2O4\", axparams...)\nhm = heatmap!(ax_pyro, qvals, qvals, Sq_pyro)\nColorbar(fig[1,2], hm)\nhm = heatmap!(ax_mgcro, qvals, qvals, Sq_mgcro)\nColorbar(fig[1,4], hm)\nfig","category":"page"},{"location":"examples/contributed/MgCr2O4-tutorial.html","page":"MgCr2O4 at Finite Temperature","title":"MgCr2O4 at Finite Temperature","text":"(Image: )","category":"page"},{"location":"renormalization.html#Interaction-Strength-Renormalization","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"","category":"section"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"A unique feature of Sunny is its support for building classical models where quantum spin is represented as an N-level system, rather than just an expected dipole. This generalization can be important when modeling quantum spin Hamiltonians that include, e.g., a single-ion anisotropy, or a biquadratic coupling between sites. Sunny also supports constraining quantum spin to the space of pure dipoles; in this case, Sunny will automatically perform an interaction strength renormalization that maximizes accuracy.","category":"page"},{"location":"renormalization.html#Local-operators","page":"Interaction Strength Renormalization","title":"Local operators","text":"","category":"section"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"A quantum spin-S state has N = 2S + 1 levels. Each local spin operator hatS^xyz is faithfully represented as an NN matrix. These matrices can be accessed using spin_matrices for a given label S. For example, the Pauli matrices are associated with S = 12.","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"When S 12, it is possible to construct multipole moments beyond the spin-dipole. For example,","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"S = spin_matrices(3/2)\n@assert S[3] ≈ diagm([3/2, 1/2, -1/2, -3/2])\n@assert S[3]^2 ≈ diagm([9/4, 1/4, 1/4, 9/4])","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"If the operator -S[3]^2 is passed to set_onsite_coupling!, it would set an easy-axis anisotropy in the hatz direction.","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"Any Hermitian operator can be expanded in the basis of Stevens operators hatmathcalO_kq up to a constant shift. To see this expansion, use print_stevens_expansion:","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"print_stevens_expansion((S[1]^2 + S[2]^2)) # Prints -(1/3)𝒪₂₀ + 5/2","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"Alternatively, the same operator could have been constructed directly from stevens_matrices:","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"O = stevens_matrices(3/2)\n@assert S[1]^2 + S[2]^2 ≈ -O[2, 0]/3 + (5/2)*I","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"See below for an explicit definition of Stevens operators as polynomials of the spin operators.","category":"page"},{"location":"renormalization.html#Renormalization-procedure-for-:dipole-mode","page":"Interaction Strength Renormalization","title":"Renormalization procedure for :dipole mode","text":"","category":"section"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"Sunny will typically operate in one of two modes: :SUN or :dipole. The former faithfully represents quantum spin as an SU(N) coherent-state which, for our purposes, is an N-component complex vector. In contrast, :dipole mode constrains the coherent-state to the space of pure dipoles. Here, Sunny will automatically renormalize the magnitude of each Stevens operator to achieve maximal consistency with :SUN mode. This procedure was derived in D. Dahlbom et al., [arXiv:2304.03874].","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"By way of illustration, consider a quantum operator hatmathcalH_mathrmlocal giving a single-ion anisotropy for one site. In Stevens operators,","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"hatmathcal H_mathrmlocal = sum_k q A_kq hatmathcalO_kq","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"for some coefficients A_kq.","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"In :SUN mode, Sunny will faithfully represent hatmathcal H_mathrmlocal as an NN matrix. In :dipole mode, the expected energy langle hatmathcal H_mathrmlocal rangle must somehow be approximated as a function of the expected dipole mathbfs.","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"One approach is to formally take S to infty, and this yields the traditional classical limit of a spin system. In this, limit spin operators commute, and expectation values of polynomials become polynomials of expectation values. For example, langle hatS^alpha hatS^betarangle to langle hatS^alpha rangle langle hatS^betarangle, because any corrections are damped by the factor S^-1 to 0. The expectation of a Stevens operator langle hatmathcalO_kq rangle becomes a Stevens function mathcalO_kq(mathbfs), i.e., a polynomial of expected dipole mathbfs = langle hatmathbfS rangle.","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"In a real magnetic compound, however, the spin magnitude S is not necessarily large. To obtain a better approximation, one should avoid the assumption S to infty. Our approach is to start with the full dynamics of SU(N) coherent states, and then constrain it to the space of pure dipole states mathbfsrangle. The latter are defined such that expectation values,","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"langle mathbfs hatmathbfS mathbfsrangle = mathbfs","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"have magnitude mathbfs = S, which is maximal.","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"For pure dipole states, expectations can be computed exactly,","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"langle mathbfs hatmathcalO mathbfsrangle = c_k mathcalO_kq(mathbfs)","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"The right-hand side involves a renormalization of the Stevens functions, where","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"beginalign*\nc_1 = 1 \nc_2 = 1-frac12S^-1 \nc_3 = 1-frac32S^-1+frac12S^-2 \nc_4 = 1-3S^-1+frac114S^-2-frac34S^-3 \nc_5 = 1-5S^-1+frac354S^-2-frac254S^-3+frac32S^-4 \nc_6 = 1-frac152S^-1+frac854S^-2-frac2258S^-3+frac1378S^-4-frac154S^-5 \nvdots\nendalign*","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"Constrained to the space of dipoles, the expected local energy becomes","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"E_mathrmlocal(mathbfs) = langle mathbfs hatmathcal H_mathrmlocal mathbfsrangle = sum_k q c_k A_kq mathcalO_kq(mathbfs)","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"It can be shown that SU(N) dynamics reduces to the usual Landau-Lifshitz dynamics of dipoles, but involving E_mathrmlocal(mathbfs) as the classical Hamiltonian. Through the renormalization factors c_k, Sunny avoids the large-S assumption, and gives a more accurate result.","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"Renormalization also applies to the coupling between different sites. In Sunny, couplings will often be expressed as a polynomial of spin operators using set_pair_coupling!, but any such coupling can be decomposed as sum of tensor products of Stevens operators. Without loss of generality, consider a single coupling between two Stevens operators hatmathcalH_mathrmcoupling = hatmathcalO_kq otimes hatmathcalO_kq along a bond connecting sites i and j. Upon constraining to pure dipole states mathbfs_irangle and mathbfs_jrangle, the expected energy takes the form E_mathrmcoupling = c_k c_k mathcalO_kq(mathbfs_i) mathcalO_kq(mathbfs_j), which now involves a product of renormalized Stevens functions. ","category":"page"},{"location":"renormalization.html#Use-:dipole_large_S-mode-to-disable-renormalization","page":"Interaction Strength Renormalization","title":"Use :dipole_large_S mode to disable renormalization","text":"","category":"section"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"Although we generally recommend the above renormalization procedure, there are circumstances where it is not desirable. Examples include reproducing a model-system study, or describing a micromagnetic system for which the Stoinfty limit is a good approximation. To simulate dipoles without interaction strength renormalization, construct a System using the mode :dipole_large_S. Symbolic operators in the large-S limit can be constructed by passing Inf to either spin_matrices or stevens_matrices.","category":"page"},{"location":"renormalization.html#Definition-of-Stevens-operators","page":"Interaction Strength Renormalization","title":"Definition of Stevens operators","text":"","category":"section"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"The Stevens operators hatmathcalO_kq are defined as polynomials of angular momentum operators hatS_xyz in some spin-S representation.","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"Using","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"beginalign*\nX = mathbfhatS cdot mathbfhatS = S (S+1) \nhatS_pm = hatS_x pm i hatS_y \nphi_+ = frac14quad phi_- = frac14 i\nendalign*","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"the relevant Stevens operators are defined as,","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"beginalign*\nhatmathcalO_00 =1\n\nhatmathcalO_1pm1 =phi_pm(hatS_+pmhatS_-)+mathrmhc\nhatmathcalO_10 =hatS_z\n\nhatmathcalO_2pm2 =phi_pm(hatS_+^2pmhatS_-^2)+mathrmhc\nhatmathcalO_2pm1 =phi_pm(hatS_+pmhatS_-)hatS_z+mathrmhc\nhatmathcalO_20 =3hatS_z^2-X\n\nhatmathcalO_3pm3 =phi_pm(hatS_+^3pmhatS_-^3)+mathrmhc\nhatmathcalO_3pm2 =phi_pm(hatS_+^2pmhatS_-^2)hatS_z+mathrmhc\nhatmathcalO_3pm1 =phi_pm(hatS_+pmhatS_-)(5hatS_z^2-X-12)+mathrmhc\nhatmathcalO_30 =5hatS_z^3-(3X-1)hatS_z\n\nhatmathcalO_4pm4 =phi_pm(hatS_+^4pmhatS_-^4)+mathrmhc\nhatmathcalO_4pm3 =phi_pm(hatS_+^3pmhatS_-^3)hatS_z+mathrmhc\nhatmathcalO_4pm2 =phi_pm(hatS_+^2pmhatS_-^2)(7hatS_z^2-(X+5))+mathrmhc\nhatmathcalO_4pm1 =phi_pm(hatS_+pmhatS_-)(7hatS_z^3-(3X+1)hatS_z)+mathrmhc\nhatmathcalO_40 =35hatS_z^4-(30X-25)hatS_z^2+(3X^2-6X)\n\nhatmathcalO_5pm5 =phi_pm(hatS_+^5pmhatS_-^5)+mathrmhc\nhatmathcalO_5pm4 =phi_pm(hatS_+^4pmhatS_-^4)hatS_z+mathrmhc\nhatmathcalO_5pm3 =phi_pm(hatS_+^3pmhatS_-^3)(9hatS_z^2-(X+332))+mathrmhc\nhatmathcalO_5pm2 =phi_pm(hatS_+^2pmhatS_-^2)(3hatS_z^3-(X+6)hatS_z)+mathrmhc\nhatmathcalO_5pm1 =phi_pm(hatS_+pmhatS_-)(21hatS_z^4-14XhatS_z^2+(X^2-X+32))+mathrmhc\nhatmathcalO_50 =63hatS_z^5-(70X-105)hatS_z^3+(15X^2-50X+12)hatS_z\n\nhatmathcalO_6pm6 =phi_pm(hatS_+^6pmhatS_-^6)+mathrmhc\nhatmathcalO_6pm5 =phi_pm(hatS_+^5pmhatS_-^5)hatS_z+mathrmhc\nhatmathcalO_6pm4 =phi_pm(hatS_+^4pmhatS_-^4)(11hatS_z^2-X-38)+mathrmhc\nhatmathcalO_6pm3 =phi_pm(hatS_+^3pmhatS_-^3)(11hatS_z^3-(3X+59)hatS_z)+mathrmhc\nhatmathcalO_6pm2 =phi_pm(hatS_+^2pmhatS_-^2)(33hatS_z^4-(18X+123)hatS_z^2+X^2+10X+102)+mathrmhc\nhatmathcalO_6pm1 =phi_pm(hatS_+pmhatS_-)(33hatS_z^5-(30X-15)hatS_z^3+(5X^2-10X+12)hatS_z)+mathrmhc\nhatmathcalO_60 =231hatS_z^6-(315X-735)hatS_z^4+(105X^2-525X+294)hatS_z^2-5X^3+40X^2-60X\nendalign*","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"Computer-generated tables of Stevens operators with k 6 are available from C. Rudowicz and C. Y. Chung, J. Phys.: Condens. Matter 16, 5825 (2004), but these typically do not appear in magnetic simulations.","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"The case k=1 gives the dipole operators,","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"(hatmathcalO_11 hatmathcalO_10 hatmathcalO_1-1) = (hatS_x hatS_z hatS_y)","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"The case k=2 gives the quadrupole operators,","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"(hatmathcalO_22 dots hatmathcalO_2-2) = left(hatS_x^2 - hatS_y^2 frachatS_x hatS_z + hatS_z hatS_x2 2hatS_z^2-hatS_x^2-hatS_y^2 frachatS_y hatS_z + hatS_z hatS_y2 hatS_x hatS_y + hatS_y hatS_xright)","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"For each k value, the set of operators hatmathcalO_kq for q = -k dots k form an irreducible representation of the group of rotations O(3). That is, rotation will transform hatmathcalO_kq into a linear combination of hatmathcalO_kq where q varies but k remains fixed. ","category":"page"},{"location":"renormalization.html","page":"Interaction Strength Renormalization","title":"Interaction Strength Renormalization","text":"In taking the large-S limit, each dipole operator is replaced by its expectation value mathbfs = langle hatmathbfS rangle, and only leading-order terms are retained. The operator hatmathcalO_kq becomes a homogeneous polynomial O_kq(mathbfs) of order k in the spin components. One can see these polynomials by constructing stevens_matrices with the argument S = Inf. Due to the normalization constraint, each dipole can be expressed in polar angles, (theta phi). Then the Stevens functions O_kq(mathbfs) correspond to the spherical harmonic functions Y_l^m(theta phi) where l=k and m=q; this correspondence is valid up to k and q-dependent rescaling factors.","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"EditURL = \"../../../../examples/spinw_tutorials/SW15_Ba3NbFe3Si2O14.jl\"","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"Download this example as Jupyter notebook or Julia script.","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html#SW15-BaNbFeSiO","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"","category":"section"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"This is a Sunny port of SpinW Tutorial 15, originally authored by Sandor Toth. The goal is to calculate the linear spin wave theory spectrum for Ba₃NbFe₃Si₂O₁₄.","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"Load packages","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"using Sunny, GLMakie","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"Build a Crystal for Ba₃NbFe₃Si₂O₁₄ using the crystal structure from Marty et al., Phys. Rev. Lett. 101, 247201 (2008).","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"a = b = 8.539 # (Å)\nc = 5.2414\nlatvecs = lattice_vectors(a, b, c, 90, 90, 120)\ntypes = [\"Fe\",\"Nb\",\"Ba\",\"Si\",\"O\",\"O\",\"O\"]\npositions = [[0.24964,0,0.5],[0,0,0],[0.56598,0,0],[2/3,1/3,0.5220],[2/3,1/3,0.2162],[0.5259,0.7024,0.3536],[0.7840,0.9002,0.7760]]\nlangasite = Crystal(latvecs, positions, 150; types)\ncrystal = subcrystal(langasite, \"Fe\")\nview_crystal(crystal, 7)","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"Create a System with a lattice size of (117). The magnetic structure of Ba₃NbFe₃Si₂O₁₄ was determined to have the ordering wavevector 𝐐=(0017) and hence the magnetic unit cell has 7 sites.","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"latsize = (1,1,7)\nS = 5/2\nseed = 5\nsys = System(crystal, latsize, [SpinInfo(1; S, g=2)], :dipole)","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"Set exchange interactions as parametrized in Loire et al., Phys. Rev. Lett. 106, 207201 (2011)","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"J₁ = 0.85\nJ₂ = 0.24\nJ₃ = 0.053\nJ₄ = 0.017\nJ₅ = 0.24\nset_exchange!(sys, J₁, Bond(3, 2, [1,1,0]))\nset_exchange!(sys, J₄, Bond(1, 1, [0,0,1]))\nset_exchange!(sys, J₂, Bond(1, 3, [0,0,0]))","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"The final two exchanges define the chirality of the magnetic structure. The crystal chirality, epsilon_T, the chirality of each triangle, ϵ_D and the sense of rotation of the spin helices along c, ϵ_H. The three chiralities are related by ϵ_T=ϵ_D ϵ_H. We now assign J_3 and J_5 according to the crystal chirality.","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"ϵD = -1\nϵH = +1\nϵT = ϵD * ϵH\n\nif ϵT == -1\n set_exchange!(sys, J₃, Bond(2, 3, [-1,-1,1]))\n set_exchange!(sys, J₅, Bond(3, 2, [1,1,1]))\nelseif ϵT == 1\n set_exchange!(sys, J₅, Bond(2, 3, [-1,-1,1]))\n set_exchange!(sys, J₃, Bond(3, 2, [1,1,1]))\nelse\n throw(\"Provide a valid chirality\")\nend","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"Whilst Sunny provides tools to optimize the ground state automatically, in this case we already know the model ground state. Set the spiral magnetic order using set_spiral_order_on_sublattice!. It takes an ordering wavevector q, an axis of rotation for the spins axis, and the initial spin S0 for each sublattice.","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"q = [0, 0, 1/7]\naxis = [0,0,1]\nset_spiral_order_on_sublattice!(sys, 1; q, axis, S0=[1, 0, 0])\nset_spiral_order_on_sublattice!(sys, 2; q, axis, S0=[-1/2, -sqrt(3)/2, 0])\nset_spiral_order_on_sublattice!(sys, 3; q, axis, S0=[-1/2, +sqrt(3)/2, 0])\n\nplot_spins(sys; color=[s[1] for s in sys.dipoles])","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"Define a path in reciprocal space, 01-1+xi for xi = 0 dots 3.","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"points_rlu = [[0,1,-1],[0,1,-1+1],[0,1,-1+2],[0,1,-1+3]];\ndensity = 100\npath, xticks = reciprocal_space_path(crystal, points_rlu, density);\nnothing #hide","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"Calculate broadened intensities","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"swt = SpinWaveTheory(sys)\nγ = 0.15 # width in meV\nbroadened_formula = intensity_formula(swt, :perp; kernel=lorentzian(γ))\nenergies = collect(0:0.01:6) # 0 < ω < 6 (meV).\nis = intensities_broadened(swt, path, energies, broadened_formula);\nnothing #hide","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"Plot","category":"page"},{"location":"examples/spinw/SW15_Ba3NbFe3Si2O14.html","page":"SW15 - Ba₃NbFe₃Si₂O₁₄","title":"SW15 - Ba₃NbFe₃Si₂O₁₄","text":"fig = Figure()\nax = Axis(fig[1,1]; xlabel=\"Momentum (r.l.u.)\", ylabel=\"Energy (meV)\", xticks, xticklabelrotation=π/6)\nheatmap!(ax, 1:size(is,1), energies, is, colorrange=(0,5))\nfig","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"EditURL = \"../../../examples/03_LLD_CoRh2O4.jl\"","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"Download this example as Jupyter notebook or Julia script.","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html#.-Landau-Lifshitz-dynamics-of-CoRhO-at-finite-*T*","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"","category":"section"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"using Sunny, GLMakie, Statistics","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html#System-construction","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"System construction","text":"","category":"section"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"Construct the system as in the previous CoRh₂O₄ tutorial. After optimization, the system will be in an unfrustrated antiferromagnetic ground state.","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"a = 8.5031 # (Å)\nlatvecs = lattice_vectors(a, a, a, 90, 90, 90)\ncryst = Crystal(latvecs, [[0,0,0]], 227, setting=\"1\")\nlatsize = (2, 2, 2)\nS = 3/2\nJ = 0.63 # (meV)\nsys = System(cryst, latsize, [SpinInfo(1; S, g=2)], :dipole; seed=0)\nset_exchange!(sys, J, Bond(1, 3, [0,0,0]))\nrandomize_spins!(sys)\nminimize_energy!(sys)","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"Use resize_supercell to build a new system with a lattice of 10×10×10 unit cells. The desired Néel order is retained.","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"sys = resize_supercell(sys, (10, 10, 10))\n@assert energy_per_site(sys) ≈ -2J*S^2","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"Use the stochastic Landau-Lifshitz dynamics to thermalize system into equilibrium at finite temperature. This is a Langevin equation, which includes damping and noise terms. The strength of the noise term is automatically fixed according to the damping time scale λ and the target temperature, according to a fluctuation-dissipation theorem.","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"Δt = 0.05/abs(J*S) # Time step\nλ = 0.1 # Dimensionless damping time-scale\nkT = 16 * meV_per_K # 16K, a temperature slightly below ordering\nlangevin = Langevin(Δt; λ, kT);\nnothing #hide","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"Because the magnetic order has been initialized correctly, relatively few additional Langevin time-steps are required to reach thermal equilibrium.","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"energies = [energy_per_site(sys)]\nfor _ in 1:1000\n step!(sys, langevin)\n push!(energies, energy_per_site(sys))\nend\nplot(energies, color=:blue, figure=(resolution=(600,300),), axis=(xlabel=\"Time steps\", ylabel=\"Energy (meV)\"))","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"Thermal fluctuations are apparent in the spin configuration.","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"S_ref = sys.dipoles[1,1,1,1]\nplot_spins(sys; color=[s'*S_ref for s in sys.dipoles])","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html#Instantaneous-structure-factor","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"Instantaneous structure factor","text":"","category":"section"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"To visualize the instantaneous (equal-time) structure factor, create an object instant_correlations and use add_sample! to accumulated data for the equilibrated spin configuration.","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"sc = instant_correlations(sys)\nadd_sample!(sc, sys) # Accumulate the newly sampled structure factor into `sf`","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"Collect 20 additional decorrelated samples. For each sample, about 100 Langevin time-steps is sufficient to collect approximately uncorrelated statistics.","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"for _ in 1:20\n for _ in 1:100\n step!(sys, langevin)\n end\n add_sample!(sc, sys)\nend","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"Define a slice of momentum space. Wavevectors are specified in reciprocal lattice units (RLU). The notation q1s in -10:0.1:10 indicates that the first q-component ranges from -10 to 10 in intervals of 0.1. That is, q spans over 20 Brillouin zones. To convert to absolute momentum units, each component of q would need to be scaled by a reciprocal lattice vector.","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"q1s = -10:0.1:10\nq2s = -10:0.1:10\nqs = [[q1, q2, 0.0] for q1 in q1s, q2 in q2s];\nnothing #hide","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"Plot the instantaneous structure factor for the given q-slice. We employ the appropriate FormFactor for Co2⁺. An intensity_formula defines how dynamical correlations correspond to the observable structure factor. The function instant_intensities_interpolated calculates intensities at the target qs by interpolating over the data available at discrete reciprocal-space lattice points.","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"formfactors = [FormFactor(\"Co2\")]\ninstant_formula = intensity_formula(sc, :perp; formfactors)\niq = instant_intensities_interpolated(sc, qs, instant_formula);\nnothing #hide","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"Plot the resulting intensity data I(𝐪). The color scale is clipped to 50% of the maximum intensity.","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"heatmap(q1s, q2s, iq;\n colorrange = (0, maximum(iq)/2),\n axis = (\n xlabel=\"Momentum Transfer Qx (r.l.u)\", xlabelsize=16,\n ylabel=\"Momentum Transfer Qy (r.l.u)\", ylabelsize=16,\n aspect=true,\n )\n)","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html#Dynamical-structure-factor","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"Dynamical structure factor","text":"","category":"section"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"To collect statistics for the dynamical structure factor intensities I(𝐪ω) at finite temperature, use dynamical_correlations. Now, each call to add_sample! will run a classical spin dynamics trajectory. Longer-time trajectories will be required to achieve greater energy resolution, as controlled by nω. Here, we pick a moderate number of energies, nω = 50, which will make the simulation run quickly.","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"ωmax = 6.0 # Maximum energy to resolve (meV)\nnω = 50 # Number of energies to resolve\nsc = dynamical_correlations(sys; Δt, nω, ωmax, process_trajectory=:symmetrize)","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"Each sample requires running a full dynamical trajectory to measure correlations, so we here restrict to 5 samples.","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"for _ in 1:5\n for _ in 1:100\n step!(sys, langevin)\n end\n add_sample!(sc, sys)\nend","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"Define points that define a piecewise-linear path through reciprocal space, and a sampling density.","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"points = [[3/4, 3/4, 0],\n [ 0, 0, 0],\n [ 0, 1/2, 1/2],\n [1/2, 1, 0],\n [ 0, 1, 0],\n [1/4, 1, 1/4],\n [ 0, 1, 0],\n [ 0, -4, 0]]\ndensity = 50 # (Å)\npath, xticks = reciprocal_space_path(cryst, points, density);\nnothing #hide","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"Calculate I(𝐪 ω) intensities along this path with Lorentzian broadening on the scale of 0.1 meV.","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"formula = intensity_formula(sc, :perp; formfactors, kT=langevin.kT)\nη = 0.1\niqw = intensities_interpolated(sc, path, formula)\niqwc = broaden_energy(sc, iqw, (ω, ω₀) -> lorentzian(ω-ω₀, η));\nnothing #hide","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"Plot the intensity data on a clipped color scale","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"ωs = available_energies(sc)\nheatmap(1:size(iqwc, 1), ωs, iqwc;\n colorrange = (0, maximum(iqwc)/50),\n axis = (;\n xlabel=\"Momentum Transfer (r.l.u)\",\n ylabel=\"Energy Transfer (meV)\",\n xticks,\n xticklabelrotation=π/5,\n aspect = 1.4,\n )\n)","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html#Powder-averaged-intensity","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"Powder averaged intensity","text":"","category":"section"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"Define spherical shells in reciprocal space via their radii, in absolute units of 1/Å. For each shell, calculate and average the intensities at 100 𝐪-points, sampled approximately uniformly.","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"radii = 0:0.05:3.5 # (1/Å)\noutput = zeros(Float64, length(radii), length(ωs))\nfor (i, radius) in enumerate(radii)\n pts = reciprocal_space_shell(sc.crystal, radius, 100)\n is = intensities_interpolated(sc, pts, formula)\n is = broaden_energy(sc, is, (ω,ω₀)->lorentzian(ω-ω₀, η))\n output[i, :] = mean(is , dims=1)[1,:]\nend","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"Plot resulting powder-averaged structure factor","category":"page"},{"location":"examples/03_LLD_CoRh2O4.html","page":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","title":"3. Landau-Lifshitz dynamics of CoRh₂O₄ at finite T","text":"heatmap(radii, ωs, output;\n axis = (\n xlabel=\"|Q| (Å⁻¹)\",\n ylabel=\"Energy Transfer (meV)\",\n aspect = 1.4,\n ),\n colorrange = (0, 20.0)\n)","category":"page"},{"location":"versions.html#Version-History","page":"Version History","title":"Version History","text":"","category":"section"},{"location":"versions.html#v0.5.6","page":"Version History","title":"v0.5.6","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Animated spin dynamics is now possible. Call notify on the result of plot_spins to trigger redrawing of the frame. The argument colorfn to plot_spins supports animation of colors.\nGeneral pair couplings are now supported in set_pair_coupling! and set_pair_coupling_at!. :SUN supports interactions of any order, but :dipole mode is limited to bilinear and biquadratic coupling of the spin.\nTo perform a calculation with dipoles in the large-S limit, use the new mode :dipole_large_S when constructing a System.\nDeprecate the option biquad to set_exchange!. Use instead set_pair_coupling!, which generalizes beyond the scalar biquadratic.\nDeprecate spin_operators, stevens_operators, large_S_spin_operators and large_S_stevens_operators. Use instead spin_matrices and stevens_matrices, which require a specific spin-S label. To infer this, one can use spin_label.\nRemove unused option energy_tol in SpinWaveTheory.","category":"page"},{"location":"versions.html#v0.5.5","page":"Version History","title":"v0.5.5","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"reshape_supercell now allows reshaping to multiples of the primitive unit cell, which can speed up certain calculations. This is illustrated in the CoRh₂O₄ powder averaging tutorial.\nresize_supercell now allows all resizings.\nAdded energy_per_site.\nset_spiral_order_on_sublattice! cannot work on reshaped systems.\nVarious bug fixes. In particular, an intensity_formula with :full will now uniformly calculate a 3x3 matrix of complex numbers.","category":"page"},{"location":"versions.html#v0.5.4","page":"Version History","title":"v0.5.4","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Various enhancements to view_crystal. Atoms are now labeled by index, and bonds support interactive inspection (GLMakie only). Font sizes work correctly on Makie v0.20-beta. If using Makie v0.19 on a high-resolution display, pass rescale=1.5 to enlarge font sizes.\nThe function suggest_magnetic_supercell now requires only a list of wavevectors, and will return a 33 matrix that can be programmatically passed to reshape_supercell. The new tolerance parameter tol allows suggest_magnetic_supercell to approximate incommensurate wavevectors with nearby commensurate ones.\nNew functions set_spiral_order! and set_spiral_order_on_sublattice! can be used to initialize a spiral, single-Q order.\nSunny now retains all constant energy shifts that have been introduced by anisotropy operators.\nFix export_vtk functionality.","category":"page"},{"location":"versions.html#v0.5.3","page":"Version History","title":"v0.5.3","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Add large_S_spin_operators and large_S_stevens_operators to support single-ion anisotropies in dipole mode without renormalization. Set large_S=true in set_exchange! to avoid renormalization of biquadratics.\nview_crystal has been rewritten in Makie.\nplot_spins now expects ghost_radius in physical length units.\nSpinWaveTheory will (currently) error if provided a system with enable_dipole_dipole!.","category":"page"},{"location":"versions.html#v0.5.2","page":"Version History","title":"v0.5.2","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Form factors for 5d transition ions.\nDownload links for notebooks and scripts on each doc example\nVarious bug fixes.","category":"page"},{"location":"versions.html#v0.5.1","page":"Version History","title":"v0.5.1","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Fix binning edge cases.\nplot_spins accepts resolution argument.","category":"page"},{"location":"versions.html#v0.5.0","page":"Version History","title":"v0.5.0","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"New features.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Support for Linear Spin Wave Theory in :dipole and :SUN modes. (Thanks Hao Zhang!)","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"New function minimize_energy! to efficiently find an optimal configuration of spin dipoles or SU(N) coherent states.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Major refactors and enhancements to intensity calculations. This new interface allows unification between LSWT and classical spin dynamics calculations. This interface allows: Custom observables as local quantum operators, better support for linebroadening, and automatic binning to facilitate comparison with experimental data. See intensity_formula for documentation. Use load_nxs to load experimental neutron scattering data.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Breaking changes.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Require Julia 1.9.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Replace set_anisotropy! with a new function set_onsite_coupling! (and similarly set_onsite_coupling_at!). The latter expects an explicit matrix representation for the local Hamiltonian. This can be constructed, e.g., as a linear combination of stevens_operators, or as a polynomial of spin_operators. To understand the mapping between these two, the new function print_stevens_expansion acts on an arbitrary local operator.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Remove set_biquadratic!. Instead, use an optional keyword argument biquad to set_exchange!.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Rename DynamicStructureFactor to dynamical_correlations. Similarly, replace InstantStructureFactor with instant_correlations. The return type has been renamed SampledCorrelations to emphasize that the object may be holding thermodynamic samples, which are collected using add_sample!. Upon construction, the SampledCorrelations object will be empty (no initial sample).","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Remove intensities function. Instead, use one of intensities_interpolated or intensities_binned. These will require an intensity_formula, which defines a calculator (e.g., LSWT).","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Rename connected_path to reciprocal_space_path, which now returns an xticks object that can be used in plotting. Replace spherical_shell with reciprocal_space_shell that functions similarly.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Rename polarize_spin! to set_dipole! for consistency with set_coherent!. The behavior of the former function is unchanged: the spin at a given site will still be polarized along the provided direction.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Rename all_sites to eachsite consistent with Julia convention for iterators.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Rename reshape_geometry to reshape_supercell, which is the fundamental reshaping function. Rename resize_periodically to resize_supercell.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"The constructor SpinInfo now requires a g-factor or tensor as a named argument.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"The constructor FormFactor no longer accepts an atom index. Instead, the form factors are associated with site-symmetry classes in order of appearance.","category":"page"},{"location":"versions.html#v0.4.3","page":"Version History","title":"v0.4.3","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Experimental support for linear SpinWaveTheory, implemented in SU(N) mode. This module may evolve rapidly.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Implement renormalization of single-ion anisotropy and biquadratic interactions when in :dipole mode. This makes the model more faithful to the quantum mechanical Hamiltonian, but is also a breaking change.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Various improvements and bugfixes for to_inhomogeneous. Setting inhomogeneous interactions via set_exchange_at! should now infer the correct bond offset direction, or will report an ambiguity error. Ambiguities can be resolved by passing an explicit offset.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"The function remove_periodicity! disables periodicity along specified dimensions.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Rename StaticStructureFactor to InstantStructureFactor.","category":"page"},{"location":"versions.html#v0.4.2","page":"Version History","title":"v0.4.2","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Introduce LocalSampler, a framework for MCMC sampling with local spin updates.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Rename print_dominant_wavevectors to print_wrapped_intensities to reduce confusion with the physical instantaneous intensities.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"The function spherical_shell now takes a radius in physical units of inverse Å.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"New exported functions global_position, magnetic_moment, all_sites.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Remove all uses of Base.deepcopy which resolves crashes.","category":"page"},{"location":"versions.html#v0.4.1","page":"Version History","title":"v0.4.1","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"The function to_inhomogeneous creates a system that supports inhomogeneous interactions, which can be set using set_exchange_at!, etc.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"set_biquadratic! replaces set_exchange_with_biquadratic!.","category":"page"},{"location":"versions.html#v0.4.0","page":"Version History","title":"v0.4.0","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"This update includes many breaking changes, and is missing some features of 0.3.0.","category":"page"},{"location":"versions.html#Creating-a-spin-System","page":"Version History","title":"Creating a spin System","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Rename SpinSystem to System. Its constructor now has the form,","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"System(crystal, latsize, infos, mode)","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"The parameter infos is now a list of SpinInfo objects. Each defines spin angular momentum S = frac12 1 frac32 , and an optional g-factor or tensor.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"The parameter mode is one of :SUN or :dipole.","category":"page"},{"location":"versions.html#Setting-interactions","page":"Version History","title":"Setting interactions","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Interactions are now added mutably to an existing System using the following functions: set_external_field!, set_exchange!, set_onsite_coupling!, enable_dipole_dipole!.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"As a convenience, one can use dmvec(D) to convert a DM vector to a 33 antisymmetric exchange matrix.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Fully general single-ion anisotropy is now possible. The function set_onsite_coupling! expects the single ion anisotropy to be expressed as a polynomial in symbolic spin operators 𝒮, or as a linear combination of symbolic Stevens operators 𝒪. For example, an easy axis anisotropy in the direction n may be written D*(𝒮⋅n)^2.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Stevens operators 𝒪[k,q] admit polynomial expression in spin operators 𝒮[α]. Conversely, a polynomial of spin operators can be expressed as a linear combination of Stevens operators. To see this expansion use print_anisotropy_as_stevens.","category":"page"},{"location":"versions.html#Inhomogeneous-field","page":"Version History","title":"Inhomogeneous field","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"An external field can be applied to a single site with set_external_field_at!. ","category":"page"},{"location":"versions.html#Structure-factor-rewrite","page":"Version History","title":"Structure factor rewrite","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"The calculation of structure factors has been completely rewritten. For the new interface see the documentation tutorials.","category":"page"},{"location":"versions.html#Various","page":"Version History","title":"Various","text":"","category":"section"},{"location":"versions.html","page":"Version History","title":"Version History","text":"The \"Sampler\" interface is in flux. Langevin replaces both LangevinHeunP and LangevinSampler. Local spin-flip Monte Carlo sampling methods are temporarily broken.\nrepeat_periodically replaces extend_periodically.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"Additional related functions include resize_periodically and reshape_geometry, the latter being fundamental.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"print_symmetry_table replaces print_bond_table().","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"The new function includes the list of symmetry-allowed single ion anisotropies in addition to exchange interactions.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"When reading CIF files, the field _atom_site_label is now used in place of the field _atom_site_type_symbol.","category":"page"},{"location":"versions.html","page":"Version History","title":"Version History","text":"This is required for correctness. The field _atom_site_label is guaranteed to be present, and is guaranteed to be a distinct label for each symmetry-inequivalent site. Code that explicitly referred to site labels (e.g. in calls to subcrystal) will need to be updated to use the new label.","category":"page"},{"location":"index.html#Overview","page":"Overview","title":"Overview","text":"","category":"section"},{"location":"index.html","page":"Overview","title":"Overview","text":"Sunny is a Julia package for modeling atomic-scale magnetism. It provides powerful tools to study equilibrium and non-equilibrium magnetic phenomena. In particular, it allows estimation of dynamical structure factor intensities, mathcalS(𝐪ω), to support quantitative modeling of experimental scattering data.","category":"page"},{"location":"index.html","page":"Overview","title":"Overview","text":"Features include:","category":"page"},{"location":"index.html","page":"Overview","title":"Overview","text":"Generalized spin dynamics using SU(N) coherent states.\nAbility to specify a crystal from a .cif file or its spacegroup symmetry.\nInteractive visualizations of the 3D crystals and magnetic ordering.\nSymmetry analysis to classify allowed interaction terms, and to propagate them by symmetry.\nSingle-ion anisotropy at arbitrary order, which can be specified using Stevens operators or as a polynomial of spin operators.\nMonte Carlo sampling of spin configurations in thermal equilibrium, and optimization tools.\nMeasurements of dynamical correlations. At low temperature, one can use linear spin wave theory and its multi-boson generalization. This generalizes to finite temperatures using the classical dynamics, which allows for strongly nonlinear effects.\nLong-range dipole-dipole interactions accelerated with the fast Fourier transform (FFT).\nSupport for comparison with experimental data: form factor, dipole factor, temperature-dependent classical-to-quantum factors, intensity binning, etc.","category":"page"},{"location":"examples/spinw/SW08_Kagome_AFM.html","page":"SW8 - Kagome Antiferromagnet","title":"SW8 - Kagome Antiferromagnet","text":"EditURL = \"../../../../examples/spinw_tutorials/SW08_Kagome_AFM.jl\"","category":"page"},{"location":"examples/spinw/SW08_Kagome_AFM.html","page":"SW8 - Kagome Antiferromagnet","title":"SW8 - Kagome Antiferromagnet","text":"Download this example as Jupyter notebook or Julia script.","category":"page"},{"location":"examples/spinw/SW08_Kagome_AFM.html#SW8-Kagome-Antiferromagnet","page":"SW8 - Kagome Antiferromagnet","title":"SW8 - Kagome Antiferromagnet","text":"","category":"section"},{"location":"examples/spinw/SW08_Kagome_AFM.html","page":"SW8 - Kagome Antiferromagnet","title":"SW8 - Kagome Antiferromagnet","text":"This is a Sunny port of SpinW Tutorial 8, originally authored by Bjorn Fak and Sandor Toth. The goal is to calculate the linear spin wave theory spectrum for the sqrt3 times sqrt3 order of a Kagome antiferromagnet.","category":"page"},{"location":"examples/spinw/SW08_Kagome_AFM.html","page":"SW8 - Kagome Antiferromagnet","title":"SW8 - Kagome Antiferromagnet","text":"Load Packages","category":"page"},{"location":"examples/spinw/SW08_Kagome_AFM.html","page":"SW8 - Kagome Antiferromagnet","title":"SW8 - Kagome Antiferromagnet","text":"using Sunny, GLMakie","category":"page"},{"location":"examples/spinw/SW08_Kagome_AFM.html","page":"SW8 - Kagome Antiferromagnet","title":"SW8 - Kagome Antiferromagnet","text":"Build a Crystal with Poverline3 space group,","category":"page"},{"location":"examples/spinw/SW08_Kagome_AFM.html","page":"SW8 - Kagome Antiferromagnet","title":"SW8 - Kagome Antiferromagnet","text":"a = 1\nlatvecs = lattice_vectors(a, a, 10a, 90, 90, 120)\ncrystal = Crystal(latvecs, [[1/2,0,0]], 147)","category":"page"},{"location":"examples/spinw/SW08_Kagome_AFM.html","page":"SW8 - Kagome Antiferromagnet","title":"SW8 - Kagome Antiferromagnet","text":"Build a System with antiferrogmanetic nearest neighbor exchange J=1.","category":"page"},{"location":"examples/spinw/SW08_Kagome_AFM.html","page":"SW8 - Kagome Antiferromagnet","title":"SW8 - Kagome Antiferromagnet","text":"S = 1\nsys = System(crystal, (3,3,1), [SpinInfo(1; S, g=2)], :dipole)\nJ = 1.0\nset_exchange!(sys, J, Bond(2,3,[0,0,0]))","category":"page"},{"location":"examples/spinw/SW08_Kagome_AFM.html","page":"SW8 - Kagome Antiferromagnet","title":"SW8 - Kagome Antiferromagnet","text":"Initialize to an energy minimizing magnetic structure, for which nearest-neighbor spins are at 120° angles.","category":"page"},{"location":"examples/spinw/SW08_Kagome_AFM.html","page":"SW8 - Kagome Antiferromagnet","title":"SW8 - Kagome Antiferromagnet","text":"q = -[1/3, 1/3, 0]\naxis = [0,0,1]\nset_spiral_order_on_sublattice!(sys, 1; q, axis, S0=[cos(0),sin(0),0])\nset_spiral_order_on_sublattice!(sys, 2; q, axis, S0=[cos(0),sin(0),0])\nset_spiral_order_on_sublattice!(sys, 3; q, axis, S0=[cos(2π/3),sin(2π/3),0])\nplot_spins(sys; dims=2)","category":"page"},{"location":"examples/spinw/SW08_Kagome_AFM.html","page":"SW8 - Kagome Antiferromagnet","title":"SW8 - Kagome Antiferromagnet","text":"Check energy. Each site participates in 4 bonds with energy JS^2cos(2π3). Factor of 1/2 avoids double counting.","category":"page"},{"location":"examples/spinw/SW08_Kagome_AFM.html","page":"SW8 - Kagome Antiferromagnet","title":"SW8 - Kagome Antiferromagnet","text":"@assert energy_per_site(sys) ≈ (4/2)*J*S^2*cos(2π/3)","category":"page"},{"location":"examples/spinw/SW08_Kagome_AFM.html","page":"SW8 - Kagome Antiferromagnet","title":"SW8 - Kagome Antiferromagnet","text":"Define a path in reciprocal space.","category":"page"},{"location":"examples/spinw/SW08_Kagome_AFM.html","page":"SW8 - Kagome Antiferromagnet","title":"SW8 - Kagome Antiferromagnet","text":"points_rlu = [[-1/2, 0, 0], [0, 0, 0], [1/2, 1/2, 0]]\ndensity = 100\npath, xticks = reciprocal_space_path(crystal, points_rlu, density);\nnothing #hide","category":"page"},{"location":"examples/spinw/SW08_Kagome_AFM.html","page":"SW8 - Kagome Antiferromagnet","title":"SW8 - Kagome Antiferromagnet","text":"Calculate discrete intensities","category":"page"},{"location":"examples/spinw/SW08_Kagome_AFM.html","page":"SW8 - Kagome Antiferromagnet","title":"SW8 - Kagome Antiferromagnet","text":"swt = SpinWaveTheory(sys)\nformula = intensity_formula(swt, :perp; kernel=delta_function_kernel)\ndisp, intensity = intensities_bands(swt, path, formula);\nnothing #hide","category":"page"},{"location":"examples/spinw/SW08_Kagome_AFM.html","page":"SW8 - Kagome Antiferromagnet","title":"SW8 - Kagome Antiferromagnet","text":"Plot over a restricted color range from [0,1e-2]. Note that the intensities of the flat band at zero-energy are off-scale.","category":"page"},{"location":"examples/spinw/SW08_Kagome_AFM.html","page":"SW8 - Kagome Antiferromagnet","title":"SW8 - Kagome Antiferromagnet","text":"fig = Figure()\nax = Axis(fig[1,1]; xlabel=\"Momentum (r.l.u.)\", ylabel=\"Energy (meV)\", xticks, xticklabelrotation=π/6)\nylims!(ax, -1e-1, 2.3)\nfor i in axes(disp, 2)\n lines!(ax, 1:length(disp[:,i]), disp[:,i]; color=intensity[:,i], colorrange=(0,1e-2))\nend\nfig","category":"page"}] } diff --git a/dev/structure-factor.html b/dev/structure-factor.html index 55979df27..b6e23674b 100644 --- a/dev/structure-factor.html +++ b/dev/structure-factor.html @@ -1,9 +1,9 @@ -Structure Factor Calculations · Sunny documentation
    GitHub

    Structure Factor Calculations

    Overview

    The dynamical structure factor is of fundamental importance for characterizing a magnetic system, and facilitates quantitative comparison between theory and experimental scattering data.

    Consider, for example, a two-point dynamical spin correlation function, $⟨s^α(𝐱+Δ𝐱, t+Δt) s^β(𝐱, t)⟩$. Here $s^α(𝐱, t)$ represents the time dynamics of a spin dipole component $α$ at position $𝐱$, and brackets represent an average over equilibrium initial conditions and over $(𝐱, t)$. The dynamical structure factor is defined as the Fourier transform of this two-point correlation in both space and time, up to an overall scaling factor. Using the convolution theorem, the result is,

    \[𝒮^{αβ}(𝐪, ω) = \frac{1}{V} ⟨ŝ^α(𝐪, ω)^\ast ŝ^β(𝐪, ω) ⟩,\]

    with $V$ the system volume. We will restrict attention to lattice systems with periodic boundaries.

    Consider a crystal unit cell defined by three lattice vectors $𝐚_1, 𝐚_2, 𝐚_3$, and linear system sizes $L_1, L_2, L_3$ measured in unit cells. The allowed momentum vectors take on discrete values $𝐪 = \sum_{α=1}^{3} m_α 𝐛_α / L_α$, where $m_α$ are an integers and the reciprocal lattice vectors $𝐛_α$ are defined to satisfy $𝐚_α ⋅ 𝐛_β = 2π δ_{α,β}$. For a Bravais lattice, $𝐪$ will be periodic in the first Brillouin zone, i.e., under any shift $𝐪 → 𝐪 ± 𝐛_α$. More generally, consider a non-Bravais lattice such that each unit cell may contain multiple spins. By partitioning spins $s_j(𝐱,t)$ according to their sublattice index $j$, the relevant momenta $𝐪$ remain discretized as above, but now periodicity in the first Brillouin zone is lost. The structure factor may be written as a phase-average over the displacements between sublattices $𝐫_{j,k}$,

    \[𝒮^{αβ}(𝐪, ω) = ∑_{j,k} e^{i 𝐫_{j,k} ⋅ 𝐪} 𝒮̃^{αβ}_{j,k}(𝐪, ω) ⟩,\]

    From a theoretical perspective, the quantity

    \[𝒮̃^{αβ}_{j,k}(𝐪, ω) = \frac{1}{V} ⟨ŝ_j^α(𝐪, ω)^\ast ŝ_k^β(𝐪, ω)⟩\]

    is fundamental. For each sublattice $j$, the data $ŝ_j^α(𝐪, ω)$ can be efficiently obtained by fast Fourier tranformation of a real space configuration $s_j^α(𝐱, t)$. Internally, Sunny will calculate and store the discrete $𝒮̃^{αβ}_{j,k}(𝐪, ω)$ correlation data, and use this to construct $𝒮^{αβ}(𝐪,ω)$ intensities that can be compared with experiment.

    Calculating this structure factor involves several steps, with various possible settings. Sunny provides a number of tools to facilitate this calculation and to extract information from the results. These tools are briefly outlined below. Please see the Examples for a "real life" use case. Detailed function information is available in the Library API.

    Estimating stucture factors with classical dynamics

    Classical dynamics may be used to estimate structure factor data by analyzing the spin-spin correlations of dynamical trajectories. This is fundamentally a Monte Carlo approach, as the trajectories must be started from an initial spin configuration that is sampled at thermal equilibrium. (Note that it is not possible to estimate a true T=0 dynamical structure factor using this method, but the temperature may be very low.) Samples are accumulated into a SampledCorrelations, from which intensity information may be extracted. The user does not typically build their own SampledCorrelations but instead initializes one by calling either dynamical_correlations or instant_correlations, as described below.

    Estimating a dynamical structure factor: $𝒮(𝐪,ω)$

    A SampledCorrelations for estimating the dynamical structure factor, $𝒮^{αβ}(𝐪,ω)$, may be created by calling dynamical_correlations. This requires three keyword arguments. These will determine the dynamics used to calculate samples and, consequently, the $ω$ information that will be available.

    1. Δt: Determines the step size used for simulating the dynamics. A smaller number will require proportionally more calculation time. While a smaller Δt will enable the resolution of higher energies, Δt is typically selected to ensure numerical stability rather than to maximize the largest $ω$ value. A safe choice is to use the smaller value of Δt = 0.1/(J* S^2) or Δt = 0.1/(D * S), where S is magnetic moment of the largest local spin (as specified in SpinInfo), J is the parameter governing the largest bilinear interaction (e.g. exchange), and D is the parameter governing the largest single-site term of the Hamiltonian (e.g., anisotropy or Zeeman term).
    2. ωmax: Sets the maximum resolved energy. Note that this is not independent of Δt. If ωmax too large, Sunny will throw an error and ask you to choose a smaller Δt.
    3. nω: Determines the number of energy bins to resolve. A larger number will require more calculation time.

    A sample may be added by calling add_sample!(sc, sys). The input sys must be a spin configuration in good thermal equilibrium, e.g., using the continuous Langevin dynamics or using single spin flip trials with LocalSampler. The statistical quality of the $𝒮^{αβ}(𝐪,ω)$ can be improved by repeatedly generating decorrelated spin configurations in sys and calling add_sample! on each configuration.

    The outline of typical use case might look like this:

    # Make a `SampledCorrelations`
+Structure Factor Calculations · Sunny documentation
    GitHub
    Structure Factor Calculations
    Overview
    The dynamical structure factor is of fundamental importance for characterizing a magnetic system, and facilitates quantitative comparison between theory and experimental scattering data.
    Consider, for example, a two-point dynamical spin correlation function, $⟨s^α(𝐱+Δ𝐱, t+Δt) s^β(𝐱, t)⟩$. Here $s^α(𝐱, t)$ represents the time dynamics of a spin dipole component $α$ at position $𝐱$, and brackets represent an average over equilibrium initial conditions and over $(𝐱, t)$. The dynamical structure factor is defined as the Fourier transform of this two-point correlation in both space and time, up to an overall scaling factor. Using the convolution theorem, the result is,
    \[𝒮^{αβ}(𝐪, ω) = \frac{1}{V} ⟨ŝ^α(𝐪, ω)^\ast ŝ^β(𝐪, ω) ⟩,\]
    with $V$ the system volume. We will restrict attention to lattice systems with periodic boundaries.
    Consider a crystal unit cell defined by three lattice vectors $𝐚_1, 𝐚_2, 𝐚_3$, and linear system sizes $L_1, L_2, L_3$ measured in unit cells. The allowed momentum vectors take on discrete values $𝐪 = \sum_{α=1}^{3} m_α 𝐛_α / L_α$, where $m_α$ are an integers and the reciprocal lattice vectors $𝐛_α$ are defined to satisfy $𝐚_α ⋅ 𝐛_β = 2π δ_{α,β}$. For a Bravais lattice, $𝐪$ will be periodic in the first Brillouin zone, i.e., under any shift $𝐪 → 𝐪 ± 𝐛_α$. More generally, consider a non-Bravais lattice such that each unit cell may contain multiple spins. By partitioning spins $s_j(𝐱,t)$ according to their sublattice index $j$, the relevant momenta $𝐪$ remain discretized as above, but now periodicity in the first Brillouin zone is lost. The structure factor may be written as a phase-average over the displacements between sublattices $𝐫_{j,k}$,
    \[𝒮^{αβ}(𝐪, ω) = ∑_{j,k} e^{i 𝐫_{j,k} ⋅ 𝐪} 𝒮̃^{αβ}_{j,k}(𝐪, ω) ⟩,\]
    From a theoretical perspective, the quantity
    \[𝒮̃^{αβ}_{j,k}(𝐪, ω) = \frac{1}{V} ⟨ŝ_j^α(𝐪, ω)^\ast ŝ_k^β(𝐪, ω)⟩\]
    is fundamental. For each sublattice $j$, the data $ŝ_j^α(𝐪, ω)$ can be efficiently obtained by fast Fourier tranformation of a real space configuration $s_j^α(𝐱, t)$. Internally, Sunny will calculate and store the discrete $𝒮̃^{αβ}_{j,k}(𝐪, ω)$ correlation data, and use this to construct $𝒮^{αβ}(𝐪,ω)$ intensities that can be compared with experiment.
    Calculating this structure factor involves several steps, with various possible settings. Sunny provides a number of tools to facilitate this calculation and to extract information from the results. These tools are briefly outlined below. Please see the Examples for a "real life" use case. Detailed function information is available in the Library API.
    Estimating stucture factors with classical dynamics
    Classical dynamics may be used to estimate structure factor data by analyzing the spin-spin correlations of dynamical trajectories. This is fundamentally a Monte Carlo approach, as the trajectories must be started from an initial spin configuration that is sampled at thermal equilibrium. (Note that it is not possible to estimate a true T=0 dynamical structure factor using this method, but the temperature may be very low.) Samples are accumulated into a SampledCorrelations, from which intensity information may be extracted. The user does not typically build their own SampledCorrelations but instead initializes one by calling either dynamical_correlations or instant_correlations, as described below.
    Estimating a dynamical structure factor: $𝒮(𝐪,ω)$
    A SampledCorrelations for estimating the dynamical structure factor, $𝒮^{αβ}(𝐪,ω)$, may be created by calling dynamical_correlations. This requires three keyword arguments. These will determine the dynamics used to calculate samples and, consequently, the $ω$ information that will be available. 
    1. Δt: Determines the step size used for simulating the dynamics. A smaller number will require proportionally more calculation time. While a smaller Δt will enable the resolution of higher energies, Δt is typically selected to ensure numerical stability rather than to maximize the largest $ω$ value. A safe choice is to use the smaller value of Δt = 0.1/(J* S^2) or Δt = 0.1/(D * S), where S is magnetic moment of the largest local spin (as specified in SpinInfo), J is the parameter governing the largest bilinear interaction (e.g. exchange), and D is the parameter governing the largest single-site term of the Hamiltonian (e.g., anisotropy or Zeeman term).
    2. ωmax: Sets the maximum resolved energy. Note that this is not independent of Δt. If ωmax too large, Sunny will throw an error and ask you to choose a smaller Δt. 
    3. nω: Determines the number of energy bins to resolve. A larger number will require more calculation time.
    A sample may be added by calling add_sample!(sc, sys). The input sys must be a spin configuration in good thermal equilibrium, e.g., using the continuous Langevin dynamics or using single spin flip trials with LocalSampler. The statistical quality of the $𝒮^{αβ}(𝐪,ω)$ can be improved by repeatedly generating decorrelated spin configurations in sys and calling add_sample! on each configuration.
    The outline of typical use case might look like this:
    # Make a `SampledCorrelations`
 sc = dynamical_correlations(sys; Δt=0.05, ωmax=10.0, nω=100) 
 
 # Add samples
 for _ in 1:nsamples
    decorrelate_system(sys) # Perform some type of Monte Carlo simulation
    add_sample!(sc, sys)    # Use spins to calculate trajectory and accumulate new sample of 𝒮(𝐪,ω)
-end
    The calculation may be configured in a number of ways; see the dynamical_correlations documentation for a list of all keywords.
    Estimating an instantaneous ("static") structure factor: $𝒮(𝐪)$
    Sunny provides two methods for calculating instantaneous, or static, structure factors: $𝒮^{αβ}(𝐪)$. The first involves calculating spatial spin-spin correlations at single time slices. The second involves calculating a dynamic structure factor first and integrating out the $ω$ information. The advantage of the latter approach is that it enables application of an $ω$-dependent classical-to-quantum rescaling of structure factor intensities, a method that should be preferred whenever comparing results to experimental data or spin wave calculations. A disadvantage of this approach is that it is computationally more expensive. There are also many cases when it is not straightforward to calculate a meaningful dynamics, as when working with Ising spins. In this section we will discuss how to calculate instantaneous structure factors from static spin configurations. Information about calculating instantaneous data from a dynamical correlations can be found in the following section.
    The basic usage for the instantaneous case is very similar to the dynamic case, except one calls instant_correlations instead of dynamical_correlations to configure a SampledCorrelations. Note that there are no required keywords as there is no need to specify any dynamics. instant_correlations will return a SampledCorrelations containing no data. Samples may be added by calling add_sample!(sc, sys), where sc is the SampledCorrelations. When performing a finite-temperature calculation, it is important to ensure that the spin configuration in the sys represents a good equilibrium sample, as in the dynamical case. Note, however, that we recommend calculating instantaneous correlations at finite temperature calculations by using full dynamics (i.e., using dynamical_correlations) and then integrating out the energy axis. An approach to doing this is described in the next section.
    Extracting information from sampled correlation data
    The basic function for extracting information from a SampledCorrelations at a particular wave vector, $𝐪$, is intensities_interpolated. It takes a SampledCorrelations, a list of wave vectors, and an intensity_formula. The intensity_formula specifies how to contract and correct correlation data to arrive at a physical intensity. A simple example is formula = intensity_formula(sc, :perp), which will instruct Sunny apply polarization corrections: $\sum_{αβ}(I-q_α q_β) 𝒮^{αβ}(𝐪,ω)$. An intensity at the wave vector $𝐪 = (𝐛_2 + 𝐛_3)/2$ may then be retrieved with  intensities_interpolated(sf, [[0.0, 0.5, 0.5]], formula) .  intensities_interpolated returns a list of nω elements at each wavevector. The corresponding $ω$ values can be retrieved by calling available_energies on sf.
    Since Sunny only calculates the structure factor on a finite lattice when performing classical simulations, it is important to realize that exact information is only available at a discrete set of wave vectors. Specifically, for each axis index $i$, we will get information at $q_i = \frac{n}{L_i}$, where $n$ runs from $(\frac{-L_i}{2}+1)$ to $\frac{L_i}{2}$ and $L_i$ is the linear dimension of the lattice used for the calculation. If you request a wave vector that does not fall into this set, Sunny will automatically round to the nearest $𝐪$ that is available. If intensities_interpolated is given the keyword argument interpolation=:linear, Sunny will use trilinear interpolation to determine a result at the requested wave vector. 
    To retrieve the intensities at all wave vectors for which there is exact data, first call the function available_wave_vectors to generate a list of qs. This takes an optional keyword argument bzsize, which must be given a tuple of three integers specifying the number of Brillouin zones to calculate, e.g., bzsize=(2,2,2). The resulting list of wave vectors may then be passed to intensities_interpolated.
    Alternatively, intensities_binned can be used to place the exact data into histogram bins for comparison with experiment.
    The convenience function reciprocal_space_path returns a list of wavevectors sampled along a path that connects specified $𝐪$ points. This list can be used as an input to intensities. Another convenience method, reciprocal_space_shell will generate points on a sphere of a given radius. This is useful for powder averaging. 
    A number of arguments for intensity_formula are available which modify the calculation of structure factor intensity. It is generally recommended to provide a value of kT corresponding to the temperature of sampled configurations. Given kT, Sunny will include an energy- and temperature-dependent classical-to-quantum  rescaling of intensities in the formula.
    To retrieve intensity data from a instantaneous structure factor, use instant_intensities_interpolated, which accepts similar arguments to intensities_interpolated. This function may also be used to calculate instantaneous information from a dynamical correlation data, i.e. from a SampledCorrelations created with dynamical_correlations. Note that it is important to supply a value to kT to reap the benefits of this approach over simply calculating a static structure factor at the outset. 
    
+end

    The calculation may be configured in a number of ways; see the dynamical_correlations documentation for a list of all keywords.

    Estimating an instantaneous ("static") structure factor: $𝒮(𝐪)$

    Sunny provides two methods for calculating instantaneous, or static, structure factors: $𝒮^{αβ}(𝐪)$. The first involves calculating spatial spin-spin correlations at single time slices. The second involves calculating a dynamic structure factor first and integrating out the $ω$ information. The advantage of the latter approach is that it enables application of an $ω$-dependent classical-to-quantum rescaling of structure factor intensities, a method that should be preferred whenever comparing results to experimental data or spin wave calculations. A disadvantage of this approach is that it is computationally more expensive. There are also many cases when it is not straightforward to calculate a meaningful dynamics, as when working with Ising spins. In this section we will discuss how to calculate instantaneous structure factors from static spin configurations. Information about calculating instantaneous data from a dynamical correlations can be found in the following section.

    The basic usage for the instantaneous case is very similar to the dynamic case, except one calls instant_correlations instead of dynamical_correlations to configure a SampledCorrelations. Note that there are no required keywords as there is no need to specify any dynamics. instant_correlations will return a SampledCorrelations containing no data. Samples may be added by calling add_sample!(sc, sys), where sc is the SampledCorrelations. When performing a finite-temperature calculation, it is important to ensure that the spin configuration in the sys represents a good equilibrium sample, as in the dynamical case. Note, however, that we recommend calculating instantaneous correlations at finite temperature calculations by using full dynamics (i.e., using dynamical_correlations) and then integrating out the energy axis. An approach to doing this is described in the next section.

    Extracting information from sampled correlation data

    The basic function for extracting information from a SampledCorrelations at a particular wave vector, $𝐪$, is intensities_interpolated. It takes a SampledCorrelations, a list of wave vectors, and an intensity_formula. The intensity_formula specifies how to contract and correct correlation data to arrive at a physical intensity. A simple example is formula = intensity_formula(sc, :perp), which will instruct Sunny apply polarization corrections: $\sum_{αβ}(I-q_α q_β) 𝒮^{αβ}(𝐪,ω)$. An intensity at the wave vector $𝐪 = (𝐛_2 + 𝐛_3)/2$ may then be retrieved with intensities_interpolated(sf, [[0.0, 0.5, 0.5]], formula) . intensities_interpolated returns a list of nω elements at each wavevector. The corresponding $ω$ values can be retrieved by calling available_energies on sf.

    Since Sunny only calculates the structure factor on a finite lattice when performing classical simulations, it is important to realize that exact information is only available at a discrete set of wave vectors. Specifically, for each axis index $i$, we will get information at $q_i = \frac{n}{L_i}$, where $n$ runs from $(\frac{-L_i}{2}+1)$ to $\frac{L_i}{2}$ and $L_i$ is the linear dimension of the lattice used for the calculation. If you request a wave vector that does not fall into this set, Sunny will automatically round to the nearest $𝐪$ that is available. If intensities_interpolated is given the keyword argument interpolation=:linear, Sunny will use trilinear interpolation to determine a result at the requested wave vector.

    To retrieve the intensities at all wave vectors for which there is exact data, first call the function available_wave_vectors to generate a list of qs. This takes an optional keyword argument bzsize, which must be given a tuple of three integers specifying the number of Brillouin zones to calculate, e.g., bzsize=(2,2,2). The resulting list of wave vectors may then be passed to intensities_interpolated.

    Alternatively, intensities_binned can be used to place the exact data into histogram bins for comparison with experiment.

    The convenience function reciprocal_space_path returns a list of wavevectors sampled along a path that connects specified $𝐪$ points. This list can be used as an input to intensities. Another convenience method, reciprocal_space_shell will generate points on a sphere of a given radius. This is useful for powder averaging.

    A number of arguments for intensity_formula are available which modify the calculation of structure factor intensity. It is generally recommended to provide a value of kT corresponding to the temperature of sampled configurations. Given kT, Sunny will include an energy- and temperature-dependent classical-to-quantum rescaling of intensities in the formula.

    To retrieve intensity data from a instantaneous structure factor, use instant_intensities_interpolated, which accepts similar arguments to intensities_interpolated. This function may also be used to calculate instantaneous information from a dynamical correlation data, i.e. from a SampledCorrelations created with dynamical_correlations. Note that it is important to supply a value to kT to reap the benefits of this approach over simply calculating a static structure factor at the outset.

    diff --git a/dev/versions.html b/dev/versions.html index 91b59ecbc..ddaf64102 100644 --- a/dev/versions.html +++ b/dev/versions.html @@ -1,2 +1,2 @@ -Version History · Sunny documentation
    GitHub

    Version History

    v0.5.6

    • Animated spin dynamics is now possible. Call notify on the result of plot_spins to trigger redrawing of the frame. The argument colorfn to plot_spins supports animation of colors.
    • General pair couplings are now supported in set_pair_coupling! and set_pair_coupling_at!. :SUN supports interactions of any order, but :dipole mode is limited to bilinear and biquadratic coupling of the spin.
    • To perform a calculation with dipoles in the large-$S$ limit, use the new mode :dipole_large_S when constructing a System.
    • Deprecate the option biquad to set_exchange!. Use instead set_pair_coupling!, which generalizes beyond the scalar biquadratic.
    • Deprecate spin_operators, stevens_operators, large_S_spin_operators and large_S_stevens_operators. Use instead spin_matrices and stevens_matrices, which require a specific spin-$S$ label. To infer this, one can use spin_label.
    • Remove unused option energy_tol in SpinWaveTheory.

    v0.5.5

    • reshape_supercell now allows reshaping to multiples of the primitive unit cell, which can speed up certain calculations. This is illustrated in the CoRh₂O₄ powder averaging tutorial.
    • resize_supercell now allows all resizings.
    • Added energy_per_site.
    • set_spiral_order_on_sublattice! cannot work on reshaped systems.
    • Various bug fixes. In particular, an intensity_formula with :full will now uniformly calculate a 3x3 matrix of complex numbers.

    v0.5.4

    • Various enhancements to view_crystal. Atoms are now labeled by index, and bonds support interactive inspection (GLMakie only). Font sizes work correctly on Makie v0.20-beta. If using Makie v0.19 on a high-resolution display, pass rescale=1.5 to enlarge font sizes.
    • The function suggest_magnetic_supercell now requires only a list of wavevectors, and will return a $3×3$ matrix that can be programmatically passed to reshape_supercell. The new tolerance parameter tol allows suggest_magnetic_supercell to approximate incommensurate wavevectors with nearby commensurate ones.
    • New functions set_spiral_order! and set_spiral_order_on_sublattice! can be used to initialize a spiral, single-$Q$ order.
    • Sunny now retains all constant energy shifts that have been introduced by anisotropy operators.
    • Fix export_vtk functionality.

    v0.5.3

    • Add large_S_spin_operators and large_S_stevens_operators to support single-ion anisotropies in dipole mode without renormalization. Set large_S=true in set_exchange! to avoid renormalization of biquadratics.
    • view_crystal has been rewritten in Makie.
    • plot_spins now expects ghost_radius in physical length units.
    • SpinWaveTheory will (currently) error if provided a system with enable_dipole_dipole!.

    v0.5.2

    • Form factors for 5d transition ions.
    • Download links for notebooks and scripts on each doc example
    • Various bug fixes.

    v0.5.1

    • Fix binning edge cases.
    • plot_spins accepts resolution argument.

    v0.5.0

    New features.

    Support for Linear Spin Wave Theory in :dipole and :SUN modes. (Thanks Hao Zhang!)

    New function minimize_energy! to efficiently find an optimal configuration of spin dipoles or SU(N) coherent states.

    Major refactors and enhancements to intensity calculations. This new interface allows unification between LSWT and classical spin dynamics calculations. This interface allows: Custom observables as local quantum operators, better support for linebroadening, and automatic binning to facilitate comparison with experimental data. See intensity_formula for documentation. Use load_nxs to load experimental neutron scattering data.

    Breaking changes.

    Require Julia 1.9.

    Replace set_anisotropy! with a new function set_onsite_coupling! (and similarly set_onsite_coupling_at!). The latter expects an explicit matrix representation for the local Hamiltonian. This can be constructed, e.g., as a linear combination of stevens_operators, or as a polynomial of spin_operators. To understand the mapping between these two, the new function print_stevens_expansion acts on an arbitrary local operator.

    Remove set_biquadratic!. Instead, use an optional keyword argument biquad to set_exchange!.

    Rename DynamicStructureFactor to dynamical_correlations. Similarly, replace InstantStructureFactor with instant_correlations. The return type has been renamed SampledCorrelations to emphasize that the object may be holding thermodynamic samples, which are collected using add_sample!. Upon construction, the SampledCorrelations object will be empty (no initial sample).

    Remove intensities function. Instead, use one of intensities_interpolated or intensities_binned. These will require an intensity_formula, which defines a calculator (e.g., LSWT).

    Rename connected_path to reciprocal_space_path, which now returns an xticks object that can be used in plotting. Replace spherical_shell with reciprocal_space_shell that functions similarly.

    Rename polarize_spin! to set_dipole! for consistency with set_coherent!. The behavior of the former function is unchanged: the spin at a given site will still be polarized along the provided direction.

    Rename all_sites to eachsite consistent with Julia convention for iterators.

    Rename reshape_geometry to reshape_supercell, which is the fundamental reshaping function. Rename resize_periodically to resize_supercell.

    The constructor SpinInfo now requires a $g$-factor or tensor as a named argument.

    The constructor FormFactor no longer accepts an atom index. Instead, the form factors are associated with site-symmetry classes in order of appearance.

    v0.4.3

    Experimental support for linear SpinWaveTheory, implemented in SU(N) mode. This module may evolve rapidly.

    Implement renormalization of single-ion anisotropy and biquadratic interactions when in :dipole mode. This makes the model more faithful to the quantum mechanical Hamiltonian, but is also a breaking change.

    Various improvements and bugfixes for to_inhomogeneous. Setting inhomogeneous interactions via set_exchange_at! should now infer the correct bond offset direction, or will report an ambiguity error. Ambiguities can be resolved by passing an explicit offset.

    The function remove_periodicity! disables periodicity along specified dimensions.

    Rename StaticStructureFactor to InstantStructureFactor.

    v0.4.2

    Introduce LocalSampler, a framework for MCMC sampling with local spin updates.

    Rename print_dominant_wavevectors to print_wrapped_intensities to reduce confusion with the physical instantaneous intensities.

    The function spherical_shell now takes a radius in physical units of inverse Å.

    New exported functions global_position, magnetic_moment, all_sites.

    Remove all uses of Base.deepcopy which resolves crashes.

    v0.4.1

    The function to_inhomogeneous creates a system that supports inhomogeneous interactions, which can be set using set_exchange_at!, etc.

    set_biquadratic! replaces set_exchange_with_biquadratic!.

    v0.4.0

    This update includes many breaking changes, and is missing some features of 0.3.0.

    Creating a spin System

    Rename SpinSystem to System. Its constructor now has the form,

    System(crystal, latsize, infos, mode)

    The parameter infos is now a list of SpinInfo objects. Each defines spin angular momentum $S = \frac{1}{2}, 1, \frac{3}{2}, …$, and an optional $g$-factor or tensor.

    The parameter mode is one of :SUN or :dipole.

    Setting interactions

    Interactions are now added mutably to an existing System using the following functions: set_external_field!, set_exchange!, set_onsite_coupling!, enable_dipole_dipole!.

    As a convenience, one can use dmvec(D) to convert a DM vector to a $3×3$ antisymmetric exchange matrix.

    Fully general single-ion anisotropy is now possible. The function set_onsite_coupling! expects the single ion anisotropy to be expressed as a polynomial in symbolic spin operators 𝒮, or as a linear combination of symbolic Stevens operators 𝒪. For example, an easy axis anisotropy in the direction n may be written D*(𝒮⋅n)^2.

    Stevens operators 𝒪[k,q] admit polynomial expression in spin operators 𝒮[α]. Conversely, a polynomial of spin operators can be expressed as a linear combination of Stevens operators. To see this expansion use print_anisotropy_as_stevens.

    Inhomogeneous field

    An external field can be applied to a single site with set_external_field_at!.

    Structure factor rewrite

    The calculation of structure factors has been completely rewritten. For the new interface, see the FeI₂ at Finite Temperature page.

    Various

    • The "Sampler" interface is in flux. Langevin replaces both LangevinHeunP and LangevinSampler. Local spin-flip Monte Carlo sampling methods are temporarily broken.

    • repeat_periodically replaces extend_periodically.

    Additional related functions include resize_periodically and reshape_geometry, the latter being fundamental.

    The new function includes the list of symmetry-allowed single ion anisotropies in addition to exchange interactions.

    • When reading CIF files, the field _atom_site_label is now used in place of the field _atom_site_type_symbol.

    This is required for correctness. The field _atom_site_label is guaranteed to be present, and is guaranteed to be a distinct label for each symmetry-inequivalent site. Code that explicitly referred to site labels (e.g. in calls to subcrystal) will need to be updated to use the new label.

    +Version History · Sunny documentation
    GitHub

    Version History

    v0.5.6

    • Animated spin dynamics is now possible. Call notify on the result of plot_spins to trigger redrawing of the frame. The argument colorfn to plot_spins supports animation of colors.
    • General pair couplings are now supported in set_pair_coupling! and set_pair_coupling_at!. :SUN supports interactions of any order, but :dipole mode is limited to bilinear and biquadratic coupling of the spin.
    • To perform a calculation with dipoles in the large-$S$ limit, use the new mode :dipole_large_S when constructing a System.
    • Deprecate the option biquad to set_exchange!. Use instead set_pair_coupling!, which generalizes beyond the scalar biquadratic.
    • Deprecate spin_operators, stevens_operators, large_S_spin_operators and large_S_stevens_operators. Use instead spin_matrices and stevens_matrices, which require a specific spin-$S$ label. To infer this, one can use spin_label.
    • Remove unused option energy_tol in SpinWaveTheory.

    v0.5.5

    • reshape_supercell now allows reshaping to multiples of the primitive unit cell, which can speed up certain calculations. This is illustrated in the CoRh₂O₄ powder averaging tutorial.
    • resize_supercell now allows all resizings.
    • Added energy_per_site.
    • set_spiral_order_on_sublattice! cannot work on reshaped systems.
    • Various bug fixes. In particular, an intensity_formula with :full will now uniformly calculate a 3x3 matrix of complex numbers.

    v0.5.4

    • Various enhancements to view_crystal. Atoms are now labeled by index, and bonds support interactive inspection (GLMakie only). Font sizes work correctly on Makie v0.20-beta. If using Makie v0.19 on a high-resolution display, pass rescale=1.5 to enlarge font sizes.
    • The function suggest_magnetic_supercell now requires only a list of wavevectors, and will return a $3×3$ matrix that can be programmatically passed to reshape_supercell. The new tolerance parameter tol allows suggest_magnetic_supercell to approximate incommensurate wavevectors with nearby commensurate ones.
    • New functions set_spiral_order! and set_spiral_order_on_sublattice! can be used to initialize a spiral, single-$Q$ order.
    • Sunny now retains all constant energy shifts that have been introduced by anisotropy operators.
    • Fix export_vtk functionality.

    v0.5.3

    • Add large_S_spin_operators and large_S_stevens_operators to support single-ion anisotropies in dipole mode without renormalization. Set large_S=true in set_exchange! to avoid renormalization of biquadratics.
    • view_crystal has been rewritten in Makie.
    • plot_spins now expects ghost_radius in physical length units.
    • SpinWaveTheory will (currently) error if provided a system with enable_dipole_dipole!.

    v0.5.2

    • Form factors for 5d transition ions.
    • Download links for notebooks and scripts on each doc example
    • Various bug fixes.

    v0.5.1

    • Fix binning edge cases.
    • plot_spins accepts resolution argument.

    v0.5.0

    New features.

    Support for Linear Spin Wave Theory in :dipole and :SUN modes. (Thanks Hao Zhang!)

    New function minimize_energy! to efficiently find an optimal configuration of spin dipoles or SU(N) coherent states.

    Major refactors and enhancements to intensity calculations. This new interface allows unification between LSWT and classical spin dynamics calculations. This interface allows: Custom observables as local quantum operators, better support for linebroadening, and automatic binning to facilitate comparison with experimental data. See intensity_formula for documentation. Use load_nxs to load experimental neutron scattering data.

    Breaking changes.

    Require Julia 1.9.

    Replace set_anisotropy! with a new function set_onsite_coupling! (and similarly set_onsite_coupling_at!). The latter expects an explicit matrix representation for the local Hamiltonian. This can be constructed, e.g., as a linear combination of stevens_operators, or as a polynomial of spin_operators. To understand the mapping between these two, the new function print_stevens_expansion acts on an arbitrary local operator.

    Remove set_biquadratic!. Instead, use an optional keyword argument biquad to set_exchange!.

    Rename DynamicStructureFactor to dynamical_correlations. Similarly, replace InstantStructureFactor with instant_correlations. The return type has been renamed SampledCorrelations to emphasize that the object may be holding thermodynamic samples, which are collected using add_sample!. Upon construction, the SampledCorrelations object will be empty (no initial sample).

    Remove intensities function. Instead, use one of intensities_interpolated or intensities_binned. These will require an intensity_formula, which defines a calculator (e.g., LSWT).

    Rename connected_path to reciprocal_space_path, which now returns an xticks object that can be used in plotting. Replace spherical_shell with reciprocal_space_shell that functions similarly.

    Rename polarize_spin! to set_dipole! for consistency with set_coherent!. The behavior of the former function is unchanged: the spin at a given site will still be polarized along the provided direction.

    Rename all_sites to eachsite consistent with Julia convention for iterators.

    Rename reshape_geometry to reshape_supercell, which is the fundamental reshaping function. Rename resize_periodically to resize_supercell.

    The constructor SpinInfo now requires a $g$-factor or tensor as a named argument.

    The constructor FormFactor no longer accepts an atom index. Instead, the form factors are associated with site-symmetry classes in order of appearance.

    v0.4.3

    Experimental support for linear SpinWaveTheory, implemented in SU(N) mode. This module may evolve rapidly.

    Implement renormalization of single-ion anisotropy and biquadratic interactions when in :dipole mode. This makes the model more faithful to the quantum mechanical Hamiltonian, but is also a breaking change.

    Various improvements and bugfixes for to_inhomogeneous. Setting inhomogeneous interactions via set_exchange_at! should now infer the correct bond offset direction, or will report an ambiguity error. Ambiguities can be resolved by passing an explicit offset.

    The function remove_periodicity! disables periodicity along specified dimensions.

    Rename StaticStructureFactor to InstantStructureFactor.

    v0.4.2

    Introduce LocalSampler, a framework for MCMC sampling with local spin updates.

    Rename print_dominant_wavevectors to print_wrapped_intensities to reduce confusion with the physical instantaneous intensities.

    The function spherical_shell now takes a radius in physical units of inverse Å.

    New exported functions global_position, magnetic_moment, all_sites.

    Remove all uses of Base.deepcopy which resolves crashes.

    v0.4.1

    The function to_inhomogeneous creates a system that supports inhomogeneous interactions, which can be set using set_exchange_at!, etc.

    set_biquadratic! replaces set_exchange_with_biquadratic!.

    v0.4.0

    This update includes many breaking changes, and is missing some features of 0.3.0.

    Creating a spin System

    Rename SpinSystem to System. Its constructor now has the form,

    System(crystal, latsize, infos, mode)

    The parameter infos is now a list of SpinInfo objects. Each defines spin angular momentum $S = \frac{1}{2}, 1, \frac{3}{2}, …$, and an optional $g$-factor or tensor.

    The parameter mode is one of :SUN or :dipole.

    Setting interactions

    Interactions are now added mutably to an existing System using the following functions: set_external_field!, set_exchange!, set_onsite_coupling!, enable_dipole_dipole!.

    As a convenience, one can use dmvec(D) to convert a DM vector to a $3×3$ antisymmetric exchange matrix.

    Fully general single-ion anisotropy is now possible. The function set_onsite_coupling! expects the single ion anisotropy to be expressed as a polynomial in symbolic spin operators 𝒮, or as a linear combination of symbolic Stevens operators 𝒪. For example, an easy axis anisotropy in the direction n may be written D*(𝒮⋅n)^2.

    Stevens operators 𝒪[k,q] admit polynomial expression in spin operators 𝒮[α]. Conversely, a polynomial of spin operators can be expressed as a linear combination of Stevens operators. To see this expansion use print_anisotropy_as_stevens.

    Inhomogeneous field

    An external field can be applied to a single site with set_external_field_at!.

    Structure factor rewrite

    The calculation of structure factors has been completely rewritten. For the new interface see the documentation tutorials.

    Various

    • The "Sampler" interface is in flux. Langevin replaces both LangevinHeunP and LangevinSampler. Local spin-flip Monte Carlo sampling methods are temporarily broken.

    • repeat_periodically replaces extend_periodically.

    Additional related functions include resize_periodically and reshape_geometry, the latter being fundamental.

    The new function includes the list of symmetry-allowed single ion anisotropies in addition to exchange interactions.

    • When reading CIF files, the field _atom_site_label is now used in place of the field _atom_site_type_symbol.

    This is required for correctness. The field _atom_site_label is guaranteed to be present, and is guaranteed to be a distinct label for each symmetry-inequivalent site. Code that explicitly referred to site labels (e.g. in calls to subcrystal) will need to be updated to use the new label.

    diff --git a/dev/writevtk.html b/dev/writevtk.html index 7de47dd02..c2c2d8d0a 100644 --- a/dev/writevtk.html +++ b/dev/writevtk.html @@ -1,5 +1,5 @@ -ParaView Rendering · Sunny documentation
    GitHub

    ParaView Rendering

    The 4D correlation data produced by Sunny is too high-dimensional to visualize directly. This page describes how to export 3D slices of correlation data from Sunny to the Visual ToolKit (VTK) format, which is compatible with the ParaView visualization software. ParaView supports volumetric rendering:

    Simulation data

    First, generate some correlation data in Sunny. We will use a 2D lattice, since the correlation data $S(Q_x,Q_y,\omega)$ is 3D and can be exported in its entirety. The following code sets up the system, thermalizes it, and records the correlation data in a SampledCorrelations called dsf.

    using Sunny
+ParaView Rendering · Sunny documentation
    GitHub
    ParaView Rendering
    The 4D correlation data produced by Sunny is too high-dimensional to visualize directly. This page describes how to export 3D slices of correlation data from Sunny to the Visual ToolKit (VTK) format, which is compatible with the ParaView visualization software. ParaView supports volumetric rendering:
    Simulation data
    First, generate some correlation data in Sunny. We will use a 2D lattice, since the correlation data $S(Q_x,Q_y,\omega)$ is  3D and can be exported in its entirety. The following code sets up the system, thermalizes it, and records the correlation data in a SampledCorrelations called dsf.
    using Sunny
 
 # Single layer 12x12 periodic square lattice
 latsize = (12,12,1)
@@ -61,4 +61,4 @@
 signal = sum(signal; dims = 4)
 
 # Export to ParaView
-export_vtk("experiment_data_as_vtk", params, signal)
    
+export_vtk("experiment_data_as_vtk", params, signal)
    GitHub

    Download this example as Jupyter notebook or Julia script.

    Powder Averaged CoRh₂O₄

    This tutorial illustrates the calculation of the powder-averaged structure factor by performing an orientational average. We consider a simple model of the diamond-cubic crystal CoRh₂O₄, with parameters extracted from Ge et al., Phys. Rev. B 96, 064413.

    using Sunny, GLMakie

    Construct a diamond Crystal in the conventional (non-primitive) cubic unit cell. Sunny will populate all eight symmetry-equivalent sites when given the international spacegroup number 227 ("Fd-3m") and the appropriate setting. For this spacegroup, there are two conventional translations of the unit cell, and it is necessary to disambiguate through the setting keyword argument. (On your own: what happens if setting is omitted?)

    a = 8.5031 # (Å)
-latvecs = lattice_vectors(a, a, a, 90, 90, 90)
-cryst = Crystal(latvecs, [[0,0,0]], 227, setting="1")
    Crystal
-Spacegroup 'F d -3 m' (227)
-Lattice params a=8.503, b=8.503, c=8.503, α=90°, β=90°, γ=90°
-Cell volume 614.8
-Wyckoff 8a (point group '-43m'):
-   1. [0, 0, 0]
-   2. [1/2, 1/2, 0]
-   3. [1/4, 1/4, 1/4]
-   4. [3/4, 3/4, 1/4]
-   5. [1/2, 0, 1/2]
-   6. [0, 1/2, 1/2]
-   7. [3/4, 1/4, 3/4]
-   8. [1/4, 3/4, 3/4]
-

    In a running Julia environment, the crystal can be viewed interactively using view_crystal.

    view_crystal(cryst, 8.0)
    Example block output

    Construct a System with an antiferromagnetic nearest neighbor interaction J. Because the diamond crystal is bipartite, the ground state will have unfrustrated Néel order. Selecting latsize=(1,1,1) is sufficient because the ground state is periodic over each cubic unit cell. By passing an explicit seed, the system's random number generator will give repeatable results.

    latsize = (2, 2, 2)
-seed = 0
-S = 3/2
-J = 7.5413*meV_per_K # (~ 0.65 meV)
-sys = System(cryst, latsize, [SpinInfo(1; S, g=2)], :dipole; seed=0)
-set_exchange!(sys, J, Bond(1, 3, [0,0,0]))

    In the ground state, each spin is exactly anti-aligned with its 4 nearest-neighbors. Because every bond contributes an energy of $-JS^2$, the energy per site is $-2JS^2$. In this calculation, a factor of 1/2 avoids double-counting the bonds. Due to lack of frustration, direct energy minimization is successful in finding the ground state.

    randomize_spins!(sys)
-minimize_energy!(sys)
-
-@assert energy_per_site(sys) ≈ -2J*S^2

    Plotting the spins confirms the expected Néel order. Note that the overall, global rotation of dipoles is arbitrary.

    s0 = sys.dipoles[1,1,1,1]
-plot_spins(sys; color=[s'*s0 for s in sys.dipoles])
    Example block output

    For numerical efficiency, it will be helpful to work with the smallest possible magnetic supercell. Here, it is the primitive unit cell, which contains just two sites. The variable shape below defines the primitive lattice vectors cryst.prim_latvecs in units of the conventional lattice vectors. This result is used as input to reshape_supercell. The energy per site remains the same, which verifies that the magnetic supercell is valid.

    shape = cryst.latvecs \ cryst.prim_latvecs
-sys_prim = reshape_supercell(sys, shape)
-@assert energy_per_site(sys_prim) ≈ -2J*S^2

    Now estimate $𝒮(𝐪,ω)$ with SpinWaveTheory and an intensity_formula. The mode :perp contracts with a dipole factor to return the unpolarized intensity. The formula also employs lorentzian broadening. The isotropic FormFactor for Cobalt(2+) dampens intensities at large $𝐪$.

    swt = SpinWaveTheory(sys_prim)
-η = 0.4 # (meV)
-kernel = lorentzian(η)
-formfactors = [FormFactor("Co2")]
-formula = intensity_formula(swt, :perp; kernel, formfactors)
    Quantum Scattering Intensity Formula
-At any (Q,ω), with S = S(Q,ωᵢ):
-
-  Intensity(Q,ω) = ∑ᵢ Kernel(ω-ωᵢ) ∑_ij (I - Q⊗Q){i,j} S{i,j}
-                                   
-                                   (i,j = Sx,Sy,Sz)
-
-Intensity(ω) reported
-

    For the "single crystal" result, we may use reciprocal_space_path to construct a path that connects high-symmetry points in reciprocal space. The intensities_broadened function collects intensities along this path for the given set of energy values.

    qpoints = [[0.0, 0.0, 0.0], [0.5, 0.0, 0.0], [0.5, 0.5, 0.0], [0.0, 0.0, 0.0]]
-path, xticks = reciprocal_space_path(cryst, qpoints, 50)
-energies = collect(0:0.01:6)
-is = intensities_broadened(swt, path, energies, formula)
-
-fig = Figure()
-ax = Axis(fig[1,1]; aspect=1.4, ylabel="ω (meV)", xlabel="𝐪 (r.l.u.)",
-          xticks, xticklabelrotation=π/10)
-heatmap!(ax, 1:size(is, 1), energies, is, colormap=:gnuplot2)
-fig
    Example block output

    A powder measurement effectively involves an average over all possible crystal orientations. We use the function reciprocal_space_shell to sample n wavevectors on a sphere of a given radius (inverse angstroms), and then calculate the spherically-averaged intensity.

    radii = 0.01:0.02:3 # (1/Å)
-output = zeros(Float64, length(radii), length(energies))
-for (i, radius) in enumerate(radii)
-    n = 300
-    qs = reciprocal_space_shell(cryst, radius, n)
-    is = intensities_broadened(swt, qs, energies, formula)
-    output[i, :] = sum(is, dims=1) / size(is, 1)
-end
-
-fig = Figure()
-ax = Axis(fig[1,1]; xlabel="Q (Å⁻¹)", ylabel="ω (meV)")
-heatmap!(ax, radii, energies, output, colormap=:gnuplot2)
-fig
    Example block output

    This result can be compared to experimental neutron scattering data from Fig. 5 of Ge et al.