From 6d1996bc7a7d5132c9ffb629455a666f00b3f666 Mon Sep 17 00:00:00 2001 From: Gideon Date: Wed, 12 Jun 2019 22:11:39 +0200 Subject: [PATCH] Restructured API docs. --- conf.py | 15 ++- core/docs/C_API.md | 119 +++++++++++++++++++++ core/docs/Python_API.md | 106 ++++++++++++++++++ core/docs/README.md | 8 +- core/docs/c-api/API.rst | 142 ------------------------- core/docs/c-api/API_Reference.rst | 24 +++++ core/docs/python-api/API.rst | 125 ---------------------- core/docs/python-api/API_Reference.rst | 20 ++++ docs/index.rst | 19 ++-- 9 files changed, 290 insertions(+), 288 deletions(-) create mode 100644 core/docs/C_API.md create mode 100644 core/docs/Python_API.md delete mode 100644 core/docs/c-api/API.rst create mode 100644 core/docs/c-api/API_Reference.rst delete mode 100644 core/docs/python-api/API.rst create mode 100644 core/docs/python-api/API_Reference.rst diff --git a/conf.py b/conf.py index 609298081..b3e932c97 100644 --- a/conf.py +++ b/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: diff --git a/core/docs/C_API.md b/core/docs/C_API.md new file mode 100644 index 000000000..f2385802b --- /dev/null +++ b/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 +#include +#include + +auto state = std::shared_ptr(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 +#include +#include +#include + +auto state = std::shared_ptr(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 +#include +#include + +auto state = std::shared_ptr(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 +#include +#include +#include +#include +#include + +int NOI = 7; + +auto state = std::shared_ptr(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.* \ No newline at end of file diff --git a/core/docs/Python_API.md b/core/docs/Python_API.md new file mode 100644 index 000000000..93fcb8feb --- /dev/null +++ b/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.* \ No newline at end of file diff --git a/core/docs/README.md b/core/docs/README.md index a2fc8cc23..84961862d 100644 --- a/core/docs/README.md +++ b/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) \ No newline at end of file +* [C API Examples](C_API.md) +* [Python API Examples](Python_API.md) \ No newline at end of file diff --git a/core/docs/c-api/API.rst b/core/docs/c-api/API.rst deleted file mode 100644 index 8ad4434ec..000000000 --- a/core/docs/c-api/API.rst +++ /dev/null @@ -1,142 +0,0 @@ -C API -================================== - - -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 - #include - #include - - auto state = std::shared_ptr(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 - #include - #include - #include - - auto state = std::shared_ptr(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 - #include - #include - - auto state = std::shared_ptr(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 - #include - #include - #include - #include - #include - - int NOI = 7; - - auto state = std::shared_ptr(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 - - Spirit/Chain.h - Spirit/Configurations.h - Spirit/Constants.h - Spirit/Geometry.h - Spirit/Hamiltonian.h - Spirit/HTST.h - Spirit/IO.h - Spirit/Log.h - Spirit/Parameters_MC.h - Spirit/Parameters_LLG.h - Spirit/Parameters_GNEB.h - Spirit/Parameters_EMA.h - Spirit/Parameters_MMF.h - Spirit/Quantities.h - Spirit/Simulation.h - Spirit/State.h - Spirit/System.h - Spirit/Transition.h \ No newline at end of file diff --git a/core/docs/c-api/API_Reference.rst b/core/docs/c-api/API_Reference.rst new file mode 100644 index 000000000..4a51cfe2b --- /dev/null +++ b/core/docs/c-api/API_Reference.rst @@ -0,0 +1,24 @@ +Full API reference +================================== + +.. toctree:: + :maxdepth: 2 + + Spirit/Chain.h + Spirit/Configurations.h + Spirit/Constants.h + Spirit/Geometry.h + Spirit/Hamiltonian.h + Spirit/HTST.h + Spirit/IO.h + Spirit/Log.h + Spirit/Parameters_MC.h + Spirit/Parameters_LLG.h + Spirit/Parameters_GNEB.h + Spirit/Parameters_EMA.h + Spirit/Parameters_MMF.h + Spirit/Quantities.h + Spirit/Simulation.h + Spirit/State.h + Spirit/System.h + Spirit/Transitions.h \ No newline at end of file diff --git a/core/docs/python-api/API.rst b/core/docs/python-api/API.rst deleted file mode 100644 index 88fc5bf9c..000000000 --- a/core/docs/python-api/API.rst +++ /dev/null @@ -1,125 +0,0 @@ -Python API -================================== - - -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 - - spirit.chain - spirit.configuration - spirit.constants - spirit.geometry - spirit.hamiltonian - spirit.htst - spirit.io - spirit.log - spirit.parameters - spirit.quantities - spirit.simulation - spirit.state - spirit.system - spirit.transition \ No newline at end of file diff --git a/core/docs/python-api/API_Reference.rst b/core/docs/python-api/API_Reference.rst new file mode 100644 index 000000000..40e5b58ac --- /dev/null +++ b/core/docs/python-api/API_Reference.rst @@ -0,0 +1,20 @@ +Full API reference +================================== + +.. toctree:: + :maxdepth: 2 + + spirit.chain + spirit.configuration + spirit.constants + spirit.geometry + spirit.hamiltonian + spirit.htst + spirit.io + spirit.log + spirit.parameters + spirit.quantities + spirit.simulation + spirit.state + spirit.system + spirit.transition \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 612ab8bb7..398381f34 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -21,16 +21,23 @@ Spirit - Spin Simulation Framework :maxdepth: 2 :caption: Installation - Build on Unix/OSX - Build on Windows - Using Docker + Build on Unix/OSX + Build on Windows + Using Docker .. toctree:: :maxdepth: 3 - :caption: API Reference + :caption: C API - C API <../core/docs/c-api/API> - Python API <../core/docs/python-api/API> + Usage <../core/docs/C_API> + Full Reference <../core/docs/c-api/API_Reference> + +.. toctree:: + :maxdepth: 3 + :caption: Python API + + Usage <../core/docs/Python_API> + Full Reference <../core/docs/python-api/API_Reference> .. toctree:: :maxdepth: 1