From b465b83e66d911209b2244016b3550c0628e195c Mon Sep 17 00:00:00 2001
From: Valentin Churavy <vchuravy@users.noreply.github.com>
Date: Mon, 24 Jun 2024 20:06:00 -0400
Subject: [PATCH] Update examples and docs (#47)

---
 Project.toml          |  2 +-
 examples/lj_forces.jl | 37 +++++++++++++++++++++++--------------
 examples/snap.jl      | 37 ++++++++++++++++++-------------------
 src/LAMMPS.jl         | 25 ++++++++++++++++++++++---
 4 files changed, 64 insertions(+), 37 deletions(-)

diff --git a/Project.toml b/Project.toml
index cdca237..4eba013 100644
--- a/Project.toml
+++ b/Project.toml
@@ -1,7 +1,7 @@
 name = "LAMMPS"
 uuid = "ee2e13b9-eee9-4449-aafa-cfa6a2dbe14d"
 authors = ["Valentin Churavy <v.churavy@gmail.com>"]
-version = "0.4.0"
+version = "0.4.1"
 
 [deps]
 CEnum = "fa961155-64e5-5f13-b03f-caf6b980ea82"
diff --git a/examples/lj_forces.jl b/examples/lj_forces.jl
index f23578d..63c0dd6 100644
--- a/examples/lj_forces.jl
+++ b/examples/lj_forces.jl
@@ -1,31 +1,40 @@
 using LAMMPS
 
 lmp = LMP()
-command(lmp, "units lj")
-command(lmp, "atom_style atomic")
-command(lmp, "atom_modify map array sort 0 0")
-command(lmp, "box tilt large")
+
+command(lmp, """
+    units lj
+    atom_style atomic
+    atom_modify map array sort 0 0
+    box tilt large
+""")
 
 # Setup box
 x_hi = 10.0
 y_hi = 10.0
 z_hi = 10.0
-command(lmp, "boundary p p p")
-command(lmp, "region cell block 0 $x_hi 0 $y_hi 0 $z_hi units box")
-command(lmp, "create_box 1 cell")
+command(lmp, """
+    boundary p p p
+    region cell block 0 $x_hi 0 $y_hi 0 $z_hi units box
+    create_box 1 cell
+""")
 
 # Setup style
-command(lmp, "pair_style lj/cut 2.5")
-command(lmp, "pair_coeff * * 1 1") # TODO
+command(lmp, """
+    pair_style lj/cut 2.5
+    pair_coeff * * 1 1
+""")
 
 # Setup atoms
 natoms = 10
-command(lmp, "create_atoms 1 random $natoms 1 NULL")
-command(lmp, "mass 1 1.0")
+command(lmp, """
+    create_atoms 1 random $natoms 1 NULL
+    mass 1 1.0
+""")
 
 # (x,y,z), natoms
 positions = rand(3, 10) .* 5
-LAMMPS.API.lammps_scatter_atoms(lmp, "x", 1, 3, positions)
+scatter!(lmp, "x", positions)
 
 # Compute pot_e
 command(lmp, "compute pot_e all pe")
@@ -33,5 +42,5 @@ command(lmp, "compute pot_e all pe")
 command(lmp, "run 0")
 
 # extract output
-forces = extract_atom(lmp, "f")
-energies = extract_compute(lmp, "pot_e", LAMMPS.API.LMP_STYLE_GLOBAL, LAMMPS.API.LMP_TYPE_SCALAR)
+forces = gather(lmp, "f")
+energies = gather(lmp, "pot_e")
diff --git a/examples/snap.jl b/examples/snap.jl
index fdb2d95..ef94ba9 100644
--- a/examples/snap.jl
+++ b/examples/snap.jl
@@ -21,27 +21,26 @@ using LAMMPS
 const DATA = joinpath(dirname(pathof(LAMMPS)), "..", "examples", "example_GaN_data")
 
 function run_snap(lmp, path, rcut, twojmax)
-    read_data_str = "read_data " * path
-
-    command(lmp, "log none")
-    command(lmp, "units metal")
-    command(lmp, "boundary p p p")
-    command(lmp, "atom_style atomic")
-    command(lmp, "atom_modify map array")
-    command(lmp, read_data_str)
-    command(lmp, "pair_style zero $rcut")
-    command(lmp, "pair_coeff * *")
-    command(lmp, "compute PE all pe")
-    command(lmp, "compute S all pressure thermo_temp")
-    command(lmp, "compute SNA all sna/atom $rcut 0.99363 $twojmax 0.5 0.5 1.0 0.5 rmin0 0.0 bzeroflag 0 quadraticflag 0 switchflag 1")
-    command(lmp, "compute SNAD all snad/atom $rcut 0.99363 $twojmax 0.5 0.5 1.0 0.5 rmin0 0.0 bzeroflag 0 quadraticflag 0 switchflag 1")
-    command(lmp, "compute SNAV all snav/atom $rcut 0.99363 $twojmax 0.5 0.5 1.0 0.5 rmin0 0.0 bzeroflag 0 quadraticflag 0 switchflag 1")
-    command(lmp, "thermo_style custom pe")
-    command(lmp, "run 0")
+    command(lmp, """
+        log none
+        units metal
+        boundary p p p
+        atom_style atomic
+        atom_modify map array
+        read_data $path
+        pair_style zero $rcut
+        pair_coeff * *
+        compute PE all pe
+        compute S all pressure thermo_temp
+        compute SNA all sna/atom $rcut 0.99363 $twojmax 0.5 0.5 1.0 0.5 rmin0 0.0 bzeroflag 0 quadraticflag 0 switchflag 1
+        compute SNAD all snad/atom $rcut 0.99363 $twojmax 0.5 0.5 1.0 0.5 rmin0 0.0 bzeroflag 0 quadraticflag 0 switchflag 1
+        compute SNAV all snav/atom $rcut 0.99363 $twojmax 0.5 0.5 1.0 0.5 rmin0 0.0 bzeroflag 0 quadraticflag 0 switchflag 1
+        thermo_style custom pe
+        run 0
+    """)
 
     ## Extract bispectrum
-    bs = extract_compute(lmp, "SNA", LAMMPS.API.LMP_STYLE_ATOM,
-                                     LAMMPS.API.LMP_TYPE_ARRAY)
+    bs = gather(lmp, "SNA", Float64)
     return bs
 end
 
diff --git a/src/LAMMPS.jl b/src/LAMMPS.jl
index 2a97aef..d9d3661 100644
--- a/src/LAMMPS.jl
+++ b/src/LAMMPS.jl
@@ -136,9 +136,28 @@ After this processing the string is handed to LAMMPS for parsing and executing.
 
 Arrays of Strings get concatenated into a single String inserting newline characters as needed.
 
-!!! warning "Newline Characters"
-    Old versions of this package (0.4.0 or older) used to ignore newline characters,
-    such that `cmd` would allways be treated as a single command. In newer version this is no longer the case.
+!!! compat "LAMMPS.jl 0.4.1"
+    Multiline string support `\"""` and support for array of strings was added.
+    Prior versions of LAMMPS.jl ignore newline characters.
+
+# Examples
+
+```
+LMP(["-screen", "none"]) do lmp
+    command(lmp, \"""
+        atom_modify map yes
+        region cell block 0 2 0 2 0 2
+        create_box 1 cell
+        lattice sc 1
+        create_atoms 1 region cell
+        mass 1 1
+
+        group a id 1 2 3 5 8
+        group even id 2 4 6 8
+        group odd id 1 3 5 7
+    \""")
+end
+```
 """
 function command(lmp::LMP, cmd::Union{String, Array{String}})
     if cmd isa String