diff --git a/docs/conf.py b/docs/conf.py index 689c691c..fa1cdb7b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -52,8 +52,8 @@ # General information about the project. project = "Smact" -copyright = "2016, Walsh Materials Design Group" -author = "Walsh Materials Design Group" +copyright = "2016, Materials Design Group" +author = "Materials Design Group" # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the diff --git a/docs/examples.rst b/docs/examples.rst index 86fe445a..9e002273 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -2,8 +2,8 @@ Examples ======== -Here we will give a demonstration of how to use some of `smact`'s features. For a full set of -work-through examples in Jupyter notebook form check out +Here we will give a demonstration of how to use some `smact` features. For a full set of +work-through examples in Jupyter Notebook form check out `the examples section of our GitHub repo `_. For workflows that have been used in real examples and in published work, visit our `separate repository `_. @@ -12,7 +12,7 @@ For workflows that have been used in real examples and in published work, visit Element and species classes =========================== -The element and species classes are at the heart of :mod:`smact`'s functionality. Elements are the +The element and species classes are at the heart of :mod:`smact` functionality. Elements are the elements of the periodic table. Species are elements, with some additional information; the oxidation state and the coordination environment (if known). So for example the element iron can have many oxidation states and those oxidation states can have many coordination @@ -29,7 +29,7 @@ environments. The element Fe has 8 oxidation states. They are [-2, -1, 1, 2, 3, 4, 5, 6]. When an element has an oxidation state and coordination environment then it has additional -features. For example the Shannon radius [1]_ of the element, this is often useful for calculating +features. For example, the Shannon radius [1]_ of the element is useful for calculating radius ratio rules [2]_, or for training neural networks [3]_ . .. code:: python @@ -43,7 +43,7 @@ radius ratio rules [2]_, or for training neural networks [3]_ . List building ============= -Often when using :mod:`smact` the aim will to be to search over combinations of a set of elements. This +Often when using :mod:`smact` the aim will be to search over combinations of a set of elements. This is most efficiently achieved by setting up a dictionary of the elements that you want to search over. The easiest way to achieve this in :mod:`smact` is to first create a list of the symbols of the elements that you want to include, then to build a dictionary of the corresponding element objects. @@ -88,7 +88,7 @@ the search. Neutral combinations ==================== -One of the most basic tests for establishing sensible combinations of elements is that they should form charge neutral +One of the most basic tests for establishing sensible combinations of elements is that they should form charge-neutral combinations. This is a straightforward combinatorial problem of comparing oxidation states and allowed stoichiometries. :math:`\Sigma_i Q_in_i = 0` @@ -211,14 +211,14 @@ in function to calculate this property for a given composition. Interfacing to machine learning =============================== -When preparing to do machine learning, we have to convert the compositions that we have into +When preparing to build machine learning models, we have to convert the chemical compositions into something that can be fed into an algorithm. Many of the properties provided in :mod:`smact` are suitable for this, -one can take properties like electronegativity, mass, electron affinity etc etc (for the full list see +one can take properties like electronegativity, mass, electron affinity, etc. (for the full list see :ref:`smact_module`). -One useful representation that is often used in machine learning is the one-hot-vector formulation. A similar -construction to this can be used to encode a chemical formula. A vector of length of the periodic table is -set up and each element set to be a number corresponding to the stoichiometric ratio of that element in the compound. +One useful representation in machine learning is the one-hot-vector formulation. A similar +construction to this can be used to encode a chemical formula. A vector of length covering the periodic table is +constructed and each element is set to a number corresponding to the stoichiometric ratio of that element in the compound. For example we could convert :math:`Ba(OH)_2` .. code:: python @@ -226,17 +226,15 @@ For example we could convert :math:`Ba(OH)_2` ml_vector = smact.screening.ml_rep_generator(['Ba', 'H', 'O'], stoichs=[1, 2, 2]) There is also `an example `_ -demonstrating the conversion of charge neutral compositions produced by `smact` to a list of formulas using Pymatgen, +demonstrating the conversion of charge-neutral compositions produced by `smact` to a list of formulas using Pymatgen, or to a Pandas dataframe, both of which could then be used as input for a machine learning algorithm. For a full machine learning example that uses `smact`, there is a repository `here `_ which demonstrates a search for solar energy materials from the four-component (quaternary) oxide materials space. -.. [1] "Revised effective ionic radii and systematic studies of interatomic distances in halides and chalcogenides". - Acta Crystallogr A. 32: 751–767, 1976 +.. [1] "Revised effective ionic radii and systematic studies of interatomic distances in halides and chalcogenides" Acta Cryst. A. **32**, 751–767 (1976). -.. [2] "Crystal Structure and Chemical Constitution" Trans. Faraday Soc. 25, 253-283, 1929. +.. [2] "Crystal structure and chemical constitution" Trans. Faraday Soc. **25**, 253-283 (1929). -.. [3] "Deep neural networks for accurate predictions of crystal stability" Nat. Comms. 9, 3800, 2018. +.. [3] "Deep neural networks for accurate predictions of crystal stability" Nat. Comms. **9**, 3800 (2018). -.. [4] "Prediction of Flatband Potentials at Semiconductor‐Electrolyte Interfaces from Atomic Electronegativities" - J. Electrochem. Soc. 125, 228-32, 1975. +.. [4] "Prediction of flatband potentials at semiconductor‐electrolyte interfaces from atomic electronegativities" J. Electrochem. Soc. **125**, 228-232 (1975). diff --git a/docs/getting_started.rst b/docs/getting_started.rst index a584b499..bb2249b6 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -15,7 +15,7 @@ and `pymatgen `_ are also required for many components. Installation ============ -The latest stable release of SMACT can be installed via pip which will automatically setup other Python packages as required: +The latest stable release of SMACT can be installed via pip, which will automatically setup other Python packages as required: .. code:: diff --git a/docs/introduction.rst b/docs/introduction.rst index b0c4b610..16453c5c 100644 --- a/docs/introduction.rst +++ b/docs/introduction.rst @@ -3,7 +3,7 @@ Introduction ============ :mod:`smact` is a collection of tools and examples for "low-fi" screening of -potential semiconducting materials through the use of simple chemical +potential semiconducting materials through the use of chemical rules. :mod:`smact` uses a combination of heuristics and models derived from data to @@ -11,17 +11,17 @@ rapidly search large areas of chemical space. This combination of methods allows :mod:`smact` to identify new materials for applications such as photovoltaics, water splitting and thermoelectrics. Read more about :mod:`smact` in our publications: -- `Computational Screening of All Stoichiometric Inorganic Materials `_ +- `Computational screening of all stoichiometric inorganic materials `_ - `Computer-aided design of metal chalcohalide semiconductors: from chemical composition to crystal structure `_ - `Materials discovery by chemical analogy: role of oxidation states in structure prediction `_ -This approach is heavily inspired by the work of Harrison [1]_ and -Pamplin [2]_. The work is an active project in the `Walsh Materials Design Group `_. +This approach is inspired by the work of Harrison [1]_ and +Pamplin [2]_. The work is an active project in the `Materials Design Group `_. -SMACT is now available *via* :code:`pip install smact`. +The package is available *via* :code:`pip install smact`. -We are also developing a set of Jupyter notebook examples `here `_. +We are also developing a set of Jupyter Notebook examples `here `_. .. [1] http://www.worldcat.org/oclc/5170450 Harrison, W. A. *Electronic structure and the properties of solids: the physics of the chemical bond* (1980) -.. [2] http://dx.doi.org/10.1016/0022-3697(64)90176-3 Pamplin, B. R. *J. Phys. Chem. Solids* (1964) **7** 675--684 +.. [2] http://dx.doi.org/10.1016/0022-3697(64)90176-3 Pamplin, B. R. *A systematic method of deriving new semiconducting compounds by structural analogy* J. Phys. Chem. Solids **7**, 675--684 (1964) diff --git a/docs/smact.builder.rst b/docs/smact.builder.rst index bcb38122..1a4099d3 100644 --- a/docs/smact.builder.rst +++ b/docs/smact.builder.rst @@ -2,7 +2,7 @@ smact.builder module ==================== A collection of functions for building certain lattice types. -Currently there are examples here for the Perovskite and Wurzite lattice types, +Currently, there are examples here for the perovskite and wurtzite structure types, which rely on the Atomic Simulation Environment (ASE) :func:`spacegroup.crystal` function. diff --git a/docs/smact.dopant_prediction.doper.rst b/docs/smact.dopant_prediction.doper.rst index 83b826a6..28e0ad8c 100644 --- a/docs/smact.dopant_prediction.doper.rst +++ b/docs/smact.dopant_prediction.doper.rst @@ -1,7 +1,8 @@ smact.dopant_prediction.doper module ============================= -A class to create possible n-type and p-type dopants +A class to create possible n-type and p-type dopants according to +their accessible oxidation states. .. automodule:: smact.dopant_prediction.doper :members: diff --git a/docs/smact.properties.rst b/docs/smact.properties.rst index 599f338b..43136104 100644 --- a/docs/smact.properties.rst +++ b/docs/smact.properties.rst @@ -1,7 +1,8 @@ smact.properties module ======================= -A collection of tools for estimating useful properties. +A collection of tools for estimating physical properties +based on chemical composition. The "electronegativity of a compound" computed with :func:`compound_electroneg` is the rescaled geometric mean of @@ -12,15 +13,15 @@ photoelectric threshold: [1]_ In other words, the computed group :math:`2.86(\chi_{A}\chi_{B})^{1/2}` -is the mid-gap energy and the VBM/CBM positions can be estimated by -subtracting/adding half of the band gap :math:`E_g`. +is the mid-gap energy. The valence band maximum/conduction band minimum positions +can be estimated by subtracting/adding half of the band gap :math:`E_g`. This is an extension Mulliken's electronegativity scale in which :math:`\chi_{A} = (I_{A} + E_{A})/2` (where :math:`I` and :math:`E` are respectively the ionisation potential and electron affinity.) [2]_ -.. [1] Nethercot, A. H. (1974). *Phys. Rev. Lett.*, **33**, 1088–1091. http://dx.doi.org/10.1103/PhysRevLett.33.1088 +.. [1] Nethercot, A. H., *Prediction of Fermi energies and photoelectric thresholds based on electronegativity concepts* Phys. Rev. Lett. **33**, 1088–1091 (1974). http://dx.doi.org/10.1103/PhysRevLett.33.1088 -.. [2] Mulliken, R. S. (1934). *J. Chem. Phys.*, **2**, 782. http://dx.doi.org/10.1063/1.1749394 +.. [2] Mulliken, R. S., *A new electroaffinity scale; together with data on valence states and on valence ionization potentials and electron affinities* J. Chem. Phys. **2**, 782 (1934). http://dx.doi.org/10.1063/1.1749394 .. automodule:: smact.properties :members: diff --git a/docs/smact.rst b/docs/smact.rst index d28c41b5..215effd8 100644 --- a/docs/smact.rst +++ b/docs/smact.rst @@ -11,7 +11,7 @@ which returns a dictionary of :class:`smact.Element` objects indexed by their chemical symbols. Generating this dictionary once and then performing lookups is generally the fastest way of accessing element data while enumerating -possibilities. +possibilities in chemical space. .. automodule:: smact :members: diff --git a/docs/smact.structure_prediction.probability_models.rst b/docs/smact.structure_prediction.probability_models.rst index 7a98139d..1a9dfe3d 100644 --- a/docs/smact.structure_prediction.probability_models.rst +++ b/docs/smact.structure_prediction.probability_models.rst @@ -2,7 +2,7 @@ Substitution Probability Models =============================== Minimal API for developing substitution likelihood probability models -for ion mutation. +for species mutation. .. automodule:: smact.structure_prediction.probability_models :members: