Update README and docs (#308)

Also require HCubature 1.7.0 to ensure thread safety.

Project.toml

@@ -1,7 +1,7 @@
 name = "Sunny"
 uuid = "2b4a2ac8-8f8b-43e8-abf4-3cb0c45e8736"
 authors = ["The Sunny team"]
-version = "0.7.0"
+version = "0.7.1"
 
 [deps]
 CrystalInfoFramework = "6007d9b0-c6b2-11e8-0510-1d10e825f3f1"
@@ -42,7 +42,7 @@ ElasticArrays = "1.2.12"
 FFTW = "1.4.5"
 FilePathsBase = "0.9.18"
 GLMakie = "0.9, 0.10"
-HCubature = "1.5.1"
+HCubature = "1.7.0"
 JLD2 = "0.4.33"
 LinearAlgebra = "1.10"
 Makie = "0.20, 0.21.1"

README.md

@@ -23,23 +23,21 @@
 
 ## Overview
 
-Sunny is a Julia package for modeling atomic-scale magnetism using classical spin dynamics with quantum corrections. It provides powerful tools to estimate dynamical structure factor intensities, $\mathcal{S}(𝐪,ω)$, enabling quantitative comparison with experimental scattering data, e.g., neutrons or x-rays.
+Sunny is a Julia package for modeling atomic-scale magnetism. Through spin dynamics simulations, it enables direct comparison with experimental scattering data, e.g., neutrons or x-rays. Ease of use is a priority, with tools for symmetry-guided modeling and interactive visualization.
 
-A unique feature of Sunny is its treatment of spins as [SU(_N_) coherent states](https://arxiv.org/abs/2106.14125). This theory generalizes Landau-Lifshitz spin dynamics to a [nonlinear Schrödinger equation](https://arxiv.org/abs/2204.07563), which retains $N=2s+1$ levels for each quantum spin-_s_ state. This generalization is important for models with strong single-ion anisotropy (see our **[FeI₂ tutorial](https://sunnysuite.github.io/Sunny.jl/dev/examples/03_LSWT_SU3_FeI2.html)**) and for [localized "units" of strongly entangled spins](https://arxiv.org/abs/2405.16315).  Efficient simulation is enabled by several algorithmic developments as listed on our [publications page](https://github.com/SunnySuite/Sunny.jl/wiki/Sunny-literature).
+At low-temperatures, Sunny supports the usual linear spin wave theory of spin dipoles, and its [multi-flavor generalization](https://arxiv.org/abs/1307.7731). At finite temperatures, Sunny can calculate the dynamical structure factor using classical spin dynamics with [quantum corrections](https://arxiv.org/abs/2310.19905). Langevin coupling to a thermal bath makes possible the study of non-equilibrium dynamics, e.g., thermal transport, pump-probe experiments, and spin-glass relaxation. Sunny also provides powerful Monte Carlo algorithms for collecting statistics in thermal equilibrium.
 
-At low-temperatures, Sunny supports the usual linear spin wave theory for spin dipoles, and its ['multi-boson' generalization](https://arxiv.org/abs/1307.7731). At finite temperatures, Sunny can calculate the dynamical structure factor using classical spin dynamics with quantum corrections. Langevin coupling to a thermal bath additionally makes possible the study of various non-equilibrium dynamics, e.g., thermal transport, pump-probe experiments, and spin-glass relaxation.
-
-Sunny provides a number of tools to facilitate the specification and solution of spin Hamiltonians. This includes spacegroup symmetry analysis, powerful Monte Carlo sampling algorithms, and interactive 3D visualization.
+A unique feature of Sunny is its treatment of spins as [SU(_N_) coherent states](https://arxiv.org/abs/2106.14125). This theory generalizes Landau-Lifshitz spin dynamics to a [nonlinear Schrödinger equation](https://arxiv.org/abs/2204.07563), which retains $N=2s+1$ levels for each quantum spin-_s_ state. The generalization is important for models with strong single-ion anisotropy (see the **[FeI₂ tutorial](https://sunnysuite.github.io/Sunny.jl/stable/examples/03_LSWT_SU3_FeI2.html)**) and for [localized "units" of strongly entangled spins](https://arxiv.org/abs/2405.16315).  Efficient simulation is enabled by [several algorithmic advances](https://github.com/SunnySuite/Sunny.jl/wiki/Sunny-literature).
 
 ## Try it out!
 
-[Download Julia](https://github.com/SunnySuite/Sunny.jl/wiki/Getting-started-with-Julia) and try the **[Sunny Tutorials](https://sunnysuite.github.io/Sunny.jl/dev/examples/01_LSWT_CoRh2O4)**. For traditional linear spin wave theory, see also the **[SpinW ports](https://sunnysuite.github.io/Sunny.jl/dev/examples/spinw/SW01_FM_Heseinberg_chain.html)**.
+[Install Sunny](https://github.com/SunnySuite/Sunny.jl/wiki/Getting-started-with-Julia) and try the **[Tutorials](https://sunnysuite.github.io/Sunny.jl/stable/examples/01_LSWT_CoRh2O4)**. For traditional linear spin wave theory, see also the **[SpinW ports](https://sunnysuite.github.io/Sunny.jl/stable/examples/spinw/SW01_FM_Heseinberg_chain.html)**.
 
-Sunny is evolving rapidly. [Version History](https://sunnysuite.github.io/Sunny.jl/dev/versions/) lists the new features and breaking changes. To install a specific version of Sunny, say `v0.x`, use the command `add Sunny@0.x`.
+See [Version History](https://sunnysuite.github.io/Sunny.jl/dev/versions) for new features and breaking changes. To install a specific version of Sunny, say `v0.x`, use the command `add Sunny@0.x`.
 
 ## Other spin wave codes
 
-Sunny is inspired by SpinW, especially regarding symmetry analysis, model specification, and linear spin wave calculations. Relative to other spin wave codes, this table highlights Sunny's special features (as of 2024):
+Sunny is inspired by SpinW, especially regarding symmetry analysis and traditional spin wave theory. Relative to other spin wave codes, this table highlights Sunny's special features (as of 2024):
 
 | | [McPhase](https://github.com/mducle/mcphase) | [SpinW](https://github.com/SpinW/spinw) | Sunny |
 | -- | -- | -- | -- |
@@ -50,10 +48,10 @@ Sunny is inspired by SpinW, especially regarding symmetry analysis, model specif
 | [Interaction renormalization corrections](https://arxiv.org/abs/2304.03874) | ❌ | ❌ | ✅ |
 | [Multi-flavor spin wave theory](https://arxiv.org/abs/1307.7731) | ✅ | ❌ | ✅ |
 | [Classical SU(_N_) spin dynamics](https://arxiv.org/abs/2209.01265) | ❌ | ❌ | ✅ |
-| [Ewald summation for dipole-dipole](https://sunnysuite.github.io/Sunny.jl/dev/examples/07_Dipole_Dipole.html) | ❌ | ❌ | ✅ |
+| [Fast long-range dipole interactions](https://sunnysuite.github.io/Sunny.jl/stable/examples/07_Dipole_Dipole.html) | ❌ | ❌ | ✅ |
 | Programming language | C++ | Matlab | [Julia](https://julialang.org/) |
 
-Codes like [Spirit](https://github.com/spirit-code/spirit) and [Vampire](https://vampire.york.ac.uk/) focus less on capturing quantum effects, but may be better options for the dynamics of classical dipoles, e.g., in the micromagnetics context.
+Codes like [Spirit](https://github.com/spirit-code/spirit) and [Vampire](https://vampire.york.ac.uk/) focus less on capturing quantum effects, but might be preferred for large-scale classical spin dynamics, e.g., for micromagnetics.
 
 ## Join our community
 

docs/src/versions.md

@@ -1,5 +1,8 @@
 # Version History
 
+## v0.7.1
+(In development)
+
 ## v0.7.0
 (Aug 30, 2024)
 

examples/03_LSWT_SU3_FeI2.jl

@@ -6,10 +6,10 @@
 # Our context will be FeI₂, an effective spin-1 material with strong single-ion
 # anisotropy. Quadrupolar fluctuations give rise to a single-ion bound state
 # that is observable in neutron scattering, and 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
-# spectrum of FeI₂. The original study was performed in [Bai et al., Nature
-# Physics 17, 467–472 (2021)](https://doi.org/10.1038/s41567-020-01110-1).
+# dipole-only model. We will use the linear spin wave theory of SU(3) coherent
+# states (i.e. 2-flavor bosons) to model the magnetic spectrum of FeI₂. The
+# original study was performed in [Bai et al., Nature Physics 17, 467–472
+# (2021)](https://doi.org/10.1038/s41567-020-01110-1).
 #
 # ```@raw html
 # <img src="https://raw.githubusercontent.com/SunnySuite/Sunny.jl/main/docs/src/assets/FeI2_crystal.jpg" style="float: left;" width="400">
@@ -43,8 +43,8 @@ cryst = Crystal(latvecs, positions; types)
 
 # Observe that the space group 'P -3 m 1' (164) has been inferred, as well as
 # point group symmetries. Only the Fe atoms are magnetic, so we focus on them
-# with [`subcrystal`](@ref). Importantly, this operation preserves the
-# spacegroup symmetries.
+# with [`subcrystal`](@ref). Importantly, the new crystal retains the symmetry
+# information for spacegroup 164.
 
 cryst = subcrystal(cryst, "Fe")
 view_crystal(cryst)
@@ -74,18 +74,18 @@ print_symmetry_table(cryst, 8.0)
 
 # ### Defining the spin model
 
-# Construct a system [`System`](@ref) with spin-1 and g=2 for the Fe ions.
+# Construct a [`System`](@ref) with spin $s=1$ and $g=2$ for the Fe ions.
 #
-# Recall that a quantum spin-1 state is, in general, a linear combination of
-# basis states ``|m⟩`` with well-defined angular momentum ``m = -1, 0, 1``. FeI₂
-# has a strong easy-axis anisotropy, which stabilizes a single-ion bound state
-# of zero angular momentum, ``|m=0⟩``. Such a bound state is inaccessible to
-# traditional spin wave theory, which works with dipole expectation values of
-# fixed magnitude. This physics can, however, be captured with a theory of
-# SU(_N_) coherent states, where ``N = 2S+1 = 3`` is the number of levels. We
-# will therefore select `:SUN` mode instead of `:dipole` mode.
+# Recall that quantum spin-1 is, in reality, a linear combination of basis
+# states ``|m⟩`` with well-defined angular momentum ``m = -1, 0, 1``. FeI₂ has a
+# strong easy-axis anisotropy, which stabilizes a single-ion bound state of zero
+# angular momentum, ``|m=0⟩``. Such a bound state is inaccessible to traditional
+# spin wave theory, which works with dipole expectation values of fixed
+# magnitude. This physics is, however, well captured with a theory of SU(_N_)
+# coherent states, where ``N = 2S+1 = 3`` is the number of levels. Activate this
+# generalized theory by selecting `:SUN` mode instead of `:dipole` mode.
 # 
-# Selecting an optional random number `seed` will make the calculations exactly
+# An optional random number `seed` will make the calculations exactly
 # reproducible.
 
 sys = System(cryst, [1 => Moment(s=1, g=2)], :SUN, seed=2)
@@ -142,13 +142,13 @@ set_onsite_coupling!(sys, S -> -D*S[3]^2, 1)
 
 # ### Finding the ground state
 
-# These model parameters have already been fitted so that energy minimization
-# yields the physically correct ground state. Knowing this, we could set the
-# magnetic configuration manually by calling [`set_dipole!`](@ref) on each site
-# in the system. Another approach, as we now demonstrate, is to use the built-in
-# optimization tools to search for the ground-state in an automated way.
+# This model has been fitted so that energy minimization yields the physically
+# correct ground state. Knowing this, we could set the magnetic configuration
+# manually by calling [`set_dipole!`](@ref) on each site in the system. Another
+# approach, as we will demonstrate, is to search for the ground-state via
+# [`minimize_energy!`](@ref).
 #
-# To minimize bias in the search, use [`resize_supercell`](@ref) to create a
+# To reduce bias in the search, use [`resize_supercell`](@ref) to create a
 # relatively large system of 4×4×4 chemical cells. Randomize all spins
 # (represented as SU(3) coherent states) and minimize the energy.
 
@@ -168,7 +168,7 @@ plot_spins(sys; color=[S[3] for S in sys.dipoles])
 # general tool for this analysis is [`SampledCorrelationsStatic`](@ref). For the
 # present purposes, however, it is more convenient to use
 # [`print_wrapped_intensities`](@ref), which reports ``\mathcal{S}(𝐪)`` with
-# periodical wrapping of all commensurate ``𝐪`` wavevectors into the first
+# periodic wrapping of all commensurate ``𝐪`` wavevectors into the first
 # Brillouin zone.
 
 print_wrapped_intensities(sys)