From b39d306ac8a207d09533a9d1322119a9ff773577 Mon Sep 17 00:00:00 2001
From: Christoph Ortner <christohortner@gmail.com>
Date: Mon, 9 Sep 2024 21:33:01 -0700
Subject: [PATCH] shell tutorial

---
 docs/make.jl                    |  1 +
 docs/src/tutorials/scripting.md | 43 +++++++++++++++++++++++++++++++++
 test/runtests.jl                |  2 +-
 3 files changed, 45 insertions(+), 1 deletion(-)
 create mode 100644 docs/src/tutorials/scripting.md

diff --git a/docs/make.jl b/docs/make.jl
index 9594489a..74554daf 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -69,6 +69,7 @@ makedocs(;
                 "literate_tutorials/basic_julia_workflow.md",
                 "literate_tutorials/smoothness_priors.md",
                 "literate_tutorials/dataset_analysis.md",
+                "tutorials/scripting.md", 
                 # "tutorials/lammps.md",
                 # "tutorials/python_ase.md",
                 # "tutorials/molly.md",
diff --git a/docs/src/tutorials/scripting.md b/docs/src/tutorials/scripting.md
new file mode 100644
index 00000000..2ac0f925
--- /dev/null
+++ b/docs/src/tutorials/scripting.md
@@ -0,0 +1,43 @@
+
+# Basic Shell Workflow
+
+This short introduces a basic workflow where models are specified via 
+JSON files and model fitting is achieved via a shell script. 
+
+At the start of a new project we 
+- create a project folder 
+- activate a Julia project in that folder 
+- add `ACEpotentials` to the Julia project 
+
+```shell 
+mkdir myace
+cd myace
+julia --project=. -e 'using Pkg; Pkg.add("ACEpotentials")'
+```
+
+Next we can use an `ACEpotentials` utility to copy a script for running 
+the model fitting, and an example model specification file. 
+
+```shell 
+julia --project=. -e 'using ACEpotentials; ACEpotentials.copy_runfit(@__DIR__())' 
+```
+
+This should create two new files in the `myace` folder: 
+- `runfit.jl`
+- `example_params.json`
+Copy (or move) the `example_params.json` file to a new filename, e.g. 
+
+```shell 
+cp example_params.json myace_params_1.json
+```
+
+then edit that file to specify the model hyperparameters, 
+the fitting method, and the path to the dataset (or, datasets if validation 
+and or test sets are also provided). To produce a fit, use 
+
+```shell 
+julia --project=. runfit.jl -p myace_params_1.json
+```
+
+This will produce an output file e.g. `results.jl` (the output filename can be changed in the input json), which contains the model specification, the fitted model parameters, and a dictionary of computed errors (rmse, mae). 
+
diff --git a/test/runtests.jl b/test/runtests.jl
index 240ab505..a76abeca 100644
--- a/test/runtests.jl
+++ b/test/runtests.jl
@@ -2,7 +2,7 @@ using ACEpotentials, Test, LazyArtifacts
 
 @testset "ACEpotentials.jl" begin
 
-    # @testset "Models" begin include("models/test_models.jl") end 
+    @testset "Models" begin include("models/test_models.jl") end 
 
     # fitting tests 
     @testset "Test silicon" begin include("test_silicon.jl") end