Metadata-Version: 2.1
Name: smol
Version: 0.5.2
Summary: Lighthweight but caffeinated Python implementation of computational methods for statistical mechanical calculations of configurational states in crystalline material systems.
Author-email: Luis Barroso-Luque <lbluque@berkeley.edu>, Fengyu Xie <lbluque@berkeley.edu>
Maintainer-email: Luis Barroso-Luque <lbluque@berkeley.edu>
License: ::
        
            Statistical Mechanics on Lattices (smol) Copyright (c) 2022, The Regents
            of the University of California, through Lawrence Berkeley National
            Laboratory (subject to receipt of any required approvals from the U.S.
            Dept. of Energy) and the University of California, Berkeley. All rights reserved.
        
            Redistribution and use in source and binary forms, with or without
            modification, are permitted provided that the following conditions are met:
        
            (1) Redistributions of source code must retain the above copyright notice,
            this list of conditions and the following disclaimer.
        
            (2) Redistributions in binary form must reproduce the above copyright
            notice, this list of conditions and the following disclaimer in the
            documentation and/or other materials provided with the distribution.
        
            (3) Neither the name of the University of California, Lawrence Berkeley
            National Laboratory, U.S. Dept. of Energy, University of California,
            Berkeley nor the names of its contributors may be used to endorse or
            promote products derived from this software without specific prior written
            permission.
        
        
            THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
            AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
            IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
            ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
            LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
            CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
            SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
            INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
            CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
            ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
            POSSIBILITY OF SUCH DAMAGE.
        
            You are under no obligation whatsoever to provide any bug fixes, patches,
            or upgrades to the features, functionality or performance of the source
            code ("Enhancements") to anyone; however, if you choose to make your
            Enhancements available either publicly, or directly to Lawrence Berkeley
            National Laboratory, without imposing a separate written license agreement
            for such Enhancements, then you hereby grant the following license: a
            non-exclusive, royalty-free perpetual license to install, use, modify,
            prepare derivative works, incorporate into other computer software,
            distribute, and sublicense such enhancements or derivative works thereof,
            in binary and source code form.
        
Project-URL: documentation, https://cedergrouphub.github.io/smol
Project-URL: repository, https://github.com/CederGroupHub/smol
Project-URL: changelog, https://cedergrouphub.github.io/smol/CHANGES.md
Project-URL: tracker, https://github.com/CederGroupHub/smol/issues
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy >=1.24
Requires-Dist: pymatgen >=2023.08.10
Requires-Dist: monty >=v2022.9.8
Provides-Extra: dev
Requires-Dist: pre-commit >=2.12.1 ; extra == 'dev'
Requires-Dist: flake8 ; extra == 'dev'
Requires-Dist: pycodestyle ; extra == 'dev'
Requires-Dist: pydocstyle ; extra == 'dev'
Requires-Dist: pylint ; extra == 'dev'
Requires-Dist: black ; extra == 'dev'
Requires-Dist: isort ; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx >=7.0.0 ; extra == 'docs'
Requires-Dist: pydata-sphinx-theme >=0.13.3 ; extra == 'docs'
Requires-Dist: ipython >=8.2.0 ; extra == 'docs'
Requires-Dist: nbsphinx >=0.9.0 ; extra == 'docs'
Requires-Dist: nbsphinx-link >=1.3.0 ; extra == 'docs'
Requires-Dist: sphinx-copybutton >=0.5.2 ; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints >=1.24.0 ; extra == 'docs'
Provides-Extra: optional
Requires-Dist: scikit-learn >=1.1.2 ; extra == 'optional'
Requires-Dist: h5py >=3.6.0 ; extra == 'optional'
Requires-Dist: polytope ; extra == 'optional'
Requires-Dist: cvxpy ; extra == 'optional'
Requires-Dist: cvxopt ; extra == 'optional'
Requires-Dist: gurobipy ; extra == 'optional'
Requires-Dist: pyscipopt ; extra == 'optional'
Provides-Extra: test
Requires-Dist: pytest >=7.2.0 ; extra == 'test'
Requires-Dist: pytest-cov >=4.0.0 ; extra == 'test'
Requires-Dist: scikit-learn >=1.1.2 ; extra == 'test'
Requires-Dist: h5py >=3.6.0 ; extra == 'test'
Requires-Dist: coverage ; extra == 'test'
Requires-Dist: polytope ; extra == 'test'
Requires-Dist: cvxpy ; extra == 'test'
Requires-Dist: gurobipy ; extra == 'test'
Requires-Dist: pyscipopt ; extra == 'test'

<p align="center"><img src="docs/src/_static/logo.png" width="500px" alt=" "></p>

<h1 align="center">Statistical Mechanics on Lattices</h1>

<h4 align="center">

