finish examples and docs

docs/src/tutorials/basic_julia_workflow.jl

@@ -85,3 +85,20 @@ end
 
 # Finally, we delete the model to clean up.
 rm("TiAl_model.json")
+
+# ### Fast Evaluator 
+#
+# `ACEpotentials.jl` provides an experimental "fast evaluator". This tries to 
+# merge some of the operations in the full model resulting in a "slimmer" and 
+# usually faster evaluator. In some cases the performance gain can be multiple 
+# factors up to an order of magnitude. This is particularly important when 
+# using a parameter estimation solver that sparsifies. In that case, the 
+# performance gain can be significant. 
+#
+# To construct the fast evaluator, simply use 
+# ```julia 
+# fpot = fast_evaluator(model)
+# ```
+# An optional keyword argument `aa_static = true` can be used to optimize the 
+# n-correlation layer for very small models (at most a few hundred parameters). 
+# For larger models this leads to a stack overflow.

examples/zuobench/zuo_asp.jl

@@ -50,7 +50,7 @@ model_100  = set_parameters!( deepcopy(model),
                   ACEfit.asp_select(asp_result, (:bysize, 100))[1])
 
 # generate sparsified, faster evaluators 
-pot_1000 = fast_evaluator(model_1000; aa_static = true)
+pot_1000 = fast_evaluator(model_1000; aa_static = false) # static can cause stack overflow
 pot_300 = fast_evaluator(model_300; aa_static = true)
 pot_100 = fast_evaluator(model_100; aa_static = true)
 

src/models/fasteval.jl

@@ -76,6 +76,22 @@ function FastACEInner(model::ACEPotential{<: ACEModel}, iz;
    return FastACEinner(rbasis, ybasis, a_basis, aadot)   
 end   
 
+"""
+      fast_evaluator(model; aa_static = :auto)
+
+Constructs an experimental "fast evaluator" for a fitted model, which merges 
+some operations resulting in a "slimmer" and usually faster evaluator. 
+In some cases the performance gain can be significant, especially when the 
+fitted parameters are sparse.
+
+To construct the fast evaluator, 
+```julia 
+fpot = fast_evaluator(model)
+```
+An optional keyword argument `aa_static = true` can be used to enforce 
+optimizing the n-correlation layer for very small models (at most a few 
+hundred parameters). For larger models this results in a stack overflow.
+"""
 function fast_evaluator(model::ACEPotential{<: ACEModel}; 
                         aa_static = :auto)
    if aa_static == :auto 

test/test_fast.jl

@@ -71,7 +71,7 @@ tolerance = 1e-10
 rattle = 0.1 
 
 for ntest = 1:20
-   local at 
+   local at, efv1, efv2, efv3  
    at = bulk(:Si, cubic=true) * 2 
    rattle!(at, rattle)
    efv1 = energy_forces_virial(at, model) 
@@ -132,7 +132,7 @@ tolerance = 1e-12
 rattle = 0.01 
 
 for ntest = 1:20
-   local sys 
+   local sys, efv1, efv2, efv3 
    sys = rattle!(bulk(:Al, cubic=true) * 2, 0.1)
    randz!(sys, [:Ti => 0.5, :Al => 0.5])
 

test/test_io.jl

@@ -17,6 +17,7 @@ ACEpotentials.save_model(model, fname; model_spec = model_spec)
 model1, meta = ACEpotentials.load_model(fname)
 
 for ntest = 1:10 
+    local sys 
     sys = rattle!(bulk(:Al, cubic=true) * 2, 0.1) 
     sys = randz!(sys, [:Ti => 0.5, :Al => 0.5]) 
     print_tf( @test potential_energy(sys, model) ≈ potential_energy(sys, model1) )