Metadata-Version: 2.4
Name: pyclupan
Version: 0.1.7.post0
Summary: This is the pyclupan module.
Author-email: Atsuto Seko <seko@cms.mtl.kyoto-u.ac.jp>
Maintainer-email: Atsuto Seko <seko@cms.mtl.kyoto-u.ac.jp>
License: BSD 3-Clause License
        
        Copyright (c) 2025, pyclupan
        
        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 copyright holder 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 HOLDER 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.
        
Project-URL: Homepage, https://github.com/sekocha/pyclupan
Project-URL: Repository, https://github.com/sekocha/pyclupan
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy!=2.0.*
Requires-Dist: scipy
Requires-Dist: scikit-learn
Requires-Dist: PyYAML>=5.3
Requires-Dist: setuptools>=61.0
Requires-Dist: spglib
Requires-Dist: phonopy
Requires-Dist: pypolymlp>=0.16.0
Requires-Dist: graphillion<2.0
Provides-Extra: tools
Dynamic: license-file

# pyclupan: Cluster Expansion Tools for Alloy and Substitutional Ionic Systems

`pyclupan` is a Python package for developing substitutional cluster expansion models based on datasets obtained from density functional theory (DFT) calculations.
The code also enables the enumeration of nonequivalent substitutional derivative structures, the calculation of correlation (cluster) functions, Monte Carlo simulations, and the evaluation of free energies for multicomponent substitutional systems.

## Citation of Pyclupan

"Cluster expansion method for multicomponent systems based on optimal selection of structures for density-functional theory calculations", [A. Seko et al., Phys. Rev. B 80, 165122 (2009)](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.80.165122)

## Required Libraries and Python Modules

- python >= 3.9
- numpy != 2.0.*
- scipy
- pyyaml
- setuptools

- scikit-learn
- pypolymlp >= 0.16.0
- spglib
- phonopy
- graphillion < 2.0

[Optional]
- openmp (recommended)


## How to Install Pyclupan

- Install from PyPI
```
conda create -n pyclupan-env
conda activate pyclupan-env
conda install -c conda-forge pypolymlp spglib phonopy
pip install pyclupan
```

- Install from GitHub
```
git clone https://github.com/sekocha/pyclupan.git
cd pyclupan
conda create -n pyclupan-env
conda activate pyclupan-env
conda install -c conda-forge pypolymlp spglib phonopy
pip install . -vvv
```

## How to Use Pyclupan
### Tutorials
- [CE Model Estimation for Alloy Systems (Binary Ag-Au and Ternary Cu-Ag-Au)](docs/tutorial-alloy.md)
- [CE Model Estimation for Ionic Substitutional Systems (SrCuO3-x)](docs/tutorial-subs.md)
- [CE Model Estimation for Substitutional Systems on Multiple Sublattices (SiC-AlN)](docs/tutorial-2x2.md)
- [Special Quasirandom Structure (SQS) Generation Using Simulated Annealing](docs/tutorial-sqs.md)

### Command-Line Interface
- [Enumeration of Derivative Structures](docs/calc_derivative.md)
- [Derivative Structure Sampling](docs/sample_derivative.md)
- [Enumeration of Clusters and Cluster Function Forms](docs/cluster_search.md)
- [Cluster Function Calculations](docs/calc_features.md)
- [Cluster Expansion Model Estimation](docs/regression.md)
- [Energy Calculations](docs/calc_properties.md)
- [Lattice Monte Carlo Simulations](docs/mc.md)
