Restructured API docs.

conf.py

@@ -209,13 +209,10 @@
 ]
 
 
-
-
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'https://docs.python.org/': None}
 
 
-
 def run_apidoc(_):
     """Runs sphinx-apidoc when building the documentation.
     Needs to be done in conf.py in order to include the APIdoc in the
@@ -242,11 +239,11 @@ def run_apidoc(_):
         '--maxdepth', '4',
     ]
 
-    builddir = os.path.join(source_dir, 'build')
-    if not os.path.exists(builddir):
-        os.mkdir(builddir)
-    subprocess.check_call(['cmake', '..', '-DSPIRIT_BUILD_FOR_CXX=OFF', '-DSPIRIT_SKIP_HTST=ON'], cwd=builddir)
-    subprocess.check_call(['make'], cwd=builddir)
+    build_dir = os.path.join(source_dir, 'build')
+    if not os.path.exists(build_dir):
+        os.mkdir(build_dir)
+    subprocess.check_call(['cmake', '..', '-DSPIRIT_BUILD_FOR_CXX=OFF', '-DSPIRIT_SKIP_HTST=ON'], cwd=build_dir)
+    subprocess.check_call(['make'], cwd=build_dir)
 
     # See https://stackoverflow.com/a/30144019
     env = os.environ.copy()
@@ -255,7 +252,7 @@ def run_apidoc(_):
 
     #####################
     with open(os.path.join(apidoc_dir, 'parameters.rst'), "w") as parameters_file:
-        parameters_file.write("Parameters\n==================================\n\n")
+        parameters_file.write("spirit.parameters\n==================================\n\n")
         with open(os.path.join(apidoc_dir, 'spirit.parameters.mc.rst'), 'r') as generated_file:
             parameters_file.write(generated_file.read())
         with open(os.path.join(apidoc_dir, 'spirit.parameters.llg.rst'), 'r') as generated_file:

core/docs/C_API.md

@@ -0,0 +1,119 @@
+Usage
+====================================================
+
+
+Energy minimisation
+----------------------------------------------------
+
+Energy minimisation of a spin system can be performed
+using the LLG method and the velocity projection (VP)
+solver:
+
+```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:
+
+```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:
+
+```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
+
+```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.*

core/docs/Python_API.md

@@ -0,0 +1,106 @@
+Usage
+====================================================
+
+
+Energy minimisation
+----------------------------------------------------
+
+Energy minimisation of a spin system can be performed
+using the LLG method and the velocity projection (VP)
+solver:
+
+```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:
+
+```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:
+
+```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
+
+
+```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.*

core/docs/README.md

@@ -25,9 +25,5 @@ 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)
+* [C API Examples](C_API.md)
+* [Python API Examples](Python_API.md)