Restructured topics

Author: aibergman

content/detailed-input-background.rst

@@ -0,0 +1,142 @@
+Detailed background and inputs
+==============================
+
+This chapter consolidates simulation methods, external control modules, and observable analysis into one place. Use it as the deep-dive reference when selecting algorithms, driving simulations with stimuli, and interpreting outputs.
+
+Simulation Methods and Algorithms
+---------------------------------
+
+Fundamental and specialized approaches for running magnetic dynamics simulations.
+
+Stochastic Integration
+~~~~~~~~~~~~~~~~~~~~~~
+
+Numerical integration schemes (solvers) for solving the stochastic Landau-Lifshitz-Gilbert equation:
+
+- :doc:`input-keywords-solvers`
+
+Monte Carlo simulations and minimization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Equilibrium sampling techniques for thermodynamic properties:
+
+- :doc:`input-keywords-montecarlo`
+
+Advanced Sampling and Equilibration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Specialized methods for exploring phase space and computing thermodynamic properties:
+
+- :doc:`input-keywords-montecarlo`
+- :doc:`input-keywords-wanglandau`
+- :doc:`input-keywords-replicaexchange`
+
+Path-Finding and Optimization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Methods for finding transitions between magnetic configurations and optimizing spin textures:
+
+- :doc:`input-keywords-gneb`
+- :doc:`input-keywords-spinspiral`
+
+Rare Event and Dynamics Methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Techniques for studying infrequent events and non-equilibrium dynamics:
+
+- :doc:`input-keywords-kmc`
+
+Spin-Lattice Coupling
+~~~~~~~~~~~~~~~~~~~~~
+
+Coupled spin and lattice evolution including magnetoelastic effects:
+
+- :doc:`input-keywords-sld`
+
+Multiscale Coupling
+~~~~~~~~~~~~~~~~~~~
+
+Hybrid atomistic–continuum simulations for large-scale magnetic systems:
+
+- :doc:`input-keywords-multiscale`
+
+External Stimuli and Control
+----------------------------
+
+Apply external driving forces and thermal control modules.
+
+Spatially and temporally varying magnetic fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- :doc:`input-keywords-fields`
+
+Spin-polarized currents and torques
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- :doc:`input-keywords-currents`
+
+Temperature control and three-temperature model (3TM)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+- :doc:`input-keywords-temperature-3tm`
+
+Temperature gradients:
+~~~~~~~~~~~~~~~~~~~~~~
+
+- :doc:`input-keywords-temperature-gradients`
+
+Observable Measurements and Analysis
+------------------------------------
+
+Theoretical foundations for measuring and analyzing magnetic observables and configurations.
+
+Magnetization Observables
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Measurements of magnetization and thermodynamic moments:
+
+- :doc:`input-keywords-averages`
+
+Spin-wave Spectra (AMS/LSWT)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Adiabatic magnon spectra and linear spin-wave theory:
+
+- :doc:`input-keywords-ams`
+
+Correlations and Structure Factors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Space and time-displaced correlation functions:
+
+- :doc:`input-keywords-correlations`
+- :doc:`input-keywords-autocorrelation`
+
+Polarization and Chirality
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Ferroelectric polarization and local chirality:
+
+- :doc:`input-keywords-polarization`
+
+Configuration Analysis and Topology
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Characterization and topological analysis of magnetic configurations:
+
+- :doc:`input-keywords-clusters`
+- :doc:`input-keywords-topology`
+
+Micromagnetic Stiffness and Parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Extraction of continuum parameters from atomistic simulations:
+
+- :doc:`input-keywords-stiffness`
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   dib-simulation-methods
+   dib-external-stimuli
+   dib-observables-analysis

content/dib-external-stimuli.rst

@@ -0,0 +1,13 @@
+External Stimuli and Control
+============================
+
+Apply external driving and thermal control modules.
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   input-keywords-fields
+   input-keywords-currents
+   input-keywords-temperature-3tm
+   input-keywords-temperature-gradients

content/dib-observables-analysis.rst

@@ -0,0 +1,17 @@
+Observable Measurements and Analysis
+====================================
+
+Theory and practice for measuring and analyzing magnetic observables.
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   input-keywords-averages
+   input-keywords-ams
+   input-keywords-correlations
+   input-keywords-autocorrelation
+   input-keywords-polarization
+   input-keywords-clusters
+   input-keywords-topology
+   input-keywords-stiffness

