Docs: updated and added C and Python usage examples.

Also added HTST paper to References.
Also fixed minor problem with OVF Readme for Readthedocs.

README.md

@@ -172,57 +172,56 @@ workflow, never having to re-compile when testing, debugging or adding features.
 
 The most simple example of a **spin dynamics simulation** would be
 ``` python
-    from spirit import state, simulation
-    with state.State("input/input.cfg") as p_state:
-        simulation.PlayPause(p_state, "LLG", "SIB")
+from spirit import state, simulation
+with state.State("input/input.cfg") as p_state:
+    simulation.start(p_state, simulation.METHOD_LLG, simulation.SOLVER_SIB)
 ```
-Where `"SIB"` denotes the semi-implicit method B and the starting configuration
+Where `SOLVER_SIB` denotes the semi-implicit method B and the starting configuration
 will be random.
 
 To add some meaningful content, we can change the **initial configuration** by
 inserting a Skyrmion into a homogeneous background:
 ``` python
-    def skyrmion_on_homogeneous(p_state):
-        from spirit import configuration
-        configuration.PlusZ(p_state)
-        configuration.Skyrmion(p_state, 5.0, phase=-90.0)
+def skyrmion_on_homogeneous(p_state):
+    from spirit import configuration
+    configuration.plus_z(p_state)
+    configuration.skyrmion(p_state, 5.0, phase=-90.0)
 ```
 
 If we want to calculate a **minimum energy path** for a transition, we need to generate
 a sensible initial guess for the path and use the **GNEB method**. Let us consider
 the collapse of a skyrmion to the homogeneous state:
 ``` python
-    from spirit import state, chain, configuration, transition, simulation 
-
-    ### Copy the system a few times
-    chain.Image_to_Clipboard(p_state)
-    for number in range(1,7):
-        chain.Insert_Image_After(p_state)
-    noi = chain.Get_NOI(p_state)
-
-    ### First image is homogeneous with a Skyrmion in the center
-    configuration.PlusZ(p_state, idx_image=0)
-    configuration.Skyrmion(p_state, 5.0, phase=-90.0, idx_image=0)
-    simulation.PlayPause(p_state, "LLG", "VP", idx_image=0)
-    ### Last image is homogeneous
-    configuration.PlusZ(p_state, idx_image=noi-1)
-    simulation.PlayPause(p_state, "LLG", "VP", idx_image=noi-1)
-
-    ### Create transition of images between first and last
-    transition.Homogeneous(p_state, 0, noi-1)
-
-    ### GNEB calculation
-    simulation.PlayPause(p_state, "GNEB", "VP")
+from spirit import state, chain, configuration, transition, simulation
+
+### Copy the system and set chain length
+chain.image_to_clipboard(p_state)
+noi = 7
+chain.set_length(p_state, noi)
+
+### First image is homogeneous with a Skyrmion in the center
+configuration.plus_z(p_state, idx_image=0)
+configuration.skyrmion(p_state, 5.0, phase=-90.0, idx_image=0)
+simulation.start(p_state, simulation.METHOD_LLG, simulation.SOLVER_VP, idx_image=0)
+### Last image is homogeneous
+configuration.plus_z(p_state, idx_image=noi-1)
+simulation.start(p_state, simulation.METHOD_LLG, simulation.SOLVER_VP, idx_image=noi-1)
+
+### Create transition of images between first and last
+transition.homogeneous(p_state, 0, noi-1)
+
+### GNEB calculation
+simulation.start(p_state, simulation.METHOD_GNEB, simulation.SOLVER_VP)
 ```
-where `"VP"` denotes a direct minimization with the velocity projection algorithm.
+where `SOLVER_VP` denotes a direct minimization with the velocity projection algorithm.
 
 You may also use *Spirit* order to **extract quantitative data**, such as the energy.
 ``` python
-    def evaluate(p_state):
-        from spirit import system, quantities
-        M = quantities.Get_Magnetization(p_state)
-        E = system.Get_Energy(p_state)
-        return M, E
+def evaluate(p_state):
+    from spirit import system, quantities
+    M = quantities.get_magnetization(p_state)
+    E = system.get_energy(p_state)
+    return M, E
 ```
 
 Obviously you may easily create significantly more complex workflows and use Python

core/docs/README.md