![test](https://github.com/CederGroupHub/smol/actions/workflows/test.yml/badge.svg)
[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/f6180b5223f346d2ac9dcf9a4bcc62d9)](https://www.codacy.com/gh/CederGroupHub/smol/dashboard?utm_source=github.com&utm_medium=referral&utm_content=CederGroupHub/smol&utm_campaign=Badge_Coverage)
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/CederGroupHub/smol/main.svg)](https://results.pre-commit.ci/latest/github/CederGroupHub/smol/main)
[![pypi version](https://img.shields.io/pypi/v/smol?color=blue)](https://pypi.org/project/smol)
[![Static Badge](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/downloads/)
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/CederGroupHub/smol/HEAD?labpath=docs%2Fsrc%2Fnotebooks%2Findex.ipynb)
[![status](https://joss.theoj.org/papers/e96a568ca53ee9d14548d7b8bed69b25/status.svg)](https://joss.theoj.org/papers/e96a568ca53ee9d14548d7b8bed69b25)

</h4>

*Lightweight but caffeinated Python implementation of computational methods
for statistical mechanical calculations of configurational states in
crystalline materials.*

-----------------------------------------------------------------------------

**smol** is a minimal implementation of computational methods to calculate
statistical mechanical and thermodynamic properties of crystalline
material systems based on the *cluster expansion* method from alloy theory and
related methods. Although **smol** is intentionally lightweight---in terms of
dependencies and built-in functionality---it has a modular design that closely
follows underlying mathematical formalism and provides useful abstractions to
easily extend existing methods or implement and test new ones.

Functionality
-------------
**smol** currently includes the following functionality:

-   Defining cluster expansion functions for a given disordered structure using a
    variety of available site basis functions with and without explicit
    redundancy.

-   Option to include explicit electrostatics in expansions using the Ewald summation
    method.
-   Computing correlation vectors for a set of training structures with a variety
    of functionality to inspect the resulting feature matrix.

-   Defining fitted cluster expansions for subsequent property prediction.
-   Fast evaluation of correlation vectors and differences in correlation vectors
    from local updates in order to quickly compute properties and changes in
    properties for specified supercell sizes.

-   Flexible toolset to sample cluster expansions using Monte Carlo with
    canonical, semigrand canonical, and charge neutral semigrand canonical ensembles
    using a Metropolis or a Wang-Landau sampler.

-   Special quasi-random structure generation based on either correlation vectors or
    cluster interaction vectors.

-   Solving for periodic ground-states of any given cluster expansion with or without
    electrostatics over a given supercell.

**smol** is built on top of [pymatgen](https://pymatgen.org) so any pre/post
structure analysis can be done seamlessly using the various functionality
supported there.

Installation
------------
From pypi:

    pip install smol

From source:

`Clone` the repository. The latest tag in the `main` branch is the stable version of the
code. The `main` branch has the newest tested features, but may have more
lingering bugs. From the top level directory

    pip install .

Although `smol` is not tested on Windows platforms, it should still run on Windows since
there aren't any platform specific dependencies. The only known installation issue
is building `pymatgen` dependencies. If simply running `pip install smol` fails, try
installing `pymatgen` with conda first:

    conda install -c conda-forge pymatgen
    pip install smol

You can also simply use the *environment.yml* file in the repository to install `smol`:

    conda env create -f environment.yml
    source activate smol-env

Usage
-----
Refer to the [documentation](https://cedergrouphub.github.io/smol/) for details on using
**smol**. Going through the [example notebooks](https://github.com/CederGroupHub/smol/tree/main/docs/src/notebooks)
will also help you get started. You can run the example notebooks interactively in
[binder](https://mybinder.org/v2/gh/CederGroupHub/smol/HEAD?labpath=docs%2Fsrc%2Fnotebooks%2Findex.ipynb).

Citing
------
If you use **smol** in your research, please give the repo a star :star: and refer to
the [citing](https://cedergrouphub.github.io/smol/citing.html) page in the documentation
for formal citation information.

Contributing
------------
We welcome all your contributions with open arms! Please fork and pull request any contributions.
See the
[developing](https://cedergrouphub.github.io/smol/developer_guide/index.html)
page in the documentation for how to contribute.

Changes
-------
The most recent changes are detailed in the
[change log](https://github.com/CederGroupHub/smol/blob/master/CHANGES.md).

Copyright Notice
----------------
    Statistical Mechanics on Lattices (smol) Copyright (c) 2022, The Regents
    of the University of California, through Lawrence Berkeley National
    Laboratory (subject to receipt of any required approvals from the U.S.
    Dept. of Energy) and the University of California, Berkeley. All rights reserved.

    If you have questions about your rights to use or distribute this software,
    please contact Berkeley Lab's Intellectual Property Office at
    IPO@lbl.gov.

    NOTICE.  This Software was developed under funding from the U.S. Department
    of Energy and the U.S. Government consequently retains certain rights.  As
    such, the U.S. Government has been granted for itself and others acting on
    its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the
    Software to reproduce, distribute copies to the public, prepare derivative
    works, and perform publicly and display publicly, and to permit others to do so.
