Chemellia · DhairyaLGandhi · Jul 4, 2021 · Jul 7, 2021 · Jul 8, 2021 · Jul 9, 2021
diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml
@@ -14,7 +14,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: julia-actions/setup-julia@latest
         with:
-          version: '1.4'
+          version: '1.6'
       - name: Install dependencies
         env:
           PYTHON: ""

diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "ChemistryFeaturization"
 uuid = "6c925690-434a-421d-aea7-51398c5b007a"
 authors = ["Rachel Kurchin <rkurchin@cmu.edu>", "Anant Thazhemadam <anant.thazhemadam@gmail.com>", "Sean Sun"]
-version = "0.4.2"
+version = "0.5.0"
 
 [deps]
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
@@ -15,9 +15,13 @@ GraphPlot = "a2cc645c-3eea-5389-862e-a155d0052231"
 JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 LightGraphs = "093fc24a-ae57-5d10-9952-331d41423f4d"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+NearestNeighbors = "b8a86587-4115-5ab1-83bc-aa920d37bbce"
 PyCall = "438e738f-606a-5dbb-bf0a-cddfbfd45ab0"
 Serialization = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
 SimpleWeightedGraphs = "47aef6b3-ad0c-573a-a1e2-d07658019622"
+SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
+Xtals = "ede5f01d-793e-4c47-9885-c447d1f18d6d"
+Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
 
 [compat]
 CSV = "0.7, 0.8"
@@ -30,12 +34,16 @@ Flux = "0.11, 0.12"
 GraphPlot = "0.4.4"
 JSON = "0.21"
 LightGraphs = "1"
+NearestNeighbors = "0.4"
 PyCall = "1"
 SimpleWeightedGraphs = "1"
-julia = "1.4, 1.5, 1.6"
+Xtals = "0.3"
+julia = "1.6"
 
 [extras]
+FiniteDifferences = "26cc04aa-876d-5657-8c51-4c34ba976000"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
 
 [targets]