@@ -24,4 +24,10 @@ The `State` is the object that holds every information needed for the simulation
 ```
 
 ### Further information
+* [Input File Reference](Input.md)
+* [How to: Energy minimisation](Use_Minimisation.md)
+* [How to: LLG dynamics](Use_LLG.md)
+* [How to: GNEB](Use_GNEB.md)
+* [How to: HTST](Use_HTST.md)
+* [How to: MMF](Use_MMF.md)
 * [Input File Reference](Input.md)

core/docs/c-api/API.rst

@@ -1,11 +1,126 @@
 C API
 ==================================
 
-Use the Spirit library by including the corresponding headers.
+
+Energy minimisation
+----------------------------------------------------
+
+Energy minimisation of a spin system can be performed
+using the LLG method and the velocity projection (VP)
+solver:
+
+.. code-block:: C++
+    #include <Spirit/Simulation.h>
+    #include <Spirit/State.h>
+    #include <memory>
+
+    auto state = std::shared_ptr<State>(State_Setup("input/input.cfg"), State_Delete);
+    Simulation_LLG_Start(state.get(), Solver_VP);
+
+or using one of the dynamics solvers, using dissipative
+dynamics:
+
+.. code-block:: C++
+    #include <Spirit/Parameters.h>
+    #include <Spirit/Simulation.h>
+    #include <Spirit/State.h>
+    #include <memory>
+
+    auto state = std::shared_ptr<State>(State_Setup("input/input.cfg"), State_Delete);
+    Parameters_LLG_Set_Direct_Minimization(state.get(), true);
+    Simulation_LLG_Start(state.get(), Solver_Depondt);
+
+
+LLG method
+----------------------------------------------------
+
+To perform an LLG dynamics simulation:
+
+.. code-block:: C++
+    #include <Spirit/Simulation.h>
+    #include <Spirit/State.h>
+    #include <memory>
+
+    auto state = std::shared_ptr<State>(State_Setup("input/input.cfg"), State_Delete);
+    Simulation_LLG_Start(state.get(), Solver_Depondt);
+
+Note that the velocity projection (VP) solver is not a dynamics solver.
+
+
+GNEB method
+----------------------------------------------------
+
+The geodesic nudged elastic band method.
+See also the [method paper](http://www.sciencedirect.com/science/article/pii/S0010465515002696).
+
+This method operates on a transition between two spin configurations,
+discretised by "images" on a "chain". The procedure follows these steps:
+1. set the number of images
+2. set the initial and final spin configuration
+3. create an initial guess for the transition path
+4. run an initial GNEB relaxation
+5. determine and set the suitable images on the chain to converge on extrema
+6. run a full GNEB relaxation using climbing and falling images
+
+
+.. code-block:: C++
+    #include <Spirit/Chain.h>
+    #include <Spirit/Configuration.h>
+    #include <Spirit/Simulation.h>
+    #include <Spirit/State.h>
+    #include <Spirit/Transition.h>
+    #include <memory>
+
+    int NOI = 7;
+
+    auto state = std::shared_ptr<State>(State_Setup("input/input.cfg"), State_Delete);
+
+    // Copy the first image and set chain length
+    Chain_Image_to_Clipboard(state.get());
+    Chain_Set_Length(state.get(), NOI);
+
+    // First image is homogeneous with a Skyrmion in the center
+    Configuration_Plus_Z(state.get(), 0);
+    Configuration_Skyrmion(state.get(), 5.0, phase=-90.0);
+    Simulation_LLG_Start(state.get(), Solver_VP);
+    // Last image is homogeneous
+    Configuration_Plus_Z(state.get(), NOI-1);
+    Simulation_LLG_Start(state.get(), simulation.SOLVER_VP, NOI-1);
+
+    // Create initial guess for transition: homogeneous rotation
+    Transition_Homogeneous(state.get(), 0, noi-1);
+
+    // Initial GNEB relaxation
+    Simulation_GNEB_Start(state.get(), Solver_VP, 5000);
+    // Automatically set climbing and falling images
+    Chain_Set_Image_Type_Automatically(state.get());
+    // Full GNEB relaxation
+    Simulation_GNEB_Start(state.get(), Solver_VP);
+
+
+HTST
+----------------------------------------------------
+
+The harmonic transition state theory.
+See also the [method paper](https://link.aps.org/doi/10.1103/PhysRevB.85.184409).
+
+*The usage of this method is not yet documented.*
+
+
+MMF method
+----------------------------------------------------
+
+The minimum mode following method.
+See also the [method paper](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.121.197202).
+
+*The usage of this method is not yet documented.*
+
+
+Full API reference
+----------------------------------------------------
 
 .. toctree::
     :maxdepth: 2
-    :caption: C API
 
     Spirit/Chain.h              <Chain>
     Spirit/Configurations.h     <Configurations>

core/docs/python-api/API.rst

@@ -1,11 +1,113 @@
 Python API
 ==================================
 
-Use the Python package by importing the corresponding submodules.
+
+Energy minimisation
+----------------------------------------------------
+
+Energy minimisation of a spin system can be performed
+using the LLG method and the velocity projection (VP)
+solver:
+
+.. code-block:: python
+    from spirit import simulation, state
+
+    with state.State("input/input.cfg") as p_state:
+        simulation.start(p_state, simulation.METHOD_LLG, simulation.SOLVER_VP)
+
+or using one of the dynamics solvers, using dissipative
+dynamics:
+
+.. code-block:: python
+    from spirit import parameters, simulation, state
+
+    with state.State("input/input.cfg") as p_state:
+        parameters.llg.set_direct_minimization(p_state, True)
+        simulation.start(p_state, simulation.METHOD_LLG, simulation.SOLVER_DEPONDT)
+
+
+LLG method
+----------------------------------------------------
+
+To perform an LLG dynamics simulation:
+
+.. code-block:: python
+    from spirit import simulation, state
+
+    with state.State("input/input.cfg") as p_state:
+        simulation.start(p_state, simulation.METHOD_LLG, simulation.SOLVER_DEPONDT)
+
+Note that the velocity projection (VP) solver is not a dynamics solver.
+
+
+GNEB method
+----------------------------------------------------
+
+The geodesic nudged elastic band method.
+See also the [method paper](http://www.sciencedirect.com/science/article/pii/S0010465515002696).
+
+This method operates on a transition between two spin configurations,
+discretised by "images" on a "chain". The procedure follows these steps:
+1. set the number of images
+2. set the initial and final spin configuration
+3. create an initial guess for the transition path
+4. run an initial GNEB relaxation
+5. determine and set the suitable images on the chain to converge on extrema
+6. run a full GNEB relaxation using climbing and falling images
+
+
+.. code-block:: python
+    from spirit import state, chain, configuration, transition, simulation 
+
+    noi = 7
+
+    with state.State("input/input.cfg") as p_state:
+        ### Copy the first image and set chain length
+        chain.image_to_clipboard(p_state)
+        chain.set_length(p_state, noi)
+
+        ### First image is homogeneous with a Skyrmion in the center
+        configuration.plus_z(p_state, idx_image=0)
+        configuration.skyrmion(p_state, 5.0, phase=-90.0, idx_image=0)
+        simulation.start(p_state, simulation.METHOD_LLG, simulation.SOLVER_VP, idx_image=0)
+        ### Last image is homogeneous
+        configuration.plus_z(p_state, idx_image=noi-1)
+        simulation.start(p_state, simulation.METHOD_LLG, simulation.SOLVER_VP, idx_image=noi-1)
+
+        ### Create initial guess for transition: homogeneous rotation
+        transition.homogeneous(p_state, 0, noi-1)
+
+        ### Initial GNEB relaxation
+        simulation.start(p_state, simulation.METHOD_GNEB, simulation.SOLVER_VP, n_iterations=5000)
+        ### Automatically set climbing and falling images
+        chain.set_image_type_automatically(p_state)
+        ### Full GNEB relaxation
+        simulation.start(p_state, simulation.METHOD_GNEB, simulation.SOLVER_VP)
+
+
+HTST
+----------------------------------------------------
+
+The harmonic transition state theory.
+See also the [method paper](https://link.aps.org/doi/10.1103/PhysRevB.85.184409).
+
+*The usage of this method is not yet documented.*
+
+
+MMF method
+----------------------------------------------------
+
+The minimum mode following method.
+See also the [method paper](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.121.197202).
+
+*The usage of this method is not yet documented.*
+
+
+Full API reference
+----------------------------------------------------
 
 .. toctree::
     :maxdepth: 2
-    :caption: Python API
 
     spirit.chain            <spirit.chain>
     spirit.configuration    <spirit.configuration>