content/dib-simulation-methods.rst

@@ -0,0 +1,18 @@
+Simulation Methods and Algorithms
+=================================
+
+Fundamental and specialized approaches for running magnetic dynamics simulations.
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   input-keywords-solvers
+   input-keywords-montecarlo
+   input-keywords-wanglandau
+   input-keywords-replicaexchange
+   input-keywords-gneb
+   input-keywords-spinspiral
+   input-keywords-kmc
+   input-keywords-sld
+   input-keywords-multiscale

content/index.rst

@@ -7,9 +7,8 @@ UppASD manual
 
    introduction
    input
-   guide
-   quick-reference
    output
+   detailed-input-background
    tutorial
    examples
 

content/input-keywords-ams.rst

@@ -12,7 +12,6 @@ UppASD implements **Linear Spin Wave Theory (LSWT)** for calculating magnon band
 * **Magnon dispersions**: Eigenfrequencies of collective spin excitations across the Brillouin zone
 * **Density of states**: Thermodynamic and spectroscopic properties from magnon spectra
 * **Topological analysis**: Chern numbers, Berry curvature, and thermal Hall conductivity
-* **Dynamical structure factor**: :math:`S(\mathbf{q},\omega)` for comparison with inelastic neutron scattering (INS)
 
 The implementation follows the **Tóth-Lake formalism** [TothLake2015]_ and extensions for non-collinear magnetism, supporting:
 

content/input-keywords-autocorrelation.rst

@@ -1,5 +1,5 @@
-inpsd.dat keywords: autocorrelation functions
-==============================================
+Autocorrelation functions
+=========================
 
 Parameters for time-resolved autocorrelation measurements
 ---------------------------------------------------------
@@ -17,6 +17,12 @@ such as relaxation times, correlation decay rates, and aging effects in
 non-equilibrium simulations. Results are written to ``autocorr.simid.out`` with
 optional spatial binning into macrocells for coarse-grained analysis.
 
+.. tip::
+
+   **Input keywords:** For a complete list of all autocorrelation measurement
+   parameters (``do_autocorr``, ``acfile``, ``ac_step``, etc.), see the
+   comprehensive reference in :doc:`input-keywords-observables`.
+
 .. _autocorr-definition:
 
 -------------------------------------------------

content/input-keywords-averages.rst

@@ -1,8 +1,5 @@
-inpsd.dat keywords: averages and cumulants
-============================================
-
-Parameters for measuring averages and statistical observables
---------------------------------------------------------------
+Averages and cumulants
+======================
 
 The UppASD code supports comprehensive statistical measurements of magnetization
 and thermodynamic observables during spin dynamics simulations. The averaging and
@@ -19,11 +16,11 @@ All measurements support ensemble averaging for improved statistical accuracy in
 Monte Carlo and Langevin dynamics simulations. The subsystem employs a buffered
 output strategy to minimize I/O overhead during long simulations.
 
-.. important::
+.. tip::
 
-   For Monte Carlo simulations, cumulant measurements (``do_cumu``) are
-   automatically enabled regardless of the input setting, as they are essential
-   for characterizing equilibrium thermodynamic properties.
+   **Input keywords:** For a complete list of all average and cumulant input
+   parameters (``do_avrg``, ``avrg_step``, ``do_cumu``, etc.), see the
+   comprehensive reference in :doc:`input-keywords-observables`.
 
 -------------------------------------------------
 Canonical measurement definitions
@@ -309,39 +306,23 @@ The averaging subsystem is independent of but compatible with:
   (seconds) instead of simulation steps in all averaging output files. This requires
   specifying the timestep ``delta_t`` in the simulation parameters.
 
-.. warning::
-
-   When performing **initial phase** measurements during equilibration, ensure
-   that cumulant sampling (``cumu_step``) does not begin until the system has
-   thermalized. Monitor ``averages.simid.out`` to verify magnetization stability
-   before analyzing cumulants.
-
 -------------------------------------------------
 Notes and best practices
 -------------------------------------------------
 
 **For Monte Carlo simulations:**
 
