JuliaMolSim · mfherbst · Jan 2, 2023 · Dec 15, 2022 · Dec 16, 2022 · Dec 17, 2022
diff --git a/Project.toml b/Project.toml
@@ -1,10 +1,11 @@
 name = "AtomsBase"
 uuid = "a963bdd2-2df7-4f54-a1ee-49d51e6be12a"
 authors = ["JuliaMolSim community"]
-version = "0.2.4"
+version = "0.2.5"
 
 [deps]
 PeriodicTable = "7b2266bf-644c-5ea3-82d8-af4bbd25a884"
+Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
 UnitfulAtomic = "a7773ee8-282e-5fa2-be4e-bd808c38a91a"

diff --git a/README.md b/README.md
@@ -7,44 +7,43 @@
 [![Build Status](https://github.com/JuliaMolSim/AtomsBase.jl/workflows/CI/badge.svg)](https://github.com/JuliaMolSim/AtomsBase.jl/actions)
 [![Coverage](https://codecov.io/gh/JuliaMolSim/AtomsBase.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaMolSim/AtomsBase.jl)
 
-**AtomsBase is currently in the relatively early stages of development and we very much
-want developer/user input! If you think anything about it should be 
-added/removed/changed, _please_ [file an issue](https://github.com/JuliaMolSim/AtomsBase.jl/issues) or chime into the discussion on an
-existing one! (Look particularly for issues with the [`question` label](https://github.com/JuliaMolSim/AtomsBase.jl/issues?q=is%3Aissue+is%3Aopen+label%3Aquestion))**
-
-AtomsBase is an abstract interface for representation of atomic geometries in Julia. It aims to be a lightweight means of facilitating interoperability between various tools including...
-* chemical simulation engines (e.g. density functional theory, molecular dynamics, etc.)
-* file I/O with standard formats (.cif, .xyz, ...)
-* numerical tools: sampling, integration schemes, etc.
+AtomsBase is an abstract interface for representation of atomic geometries in
+Julia. It aims to be a lightweight means of facilitating interoperability
+between various tools including ...
+
+* Chemical simulation engines:
+    - [DFTK.jl](https://github.com/JuliaMolSim/DFTK.jl) (density-functional theory)
+    - [Molly.jl](https://github.com/JuliaMolSim/Molly.jl) (molecular dynamics)
+* Integration with third party-libraries:
+    - [ASEconvert.jl](https://github.com/mfherbst/ASEconvert.jl) (integration with the Atomistic Simulation Environment)
+* I/O with standard file formats (.cif, .xyz, ...)
+    - E.g. [AtomIO.jl](https://github.com/mfherbst/AtomIO.jl)
 * automatic differentiation and machine learning systems
+    - [ChemistryFeaturization.jl](https://github.com/Chemellia/ChemistryFeaturization.jl)
+      (featurization of atomic systems)
+* numerical tools: sampling, integration schemes, etc.
 * visualization (e.g. plot recipes)
 
-Currently, the design philosophy is to be as lightweight as possible, with only
-a small set of required function dispatches to make adopting the interface into
-existing packages easy. We also provide a couple of
+Currently, the design philosophy is to be as lightweight as possible with a small set
+of required function dispatches to make adopting the interface easy.
+We also provide a couple of
 [standard flexible implementations of the interface](https://juliamolsim.github.io/AtomsBase.jl/stable/atomicsystems/#atomic-systems)
 that we envision to be broadly applicable.
 If features beyond these are required we
 encourage developers to open PRs or provide their own implementations.
-For more on how to use the package, see [the documentation](https://juliamolsim.github.io/AtomsBase.jl/stable).
-
-## Installation
-
-AtomsBase can be installed using the Julia package manager.
-From the Julia REPL, type `]` to enter the Pkg REPL mode and run
-
-```
-pkg> add AtomsBase
-```
+For more on how to use the package,
+see [the documentation](https://juliamolsim.github.io/AtomsBase.jl/stable).
 
-## Packages Using AtomsBase
-The following (not all yet-registered) packages currently make use of this interface (please feel free to send a PR to add to this list!):
+## Packages using AtomsBase
+The following (not all yet-registered) packages currently make use of AtomsBase:
 * [ASEPotential](https://github.com/jrdegreeff/ASEPotential.jl)
+* [ASEconvert](https://github.com/mfherbst/ASEconvert.jl)
 * [AtomIO](https://github.com/mfherbst/AtomIO.jl): I/O for atomic structures, also wraps some ASE functionality
 * [Atomistic](https://github.com/cesmix-mit/Atomistic.jl/tree/263ec97b5f380f1b2ba593bf8feaf36e7f7cff9a): integrated workflow for MD simulations, part of [CESMIX](https://computing.mit.edu/cesmix/)
 * [BFPIS](https://github.com/GDufenshuoo/BFPIS.jl)
 * [ChemistryFeaturization](https://github.com/Chemellia/ChemistryFeaturization.jl): Interface for featurization of atomic structures for input into machine learning models, part of [Chemellia](https://chemellia.org)
 * [DFTK](https://github.com/JuliaMolSim/DFTK.jl): density functional theory simulations
+* [ExtXYZ](https://github.com/libAtoms/ExtXYZ.jl): Parser for extended XYZ files
 * [InteratomicPotentials](https://github.com/cesmix-mit/InteratomicPotentials.jl): implementations of a variety of interatomic potentials, also part of [CESMIX](https://computing.mit.edu/cesmix/)
 * [Molly](https://github.com/JuliaMolSim/Molly.jl): molecular dynamics simulations
 * [Xtals](https://github.com/SimonEnsemble/Xtals.jl): I/O and structure representation for crystals
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,3 +1,5 @@
 [deps]
 AtomsBase = "a963bdd2-2df7-4f54-a1ee-49d51e6be12a"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
+UnitfulAtomic = "a7773ee8-282e-5fa2-be4e-bd808c38a91a"
diff --git a/docs/make.jl b/docs/make.jl
@@ -11,12 +11,13 @@ makedocs(;
     format=Documenter.HTML(;
         prettyurls=get(ENV, "CI", "false") == "true",
         canonical="https://juliamolsim.github.io/AtomsBase.jl",
+        edit_link="master",
         assets=String[],
     ),
     pages=[
         "Home" => "index.md",
+        "tutorial.md",
         "overview.md",
-        "atomicsystems.md",
         "apireference.md"
     ],
     checkdocs=:exports,

diff --git a/docs/src/apireference.md b/docs/src/apireference.md
@@ -1,3 +1,7 @@
+```@meta
+CurrentModule = AtomsBase
+```
+
 # API reference
 
 ## Index
@@ -6,25 +10,35 @@
 Pages = ["apireference.md"]
 ```
 
-## Types
-
+## System properties
 ```@docs
-AbstractSystem{D}
+boundary_conditions
+bounding_box
+chemical_formula
+isinfinite
+n_dimensions
+periodicity
+species_type
 ```
 
-## Functions
+## Species / atom properties
 
 ```@docs
 atomic_mass
 atomic_number
 atomic_symbol
-chemical_formula
-boundary_conditions
-bounding_box
-element
-n_dimensions
-periodicity
-species_type
 velocity
 position
+element
+```
+
+## Atom and system constructors
+
+```@docs
+Atom
+FlexibleSystem
+AbstractSystem
+atomic_system
+isolated_system
+periodic_system
 ```
diff --git a/docs/src/atomicsystems.md b/docs/src/atomicsystems.md
diff --git a/docs/src/overview.md b/docs/src/overview.md
@@ -47,7 +47,7 @@ position(sys, i) # position of `i`th particle in `sys`
 Currently, this syntax only supports linear indexing.
 
 To simplify working with `AtomsBase`, default implementations for systems
-composed of atoms are provided (see [Atomic systems](@ref atomic-systems)).
+composed of atoms are provided (see [Tutorial](@ref)).
 
 ## Struct-of-Arrays vs. Array-of-Structs
 The "struct-of-arrays" (SoA) vs. "array-of-structs" (AoS) is a common design
@@ -66,9 +66,33 @@ positions, then index into it for a single particle). The beauty of an abstract
 interface in Julia is that these details can be, in large part, abstracted away
 through method dispatch such that the end user sees the same expected behavior
 irrespective of how things are implemented "under the hood".
-For concrete implementations see the section on [atomic systems](@ref atomic-systems).
 
 ## Boundary Conditions
 Finally, we include support for defining boundary conditions. Currently
 included are `Periodic` and `DirichletZero`. There should be one boundary
 condition specified for each spatial dimension represented.
+
+## Atomic system
+Since we anticipate atomic systems to be a commonly needed representation,
+`AtomsBase` provides two flexible implementations for this setting.
+One implementation follows the struct-of-arrays approach introducing the `AtomView`
+type to conveniently expose atomic data.
+The more flexible implementation is based on an array-of-structs approach
+and can be easily customised, e.g. by adding custom properties or by swapping
+the underlying `Atom` struct by a custom one.
+In both cases the respective datastructures can be used either fully
+or in parts in downstream packages and we hope these to develop into universally
+useful types within the Julia ecosystem over time.
+
+### Struct of Arrays / FastSystem
+The file [src/fast_system.jl](https://github.com/JuliaMolSim/AtomsBase.jl/blob/master/src/fast_system.jl) contains an implementation of
+AtomsBase based on the struct-of-arrays approach. All species data is stored
+as plain arrays, but for convenience indexing of individual atoms is supported
+by a light-weight `AtomView`. See the implementation files
+as well as the tests for how these can be used.
+
+### Atoms and FlexibleSystem
+A flexible implementation of the interface is provided by the
+`FlexibleSystem` and the `Atom` structs
+for representing atomic systems.
+These are discussed in detail in [Tutorial](@ref).