-test = ["Test"]
+test = ["FiniteDifferences", "Test", "Zygote"]
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # ChemistryFeaturization.jl
-![Run tests](https://github.com/chemellia/ChemistryFeaturization.jl/workflows/Run%20tests/badge.svg)[![codecov](https://codecov.io/gh/chemellia/ChemistryFeaturization.jl/branch/main/graph/badge.svg?token=C0Fdt8BGnr)](https://codecov.io/gh/chemellia/ChemistryFeaturization.jl)[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://chemellia.github.io/ChemistryFeaturization.jl/stable/)
-[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://chemellia.github.io/ChemistryFeaturization.jl/dev/)
+![Run tests](https://github.com/chemellia/ChemistryFeaturization.jl/workflows/Run%20tests/badge.svg) [![codecov](https://codecov.io/gh/chemellia/ChemistryFeaturization.jl/branch/main/graph/badge.svg?token=C0Fdt8BGnr)](https://codecov.io/gh/chemellia/ChemistryFeaturization.jl)  [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://chemistryfeaturization.chemellia.org/stable/)
+ [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://chemistryfeaturization.chemellia.org/dev/)
 
 Flexible, modular, invertible featurization for Chemellia models including AtomicGraphnets.jl and WeaveModel.jl.
 

diff --git a/data/pymatgen_atom_data.csv b/data/pymatgen_atom_data.csv
diff --git a/data/tabulate_pmg_data.py b/data/tabulate_pmg_data.py
@@ -71,14 +71,16 @@
 groups = []
 valences = []
 blocks = []
+electronic_structure = []
 for row in df.iterrows():
     sym = row[1]['Symbol']
     el = pt.Element(sym)
     rows.append(el.row)
     groups.append(el.group)
     blocks.append(el.block)
+    electronic_structure.append(el.electronic_structure)
     try:
-        v = valence(el)[1]
+        v = el.valence[1]
     except ValueError: #ambiguous valence
         v = np.nan
     valences.append(v)
@@ -87,6 +89,7 @@
 df['Group'] = groups
 df['Valence'] = valences
 df['Block'] = blocks
+df['Electronic Structure'] = electronic_structure
 
 df.to_csv("pymatgen_atom_data.csv")
 

diff --git a/docs/make.jl b/docs/make.jl
@@ -8,12 +8,13 @@ makedocs(
         "Terminology"=>"terminology.md",
         "Tutorial"=>"tutorial.md",
         "Types"=>Any[
+            "Overview"=>"types/overview.md",
             "Abstract Types"=>"types/abstracttypes.md",
             "Atoms Objects"=>"types/atoms.md",
             "Feature Descriptors"=>"types/feature_descriptors.md",
+            "Codec"=>"types/codecs.md",
             "Featurization"=>"types/featurizations.md",
             "Featurized Atoms"=>"types/featurizedatoms.md",
-            "Codec"=>"types/codecs.md",
         ],
         "Utilities"=>"utils.md",
         "Contributing"=>"contributing.md",
@@ -31,7 +32,6 @@ deploydocs(
     repo = "github.com/Chemellia/ChemistryFeaturization.jl.git",
     target = "build",
     devbranch = "main",
-    versions = ["stable" => "v^", "v#.#"],
     branch = "gh-pages",
 )
 

diff --git a/docs/src/changelog.md b/docs/src/changelog.md
@@ -5,14 +5,29 @@ I'm generally trying to adhere to [semver](https://semver.org) here. This means
 Categories to include for each release, if relevant: breaking, added, fixed, removed/deprecated
 
 ## Upcoming
+
+## v0.5.0 [2021-09-07]
+
 ### Added
+
+* Add new `FeatureDescriptor` - `OrbitalFeatureDescriptor`
+* Add new module `OrbitalFeatureUtils` which provides utility functions used by `OrbitalFeatureDescriptor`
+* Add new simple `Codec` - `SimpleCodec`
+* Add a new function - `elements`, which prints the elements in an `Atoms` object
+* Make `output_shape` generic
+* Add a new module - `Data` which encapsulates all the data and tables required by the package.
 * add pretty printing for `GraphNodeFeaturization`, `FeaturizedAtoms`, uniformize spacing via `\t` across these and `AtomGraph`
 * [logic] move `data/` directory to root of repo
 * [logic] move `build_onehot_vec` to `OneHotOneCold`
+* replaced Python ASE dependency with Xtals.jl, allowing AD through graph-building! Can now also pass a Crystal object for graph-building
 
 ### Fixed
+
 * export `featurize` and `decode` properly for `FeaturizedAtoms`
 
+### Removed/Deprecated
+* ASE deprecation removes compatibility with reading some file formats that ASE supports but Xtals does not
+
 ## v0.4.2 [2021-07-02]
 ### Added
 * export `featurize` and `decode` functions at top-level module

diff --git a/docs/src/contributing.md b/docs/src/contributing.md
@@ -10,7 +10,7 @@ Pages = ["contributing.md"]
 
 For some high-level general guidance, please see [CONTRIBUTING.md](https://github.com/Chemellia/ChemistryFeaturization.jl/blob/main/CONTRIBUTING.md) on the GitHub repo.
 
-The remainder of this page includes some pointers about package structure, etc. that could be helpful depending on what sorts of functionality you're interested in adding to the package. An understanding of "what goes where" will help in making sure you put your code in the right place! We also strongly encourage you to read the [Terminology/Philosophy](@ref) page, as it will help to understand the best ways to add different types of functionality.
+The remainder of this page includes some pointers about package structure, etc. that could be helpful depending on what sorts of functionality you're interested in adding to the package. An understanding of "what goes where" will help in making sure you put your code in the right place! We also strongly encourage you to read the [Terminology and Philosophy](@ref) page, as it will help to understand the best ways to add different types of functionality.
 
 TODO: flesh out everything below
 

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -14,4 +14,4 @@ It provides flexible, modular data types and functions for starting from a "bare
 
 ![CF_flowchart](files/flowchart.png)
 
-To learn more about the package, it would be good to start with the [Terminology/Philosophy](@ref) section to get a handle on the vocabulary as we use it, and also some insights about the design philosophy behind the package. Then go ahead and browse the sidebar for more!
+To learn more about the package, it would be good to start with the [Terminology and Philosophy](@ref) section to get a handle on the vocabulary as we use it, and also some insights about the design philosophy behind the package. Then go ahead and browse the sidebar for more!
diff --git a/docs/src/terminology.md b/docs/src/terminology.md
@@ -1,4 +1,4 @@
-# Terminology/Philosophy
+# Terminology and Philosophy
 
 There are a lot of seemingly similar terms used for quantities in this package that refer to disparate things (or, are used slightly differently by other people in other places). Here, we try to best define these terms as we intend them. Further down, once the terms are defined, we elaborate on why the package is designed the way it is.
 
@@ -11,39 +11,24 @@ Depth = 3
 
 ### Feature
 
-A quality or quantity associated with an atom that we wish to encode, such as atomic mass, row in the periodic table, etc.
+A quality or a quantity that is associated with an atom, which is of interest to us.\
+A feature could be a property of an individual atom, such as its atomic mass or the row in the periodic table to which it belongs; or it could be a property of a pair of atoms (e.g. distance between them, presence of a bond), or even a fingerprint of an entire structure.
 
 ### Encoding
 
-The process of translating the value of a feature from its human-readable form (such as a float or a string) to whatever form will be ingested by a machine learning model. This could be as simple as an equality operation, but more often is, e.g. building a one-hot vector.
+The process of translating the value of a feature from its human-readable form (such as a `Float` or a `String`) to the form fed into the machine learning model.
 
-### Decoding
-
-The inverse process to encoding. Note that in many cases (e.g. a continuous-valued feature encoded to a one-hot vector), the process isn't fully invertible, i.e. you can't get back a precise value but rather only a range corresponding to the associated onehot bin.
-
-## Data types in `ChemistryFeaturization`
-
-### Feature Descriptor
-
-Describes the "features of a feature" – i.e. its name, possible values, instructions for encoding it, etc., but does NOT store an actual instance of its value.
-
-For more on the available types of feature descriptors, see [Feature Descriptors](@ref fd).
+The complexity of the encoding logic, whether it's something as simple as an equality operation, or something much more complex, is a decision left to the user. Often, this is building a one-hot vector.
 
-### AbstractCodec
-
-Component of a feature descriptor that stores the actual encoding/decoding functions. 
-
-### Atoms Object
-
-Describes a molecule, crystal, etc. in whatever representation will be ingested by an ML model (e.g. a graph), and can also store encoded features of that structure. 
-
-For more on the available types of atoms objects, see [Atoms Objects](@ref atoms).
+### Decoding
 
-### Featurization Object
+The inverse process to encoding.
 
-Stores sets of feature descriptors and instructions for combining the values they encode on an atoms object.
+Generally, it is recommended that there is symmetry between the encoding and decoding logic.
 
-For more on the available types of featurization objects, see [Featurization](@ref).
+!!! note
+    In many cases, the process isn't fully invertible. For instance, for a continuous-valued feature encoded to a one-hot vector you can't get back a precise value but rather only a range corresponding to the associated onehot bin.
+    In such cases, the decoding mechanism should try and return the most meaningful and human-interpretable form.
 
 ## Design Philosophy
 

diff --git a/docs/src/types/atoms.md b/docs/src/types/atoms.md
@@ -4,13 +4,17 @@
 Atoms
 ```
 
-Atoms objects (terminology borrowed from [ASE](https://wiki.fysik.dtu.dk/ase/)) store information about the structure of a molecule, crystal, etc. as well as, optionally, encoded features and the featurization used to encode them. The parent abstract type is `AbstractAtoms`.
+Atoms objects (terminology borrowed from [ASE](https://wiki.fysik.dtu.dk/ase/)) store information about the structure of a molecule, crystal, etc.
+
+The parent abstract type is `AbstractAtoms`.
 
 ## AtomGraph
+
 The `AtomGraph` type is used to store atomic graph representations. It can also be visualized using some customized formatting with the GraphPlot package.
 
 ```@docs
 Atoms.AtomGraph
 Atoms.AtomGraph(::String, ::String)
+Atoms.AtomGraph(::Crystal)
 Atoms.visualize
 ```
diff --git a/docs/src/types/codecs.md b/docs/src/types/codecs.md
@@ -1,4 +1,4 @@
-# Codecs
+# [Codecs](@id codecs)
 
 ```@docs
 Codec

diff --git a/docs/src/types/feature_descriptors.md b/docs/src/types/feature_descriptors.md
@@ -4,31 +4,36 @@
 FeatureDescriptor
 ```
 
-Feature descriptors store all necessary information to encode **and decode** feature values on various parts of an atoms object and appropriately combine them into a single object (vector, matrix, etc.) describing the value/values of the feature for the entire object.
+Feature descriptors store all necessary information to encode and decode feature values on various parts of an [Atoms](@ref atoms) object and appropriately combine them into a single form (vector, matrix, etc.), describing the value(s) of the feature for the entire object.
 
 For example, if an `ElementFeatureDescriptor` encodes a vector for each atom in an object, they could be concatenated together into a matrix with a column for each atom to describe a structure.
 
-Feature Descriptors must be designed with interoperability in mind. A `FeatureDescriptor` object must work deterministically with different datasets.
-
-The type hierarchy of these objects is currently:
-```
-|---- AbstractFeatureDescriptor
-    |---- AbstractAtomFeatureDescriptor
-        |==== ElementFeatureDescriptor
-        |==== SpeciesFeatureDescriptor
-    |---- AbstractPairFeatureDescriptor
-        |==== PairFeatureDescriptor
-        |---- BondFeatureDescriptor
-            |==== BondType
-            |==== InRing
-            |==== IsConjugated
+Feature Descriptors must be designed with interoperability in mind. A [FeatureDescriptor](@ref fd) object must work deterministically with different datasets.
+
+## Hierarchy
+
+The type hierarchy of these objects is currently as follows.
+
+```text
+AbstractType.AbstractFeatureDescriptor
+├─── AbstractAtomFeatureDescriptor
+│    ├─── SpeciesFeatureDescriptor
+│    └─── ElementFeatureDescriptor
+│
+├─── AbstractEnvironmentFeatureDescriptor
+│    └─── OrbitalFieldMatrix
+│
+└─── AbstractPairFeatureDescriptor
+     ├─── BondFeatureDescriptor
+     │    ├─── BondType
+     │    ├─── InRing
+     │    └─── IsConjugated
+     │
+     └─── PairFeatureDescriptor
 ```
-where 
-`----` = Abstract Type
-and
-`====` = Concrete Type
 
-More details on each of these types is below, and more types (e.g. environment features) will be implemented in the future!
+More details on each of these types can be found below.\
+More types (e.g. environment features) will be implemented in the future!
 
 ## Functionality common to all feature descriptors
 

diff --git a/docs/src/types/featurizations.md b/docs/src/types/featurizations.md
@@ -1,4 +1,4 @@
-# Featurization
+# [Featurization](@id fzn)
 
 ```@docs
 Featurization
@@ -10,4 +10,4 @@ The implementation for a featurization must be as standardized and generic as po
 
 ```@docs
 GraphNodeFeaturization
-```
+```
diff --git a/docs/src/types/featurizedatoms.md b/docs/src/types/featurizedatoms.md
@@ -1,9 +1,10 @@
-# Featurized Atoms
+# [Featurized Atoms](@id fznatoms)
 
-A `FeaturizedAtoms` object is a flexible container for an `Atoms` object, a compatible `Featurization` object, and the resulting encoded features. The type is parameterized by the type of atoms object and the featurization type, e.g. `FeaturizedAtoms{AtomGraph,GraphNodeFeaturization}`.
+A [FeaturizedAtoms](@ref fznatoms) object is a container for an [Atoms](@ref atoms) object, a compatible [Featurization](@ref fzn) object, and the resulting encoded features.\
+The type is parameterized by the type of atoms object and the featurization type, e.g. `FeaturizedAtoms{AtomGraph,GraphNodeFeaturization}`.
 
 This is intended to be the type that is directly fed into a Chemellia model, so the format of `encoded_features` should be whatever the associated model requires, and not necessarily human-readable (though interpretable through the `decode` function!).
 
 ```@docs
 FeaturizedAtoms
-```
+```
diff --git a/docs/src/types/overview.md b/docs/src/types/overview.md
@@ -0,0 +1,23 @@
+
+# Primary Data Types
+
+In [Terminology and Philosophy](@ref), we discussed general terms that pop up all over the package and the overall design philosophy of the package.
+
+Let's go one step further and gloss over some essential categories of data structures.\
+More information about each of these types can be found in the respective sections.
+
+## Atoms
+
+[Atoms](@ref atoms) objects (terminology borrowed from [ASE](https://wiki.fysik.dtu.dk/ase/)) store information about the structure of a molecule, crystal, etc., and other useful information required to interpret the same.
+
+## Feature Descriptor
+
+[Feature Descriptors](@ref fd) represent the *"features of a feature"* - i.e., its name, possible values, instructions for encoding it, etc., but do NOT store an actual instance of their value.
+
+## Codec
+
+[Codecs](@ref codecs) define the actual encoding and decoding logic to be used with a feature descriptor.
+
+## Featurization
+
+A [Featurization](@ref fzn) stores sets of feature descriptors and defines the logic for combining the values they encode on an `Atoms` object.
diff --git a/docs/src/utils.md b/docs/src/utils.md
@@ -1,10 +1,22 @@
 # Utilities
 Some helper/utility functions that aren't documented elsewhere...
 
-```@index
+```@contents
 Pages = ["utils.md"]
 ```
 
+## Element Feature Utilities
+
+Utility methods primarily used for representing element features.
+
+```@autodocs
+Modules = [Utils.ElementFeatureUtils]
+```
+
+## Graph Building
+
+Utility methods used for building adjacency graph representations for [Atoms](@ref atoms).
+
 ```@autodocs
-Modules = [Utils.ElementFeatureUtils, Utils.GraphBuilding]
-```
+Modules = [Utils.GraphBuilding]
+```
diff --git a/src/ChemistryFeaturization.jl b/src/ChemistryFeaturization.jl
@@ -5,6 +5,10 @@ using SimpleWeightedGraphs
 encodable_elements(a::Any) = throw(MethodError(encodable_elements, a))
 encode(a::Any, object_to_be_encoded) = throw(MethodError(encode, a))
 decode(a::Any, encoded_features) = throw(MethodError(decode, a))
+elements(a::Any) = throw(MethodError(elements, a))
+
+include("data.jl")
+export Data
 
 include("abstracts/abstracttypes.jl")
 export AbstractType
@@ -23,7 +27,7 @@ export ElementFeatureDescriptor, output_shape
 include("atoms/atoms.jl")
 export Atoms
 
-using .Atoms: AtomGraph, visualize
+using .Atoms: AtomGraph, visualize, elements
 export AtomGraph, visualize
 
 include("featurizations/featurizations.jl")
Original file line number	Diff line number	Diff line change
Expand Up		@@ -14,4 +14,4 @@ It provides flexible, modular data types and functions for starting from a "bare

		![CF_flowchart](files/flowchart.png)

		To learn more about the package, it would be good to start with the [Terminology/Philosophy](@ref) section to get a handle on the vocabulary as we use it, and also some insights about the design philosophy behind the package. Then go ahead and browse the sidebar for more!
		To learn more about the package, it would be good to start with the [Terminology and Philosophy](@ref) section to get a handle on the vocabulary as we use it, and also some insights about the design philosophy behind the package. Then go ahead and browse the sidebar for more!