Merge pull request #252 from ACEsuit/co/descrip

Docs update

docs/make.jl

@@ -25,8 +25,8 @@ Literate.markdown(_tutorial_src * "/smoothness_priors.jl",
 Literate.markdown(_tutorial_src * "/dataset_analysis.jl", 
                   _tutorial_out; documenter = true)
 
-# Literate.markdown(_tutorial_src * "/descriptor.jl",
-#                   _tutorial_out; documenter = true)
+Literate.markdown(_tutorial_src * "/descriptor.jl",
+                  _tutorial_out; documenter = true)
 
 
 # Literate.markdown(_tutorial_src * "/first_example_model.jl", 
@@ -70,10 +70,10 @@ makedocs(;
                 "literate_tutorials/smoothness_priors.md",
                 "literate_tutorials/dataset_analysis.md",
                 "tutorials/scripting.md", 
+                "literate_tutorials/descriptor.md",
                 # "tutorials/lammps.md",
                 # "tutorials/python_ase.md",
                 # "tutorials/molly.md",
-                # "literate_tutorials/descriptor.md",
                 # "literate_tutorials/committee.md",
                 # "tutorials/AtomsBase_interface.md",
                 # "literate_tutorials/experimental.md",

docs/src/gettingstarted/saving-and-loading.md

@@ -1,55 +1,48 @@
 # Saving and Loading Potentials
 
 !!! warning 
-    Saving and loading potentials is currently not automated; the 
-    following documentation is out of date. 
+    Saving and loading potentials is currently only supported for the 
+    a workflow that uses JSON / dictionaries to specify models. For anything 
+    "too creative" the user is responsible for ensuring reproducability. 
 
+### General Principles 
 
+Loading a saved potentials is only guaranteed if the Julia environment 
+remains the same. A new project should therefore always work with a specified 
+`Project.toml` and `Manifest.toml`. See [out Pkg intro](pkg.md) for a brief 
+introduction and references to further details. 
 
-## Saving Potentials for Julia use
+If the manifest changes, but the ACEpotentials version remains the same or 
+a backward compatible update (cf semver) then in principle a saved potential 
+should remain loadable. We cannot guarntee this but would consider it a bug 
+if this is not the case.
 
-To save potentials for future Julia use can use
+Normally, we save the entire Julia environment together with a fitted 
+potential. This way it should always be possible to reconstruct the 
+environment and hence the potential. More details follow. 
 
-```julia
-save_potential("my-potential-file.json", potential)
-```
-
-This will save the potential in `json` format. You can also use `yml` and `yace` suffixes.
 
-The format used for saving can be either ACEmodel from `acemodel` function, `JuLIP` style potentials or `ACEmd` style `ACEpotential`.
+### Saving JSON-specified potentials
 
-## Loading Potentials
+If using the `runfit.jl` script, then an output folder is specified, where 
+all information including the full model specification and model parameters 
+are stored as a JSON file (together with other meta-information). 
 
-To load potential use
+### Loading a JSON-specified potential
 
+Suppose the result of `runfit.jl` (or an analogous approach) is saved to 
+`path/result.json`. If the original or a compatible Julia environment is 
+activated, then 
 ```julia
-potential = load_potential("my-potential-file.json")
-```
-
-By default this should print information about version in use when the potential was saved. E.g. like following
-
-```txt
-This potential was saved with following versions:
-
-JuLIP v0.14.5
-ACEbase v0.4.3
-ACE1x v0.1.8
-ACE1 v0.11.16
-ACEmd v0.1.7
-ACEpotentials v0.6.3
-ACEfit v0.1.4
-
-If you have problems using this potential, pin your installation to above versions.
+model = ACEpotentials.load_model("path/result.json")
 ```
+will return a `model::ACEPotential` structure that should be equivalent 
+to the original fitted potential. 
 
-If you have problems with the potential, you can use the given version numbers to build an installation that should have the potential working.
-
-By default the loaded potential is in JuLIP style format. To load a new `ACEmd` style `ACEpotential` you can give keyword `new_format=true`
-
-```julia
-potential = load_potential("my-potential-file.json"; new_format=true)
-```
+### Recovering the Julia environment 
 
-## Exporting Potentials for Other Programs
+At the moment, this process is not implemented, but the `result.json` file
+can loaded into a dictionary which can then be investigated to manually 
+reconstruct the environment and then load the potential as described in 
+the previous section. 
 
-LAMMPS export is described in section [ACEpotentials potentials in LAMMPS](@ref).

docs/src/tutorials/descriptor.jl

@@ -12,24 +12,24 @@ dataset, _, _ = ACEpotentials.example_dataset("Si_tiny");
 
 # An ACE basis specifies a vector of invariant features of atomic environments and can therefore be used as a general descriptor.
 
-basis = ACE1x.ace_basis(elements = [:Si],
-                        rcut = 5.5,
-                        order = 3,        # body-order - 1
-                        totaldegree = 8);
+model = ace1_model(elements = [:Si],
+                rcut = 5.5,
+                order = 3,        # body-order - 1
+                totaldegree = 8);
 
 # Compute an averaged structural descriptor for each configuration.
 
 descriptors = []
 config_types = []
-for atoms in dataset
-    struct_descriptor = sum(site_descriptors(basis, atoms)) / length(atoms)
-    push!(descriptors, struct_descriptor)
-    push!(config_types, atoms.data["config_type"].data)
+for sys in dataset
+    sys_descriptor = sum(site_descriptors(sys, model)) / length(sys)
+    push!(descriptors, sys_descriptor)
+    push!(config_types, sys[:config_type])
 end
 
 # Finally, extract the descriptor principal components and plot. Note the segregation by configuration type.
 
-descriptors = hcat(descriptors...)
+descriptors = reduce(hcat, descriptors)
 M = fit(PCA, descriptors; maxoutdim=3, pratio=1)
 descriptors_trans = transform(M, descriptors)
 p = scatter(
@@ -39,15 +39,14 @@ plot!(p, xlabel="PC1", ylabel="PC2", zlabel="PC3", camera=(20,10))
 
 
 # The basis used above uses defaults that are suitable for regression of a potential energy surface, but other defaults might be better when using the ACE descriptor for other tasks such as classification. The following short script shows how to make some changes of this kind: 
-
-model = acemodel(elements = [:Si,], order = 3, totaldegree = 10,
-       pair_transform = (:agnesi, 1, 4, 0.0),
-       pair_envelope = (:x, 0, 2),
-       transform = (:agnesi, 1, 4, 0.0),
-       envelope = (:x, 0, 2),
-       r0 = :bondlen, # default, could specify explicitly
-       )
-basis = model.basis       
-
-# - `[pair_]transfor = (:agnesi, 1, 4, 0.0)` : this generates a transform that behaves as t' ~ r^3 near zero and t' ~ r^-2 near the cutoff, but then actually enforces t' = 0 at the cutoff. 
+# ```julia
+# model = ace1_model(elements = [:Si,], order = 3, totaldegree = 10,
+#        pair_transform = (:agnesi, 1, 4),
+#        pair_envelope = (:x, 0, 2),
+#        transform = (:agnesi, 1, 4),
+#        envelope = (:x, 0, 2),
+#        r0 = :bondlen, # default, could specify explicitly
+#        )
+# ```     
+# - `[pair_]transform = (:agnesi, 1, 4)` : this generates a transform that behaves as t' ~ r^3 near zero and t' ~ r^-2 near the cutoff
 # - `[pair_]envelope = (:x, 0, 2)` : this generates an envelope that is ~ (x - xcut)^2 at the cutoff and just ~ 1 for r -> 0. 

docs/src/tutorials/index.md

@@ -2,9 +2,11 @@
 # Tutorials Overview
 
 * [Basic Julia Workflow](../literate_tutorials/basic_julia_workflow.md) : minimal example to fit a potential to an existing dataset using a Julia script 
+* [Basic Shell Workflow](scripting.md) : basic workflow for fitting via the command line
 * [Smoothness Priors](../literate_tutorials/smoothness_priors.md) : brief introduction to smoothness priors
 * [Basic Dataset Analysis](../literate_tutorials/dataset_analysis.md) : basic techniques to visualize training datasets and correlate such observations to the choice of geometric priors
-* [Basic Shell Workflow](scripting.md) : basic workflow for fitting via the command line
+* [Descriptors](../literate_tutorials/descriptor.md) : `ACEpotentials` can be used as descriptors of atomic environments or structures, which is described here. 
+
 
 ```@raw html
 <!-- ### Using `ACEpotentials` Potentials in External Software