-- Use ``cumu_step`` comparable to or larger than system size to ensure decorrelation
-- Perform long runs (millions of sweeps) to reduce statistical noise in :math:`\langle m^4 \rangle`
+- Perform sufficiently long runs to reduce statistical noise in :math:`\langle m^4 \rangle`
 - Check convergence by monitoring running averages in ``cumulants.simid.out``
 
 **For spin dynamics simulations:**
 
 - Set ``avrg_step`` to sample faster than the slowest relevant timescale (e.g., domain wall motion)
-- Use ``cumu_step`` :math:`\gg` ``avrg_step`` for reliable statistics
 - Equilibrate thoroughly before enabling cumulant measurements
 
 **For parallel tempering:**
 
 - Ensure ``Mensemble`` is sufficient for accurate ensemble averaging (typically ≥ 16)
-- Use projected cumulants (``do_cumu_proj Y``) to analyze sublattice ordering independently
-
-**Memory considerations:**
-
-- Buffer size ``avrg_buff`` :math:`\times` 3 :math:`\times` ``Mensemble`` determines memory per output cycle
-- For large ``Mensemble``, reduce ``avrg_buff`` to avoid memory pressure
-- Projected averages require additional memory proportional to number of types/sites
 
 -------------------------------------------------
 Example inpsd.dat snippet

content/input-keywords-clusters.rst

@@ -1,39 +1,5 @@
-inpsd.dat keywords: cluster analysis
-==============================================================
-
-Cluster analysis keywords for grouping spins or atoms into clusters.
---------------------------------------------------------------------------------
-
-The UppASD code can perform simple cluster analyses for post-processing and
-coarse-grained measurements. This page documents the input keywords used to
-control cluster detection and reporting.
-
-cluster_method
-   Method used to define clusters. Typical values: ``distance`` (geometric cutoff), ``bond`` (bond connectivity), ``label`` (read clusters from file). Default: ``distance``.
-
-cluster_cutoff
-   Distance cutoff (in Å) used when ``cluster_method = distance``. Two sites belong to the same cluster if their separation is less than this value. Default: **3.0**.
-
-cluster_file
-   Path to a file containing pre-defined cluster assignments (used when ``cluster_method = label``). Format: one integer cluster id per atom, matching the system indexing used in the input files.
-
-cluster_min_size
-   Minimum number of atoms/spins for a cluster to be reported. Clusters smaller than this value are ignored. Default: **2**.
-
-prn_clusters
-   Print cluster statistics to output (Y=yes, N=no). If enabled, the code writes cluster sizes, centroids, and a list of member indices. Default: **N**.
-
-save_clusters
-   Save cluster assignments to disk (Y=yes, N=no). When enabled, writes ``clusters_<simid>.dat`` with one cluster id per line. Default: **N**.
-
-See also
---------
-
-- :doc:`input-keywords-system` (system setup and atom indices)
-- :doc:`input-keywords-observables` (writing per-site outputs)
-
-inpsd.dat keywords: cluster embedding
-======================================
+Cluster embedding
+=================
 
 Parameters for embedding impurity clusters within a host system
 ---------------------------------------------------------------
@@ -86,9 +52,6 @@ and orientation of the cluster within the host supercell.
 Input file parameters for cluster embedding
 --------------------------------------------------
 
-.. warning:: The original tabular grid has been replaced with a definition-style keyword list to
-   avoid fragile grid-table parsing errors. See the keywords below for parameter descriptions.
-
 do_cluster
    Enable cluster embedding functionality (Y=yes, N=no). When enabled, the code reads separate cluster data files and maps cluster atoms to the host system. Default: **N**.
 

content/input-keywords-correlations.rst

@@ -1,5 +1,5 @@
-inpsd.dat keywords: correlation functions
-==========================================
+Correlation functions
+=====================
 
 Parameters for measuring spin correlations and dynamical structure factors
 --------------------------------------------------------------------------
@@ -43,6 +43,12 @@ and its Fourier transform :math:`S^k(\mathbf{q})` reveal:
 - **Correlation lengths** (width of :math:`S(\mathbf{q})` near the peak)
 - **Phase transitions** (changes in ordering as a function of temperature)
 
+.. tip::
+
+   **Input keywords:** For a complete list of all correlation measurement parameters
+   (``do_sc``, ``do_sr``, ``sc_step``, ``qpoints``, etc.), see the comprehensive
+   reference in :doc:`input-keywords-observables`.
+
 --------------------------------------------------
 Sampling strategy and resolution
 --------------------------------------------------