diff --git a/docs/source/_examples/01_Data_Loading_and_Selection.nblink b/docs/source/_examples/01_Data_Loading_and_Selection.nblink
new file mode 100644
index 00000000..4949dc69
--- /dev/null
+++ b/docs/source/_examples/01_Data_Loading_and_Selection.nblink
@@ -0,0 +1,3 @@
+{
+ "path": "../../../examples/01_Data_Loading_and_Selection.ipynb"
+}
diff --git a/docs/source/_examples/02_Training_Models.nblink b/docs/source/_examples/02_Training_Models.nblink
new file mode 100644
index 00000000..43debfed
--- /dev/null
+++ b/docs/source/_examples/02_Training_Models.nblink
@@ -0,0 +1,3 @@
+{
+ "path": "../../../examples/02_Training_Models.ipynb"
+}
diff --git a/docs/source/_examples/03_Analysing_Datasets_and_Model_Predictions.nblink b/docs/source/_examples/03_Analysing_Datasets_and_Model_Predictions.nblink
new file mode 100644
index 00000000..f73a3f83
--- /dev/null
+++ b/docs/source/_examples/03_Analysing_Datasets_and_Model_Predictions.nblink
@@ -0,0 +1,3 @@
+{
+ "path": "../../../examples/03_Analysing_Datasets_and_Model_Predictions.ipynb"
+}
diff --git a/docs/source/_examples/04_Molecular_Dynamics_Structure_Generation_and_Simulation.nblink b/docs/source/_examples/04_Molecular_Dynamics_Structure_Generation_and_Simulation.nblink
new file mode 100644
index 00000000..48f1d5a1
--- /dev/null
+++ b/docs/source/_examples/04_Molecular_Dynamics_Structure_Generation_and_Simulation.nblink
@@ -0,0 +1,3 @@
+{
+ "path": "../../../examples/04_Molecular_Dynamics_Structure_Generation_and_Simulation.ipynb"
+}
diff --git a/docs/source/_examples/05_Labeling_with_Calculators.nblink b/docs/source/_examples/05_Labeling_with_Calculators.nblink
new file mode 100644
index 00000000..56af6e18
--- /dev/null
+++ b/docs/source/_examples/05_Labeling_with_Calculators.nblink
@@ -0,0 +1,3 @@
+{
+ "path": "../../../examples/05_Labeling_with_Calculators.ipynb"
+}
diff --git a/docs/source/_examples/06_Bootstrapping_Datasets.nblink b/docs/source/_examples/06_Bootstrapping_Datasets.nblink
new file mode 100644
index 00000000..56b6c559
--- /dev/null
+++ b/docs/source/_examples/06_Bootstrapping_Datasets.nblink
@@ -0,0 +1,3 @@
+{
+ "path": "../../../examples/06_Bootstrapping_Datasets.ipynb"
+}
diff --git a/docs/source/_examples/index.rst b/docs/source/_examples/index.rst
new file mode 100644
index 00000000..62bafde7
--- /dev/null
+++ b/docs/source/_examples/index.rst
@@ -0,0 +1,30 @@
+
+
+.. _userdoc-examples:
+
+IPS is based on `ZnTrack `_, and we suggest working through the examples on the ZnTrack docs to understand how to construct version controlled workflows.
+The notebooks contained in this section cover the functionality of IPS and assume familiarity with the basics of running workflows and experiments.
+
+The utility of IPS is best demonstrated by some worked examples.
+This section starts out with some introductory notebooks demonstrating the capabilities of the Nodes from each submodule.
+Later notebooks feature some more complex workflows which are closer to real world use case.
+All notebooks can be found in `/examples/docs`.
+
+
+.. image:: https://mybinder.org/badge_logo.svg
+ :alt: Binder
+ :target: https://mybinder.org/v2/gh/zincware/IPSuite/HEAD
+
+
+Examples
+========
+
+.. toctree::
+ :maxdepth: 0
+
+ 01_Data_Loading_and_Selection
+ 02_Training_Models
+ 03_Analysing_Datasets_and_Model_Predictions
+ 04_Molecular_Dynamics_Structure_Generation_and_Simulation
+ 05_Labeling_with_Calculators
+ 06_Bootstrapping_Datasets
diff --git a/docs/source/_get_started/_autosummary/ipsuite.analysis.bin_property.rst b/docs/source/_get_started/_autosummary/ipsuite.analysis.bin_property.rst
new file mode 100644
index 00000000..a8116ab2
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.analysis.bin_property.rst
@@ -0,0 +1,26 @@
+ipsuite.analysis.bin\_property
+==============================
+
+.. automodule:: ipsuite.analysis.bin_property
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ DipoleHistogram
+ EnergyHistogram
+ EnergyUncertaintyHistogram
+ ForcesHistogram
+ ForcesUncertaintyHistogram
+ LabelHistogram
+ StressHistogram
diff --git a/docs/source/_get_started/_autosummary/ipsuite.analysis.bond_stretch.rst b/docs/source/_get_started/_autosummary/ipsuite.analysis.bond_stretch.rst
new file mode 100644
index 00000000..b66183d5
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.analysis.bond_stretch.rst
@@ -0,0 +1,20 @@
+ipsuite.analysis.bond\_stretch
+==============================
+
+.. automodule:: ipsuite.analysis.bond_stretch
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ BondStretchAnalyses
diff --git a/docs/source/_get_started/_autosummary/ipsuite.analysis.ensemble.rst b/docs/source/_get_started/_autosummary/ipsuite.analysis.ensemble.rst
new file mode 100644
index 00000000..55e9653f
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.analysis.ensemble.rst
@@ -0,0 +1,26 @@
+ipsuite.analysis.ensemble
+=========================
+
+.. automodule:: ipsuite.analysis.ensemble
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ plot_with_uncertainty
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ ModelEnsembleAnalysis
diff --git a/docs/source/_get_started/_autosummary/ipsuite.analysis.md.rst b/docs/source/_get_started/_autosummary/ipsuite.analysis.md.rst
new file mode 100644
index 00000000..29166462
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.analysis.md.rst
@@ -0,0 +1,20 @@
+ipsuite.analysis.md
+===================
+
+.. automodule:: ipsuite.analysis.md
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ AnalyseDensity
diff --git a/docs/source/_get_started/_autosummary/ipsuite.analysis.model.dynamics.rst b/docs/source/_get_started/_autosummary/ipsuite.analysis.model.dynamics.rst
new file mode 100644
index 00000000..ded615c5
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.analysis.model.dynamics.rst
@@ -0,0 +1,29 @@
+ipsuite.analysis.model.dynamics
+===============================
+
+.. automodule:: ipsuite.analysis.model.dynamics
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ run_stability_nve
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ BoxHeatUp
+ BoxScale
+ MDStability
+ RattleAnalysis
diff --git a/docs/source/_get_started/_autosummary/ipsuite.analysis.model.dynamics_checks.rst b/docs/source/_get_started/_autosummary/ipsuite.analysis.model.dynamics_checks.rst
new file mode 100644
index 00000000..f09235c8
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.analysis.model.dynamics_checks.rst
@@ -0,0 +1,24 @@
+ipsuite.analysis.model.dynamics\_checks
+=======================================
+
+.. automodule:: ipsuite.analysis.model.dynamics_checks
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ ConnectivityCheck
+ EnergySpikeCheck
+ NaNCheck
+ TemperatureCheck
+ ThresholdCheck
diff --git a/docs/source/_get_started/_autosummary/ipsuite.analysis.model.math.rst b/docs/source/_get_started/_autosummary/ipsuite.analysis.model.math.rst
new file mode 100644
index 00000000..35998d9b
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.analysis.model.math.rst
@@ -0,0 +1,20 @@
+ipsuite.analysis.model.math
+===========================
+
+.. automodule:: ipsuite.analysis.model.math
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ compute_intertia_tensor
+ compute_rot_forces
+ compute_trans_forces
+ decompose_stress_tensor
+ force_decomposition
diff --git a/docs/source/_get_started/_autosummary/ipsuite.analysis.model.plots.rst b/docs/source/_get_started/_autosummary/ipsuite.analysis.model.plots.rst
new file mode 100644
index 00000000..88abaceb
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.analysis.model.plots.rst
@@ -0,0 +1,19 @@
+ipsuite.analysis.model.plots
+============================
+
+.. automodule:: ipsuite.analysis.model.plots
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ density_scatter
+ get_figure
+ get_hist
+ get_histogram_figure
diff --git a/docs/source/_get_started/_autosummary/ipsuite.analysis.model.predict.rst b/docs/source/_get_started/_autosummary/ipsuite.analysis.model.predict.rst
new file mode 100644
index 00000000..9357f2ac
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.analysis.model.predict.rst
@@ -0,0 +1,23 @@
+ipsuite.analysis.model.predict
+==============================
+
+.. automodule:: ipsuite.analysis.model.predict
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ ForceAngles
+ ForceDecomposition
+ Prediction
+ PredictionMetrics
diff --git a/docs/source/_get_started/_autosummary/ipsuite.analysis.model.rst b/docs/source/_get_started/_autosummary/ipsuite.analysis.model.rst
new file mode 100644
index 00000000..8ee20ffd
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.analysis.model.rst
@@ -0,0 +1,34 @@
+ipsuite.analysis.model
+======================
+
+.. automodule:: ipsuite.analysis.model
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+.. rubric:: Modules
+
+.. autosummary::
+ :toctree:
+ :recursive:
+
+ ipsuite.analysis.model.dynamics
+ ipsuite.analysis.model.dynamics_checks
+ ipsuite.analysis.model.math
+ ipsuite.analysis.model.plots
+ ipsuite.analysis.model.predict
diff --git a/docs/source/_get_started/_autosummary/ipsuite.analysis.rst b/docs/source/_get_started/_autosummary/ipsuite.analysis.rst
new file mode 100644
index 00000000..345e9ded
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.analysis.rst
@@ -0,0 +1,35 @@
+ipsuite.analysis
+================
+
+.. automodule:: ipsuite.analysis
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+.. rubric:: Modules
+
+.. autosummary::
+ :toctree:
+ :recursive:
+
+ ipsuite.analysis.bin_property
+ ipsuite.analysis.bond_stretch
+ ipsuite.analysis.ensemble
+ ipsuite.analysis.md
+ ipsuite.analysis.model
+ ipsuite.analysis.sensitivity
diff --git a/docs/source/_get_started/_autosummary/ipsuite.analysis.sensitivity.rst b/docs/source/_get_started/_autosummary/ipsuite.analysis.sensitivity.rst
new file mode 100644
index 00000000..9f95b8b9
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.analysis.sensitivity.rst
@@ -0,0 +1,29 @@
+ipsuite.analysis.sensitivity
+============================
+
+.. automodule:: ipsuite.analysis.sensitivity
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ nonuniform_imshow
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ AnalyseGlobalForceSensitivity
+ AnalyseSingleForceSensitivity
+ IsConstraintMD
+ MoveSingleParticle
diff --git a/docs/source/_get_started/_autosummary/ipsuite.base.base.rst b/docs/source/_get_started/_autosummary/ipsuite.base.base.rst
new file mode 100644
index 00000000..0ed40d88
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.base.base.rst
@@ -0,0 +1,26 @@
+ipsuite.base.base
+=================
+
+.. automodule:: ipsuite.base.base
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ AnalyseAtoms
+ AnalyseProcessAtoms
+ CheckBase
+ IPSNode
+ Mapping
+ ProcessAtoms
+ ProcessSingleAtom
diff --git a/docs/source/_get_started/_autosummary/ipsuite.base.protocol.rst b/docs/source/_get_started/_autosummary/ipsuite.base.protocol.rst
new file mode 100644
index 00000000..720cbb0f
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.base.protocol.rst
@@ -0,0 +1,22 @@
+ipsuite.base.protocol
+=====================
+
+.. automodule:: ipsuite.base.protocol
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ HasAtoms
+ HasSelectedConfigurations
+ ProcessAtoms
diff --git a/docs/source/_get_started/_autosummary/ipsuite.base.rst b/docs/source/_get_started/_autosummary/ipsuite.base.rst
new file mode 100644
index 00000000..d3507240
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.base.rst
@@ -0,0 +1,31 @@
+ipsuite.base
+============
+
+.. automodule:: ipsuite.base
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+.. rubric:: Modules
+
+.. autosummary::
+ :toctree:
+ :recursive:
+
+ ipsuite.base.base
+ ipsuite.base.protocol
diff --git a/docs/source/_get_started/_autosummary/ipsuite.bootstrap.random_displacements.rst b/docs/source/_get_started/_autosummary/ipsuite.bootstrap.random_displacements.rst
new file mode 100644
index 00000000..fb43e7d5
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.bootstrap.random_displacements.rst
@@ -0,0 +1,23 @@
+ipsuite.bootstrap.random\_displacements
+=======================================
+
+.. automodule:: ipsuite.bootstrap.random_displacements
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ Bootstrap
+ RattleAtoms
+ RotateMolecules
+ TranslateMolecules
diff --git a/docs/source/_get_started/_autosummary/ipsuite.bootstrap.rst b/docs/source/_get_started/_autosummary/ipsuite.bootstrap.rst
new file mode 100644
index 00000000..a8850783
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.bootstrap.rst
@@ -0,0 +1,31 @@
+ipsuite.bootstrap
+=================
+
+.. automodule:: ipsuite.bootstrap
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+.. rubric:: Modules
+
+.. autosummary::
+ :toctree:
+ :recursive:
+
+ ipsuite.bootstrap.random_displacements
+ ipsuite.bootstrap.surface_mods
diff --git a/docs/source/_get_started/_autosummary/ipsuite.bootstrap.surface_mods.rst b/docs/source/_get_started/_autosummary/ipsuite.bootstrap.surface_mods.rst
new file mode 100644
index 00000000..87ed5dbc
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.bootstrap.surface_mods.rst
@@ -0,0 +1,27 @@
+ipsuite.bootstrap.surface\_mods
+===============================
+
+.. automodule:: ipsuite.bootstrap.surface_mods
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ plot_ture_vs_pred
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ SurfaceRasterMetrics
+ SurfaceRasterScan
diff --git a/docs/source/_get_started/_autosummary/ipsuite.calculators.apax_jax_md.rst b/docs/source/_get_started/_autosummary/ipsuite.calculators.apax_jax_md.rst
new file mode 100644
index 00000000..7a9298b6
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.calculators.apax_jax_md.rst
@@ -0,0 +1,20 @@
+ipsuite.calculators.apax\_jax\_md
+=================================
+
+.. automodule:: ipsuite.calculators.apax_jax_md
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ ApaxJaxMD
diff --git a/docs/source/_get_started/_autosummary/ipsuite.calculators.ase_geoopt.rst b/docs/source/_get_started/_autosummary/ipsuite.calculators.ase_geoopt.rst
new file mode 100644
index 00000000..4d87733f
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.calculators.ase_geoopt.rst
@@ -0,0 +1,21 @@
+ipsuite.calculators.ase\_geoopt
+===============================
+
+.. automodule:: ipsuite.calculators.ase_geoopt
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ ASEGeoOpt
+ BatchASEGeoOpt
diff --git a/docs/source/_get_started/_autosummary/ipsuite.calculators.ase_md.rst b/docs/source/_get_started/_autosummary/ipsuite.calculators.ase_md.rst
new file mode 100644
index 00000000..b829a446
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.calculators.ase_md.rst
@@ -0,0 +1,36 @@
+ipsuite.calculators.ase\_md
+===========================
+
+.. automodule:: ipsuite.calculators.ase_md
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ get_desc
+ update_metrics_dict
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ ASEMD
+ BoxOscillatingRampModifier
+ FixedLayerConstraint
+ FixedSphereConstraint
+ LangevinThermostat
+ NPTThermostat
+ PressureRampModifier
+ RescaleBoxModifier
+ TemperatureOscillatingRampModifier
+ TemperatureRampModifier
diff --git a/docs/source/_get_started/_autosummary/ipsuite.calculators.ase_standard.rst b/docs/source/_get_started/_autosummary/ipsuite.calculators.ase_standard.rst
new file mode 100644
index 00000000..3effc4a2
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.calculators.ase_standard.rst
@@ -0,0 +1,22 @@
+ipsuite.calculators.ase\_standard
+=================================
+
+.. automodule:: ipsuite.calculators.ase_standard
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ EMTCalculator
+ EMTSinglePoint
+ LJSinglePoint
diff --git a/docs/source/_get_started/_autosummary/ipsuite.calculators.cp2k.rst b/docs/source/_get_started/_autosummary/ipsuite.calculators.cp2k.rst
new file mode 100644
index 00000000..16663e1f
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.calculators.cp2k.rst
@@ -0,0 +1,21 @@
+ipsuite.calculators.cp2k
+========================
+
+.. automodule:: ipsuite.calculators.cp2k
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ CP2KSinglePoint
+ CP2KYaml
diff --git a/docs/source/_get_started/_autosummary/ipsuite.calculators.lammps.rst b/docs/source/_get_started/_autosummary/ipsuite.calculators.lammps.rst
new file mode 100644
index 00000000..9e71f215
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.calculators.lammps.rst
@@ -0,0 +1,20 @@
+ipsuite.calculators.lammps
+==========================
+
+.. automodule:: ipsuite.calculators.lammps
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ LammpsSimulator
diff --git a/docs/source/_get_started/_autosummary/ipsuite.calculators.mix.rst b/docs/source/_get_started/_autosummary/ipsuite.calculators.mix.rst
new file mode 100644
index 00000000..9fc2a7de
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.calculators.mix.rst
@@ -0,0 +1,21 @@
+ipsuite.calculators.mix
+=======================
+
+.. automodule:: ipsuite.calculators.mix
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ CalculatorNode
+ MixCalculator
diff --git a/docs/source/_get_started/_autosummary/ipsuite.calculators.orca.rst b/docs/source/_get_started/_autosummary/ipsuite.calculators.orca.rst
new file mode 100644
index 00000000..3135f426
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.calculators.orca.rst
@@ -0,0 +1,20 @@
+ipsuite.calculators.orca
+========================
+
+.. automodule:: ipsuite.calculators.orca
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ OrcaSinglePoint
diff --git a/docs/source/_get_started/_autosummary/ipsuite.calculators.rst b/docs/source/_get_started/_autosummary/ipsuite.calculators.rst
new file mode 100644
index 00000000..3e90e425
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.calculators.rst
@@ -0,0 +1,39 @@
+ipsuite.calculators
+===================
+
+.. automodule:: ipsuite.calculators
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+.. rubric:: Modules
+
+.. autosummary::
+ :toctree:
+ :recursive:
+
+ ipsuite.calculators.apax_jax_md
+ ipsuite.calculators.ase_geoopt
+ ipsuite.calculators.ase_md
+ ipsuite.calculators.ase_standard
+ ipsuite.calculators.cp2k
+ ipsuite.calculators.lammps
+ ipsuite.calculators.mix
+ ipsuite.calculators.orca
+ ipsuite.calculators.torch_d3
+ ipsuite.calculators.xtb
diff --git a/docs/source/_get_started/_autosummary/ipsuite.calculators.torch_d3.rst b/docs/source/_get_started/_autosummary/ipsuite.calculators.torch_d3.rst
new file mode 100644
index 00000000..128bf78d
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.calculators.torch_d3.rst
@@ -0,0 +1,21 @@
+ipsuite.calculators.torch\_d3
+=============================
+
+.. automodule:: ipsuite.calculators.torch_d3
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ TorchD3
+ TorchDFTD3CalculatorNL
diff --git a/docs/source/_get_started/_autosummary/ipsuite.calculators.xtb.rst b/docs/source/_get_started/_autosummary/ipsuite.calculators.xtb.rst
new file mode 100644
index 00000000..a40e989e
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.calculators.xtb.rst
@@ -0,0 +1,20 @@
+ipsuite.calculators.xtb
+=======================
+
+.. automodule:: ipsuite.calculators.xtb
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ xTBSinglePoint
diff --git a/docs/source/_get_started/_autosummary/ipsuite.configuration_comparison.MMKernel.rst b/docs/source/_get_started/_autosummary/ipsuite.configuration_comparison.MMKernel.rst
new file mode 100644
index 00000000..7adeab24
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.configuration_comparison.MMKernel.rst
@@ -0,0 +1,47 @@
+ipsuite.configuration\_comparison.MMKernel
+==========================================
+
+.. currentmodule:: ipsuite.configuration_comparison
+
+.. autoclass:: MMKernel
+
+
+ .. automethod:: __init__
+
+
+ .. rubric:: Methods
+
+ .. autosummary::
+
+ ~MMKernel.__init__
+ ~MMKernel.compare
+ ~MMKernel.convert_notebook
+ ~MMKernel.from_rev
+ ~MMKernel.load
+ ~MMKernel.run
+ ~MMKernel.save
+ ~MMKernel.save_representation
+ ~MMKernel.unlink_database
+
+
+
+
+
+ .. rubric:: Attributes
+
+ .. autosummary::
+
+ ~MMKernel.analyte
+ ~MMKernel.init_descriptors
+ ~MMKernel.init_subclass_basecls
+ ~MMKernel.memory
+ ~MMKernel.name
+ ~MMKernel.nwd
+ ~MMKernel.reference
+ ~MMKernel.result
+ ~MMKernel.similarities
+ ~MMKernel.soap
+ ~MMKernel.state
+ ~MMKernel.use_jit
+ ~MMKernel.use_repr
+ ~MMKernel.uuid
diff --git a/docs/source/_get_started/_autosummary/ipsuite.configuration_comparison.REMatch.rst b/docs/source/_get_started/_autosummary/ipsuite.configuration_comparison.REMatch.rst
new file mode 100644
index 00000000..bbe8ea70
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.configuration_comparison.REMatch.rst
@@ -0,0 +1,50 @@
+ipsuite.configuration\_comparison.REMatch
+=========================================
+
+.. currentmodule:: ipsuite.configuration_comparison
+
+.. autoclass:: REMatch
+
+
+ .. automethod:: __init__
+
+
+ .. rubric:: Methods
+
+ .. autosummary::
+
+ ~REMatch.__init__
+ ~REMatch.compare
+ ~REMatch.convert_notebook
+ ~REMatch.from_rev
+ ~REMatch.load
+ ~REMatch.run
+ ~REMatch.save
+ ~REMatch.save_representation
+ ~REMatch.unlink_database
+
+
+
+
+
+ .. rubric:: Attributes
+
+ .. autosummary::
+
+ ~REMatch.alpha
+ ~REMatch.analyte
+ ~REMatch.init_descriptors
+ ~REMatch.init_subclass_basecls
+ ~REMatch.memory
+ ~REMatch.metric
+ ~REMatch.name
+ ~REMatch.nwd
+ ~REMatch.reference
+ ~REMatch.result
+ ~REMatch.similarities
+ ~REMatch.soap
+ ~REMatch.state
+ ~REMatch.threshold
+ ~REMatch.use_jit
+ ~REMatch.use_repr
+ ~REMatch.uuid
diff --git a/docs/source/_get_started/_autosummary/ipsuite.configuration_comparison.base.rst b/docs/source/_get_started/_autosummary/ipsuite.configuration_comparison.base.rst
new file mode 100644
index 00000000..573796d3
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.configuration_comparison.base.rst
@@ -0,0 +1,30 @@
+ipsuite.configuration\_comparison.base
+======================================
+
+.. automodule:: ipsuite.configuration_comparison.base
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ convert_to_df
+ create_dataset
+ write_dataset
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ ConfigurationComparison
+ SOAPParameter
+ SOAPParameterConverter
diff --git a/docs/source/_get_started/_autosummary/ipsuite.configuration_comparison.rst b/docs/source/_get_started/_autosummary/ipsuite.configuration_comparison.rst
new file mode 100644
index 00000000..e3defe7d
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.configuration_comparison.rst
@@ -0,0 +1,32 @@
+ipsuite.configuration\_comparison
+=================================
+
+.. automodule:: ipsuite.configuration_comparison
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+.. rubric:: Modules
+
+.. autosummary::
+ :toctree:
+ :recursive:
+
+ ipsuite.configuration_comparison.MMKernel
+ ipsuite.configuration_comparison.REMatch
+ ipsuite.configuration_comparison.base
diff --git a/docs/source/_get_started/_autosummary/ipsuite.configuration_generation.packmol.rst b/docs/source/_get_started/_autosummary/ipsuite.configuration_generation.packmol.rst
new file mode 100644
index 00000000..1c66af6b
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.configuration_generation.packmol.rst
@@ -0,0 +1,21 @@
+ipsuite.configuration\_generation.packmol
+=========================================
+
+.. automodule:: ipsuite.configuration_generation.packmol
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ MultiPackmol
+ Packmol
diff --git a/docs/source/_get_started/_autosummary/ipsuite.configuration_generation.rst b/docs/source/_get_started/_autosummary/ipsuite.configuration_generation.rst
new file mode 100644
index 00000000..7f6b21b7
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.configuration_generation.rst
@@ -0,0 +1,31 @@
+ipsuite.configuration\_generation
+=================================
+
+.. automodule:: ipsuite.configuration_generation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+.. rubric:: Modules
+
+.. autosummary::
+ :toctree:
+ :recursive:
+
+ ipsuite.configuration_generation.packmol
+ ipsuite.configuration_generation.smiles_to_atoms
diff --git a/docs/source/_get_started/_autosummary/ipsuite.configuration_generation.smiles_to_atoms.rst b/docs/source/_get_started/_autosummary/ipsuite.configuration_generation.smiles_to_atoms.rst
new file mode 100644
index 00000000..fb6227d0
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.configuration_generation.smiles_to_atoms.rst
@@ -0,0 +1,21 @@
+ipsuite.configuration\_generation.smiles\_to\_atoms
+===================================================
+
+.. automodule:: ipsuite.configuration_generation.smiles_to_atoms
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ SmilesToAtoms
+ SmilesToConformers
diff --git a/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.base.rst b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.base.rst
new file mode 100644
index 00000000..2db8513e
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.base.rst
@@ -0,0 +1,21 @@
+ipsuite.configuration\_selection.base
+=====================================
+
+.. automodule:: ipsuite.configuration_selection.base
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ BatchConfigurationSelection
+ ConfigurationSelection
diff --git a/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.filter.rst b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.filter.rst
new file mode 100644
index 00000000..44fd9a9a
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.filter.rst
@@ -0,0 +1,20 @@
+ipsuite.configuration\_selection.filter
+=======================================
+
+.. automodule:: ipsuite.configuration_selection.filter
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ FilterOutlier
diff --git a/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.index.rst b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.index.rst
new file mode 100644
index 00000000..9a4e32d0
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.index.rst
@@ -0,0 +1,20 @@
+ipsuite.configuration\_selection.index
+======================================
+
+.. automodule:: ipsuite.configuration_selection.index
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ IndexSelection
diff --git a/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.kernel.rst b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.kernel.rst
new file mode 100644
index 00000000..ecb538af
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.kernel.rst
@@ -0,0 +1,20 @@
+ipsuite.configuration\_selection.kernel
+=======================================
+
+.. automodule:: ipsuite.configuration_selection.kernel
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ KernelSelection
diff --git a/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.random.rst b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.random.rst
new file mode 100644
index 00000000..794a63fb
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.random.rst
@@ -0,0 +1,20 @@
+ipsuite.configuration\_selection.random
+=======================================
+
+.. automodule:: ipsuite.configuration_selection.random
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ RandomSelection
diff --git a/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.rst b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.rst
new file mode 100644
index 00000000..fc04d6e8
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.rst
@@ -0,0 +1,39 @@
+ipsuite.configuration\_selection
+================================
+
+.. automodule:: ipsuite.configuration_selection
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+.. rubric:: Modules
+
+.. autosummary::
+ :toctree:
+ :recursive:
+
+ ipsuite.configuration_selection.base
+ ipsuite.configuration_selection.filter
+ ipsuite.configuration_selection.index
+ ipsuite.configuration_selection.kernel
+ ipsuite.configuration_selection.random
+ ipsuite.configuration_selection.split
+ ipsuite.configuration_selection.threshold
+ ipsuite.configuration_selection.uniform_arange
+ ipsuite.configuration_selection.uniform_energetic
+ ipsuite.configuration_selection.uniform_temporal
diff --git a/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.split.rst b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.split.rst
new file mode 100644
index 00000000..23aa1dba
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.split.rst
@@ -0,0 +1,20 @@
+ipsuite.configuration\_selection.split
+======================================
+
+.. automodule:: ipsuite.configuration_selection.split
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ SplitSelection
diff --git a/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.threshold.rst b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.threshold.rst
new file mode 100644
index 00000000..ac297e54
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.threshold.rst
@@ -0,0 +1,28 @@
+ipsuite.configuration\_selection.threshold
+==========================================
+
+.. automodule:: ipsuite.configuration_selection.threshold
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ check_dimension
+ max_reduction
+ mean_reduction
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ ThresholdSelection
diff --git a/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.uniform_arange.rst b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.uniform_arange.rst
new file mode 100644
index 00000000..ad5494bf
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.uniform_arange.rst
@@ -0,0 +1,20 @@
+ipsuite.configuration\_selection.uniform\_arange
+================================================
+
+.. automodule:: ipsuite.configuration_selection.uniform_arange
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ UniformArangeSelection
diff --git a/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.uniform_energetic.rst b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.uniform_energetic.rst
new file mode 100644
index 00000000..a58532cf
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.uniform_energetic.rst
@@ -0,0 +1,20 @@
+ipsuite.configuration\_selection.uniform\_energetic
+===================================================
+
+.. automodule:: ipsuite.configuration_selection.uniform_energetic
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ UniformEnergeticSelection
diff --git a/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.uniform_temporal.rst b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.uniform_temporal.rst
new file mode 100644
index 00000000..fc0f04f5
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.configuration_selection.uniform_temporal.rst
@@ -0,0 +1,20 @@
+ipsuite.configuration\_selection.uniform\_temporal
+==================================================
+
+.. automodule:: ipsuite.configuration_selection.uniform_temporal
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ UniformTemporalSelection
diff --git a/docs/source/_get_started/_autosummary/ipsuite.data_loading.add_data_ase.rst b/docs/source/_get_started/_autosummary/ipsuite.data_loading.add_data_ase.rst
new file mode 100644
index 00000000..2a5b6212
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.data_loading.add_data_ase.rst
@@ -0,0 +1,27 @@
+ipsuite.data\_loading.add\_data\_ase
+====================================
+
+.. automodule:: ipsuite.data_loading.add_data_ase
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ load_data
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ AddData
+ ReadData
diff --git a/docs/source/_get_started/_autosummary/ipsuite.data_loading.add_data_h5md.rst b/docs/source/_get_started/_autosummary/ipsuite.data_loading.add_data_h5md.rst
new file mode 100644
index 00000000..4586617f
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.data_loading.add_data_h5md.rst
@@ -0,0 +1,20 @@
+ipsuite.data\_loading.add\_data\_h5md
+=====================================
+
+.. automodule:: ipsuite.data_loading.add_data_h5md
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ AddDataH5MD
diff --git a/docs/source/_get_started/_autosummary/ipsuite.data_loading.rst b/docs/source/_get_started/_autosummary/ipsuite.data_loading.rst
new file mode 100644
index 00000000..7a92b629
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.data_loading.rst
@@ -0,0 +1,31 @@
+ipsuite.data\_loading
+=====================
+
+.. automodule:: ipsuite.data_loading
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+.. rubric:: Modules
+
+.. autosummary::
+ :toctree:
+ :recursive:
+
+ ipsuite.data_loading.add_data_ase
+ ipsuite.data_loading.add_data_h5md
diff --git a/docs/source/_get_started/_autosummary/ipsuite.fields.atoms.rst b/docs/source/_get_started/_autosummary/ipsuite.fields.atoms.rst
new file mode 100644
index 00000000..6f650f93
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.fields.atoms.rst
@@ -0,0 +1,20 @@
+ipsuite.fields.atoms
+====================
+
+.. automodule:: ipsuite.fields.atoms
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ Atoms
diff --git a/docs/source/_get_started/_autosummary/ipsuite.fields.rst b/docs/source/_get_started/_autosummary/ipsuite.fields.rst
new file mode 100644
index 00000000..ef4da94f
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.fields.rst
@@ -0,0 +1,30 @@
+ipsuite.fields
+==============
+
+.. automodule:: ipsuite.fields
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+.. rubric:: Modules
+
+.. autosummary::
+ :toctree:
+ :recursive:
+
+ ipsuite.fields.atoms
diff --git a/docs/source/_get_started/_autosummary/ipsuite.geometry.barycenter_coarse_grain.rst b/docs/source/_get_started/_autosummary/ipsuite.geometry.barycenter_coarse_grain.rst
new file mode 100644
index 00000000..790d0303
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.geometry.barycenter_coarse_grain.rst
@@ -0,0 +1,17 @@
+ipsuite.geometry.barycenter\_coarse\_grain
+==========================================
+
+.. automodule:: ipsuite.geometry.barycenter_coarse_grain
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ barycenter_backmapping
+ coarse_grain_to_barycenter
diff --git a/docs/source/_get_started/_autosummary/ipsuite.geometry.graphs.rst b/docs/source/_get_started/_autosummary/ipsuite.geometry.graphs.rst
new file mode 100644
index 00000000..e4e1cb6e
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.geometry.graphs.rst
@@ -0,0 +1,19 @@
+ipsuite.geometry.graphs
+=======================
+
+.. automodule:: ipsuite.geometry.graphs
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ atoms_to_graph
+ edges_from_atoms
+ identify_molecules
+ split_molecule
diff --git a/docs/source/_get_started/_autosummary/ipsuite.geometry.mapping.rst b/docs/source/_get_started/_autosummary/ipsuite.geometry.mapping.rst
new file mode 100644
index 00000000..fe850898
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.geometry.mapping.rst
@@ -0,0 +1,20 @@
+ipsuite.geometry.mapping
+========================
+
+.. automodule:: ipsuite.geometry.mapping
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ BarycenterMapping
diff --git a/docs/source/_get_started/_autosummary/ipsuite.geometry.rst b/docs/source/_get_started/_autosummary/ipsuite.geometry.rst
new file mode 100644
index 00000000..6dd258b8
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.geometry.rst
@@ -0,0 +1,33 @@
+ipsuite.geometry
+================
+
+.. automodule:: ipsuite.geometry
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+.. rubric:: Modules
+
+.. autosummary::
+ :toctree:
+ :recursive:
+
+ ipsuite.geometry.barycenter_coarse_grain
+ ipsuite.geometry.graphs
+ ipsuite.geometry.mapping
+ ipsuite.geometry.unwrap
diff --git a/docs/source/_get_started/_autosummary/ipsuite.geometry.unwrap.rst b/docs/source/_get_started/_autosummary/ipsuite.geometry.unwrap.rst
new file mode 100644
index 00000000..87728056
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.geometry.unwrap.rst
@@ -0,0 +1,20 @@
+ipsuite.geometry.unwrap
+=======================
+
+.. automodule:: ipsuite.geometry.unwrap
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ closest_atom_to_center
+ displace_neighbors
+ sort_atomic_edges
+ unwrap
+ unwrap_system
diff --git a/docs/source/_get_started/_autosummary/ipsuite.models.apax.rst b/docs/source/_get_started/_autosummary/ipsuite.models.apax.rst
new file mode 100644
index 00000000..cab116c5
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.models.apax.rst
@@ -0,0 +1,22 @@
+ipsuite.models.apax
+===================
+
+.. automodule:: ipsuite.models.apax
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ Apax
+ ApaxEnsemble
+ BatchKernelSelection
diff --git a/docs/source/_get_started/_autosummary/ipsuite.models.base.rst b/docs/source/_get_started/_autosummary/ipsuite.models.base.rst
new file mode 100644
index 00000000..674be800
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.models.base.rst
@@ -0,0 +1,20 @@
+ipsuite.models.base
+===================
+
+.. automodule:: ipsuite.models.base
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ MLModel
diff --git a/docs/source/_get_started/_autosummary/ipsuite.models.ensemble.rst b/docs/source/_get_started/_autosummary/ipsuite.models.ensemble.rst
new file mode 100644
index 00000000..f42c02fe
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.models.ensemble.rst
@@ -0,0 +1,21 @@
+ipsuite.models.ensemble
+=======================
+
+.. automodule:: ipsuite.models.ensemble
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ EnsembleCalculator
+ EnsembleModel
diff --git a/docs/source/_get_started/_autosummary/ipsuite.models.gap.rst b/docs/source/_get_started/_autosummary/ipsuite.models.gap.rst
new file mode 100644
index 00000000..3d3b7a85
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.models.gap.rst
@@ -0,0 +1,26 @@
+ipsuite.models.gap
+==================
+
+.. automodule:: ipsuite.models.gap
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ DistanceNb
+ DistanceNbConverter
+ GAP
+ GapParameter
+ GapParameterConverter
+ SOAP
+ SOAPConverter
diff --git a/docs/source/_get_started/_autosummary/ipsuite.models.mace_model.rst b/docs/source/_get_started/_autosummary/ipsuite.models.mace_model.rst
new file mode 100644
index 00000000..b77873f0
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.models.mace_model.rst
@@ -0,0 +1,26 @@
+ipsuite.models.mace\_model
+==========================
+
+.. automodule:: ipsuite.models.mace_model
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ execute
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ MACE
diff --git a/docs/source/_get_started/_autosummary/ipsuite.models.nequip.rst b/docs/source/_get_started/_autosummary/ipsuite.models.nequip.rst
new file mode 100644
index 00000000..508ee5f4
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.models.nequip.rst
@@ -0,0 +1,20 @@
+ipsuite.models.nequip
+=====================
+
+.. automodule:: ipsuite.models.nequip
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ Nequip
diff --git a/docs/source/_get_started/_autosummary/ipsuite.models.rst b/docs/source/_get_started/_autosummary/ipsuite.models.rst
new file mode 100644
index 00000000..4bd01e37
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.models.rst
@@ -0,0 +1,35 @@
+ipsuite.models
+==============
+
+.. automodule:: ipsuite.models
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+.. rubric:: Modules
+
+.. autosummary::
+ :toctree:
+ :recursive:
+
+ ipsuite.models.apax
+ ipsuite.models.base
+ ipsuite.models.ensemble
+ ipsuite.models.gap
+ ipsuite.models.mace_model
+ ipsuite.models.nequip
diff --git a/docs/source/_get_started/_autosummary/ipsuite.nodes.rst b/docs/source/_get_started/_autosummary/ipsuite.nodes.rst
new file mode 100644
index 00000000..79e2bca2
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.nodes.rst
@@ -0,0 +1,4 @@
+ipsuite.nodes
+=============
+
+.. automodule:: ipsuite.nodes
diff --git a/docs/source/_get_started/_autosummary/ipsuite.project.rst b/docs/source/_get_started/_autosummary/ipsuite.project.rst
new file mode 100644
index 00000000..39eac890
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.project.rst
@@ -0,0 +1,20 @@
+ipsuite.project
+===============
+
+.. automodule:: ipsuite.project
+
+
+
+
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ Project
diff --git a/docs/source/_get_started/_autosummary/ipsuite.rst b/docs/source/_get_started/_autosummary/ipsuite.rst
new file mode 100644
index 00000000..5f8561aa
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.rst
@@ -0,0 +1,44 @@
+ipsuite
+=======
+
+.. automodule:: ipsuite
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+.. rubric:: Modules
+
+.. autosummary::
+ :toctree:
+ :recursive:
+
+ ipsuite.analysis
+ ipsuite.base
+ ipsuite.bootstrap
+ ipsuite.calculators
+ ipsuite.configuration_comparison
+ ipsuite.configuration_generation
+ ipsuite.configuration_selection
+ ipsuite.data_loading
+ ipsuite.fields
+ ipsuite.geometry
+ ipsuite.models
+ ipsuite.nodes
+ ipsuite.project
+ ipsuite.static_data
+ ipsuite.utils
diff --git a/docs/source/_get_started/_autosummary/ipsuite.static_data.rst b/docs/source/_get_started/_autosummary/ipsuite.static_data.rst
new file mode 100644
index 00000000..cb98b831
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.static_data.rst
@@ -0,0 +1,4 @@
+ipsuite.static\_data
+====================
+
+.. automodule:: ipsuite.static_data
diff --git a/docs/source/_get_started/_autosummary/ipsuite.utils.ase_sim.rst b/docs/source/_get_started/_autosummary/ipsuite.utils.ase_sim.rst
new file mode 100644
index 00000000..d860b798
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.utils.ase_sim.rst
@@ -0,0 +1,20 @@
+ipsuite.utils.ase\_sim
+======================
+
+.. automodule:: ipsuite.utils.ase_sim
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ freeze_copy_atoms
+ get_box_from_density
+ get_density_from_atoms
+ get_desc
+ get_energy
diff --git a/docs/source/_get_started/_autosummary/ipsuite.utils.combine.rst b/docs/source/_get_started/_autosummary/ipsuite.utils.combine.rst
new file mode 100644
index 00000000..8659aecd
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.utils.combine.rst
@@ -0,0 +1,27 @@
+ipsuite.utils.combine
+=====================
+
+.. automodule:: ipsuite.utils.combine
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ get_flat_data_from_dict
+ get_ids_per_key
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+
+ ExcludeIds
diff --git a/docs/source/_get_started/_autosummary/ipsuite.utils.docs.rst b/docs/source/_get_started/_autosummary/ipsuite.utils.docs.rst
new file mode 100644
index 00000000..6c4606cd
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.utils.docs.rst
@@ -0,0 +1,16 @@
+ipsuite.utils.docs
+==================
+
+.. automodule:: ipsuite.utils.docs
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ create_dvc_git_env_for_doctest
diff --git a/docs/source/_get_started/_autosummary/ipsuite.utils.helpers.rst b/docs/source/_get_started/_autosummary/ipsuite.utils.helpers.rst
new file mode 100644
index 00000000..8446b16e
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.utils.helpers.rst
@@ -0,0 +1,18 @@
+ipsuite.utils.helpers
+=====================
+
+.. automodule:: ipsuite.utils.helpers
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ check_duplicate_keys
+ get_deps_if_node
+ setup_ase
diff --git a/docs/source/_get_started/_autosummary/ipsuite.utils.logs.rst b/docs/source/_get_started/_autosummary/ipsuite.utils.logs.rst
new file mode 100644
index 00000000..17b6c896
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.utils.logs.rst
@@ -0,0 +1,16 @@
+ipsuite.utils.logs
+==================
+
+.. automodule:: ipsuite.utils.logs
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ setup_logging
diff --git a/docs/source/_get_started/_autosummary/ipsuite.utils.md.rst b/docs/source/_get_started/_autosummary/ipsuite.utils.md.rst
new file mode 100644
index 00000000..16ab6dba
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.utils.md.rst
@@ -0,0 +1,16 @@
+ipsuite.utils.md
+================
+
+.. automodule:: ipsuite.utils.md
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ get_energy_terms
diff --git a/docs/source/_get_started/_autosummary/ipsuite.utils.metrics.rst b/docs/source/_get_started/_autosummary/ipsuite.utils.metrics.rst
new file mode 100644
index 00000000..5a6420b4
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.utils.metrics.rst
@@ -0,0 +1,24 @@
+ipsuite.utils.metrics
+=====================
+
+.. automodule:: ipsuite.utils.metrics
+
+
+
+
+
+
+
+ .. rubric:: Functions
+
+ .. autosummary::
+
+ calculate_l_p_norm
+ get_angles
+ get_full_metrics
+ get_u_vecs
+ maximum_error
+ mean_absolute_error
+ mean_squared_error
+ relative_rmse
+ root_mean_squared_error
diff --git a/docs/source/_get_started/_autosummary/ipsuite.utils.rst b/docs/source/_get_started/_autosummary/ipsuite.utils.rst
new file mode 100644
index 00000000..ff838736
--- /dev/null
+++ b/docs/source/_get_started/_autosummary/ipsuite.utils.rst
@@ -0,0 +1,36 @@
+ipsuite.utils
+=============
+
+.. automodule:: ipsuite.utils
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+.. rubric:: Modules
+
+.. autosummary::
+ :toctree:
+ :recursive:
+
+ ipsuite.utils.ase_sim
+ ipsuite.utils.combine
+ ipsuite.utils.docs
+ ipsuite.utils.helpers
+ ipsuite.utils.logs
+ ipsuite.utils.md
+ ipsuite.utils.metrics
diff --git a/docs/source/_get_started/index.rst b/docs/source/_get_started/index.rst
new file mode 100644
index 00000000..1d51c41d
--- /dev/null
+++ b/docs/source/_get_started/index.rst
@@ -0,0 +1,15 @@
+
+.. _userdoc-get-started:
+
+
+Getting Started
+===============
+
+TODO link to zntrack docs
+
+
+
+.. toctree::
+ :maxdepth: 0
+
+ installation
diff --git a/docs/source/_get_started/installation.rst b/docs/source/_get_started/installation.rst
new file mode 100644
index 00000000..622c5858
--- /dev/null
+++ b/docs/source/_get_started/installation.rst
@@ -0,0 +1,35 @@
+Installation
+============
+
+IPS is available on PyPI and can be installed using
+
+.. code-block:: bash
+
+ pip install ipsuite
+
+
+Note that a default installation does not come with any of the models.
+These are available as extras and can be installed by specifying the models you would like to install.
+For example, the following code snippets install the GAP model (via `quippy `_ ) and all available models respectively
+
+.. code-block:: bash
+
+ pip install ipsuite[gap]
+
+.. code-block:: bash
+
+ pip install ipsuite[all]
+
+
+
+Developer Installation
+----------------------
+
+IPS is devloped using `Poetry `_.
+To install a developer verions of IPS, clone the repository and install it with poetry:
+
+.. code-block:: bash
+
+ git clone https://github.com/zincware/IPSuite.git
+ cd IPSuite
+ poetry install
diff --git a/docs/source/_get_started/nodes_list.rst b/docs/source/_get_started/nodes_list.rst
new file mode 100644
index 00000000..5f245ee0
--- /dev/null
+++ b/docs/source/_get_started/nodes_list.rst
@@ -0,0 +1,23 @@
+List of IPSuite Nodes
+=====================
+
+
+
+.. autosummary::
+ :toctree: _autosummary
+ :recursive:
+
+ ipsuite.analysis
+ ipsuite.base
+ ipsuite.bootstrap
+ ipsuite.calculators
+ ipsuite.configuration_generation
+ ipsuite.configuration_selection
+ ipsuite.configuration_comparison
+ ipsuite.data_loading
+ ipsuite.fields
+ ipsuite.geometry
+ ipsuite.models
+ ipsuite.project
+ ipsuite.static_data
+ ipsuite.utils
diff --git a/docs/source/_nodes/analysis.rst b/docs/source/_nodes/analysis.rst
new file mode 100644
index 00000000..0e5fd368
--- /dev/null
+++ b/docs/source/_nodes/analysis.rst
@@ -0,0 +1,5 @@
+Analysis
+========
+.. automodule:: ipsuite.analysis
+ :members:
+ :show-inheritance:
diff --git a/docs/source/_nodes/bootstrap.rst b/docs/source/_nodes/bootstrap.rst
new file mode 100644
index 00000000..08859e17
--- /dev/null
+++ b/docs/source/_nodes/bootstrap.rst
@@ -0,0 +1,5 @@
+Bootstrap
+=========
+.. automodule:: ipsuite.bootstrap
+ :members:
+ :show-inheritance:
diff --git a/docs/source/_nodes/calculators.rst b/docs/source/_nodes/calculators.rst
new file mode 100644
index 00000000..b6841898
--- /dev/null
+++ b/docs/source/_nodes/calculators.rst
@@ -0,0 +1,5 @@
+Calculators
+===========
+.. automodule:: ipsuite.calculators
+ :members:
+ :show-inheritance:
diff --git a/docs/source/_nodes/configuration_comparison.rst b/docs/source/_nodes/configuration_comparison.rst
new file mode 100644
index 00000000..fc71452d
--- /dev/null
+++ b/docs/source/_nodes/configuration_comparison.rst
@@ -0,0 +1,5 @@
+Configuration Comparison
+========================
+.. automodule:: ipsuite.configuration_comparison
+ :members:
+ :show-inheritance:
diff --git a/docs/source/_nodes/configuration_generation.rst b/docs/source/_nodes/configuration_generation.rst
new file mode 100644
index 00000000..d4213157
--- /dev/null
+++ b/docs/source/_nodes/configuration_generation.rst
@@ -0,0 +1,5 @@
+Configuration Generation
+========================
+.. automodule:: ipsuite.configuration_generation
+ :members:
+ :show-inheritance:
diff --git a/docs/source/_nodes/configuration_selection.rst b/docs/source/_nodes/configuration_selection.rst
new file mode 100644
index 00000000..36dda743
--- /dev/null
+++ b/docs/source/_nodes/configuration_selection.rst
@@ -0,0 +1,5 @@
+Configuration Selection
+=======================
+.. automodule:: ipsuite.configuration_selection
+ :members:
+ :show-inheritance:
diff --git a/docs/source/_nodes/data_loading.rst b/docs/source/_nodes/data_loading.rst
new file mode 100644
index 00000000..824ebf0d
--- /dev/null
+++ b/docs/source/_nodes/data_loading.rst
@@ -0,0 +1,5 @@
+Data Loading
+============
+.. automodule:: ipsuite.data_loading
+ :members:
+ :show-inheritance:
diff --git a/docs/source/_nodes/geometry.rst b/docs/source/_nodes/geometry.rst
new file mode 100644
index 00000000..8bdbc2c4
--- /dev/null
+++ b/docs/source/_nodes/geometry.rst
@@ -0,0 +1,5 @@
+Geometry
+========
+.. automodule:: ipsuite.geometry
+ :members:
+ :show-inheritance:
diff --git a/docs/source/_nodes/index.rst b/docs/source/_nodes/index.rst
new file mode 100644
index 00000000..5b8cdf07
--- /dev/null
+++ b/docs/source/_nodes/index.rst
@@ -0,0 +1,19 @@
+
+
+.. _userdoc-modules:
+
+Nodes
+=====
+
+.. toctree::
+ :maxdepth: 2
+
+ data_loading
+ bootstrap
+ calculators
+ configuration_selection
+ models
+ analysis
+ configuration_comparison
+ configuration_generation
+ geometry
diff --git a/docs/source/_nodes/models.rst b/docs/source/_nodes/models.rst
new file mode 100644
index 00000000..6f66ee98
--- /dev/null
+++ b/docs/source/_nodes/models.rst
@@ -0,0 +1,5 @@
+Models
+======
+.. automodule:: ipsuite.models
+ :members:
+ :show-inheritance:
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 53f30f9d..3b158f3f 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -25,8 +25,10 @@
"sphinx.ext.doctest",
"sphinx_copybutton",
"sphinx.ext.viewcode",
+ "sphinx.ext.autosummary",
]
+autosummary_generate = True
templates_path = ["_templates"]
exclude_patterns = []
diff --git a/docs/source/images/water_packmol.png b/docs/source/images/water_packmol.png
index e0604e56..fecc8ed9 100644
Binary files a/docs/source/images/water_packmol.png and b/docs/source/images/water_packmol.png differ
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 76bb3bf8..35df39c8 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,3 +1,44 @@
+.. IPSuite documentation master file, created by
+ sphinx-quickstart on Mon May 22 19:58:40 2023.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+IPS - The Inter Atomic Potential Suite
+======================================
+
+The Inter Atomic Potential Suite (IPS) allows for the fast construction and extension of atomistic machine learning workflows.
+It is based on `ZnTrack `_ and thus allows for fully version controlled and reproducible workflows.
+Within IPS, we provide numerous Nodes for creating atomistic data, training models, analyzing predictions and performing molecular dynamics.
+
+
+
+Example
+=======
+
+Routine workflows are easy to set up and can be easily extended for more complex tasks.
+Training any of the interfaced models only requires a few lines of code:
+
+.. code-block:: python
+
+ import ipsuite as ips
+
+ with ips.Project() as project:
+ data = ips.AddData(file="dataset.extxyz")
+ random_selection = ips.configuration_selection.RandomSelection(
+ data=data, n_configurations=100
+ )
+
+ model = ips.models.GAP(data=random_selection)
+
+
+
+.. toctree::
+ :hidden:
+
+ _get_started/index
+ _examples/index
+ _nodes/index
+
.. IPSuite documentation master file, created by
sphinx-quickstart on Fri Feb 2 12:58:52 2024.
You can adapt this file completely to your liking, but it should at least
@@ -16,8 +57,8 @@ Welcome to IPSuite's documentation!
What is IPS? <_get_started/ips>
Getting Started <_get_started/quickstart>
- IPSuite <_nodes/ipsuite>
- Modules <_nodes/modlules>
+ Nodes List <_get_started/nodes_list>
+ Modules <_nodes/modules>
Indices and tables
diff --git a/examples/01_Data_Loading_and_Selection.ipynb b/examples/01_Data_Loading_and_Selection.ipynb
new file mode 100644
index 00000000..723f56f0
--- /dev/null
+++ b/examples/01_Data_Loading_and_Selection.ipynb
@@ -0,0 +1,567 @@
+{
+ "cells": [
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Data Loading and Selection"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Welcome to the first IPS example notebook!\n",
+ "Here we will demonstrate how to load existing datasets and perform some simple and more involved data splitting workflows.\n",
+ "\n",
+ "All examples are self-contained, and the data is created within the notebooks themselves."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "2023-05-31 23:10:07,791 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n"
+ ]
+ }
+ ],
+ "source": [
+ "import ipsuite as ips\n",
+ "from zntrack.utils import cwd_temp_dir\n",
+ "\n",
+ "temp_dir = cwd_temp_dir()\n",
+ "\n",
+ "import ipsuite as ips\n",
+ "\n",
+ "import os\n",
+ "from ase import units\n",
+ "from ase.calculators.emt import EMT\n",
+ "from ase.io.trajectory import TrajectoryWriter\n",
+ "from ase.lattice.cubic import FaceCenteredCubic\n",
+ "from ase.md.velocitydistribution import MaxwellBoltzmannDistribution\n",
+ "from ase.md.langevin import Langevin\n",
+ "from ase.visualize import view\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "hint: Using 'master' as the name for the initial branch. This default branch name\n",
+ "hint: is subject to change. To configure the initial branch name to use in all\n",
+ "hint: of your new repositories, which will suppress this warning, call:\n",
+ "hint: \n",
+ "hint: \tgit config --global init.defaultBranch \n",
+ "hint: \n",
+ "hint: Names commonly chosen instead of 'master' are 'main', 'trunk' and\n",
+ "hint: 'development'. The just-created branch can be renamed via this command:\n",
+ "hint: \n",
+ "hint: \tgit branch -m \n",
+ "Initialized empty Git repository in /tmp/tmpok_da3k5/.git/\n",
+ "Initialized DVC repository.\n",
+ "\n",
+ "You can now commit the changes to git.\n",
+ "\n",
+ "+---------------------------------------------------------------------+\n",
+ "| |\n",
+ "| DVC has enabled anonymous aggregate usage analytics. |\n",
+ "| Read the analytics documentation (and how to opt-out) here: |\n",
+ "| |\n",
+ "| |\n",
+ "+---------------------------------------------------------------------+\n",
+ "\n",
+ "What's next?\n",
+ "------------\n",
+ "- Check out the documentation: \n",
+ "- Get help and share ideas: \n",
+ "- Star us on GitHub: \n"
+ ]
+ }
+ ],
+ "source": [
+ "!git init\n",
+ "!dvc init"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Data Creation\n",
+ "\n",
+ "First, we will create some sample data using ASE to perform a short molecular dynamics simulation.\n",
+ "\n",
+ "TODO make data and run MD\n",
+ "TODO combining multiple datasets"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "size = 3\n",
+ "\n",
+ "# Set up a crystal\n",
+ "atoms = FaceCenteredCubic(\n",
+ " directions=[[1, 0, 0], [0, 1, 0], [0, 0, 1]],\n",
+ " symbol='Cu',\n",
+ " size=(size, size, size),\n",
+ " pbc=True\n",
+ ")\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "True"
+ ]
+ },
+ "execution_count": 4,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "timestep = 5 * units.fs\n",
+ "steps = 100\n",
+ "temperature = 800\n",
+ "traj_path = os.path.join(temp_dir.name, \"trajectory.traj\")\n",
+ "\n",
+ "\n",
+ "atoms.calc = EMT()\n",
+ "MaxwellBoltzmannDistribution(atoms, temperature_K=temperature)\n",
+ "\n",
+ "dyn = Langevin(atoms, timestep, temperature_K=temperature, friction=0.002)\n",
+ "\n",
+ "writer = TrajectoryWriter(traj_path, \"w\", atoms=atoms)\n",
+ "dyn.attach(writer, interval=1)\n",
+ "\n",
+ "dyn.run(steps)"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Data Loading\n",
+ "\n",
+ "IPS uses ASE for many of its internals and datasets can be loaded from any ASE compatible format.\n",
+ "Here we are going to pretend that the above created sample data is some literature dataset that we have already downloaded."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "2023-05-31 23:10:17,739 (WARNING): Please run 'dvc add /tmp/tmpok_da3k5/trajectory.traj' to track the file with DVC. Otherwise, it might end up being git tracked.\n"
+ ]
+ },
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "Running DVC command: 'stage add --name trajectory --force ...'\n",
+ "Running DVC command: 'repro'\n"
+ ]
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "2023-05-31 23:10:19,001 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n"
+ ]
+ },
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "Reading File: 101it [00:00, 3355.28it/s]\n"
+ ]
+ }
+ ],
+ "source": [
+ "with ips.Project() as project:\n",
+ " trajectory = ips.AddData(file=traj_path, name=\"trajectory\")\n",
+ "project.run()"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The data is read from disk and is now available to both other Nodes in the project and for use in the notebook."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 6,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "trajectory.load() # requires the project to have been run"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "We obtain a list of ASE Atoms, with which we can work in our notebook and use other ASE functionality, e.g.:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "view(trajectory)"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The H5MD standard offers substantial size and I/O speed advantages.\n",
+ "For this reason H5MD is used by Nodes which serialize atomistic data, including `AddData`."
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Data Selection\n",
+ "\n",
+ "A common way to split data into training, validation and test splits is to randomly partition them into fractions like 75:15:10.\n",
+ "We can add the respective selection Nodes to our existing project."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 7,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "Running DVC command: 'stage add --name trajectory --force ...'\n",
+ "Running DVC command: 'stage add --name random_test_selection --force ...'\n",
+ "Running DVC command: 'stage add --name random_val_selection --force ...'\n",
+ "Running DVC command: 'stage add --name random_train_selection --force ...'\n",
+ "Running DVC command: 'repro'\n"
+ ]
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "2023-05-31 23:10:20,899 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n",
+ "2023-05-31 23:10:21,047 (DEBUG): Selecting from 101 configurations.\n",
+ "2023-05-31 23:10:22,301 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n",
+ "2023-05-31 23:10:22,491 (DEBUG): Selecting from 91 configurations.\n",
+ "2023-05-31 23:10:23,804 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n",
+ "2023-05-31 23:10:24,044 (DEBUG): Selecting from 76 configurations.\n"
+ ]
+ }
+ ],
+ "source": [
+ "with project:\n",
+ " random_test_selection = ips.configuration_selection.RandomSelection(data=trajectory, n_configurations=10, name=\"random_test_selection\")\n",
+ " random_val_selection = ips.configuration_selection.RandomSelection(data=random_test_selection.excluded_atoms, n_configurations=15, name=\"random_val_selection\")\n",
+ " random_train_selection = ips.configuration_selection.RandomSelection(data=random_val_selection.excluded_atoms, n_configurations=75, name=\"random_train_selection\")\n",
+ "project.run()"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Selecting the testing data first means we can change our training and validation selection, e.g. by using a different selection method or a different number of configurations, without altering our test set.\n",
+ "Note that we had to give names to our selection nodes since we use multiple instances of that Node in our graph.\n",
+ "For convenience, it is also possible to assign numerical IDs by supplying `automatic_node_names=True` to the `Project`."
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "We can visualize our workflow at any time using"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 8,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ " +------------+ \n",
+ " | trajectory | \n",
+ " +------------+ \n",
+ " * \n",
+ " * \n",
+ " * \n",
+ "+-----------------------+ \n",
+ "| random_test_selection | \n",
+ "+-----------------------+ \n",
+ " * \n",
+ " * \n",
+ " * \n",
+ " +----------------------+ \n",
+ " | random_val_selection | \n",
+ " +----------------------+ \n",
+ " * \n",
+ " * \n",
+ " * \n",
+ "+------------------------+ \n",
+ "| random_train_selection | \n",
+ "+------------------------+ \n"
+ ]
+ }
+ ],
+ "source": [
+ "!dvc dag"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "While straightforward, this is not necessarily advisable for molecular dynamics data.\n",
+ "Trajectories are created sequentially, and a random split will result in validation samples that are drawn from between training samples.\n",
+ "By instead separating the dataset into fixed fraction first, we can ensure that the splits do not temporally overlap.\n",
+ "\n",
+ "For demonstration purposes, we will delete the random splitting workflow we created above with `remove_existing_graph=True`."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 9,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "2023-05-31 23:11:14,183 (WARNING): Please run 'dvc add /tmp/tmpok_da3k5/trajectory.traj' to track the file with DVC. Otherwise, it might end up being git tracked.\n"
+ ]
+ },
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "Running DVC command: 'stage add --name trajectory --force ...'\n",
+ "Running DVC command: 'stage add --name test_split --force ...'\n",
+ "Running DVC command: 'stage add --name val_split --force ...'\n",
+ "Running DVC command: 'stage add --name test_data --force ...'\n",
+ "Running DVC command: 'stage add --name val_data --force ...'\n",
+ "Running DVC command: 'stage add --name train_data --force ...'\n",
+ "Running DVC command: 'repro'\n"
+ ]
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "2023-05-31 23:11:15,722 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n",
+ "2023-05-31 23:11:15,915 (DEBUG): Selecting from 101 configurations.\n",
+ "2023-05-31 23:11:17,228 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n",
+ "2023-05-31 23:11:17,459 (DEBUG): Selecting from 91 configurations.\n",
+ "2023-05-31 23:11:18,780 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n",
+ "2023-05-31 23:11:19,031 (DEBUG): Selecting from 76 configurations.\n",
+ "2023-05-31 23:11:19,031 (WARNING): Running search for 80 to max 76\n",
+ "2023-05-31 23:11:20,350 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n",
+ "2023-05-31 23:11:20,561 (DEBUG): Selecting from 10 configurations.\n",
+ "2023-05-31 23:11:21,836 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n",
+ "2023-05-31 23:11:22,081 (DEBUG): Selecting from 15 configurations.\n"
+ ]
+ }
+ ],
+ "source": [
+ "with ips.Project(remove_existing_graph=True) as project:\n",
+ " trajectory = ips.AddData(file=traj_path, name=\"trajectory\")\n",
+ " test_split = ips.configuration_selection.SplitSelection(data=trajectory, split=0.1, name=\"test_split\")\n",
+ " val_split = ips.configuration_selection.SplitSelection(data=test_split.excluded_atoms, split=0.17, name=\"val_split\") # 0.15 / 0.9 * 1.0 \\approx 0.17\n",
+ " train_split = val_split.excluded_atoms # 0.8 of the total data\n",
+ "\n",
+ " test_data = ips.configuration_selection.UniformTemporalSelection(data=test_split, n_configurations=10, name=\"test_data\")\n",
+ " val_data = ips.configuration_selection.UniformTemporalSelection(data=val_split, n_configurations=15, name=\"val_data\")\n",
+ " train_data = ips.configuration_selection.UniformEnergeticSelection(data=train_split, n_configurations=80, name=\"train_data\")\n",
+ "\n",
+ "project.run()"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The selection methods here are purely for demonstration purposes.\n",
+ "Usually it makes sense to use all available test data and not perform a sub-selection since the test set should only be evaluated once which does not pose a performance bottleneck."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 10,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ " +------------+ \n",
+ " | trajectory | \n",
+ " +------------+ \n",
+ " * \n",
+ " * \n",
+ " * \n",
+ " +------------+ \n",
+ " | test_split | \n",
+ " +------------+ \n",
+ " *** *** \n",
+ " * * \n",
+ " ** ** \n",
+ "+-----------+ +-----------+ \n",
+ "| test_data | | val_split | \n",
+ "+-----------+ +-----------+ \n",
+ " *** *** \n",
+ " * * \n",
+ " ** ** \n",
+ " +----------+ +------------+ \n",
+ " | val_data | | train_data | \n",
+ " +----------+ +------------+ \n"
+ ]
+ }
+ ],
+ "source": [
+ "!dvc dag"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Below is a list of all currently implemented selection methods.\n",
+ "Check out the API docs for more information about the methods not covered here."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "['ConfigurationSelection',\n",
+ " 'RandomSelection',\n",
+ " 'UniformEnergeticSelection',\n",
+ " 'UniformTemporalSelection',\n",
+ " 'UniformArangeSelection',\n",
+ " 'KernelSelection',\n",
+ " 'IndexSelection',\n",
+ " 'ThresholdSelection',\n",
+ " 'SplitSelection']"
+ ]
+ },
+ "execution_count": 2,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "ips.configuration_selection.__all__"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Kernel Based Selection Methods"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": []
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# TODO"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "temp_dir.cleanup()"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "ips2",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.10.11"
+ },
+ "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/examples/02_Training_Models.ipynb b/examples/02_Training_Models.ipynb
new file mode 100644
index 00000000..cf1418ac
--- /dev/null
+++ b/examples/02_Training_Models.ipynb
@@ -0,0 +1,113 @@
+{
+ "cells": [
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Training Models"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "2023-05-26 15:16:04,580 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n"
+ ]
+ }
+ ],
+ "source": [
+ "import ipsuite as ips"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": []
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "IPS is interfaced with a series of models. A complete list of available models is found below."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "['Apax', 'EnsembleModel', 'GAP', 'MACE', 'MLModel', 'Nequip']"
+ ]
+ },
+ "execution_count": 3,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "ips.models.__all__"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Using the Trained Model\n",
+ "\n",
+ "Here we will briefly evaluate our model\"s predictions with a correlation plot of predicted and actual labels.\n",
+ "A more detailed presentation of the analysis capabilities contained in IPS can be found in the next notebook."
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": []
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Transfer Learning\n",
+ "\n",
+ "TODO"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "ips",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.10.11"
+ },
+ "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/examples/03_Analysing_Datasets_and_Model_Predictions.ipynb b/examples/03_Analysing_Datasets_and_Model_Predictions.ipynb
new file mode 100644
index 00000000..47afa1ec
--- /dev/null
+++ b/examples/03_Analysing_Datasets_and_Model_Predictions.ipynb
@@ -0,0 +1,204 @@
+{
+ "cells": [
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Analysing Datasets and Model Predictions"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "In the last example we already saw how to obtain a simple prediction-label correlation plot.\n",
+ "However, for most real-life applications, this alone would be insufficient to ascertain the reliability of the model across configuration space.\n",
+ "This notebook goes into more detail about how to use the various analysis tools implemented in IPS."
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Data Generation and Training\n",
+ "\n",
+ "We will once again create a simple dataset."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "2023-06-06 22:00:51,620 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n"
+ ]
+ }
+ ],
+ "source": [
+ "import ipsuite as ips\n",
+ "from zntrack.utils import cwd_temp_dir\n",
+ "\n",
+ "temp_dir = cwd_temp_dir()\n",
+ "\n",
+ "import ipsuite as ips\n",
+ "\n",
+ "import os\n",
+ "from ase import units\n",
+ "from ase.calculators.emt import EMT\n",
+ "from ase.io.trajectory import TrajectoryWriter\n",
+ "from ase.lattice.cubic import FaceCenteredCubic\n",
+ "from ase.md.velocitydistribution import MaxwellBoltzmannDistribution\n",
+ "from ase.md.langevin import Langevin\n",
+ "from ase.visualize import view\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "hint: Using 'master' as the name for the initial branch. This default branch name\n",
+ "hint: is subject to change. To configure the initial branch name to use in all\n",
+ "hint: of your new repositories, which will suppress this warning, call:\n",
+ "hint: \n",
+ "hint: \tgit config --global init.defaultBranch \n",
+ "hint: \n",
+ "hint: Names commonly chosen instead of 'master' are 'main', 'trunk' and\n",
+ "hint: 'development'. The just-created branch can be renamed via this command:\n",
+ "hint: \n",
+ "hint: \tgit branch -m \n",
+ "Initialized empty Git repository in /tmp/tmpjx247w5h/.git/\n",
+ "Initialized DVC repository.\n",
+ "\n",
+ "You can now commit the changes to git.\n",
+ "\n",
+ "+---------------------------------------------------------------------+\n",
+ "| |\n",
+ "| DVC has enabled anonymous aggregate usage analytics. |\n",
+ "| Read the analytics documentation (and how to opt-out) here: |\n",
+ "| |\n",
+ "| |\n",
+ "+---------------------------------------------------------------------+\n",
+ "\n",
+ "What's next?\n",
+ "------------\n",
+ "- Check out the documentation: \n",
+ "- Get help and share ideas: \n",
+ "- Star us on GitHub: \n"
+ ]
+ }
+ ],
+ "source": [
+ "!git init\n",
+ "!dvc init"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "size = 3\n",
+ "\n",
+ "# Set up a crystal\n",
+ "atoms = FaceCenteredCubic(\n",
+ " directions=[[1, 0, 0], [0, 1, 0], [0, 0, 1]],\n",
+ " symbol='Cu',\n",
+ " size=(size, size, size),\n",
+ " pbc=True\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "True"
+ ]
+ },
+ "execution_count": 4,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "timestep = 5 * units.fs\n",
+ "steps = 100\n",
+ "temperature = 800\n",
+ "traj_path = os.path.join(temp_dir.name, \"trajectory.traj\")\n",
+ "\n",
+ "atoms.calc = EMT()\n",
+ "MaxwellBoltzmannDistribution(atoms, temperature_K=temperature)\n",
+ "\n",
+ "dyn = Langevin(atoms, timestep, temperature_K=temperature, friction=0.002)\n",
+ "\n",
+ "writer = TrajectoryWriter(traj_path, \"w\", atoms=atoms)\n",
+ "dyn.attach(writer, interval=1)\n",
+ "\n",
+ "dyn.run(steps)"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Dataset Analysis"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "This time around, we will explore the dataset a bit before training models on it.\n",
+ "It is often useful to visualize the distribution of labels "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": []
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "ips2",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.10.10"
+ },
+ "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/examples/04_Molecular_Dynamics_Structure_Generation_and_Simulation.ipynb b/examples/04_Molecular_Dynamics_Structure_Generation_and_Simulation.ipynb
new file mode 100644
index 00000000..5fceda42
--- /dev/null
+++ b/examples/04_Molecular_Dynamics_Structure_Generation_and_Simulation.ipynb
@@ -0,0 +1,29 @@
+{
+ "cells": [
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Molecular Dynamics Structure Generation and Simulation"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import ipsuite as ips"
+ ]
+ }
+ ],
+ "metadata": {
+ "language_info": {
+ "name": "python"
+ },
+ "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/examples/05_Labeling_with_Calculators.ipynb b/examples/05_Labeling_with_Calculators.ipynb
new file mode 100644
index 00000000..707d18ca
--- /dev/null
+++ b/examples/05_Labeling_with_Calculators.ipynb
@@ -0,0 +1,29 @@
+{
+ "cells": [
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Labeling with Calculators"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import ipsuite as ips"
+ ]
+ }
+ ],
+ "metadata": {
+ "language_info": {
+ "name": "python"
+ },
+ "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/examples/06_Bootstrapping_Datasets.ipynb b/examples/06_Bootstrapping_Datasets.ipynb
new file mode 100644
index 00000000..fd679462
--- /dev/null
+++ b/examples/06_Bootstrapping_Datasets.ipynb
@@ -0,0 +1,548 @@
+{
+ "cells": [
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Bootstrapping Datasets"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "In previous examples we assumed that there was a pre-existing dataset available for us to use.\n",
+ "This is typically the case when working with literature datasets or if we perform the dataset aquisition with an external (molecular dyamics) program.\n",
+ "\n",
+ "However, in active learning scenarios one typically starts with a single (unlabeled) configuration. In these cases it is often convenient to bootstrap an initial training set in order to quickly obtain a stable force field with which to drive the sampling.\n",
+ "\n",
+ "A full active learning example can be found in a later notebook in this series."
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "This notebook requires packmol for setting up the initial configuration and the xtb. \n",
+ "`xtb-python` and `packmol` are available from conda and can be installed via\n",
+ "\n",
+ "```bash\n",
+ "conda install -c conda-forge xtb-python\n",
+ "conda install -c conda-forge packmol\n",
+ "```"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "2023-05-30 16:18:18,325 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n"
+ ]
+ }
+ ],
+ "source": [
+ "import ipsuite as ips\n",
+ "import znflow\n",
+ "import matplotlib.pyplot as plt\n",
+ "\n",
+ "from zntrack.utils import cwd_temp_dir\n",
+ "\n",
+ "temp_dir = cwd_temp_dir()"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "hint: Using 'master' as the name for the initial branch. This default branch name\n",
+ "hint: is subject to change. To configure the initial branch name to use in all\n",
+ "hint: of your new repositories, which will suppress this warning, call:\n",
+ "hint: \n",
+ "hint: \tgit config --global init.defaultBranch \n",
+ "hint: \n",
+ "hint: Names commonly chosen instead of 'master' are 'main', 'trunk' and\n",
+ "hint: 'development'. The just-created branch can be renamed via this command:\n",
+ "hint: \n",
+ "hint: \tgit branch -m \n",
+ "Initialized empty Git repository in /tmp/tmp8k077isy/.git/\n",
+ "Initialized DVC repository.\n",
+ "\n",
+ "You can now commit the changes to git.\n",
+ "\n",
+ "+---------------------------------------------------------------------+\n",
+ "| |\n",
+ "| DVC has enabled anonymous aggregate usage analytics. |\n",
+ "| Read the analytics documentation (and how to opt-out) here: |\n",
+ "| |\n",
+ "| |\n",
+ "+---------------------------------------------------------------------+\n",
+ "\n",
+ "What's next?\n",
+ "------------\n",
+ "- Check out the documentation: \n",
+ "- Get help and share ideas: \n",
+ "- Star us on GitHub: \n"
+ ]
+ }
+ ],
+ "source": [
+ "!git init\n",
+ "!dvc init"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "We can use packmol to create an initial configuration.\n",
+ "Based on this, it is possible to bootstrap datasets using a combination of various methods.\n",
+ "Each of them is designed to probe a different seet of degrees of freedom.\n",
+ "Random atomic displacements will probe vibrations, while random translations and rotations of molecules, as well as box size scans probe slower degrees of freedom that depend on intermolecular interactions."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "Running DVC command: 'stage add --name SmilesToAtoms --force ...'\n",
+ "Running DVC command: 'stage add --name Packmol --force ...'\n",
+ "Running DVC command: 'stage add --name opt_calc --force ...'\n",
+ "Running DVC command: 'stage add --name ASEGeoOpt --force ...'\n",
+ "Running DVC command: 'stage add --name RattleAtoms --force ...'\n",
+ "Running DVC command: 'stage add --name RotateMolecules --force ...'\n",
+ "Running DVC command: 'stage add --name TranslateMolecules --force ...'\n",
+ "Running DVC command: 'stage add --name label_calc --force ...'\n",
+ "Running DVC command: 'stage add --name BoxScale --force ...'\n",
+ "Running DVC command: 'stage add --name BoxScale_mapping --force ...'\n",
+ "Could not create .gitignore entry in /tmp/tmp8k077isy/nodes/BoxScale_mapping/.gitignore. DVC will attempt to create .gitignore entry again when the stage is run.\n",
+ "Running DVC command: 'stage add --name EnergyHistogram --force ...'\n",
+ "Running DVC command: 'stage add --name ForcesHistogram --force ...'\n",
+ "Running DVC command: 'repro'\n"
+ ]
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "2023-05-30 16:18:20,899 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n",
+ "2023-05-30 16:18:22,115 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n",
+ "2023-05-30 16:18:22,296 (INFO): estimated box size: [6.6946734740471925, 6.6946734740471925, 6.6946734740471925]\n",
+ "\n",
+ "################################################################################\n",
+ "\n",
+ " PACKMOL - Packing optimization for the automated generation of\n",
+ " starting configurations for molecular dynamics simulations.\n",
+ " \n",
+ " Version 20.010 \n",
+ "\n",
+ "################################################################################\n",
+ "\n",
+ " Packmol must be run with: packmol < inputfile.inp \n",
+ "\n",
+ " Userguide at: http://m3g.iqm.unicamp.br/packmol \n",
+ "\n",
+ " Reading input file... (Control-C aborts)\n",
+ " Seed for random number generator: 1234567\n",
+ " Output file: mixture.xyz\n",
+ " Reading coordinate file: 0.xyz\n",
+ " Number of independent structures: 1\n",
+ " The structures are: \n",
+ " Structure 1 :Properties=species:S:1:pos:R:3 pbc=\"F F F\"( 3 atoms)\n",
+ " Maximum number of GENCAN loops for all molecule packing: 200\n",
+ " Total number of restrictions: 1\n",
+ " Distance tolerance: 2.0000000000000000 \n",
+ " Number of molecules of type 1 : 10\n",
+ " Total number of atoms: 30\n",
+ " Total number of molecules: 10\n",
+ " Number of fixed molecules: 0\n",
+ " Number of free molecules: 10\n",
+ " Number of variables: 60\n",
+ " Total number of fixed atoms: 0\n",
+ " Maximum internal distance of type 1 : 1.5660731739637310 \n",
+ " All atoms must be within these coordinates: \n",
+ " x: [ -998.39999999999998 , 1001.6000000000000 ] \n",
+ " y: [ -999.17727845236561 , 1000.8227215476344 ] \n",
+ " z: [ -1000.0000000000000 , 1000.0000000000000 ] \n",
+ " If the system is larger than this, increase the sidemax parameter. \n",
+ "\n",
+ "################################################################################\n",
+ "\n",
+ " Building initial approximation ... \n",
+ "\n",
+ "################################################################################\n",
+ "\n",
+ " Adjusting initial point to fit the constraints \n",
+ "\n",
+ "--------------------------------------------------------------------------------\n",
+ "\n",
+ "--------------------------------------------------------------------------------\n",
+ "\n",
+ " Molecules of type: 1\n",
+ "\n",
+ " Packing:|0 100%|\n",
+ " |*********************\n",
+ "\n",
+ " Restraint-only function value: 4.7908344210240500E-005\n",
+ " Maximum violation of the restraints: 3.3276214373314433E-005\n",
+ "\n",
+ "--------------------------------------------------------------------------------\n",
+ "\n",
+ " Rescaling maximum and minimum coordinates... \n",
+ " Computing size of patches... \n",
+ " Add fixed molecules to permanent arrays... \n",
+ " Reseting center of mass... \n",
+ "\n",
+ "--------------------------------------------------------------------------------\n",
+ "\n",
+ " Setting initial trial coordinates ... \n",
+ "\n",
+ "--------------------------------------------------------------------------------\n",
+ "\n",
+ "--------------------------------------------------------------------------------\n",
+ "\n",
+ " Molecules of type: 1\n",
+ " Adjusting random positions to fit the constraints. \n",
+ " Restraint-only function value: 0.0000000000000000 \n",
+ " Maximum violation of the restraints: 0.0000000000000000 \n",
+ "\n",
+ "################################################################################\n",
+ "\n",
+ " Objective function at initial point: 305.75852348958790 \n",
+ "\n",
+ "################################################################################\n",
+ "\n",
+ " Packing molecules of type: 1\n",
+ "\n",
+ "################################################################################\n",
+ "\n",
+ "\n",
+ "--------------------------------------------------------------------------------\n",
+ "\n",
+ " Starting GENCAN loop: 0\n",
+ " Scaling radii by: 1.1000000000000001 \n",
+ "\n",
+ " Packing:|0 100%|\n",
+ " |***********************************\n",
+ "\n",
+ " Function value from last GENCAN loop: f = .15568E-04\n",
+ " Best function value before: f = .30576E+03\n",
+ " Improvement from best function value: 99.99 %\n",
+ " Improvement from last loop: 99.99 %\n",
+ " Maximum violation of target distance: 0.000000\n",
+ " Maximum violation of the constraints: .15568E-04\n",
+ " Current structure written to file: mixture.xyz\n",
+ "--------------------------------------------------------------------------------\n",
+ " Packing solved for molecules of type 1\n",
+ " Objective function value: 1.5567789525860229E-005\n",
+ " Maximum violation of target distance: 0.0000000000000000 \n",
+ " Max. constraint violation: 1.5567789525860229E-005\n",
+ "--------------------------------------------------------------------------------\n",
+ "\n",
+ "################################################################################\n",
+ "\n",
+ " Packing all molecules together \n",
+ "\n",
+ "################################################################################\n",
+ "\n",
+ "\n",
+ " Initial approximation is a solution. Nothing to do. \n",
+ "\n",
+ " Solution written to file: mixture.xyz\n",
+ "\n",
+ "################################################################################\n",
+ "\n",
+ " Success! \n",
+ " Final objective function value: .31847E-01\n",
+ " Maximum violation of target distance: 0.000000\n",
+ " Maximum violation of the constraints: .15568E-04\n",
+ "\n",
+ "--------------------------------------------------------------------------------\n",
+ "\n",
+ " Please cite this work if Packmol was useful: \n",
+ "\n",
+ " L. Martinez, R. Andrade, E. G. Birgin, J. M. Martinez, \n",
+ " PACKMOL: A package for building initial configurations for\n",
+ " molecular dynamics simulations. \n",
+ " Journal of Computational Chemistry, 30:2157-2164,2009.\n",
+ "\n",
+ "################################################################################\n",
+ "\n",
+ " Running time: 5.92000026E-04 seconds. \n",
+ "\n",
+ "--------------------------------------------------------------------------------\n",
+ "\n",
+ "\n",
+ "2023-05-30 16:18:23,396 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n"
+ ]
+ },
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "100%|██████████| 1/1 [00:00<00:00, 10.92it/s]\n"
+ ]
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "2023-05-30 16:18:24,687 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n",
+ " Step Time Energy fmax\n",
+ "BFGS: 0 16:18:24 -1452.227673 560.1183\n",
+ "BFGS: 1 16:18:25 -1525.179018 73.0175\n",
+ "BFGS: 2 16:18:25 -1541.432084 26.5437\n",
+ "BFGS: 3 16:18:25 -1548.847866 20.9261\n",
+ "BFGS: 4 16:18:25 -1553.041573 21.0507\n",
+ "BFGS: 5 16:18:25 -1557.985665 14.9412\n",
+ "BFGS: 6 16:18:25 -1560.632213 8.3526\n",
+ "BFGS: 7 16:18:25 -1562.409822 5.2405\n",
+ "BFGS: 8 16:18:25 -1563.889836 4.6672\n",
+ "BFGS: 9 16:18:26 -1565.320047 13.2885\n",
+ "BFGS: 10 16:18:26 -1566.448285 3.4639\n",
+ "BFGS: 11 16:18:26 -1567.953756 4.4025\n",
+ "BFGS: 12 16:18:26 -1568.948496 7.1006\n",
+ "BFGS: 13 16:18:26 -1569.550374 4.1206\n",
+ "BFGS: 14 16:18:26 -1570.227879 2.1917\n",
+ "BFGS: 15 16:18:26 -1570.532967 7.2313\n",
+ "BFGS: 16 16:18:26 -1570.847957 2.6559\n",
+ "BFGS: 17 16:18:27 -1571.138681 1.4818\n",
+ "BFGS: 18 16:18:27 -1571.662669 2.2882\n",
+ "BFGS: 19 16:18:27 -1571.800839 1.6854\n",
+ "BFGS: 20 16:18:27 -1571.956670 0.8907\n",
+ "2023-05-30 16:18:28,493 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n",
+ "2023-05-30 16:18:29,693 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n",
+ "2023-05-30 16:18:30,954 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n",
+ "2023-05-30 16:18:31,096 (WARNING): Setting maximum to 2 Pi.\n",
+ "2023-05-30 16:18:32,202 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n",
+ "2023-05-30 16:18:33,349 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n"
+ ]
+ },
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "100%|██████████| 16/16 [00:01<00:00, 8.80it/s]\n"
+ ]
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "2023-05-30 16:18:36,564 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n"
+ ]
+ },
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "Could not load field atoms for node BoxScale_mapping.\n",
+ "100%|███████████████████████████████████| 5/5 [00:00<00:00, 8.29it/s]\n"
+ ]
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "2023-05-30 16:18:38,818 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n",
+ "2023-05-30 16:18:40,299 (DEBUG): Welcome to IPS - the Interatomic Potential Suite!\n"
+ ]
+ }
+ ],
+ "source": [
+ "mapping = ips.geometry.BarycenterMapping(data=None)\n",
+ "\n",
+ "with ips.Project(automatic_node_names=True) as project:\n",
+ " water = ips.configuration_generation.SmilesToAtoms(smiles=\"O\")\n",
+ " packmol = ips.configuration_generation.Packmol(\n",
+ " data=[water.atoms], count=[10], density=997\n",
+ " )\n",
+ "\n",
+ " opt_calc = ips.calculators.xTBSinglePoint(data=packmol, method=\"gfn1-xtb\", name=\"opt_calc\")\n",
+ "\n",
+ " geopt = ips.calculators.ASEGeoOpt(\n",
+ " model=opt_calc,\n",
+ " data=packmol.atoms,\n",
+ " optimizer=\"BFGS\",\n",
+ " run_kwargs={\"fmax\": 1.0},\n",
+ " )\n",
+ "\n",
+ " n_configs = 5\n",
+ " rattle = ips.bootstrap.RattleAtoms(\n",
+ " data=geopt.atoms,\n",
+ " data_id=-1,\n",
+ " n_configurations=n_configs,\n",
+ " maximum=0.08, # Ang max atomic displacement\n",
+ " include_original=True\n",
+ " )\n",
+ " rotate = ips.bootstrap.RotateMolecules(\n",
+ " data=geopt.atoms,\n",
+ " data_id=-1,\n",
+ " n_configurations=n_configs,\n",
+ " maximum=15, # deg max rotation\n",
+ " include_original=False\n",
+ " )\n",
+ " translate = ips.bootstrap.TranslateMolecules(\n",
+ " data=geopt.atoms,\n",
+ " data_id=-1,\n",
+ " n_configurations=n_configs,\n",
+ " maximum=0.3, # Ang max molecular displacement\n",
+ " include_original=False\n",
+ " )\n",
+ "\n",
+ " bootstrap_configurations = rattle.atoms + rotate.atoms + translate.atoms\n",
+ "\n",
+ " labeling_calc = ips.calculators.xTBSinglePoint(data=bootstrap_configurations, method=\"gfn1-xtb\", name=\"label_calc\")\n",
+ " volume_scan = ips.analysis.BoxScale(\n",
+ " data=rattle.atoms,\n",
+ " data_id=0,\n",
+ " model=labeling_calc,\n",
+ " mapping=mapping,\n",
+ " start=0.8,\n",
+ " stop=1.5,\n",
+ " num=5,\n",
+ " )\n",
+ " bootstrap_dataset = znflow.combine([labeling_calc, volume_scan], attribute=\"atoms\")\n",
+ "\n",
+ " energy_hist = ips.analysis.EnergyHistogram(data=bootstrap_dataset, bins=10)\n",
+ " forces_hist = ips.analysis.ForcesHistogram(data=bootstrap_dataset, bins=10)\n",
+ "\n",
+ "project.run()"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Lets inspect the label distribution of our new dataset.\n",
+ "While they produce a plot in the respective `nodes` subdirectory, we will recreate them here to view them from within the notebook.\n",
+ "\n",
+ "In order to do that, we first have to load the histogram nodes.\n",
+ "Then we can create simple histogram with matplotlib.\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "energy_hist.load()\n",
+ "forces_hist.load()"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 6,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "image/png": "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/KK/F154wfkeEhERYdx8883Ghg0bXI5TVVVlPP7440ZsbKwREhJi9OjRw3j66acvem2uv/VoGIbx97//3ejXr58RHBxsXHPNNRf9/dIQi2FchsedAgAANGM8hwoAAMAkAhUAAIBJBCoAAACTCFQAAAAmEagAAABMIlABAACYRKACAAAwiUAFAABgEoEKAADAJAIVAACASQQqAFecm266SRaLpc7XmDFjLvq6cePG6be//W2jj5eVlaWf/vSn9e577733ZLFY9PHHHzd6XQC+g7/lB+CKYhiGwsPDNX36dI0ePdplX2hoqEJDQ+t9nd1uV6dOnbRmzRolJyc36pgrV67Uz3/+c33++efq0qWLy74HHnhAe/fu1Y4dOxrXCACfwhkqAFeUgwcP6syZMxoyZIg6derk8tVQmJKk999/Xy1bttSAAQPq3e9wOJSbm6vu3burVatWSkhI0BtvvCFJ+tnPfqaOHTsqPz/f5TXV1dVatmyZHnzwQY/1B8A7CFQAriglJSUKDAzUdddd16jXrVq1SllZWbJYLPXuz83N1Wuvvab58+frk08+0cSJE3Xfffdp8+bNCgwM1JgxY5Sfn6/vfyiwbNky2e123XvvvaZ6AuB9BCoAV5Rdu3bJbrerffv2zo/4QkND9fDDD1/0dW+99ZaGDx9e775z585p1qxZWrRokTIyMtSjRw+NHTtW9913n/7yl79I+vajvcOHD2vz5s3O1y1evFg///nPFR4e7rkGAXgF11ABuKIMGzZMnTp10rPPPusyHhERoYiIiHpf8+mnn2rAgAGqrKxUSEhInf2ffPKJ+vXrp6uuusplvLa2Vtdff70+/PBDSVJqaqp69uyp1157TYcOHVJcXJw2btyom2++2TPNAfCaQG8XAACX065duzRz5kz16tXrkl+zatUq3XLLLfWGKenba6Ekac2aNbJarS77goODnf/7wQcf1K9+9Svl5eVp8eLF6tmzp2666SY3ugDga/jID8AV48iRIzp16pQSEhIa9bq33npLd9xxR4P74+PjFRwcrOPHj6tXr14uXzExMc55d911lwICArR06VK99tpreuCBBxq8JguAf+EMFYArRklJiSQpKipK5eXlLvsiIyMVEFD3/2OePHlSO3fu1KpVqxpcNywsTJMmTdLEiRPlcDh044036vTp09q2bZvatGmj7OxsSd8+luHuu+/W1KlTVVVVpbFjx3quOQBeRaACcMXYtWuXJCkuLs5lPDg4WFVVVQoKCqrzmr///e9KTk5Whw4dLrr2c889p44dOyo3N1dHjhxR27ZtdcMNN+ipp55ymffggw9q4cKFuu222xQdHW2yIwC+govSAeAihg8frhtvvFGTJ0/2dikAfBjXUAHARdx44408JwrAj+IMFQAAgEmcoQIAADCJQAUAAGASgQoAAMAkAhUAAIBJBCoAAACTCFQAAAAmEagAAABMIlABAACYRKACAAAw6f8DWRp5AQ5+KQgAAAAASUVORK5CYII=",
+ "text/plain": [
+ "