pyclupan 0.1.1.post8__tar.gz

pyclupan-0.1.1.post8/.pre-commit-config.yaml

@@ -0,0 +1,40 @@
+# See https://pre-commit.com for more informatio
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.5.0
+  hooks:
+  - id: trailing-whitespace
+  - id: end-of-file-fixer
+#  - id: check-yaml
+#    exclude: ^conda/
+  - id: check-added-large-files
+    args: ['--maxkb=10000']
+
+- repo: https://github.com/pycqa/flake8
+  rev: 7.0.0
+  hooks:
+  - id: flake8
+    args:
+    - "--max-line-length=88"
+    - "--ignore=E203,W503,E501,W605,E712,E741,E722"
+    - "--exclude=src/pyclupan/misc/*, src/pyclupan/utils/*deprecated*"
+    #- "--ignore=E203,W503,E501"
+
+- repo: https://github.com/psf/black
+  rev: 24.1.1
+  hooks:
+  - id: black
+    args:
+    - --line-length=88
+
+# - repo: https://github.com/pycqa/pydocstyle
+#   rev: 6.3.0
+#   hooks:
+#   - id: pydocstyle
+
+- repo: https://github.com/pycqa/isort
+  rev: 5.13.2
+  hooks:
+    - id: isort
+      name: isort (python)

pyclupan-0.1.1.post8/LICENSE

@@ -0,0 +1,28 @@
+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.

pyclupan-0.1.1.post8/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: pyclupan
+Version: 0.1.1.post8
+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
+Provides-Extra: graphillion
+Requires-Dist: graphillion; extra == "graphillion"
+Provides-Extra: tools
+Requires-Dist: graphillion; 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
+
+- pypolymlp >= 0.16.0
+- spglib
+- phonopy
+- openmp (recommended)
+
+[Optional]
+- graphillion
+- scikit-learn
+
+
+## How to Install Pyclupan
+
+- Install from PyPI
+```
+conda create -n pyclupan-env
+conda activate pyclupan-env
+conda install -c conda-forge numpy scipy spglib
+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 numpy scipy spglib
+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)
+
+### 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)

pyclupan-0.1.1.post8/README.md

@@ -0,0 +1,60 @@
+# 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
+
+- pypolymlp >= 0.16.0
+- spglib
+- phonopy
+- openmp (recommended)
+
+[Optional]
+- graphillion
+- scikit-learn
+
+
+## How to Install Pyclupan
+
+- Install from PyPI
+```
+conda create -n pyclupan-env
+conda activate pyclupan-env
+conda install -c conda-forge numpy scipy spglib
+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 numpy scipy spglib
+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)
+
+### 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)

pyclupan-0.1.1.post8/docs/calc_derivative.md

@@ -0,0 +1,195 @@
+# Enumeration of Derivative Structures
+Examples of enumerating derivative structures are shown here.
+Derivative structures are defined as nonequivalent substitutional configurations on a given lattice.
+These structures will be used to perform DFT calculations for developing cluster expansion models and to identify ground-state structures by calculating the energies of all derivative structures.
+The `graphillion` package is additionally required to enumerate the derivative structures.
+
+## Enumeration of Derivative Structures for Single Lattice
+### Binary Derivative Structures
+Here is an example of enumerating binary derivative structures for a single lattice.
+When the expansion degree is set to three, corresponding to possible supercell expansions of size three, all nonequivalent configurations on the lattice are enumerated.
+The command line for performing this operation is as follows.
+```shell
+# > cat poscar-fcc-primitive
+# FCC
+# 4.0
+#   0.000000000  0.5000000000  0.5000000000
+#   0.5000000000  0.000000000  0.5000000000
+#   0.5000000000  0.5000000000  0.000000000
+#  Ag
+#   1
+# Direct
+#   0.000000000 0.000000000 0.000000000
+
+> pyclupan -p poscar-fcc-primitive --supercell_size 3
+```
+The expansion degree can be given using the `--supercell_size` option.
+
+If the composition of the derivative structures is constrained, the `--comp` option can be used.
+In the `--comp` option, the element IDs (starting from zero) and their corresponding compositions must be specified for all elements.
+```shell
+# --comp element_id chemical_composition
+> pyclupan -p fcc-primitive --supercell_size 3 --comp 0 0.3333333333 --comp 1 0.66666666666
+```
+
+The compositions do not need to be normalized; equivalently, they can be specified as follows.
+```shell
+> pyclupan -p fcc-primitive --supercell_size 3 --comp 0 1.0 --comp 1 2.0
+```
+
+The composition ranges can also be specified as input parameters.
+The lower and upper bounds of the composition for each element can be defined.
+```shell
+> pyclupan -p fcc-primitive --supercell_size 6 --comp_lb 0 0.5 --comp_ub 0 0.67
+```
+In this example, only structures in which the composition of element 0 ranges from 0.5 to 0.67 are enumerated.
+Note that structures with a composition exactly equal to 0.5 are included.
+
+If a specific supercell matrix is provided instead of the expansion degree, the `--hnf` option can be used.
+A given one-dimensional sequence containing nine elements is reshaped into a 3x3 matrix using `np.reshape((3, 3))`.
+```shell
+# supercell = [[1, 0, 0]
+#              [0, 2, 0]
+#              [1, 0, 3]]
+
+> pyclupan -p fcc-primitive --hnf 1 0 0 0 2 0 1 0 3
+```
+
+After running the derivative structure search, a result file named `derivative.yaml`, containing all possible labelings corresponding to the derivative structures, is generated.
+
+### Beyond Binary Derivative Structures
+Here is an example demonstrating the enumeration of ternary derivative structures for a single lattice.
+The element types on the lattice are specified using the `-e` option.
+In the example below, `-e 0 1 2` indicates that three different elements occupy the same underlying (single) lattice.
+
+```shell
+# > cat poscar-fcc-primitive
+# FCC
+# 4.0
+#   0.000000000  0.5000000000  0.5000000000
+#   0.5000000000  0.000000000  0.5000000000
+#   0.5000000000  0.5000000000  0.000000000
+#  Ag
+#   1
+# Direct
+#   0.000000000 0.000000000 0.000000000
+
+(For Ternary)
+> pyclupan -p poscar-fcc-primitive --supercell_size 3 -e 0 1 2
+
+(For Quaternary)
+> pyclupan -p poscar-fcc-primitive --supercell_size 4 -e 0 1 2 3
+```
+
+## Enumeration of Derivative Structures for Multiple Lattices
+
+### Configurations on Single Sublattice
+
+In the following example, binary nonequivalent configurations on the anion sites are enumerated in the cubic perovskite structure.
+The elements Sr (index 0) and Ti (index 1) are fixed, and configurations of two elements (indices 2 and 3) are considered on the third sublattice.
+The order of the `-e` options is important for controlling the sublattices on which configurations are considered.
+
+```shell
+# > cat POSCAR
+# Perovskite unit cell
+# 1.0
+#   4.000000000  0.000000000  0.000000000
+#   0.000000000  4.000000000  0.000000000
+#   0.000000000  0.000000000  4.000000000
+#   Sr Ti O
+#   1  1  3
+# Direct
+#   0.000000000 0.000000000 0.000000000
+#   0.5000000000 0.5000000000 0.5000000000
+#   0.5000000000 0.5000000000 0.000000000
+#   0.000000000 0.5000000000 0.5000000000
+#   0.5000000000 0.000000000 0.5000000000
+
+> pyclupan -p POSCAR --supercell_size 4 -e 0 -e 1 -e 2 3
+```
+
+The other options `--comp`, `--comp_lb`, `--comp_ub`, and `--hnf` are also available.
+To restrict the composition, `--comp_lb` and `--comp_ub` options can be used as follows:
+```shell
+> pyclupan -p POSCAR --supercell_size 4 -e 0 -e 1 -e 2 3 --comp_lb 2 0.66 --comp_ub 2 0.9
+```
+
+### Configurations on Multiple Lattices
+
+In the following example, ternary configurations on the cation A and B sublattices and binary configurations on the anion sublattice are enumerated for the perovskite structure.
+Configurations involving three elements (indices 0, 1, and 2) on the first and second sublattices, and two elements (indices 3 and 4) on the third sublattice, are considered.
+
+```shell
+# > cat POSCAR
+# Perovskite unit cell
+# 1.0
+#   4.000000000  0.000000000  0.000000000
+#   0.000000000  4.000000000  0.000000000
+#   0.000000000  0.000000000  4.000000000
+#   Sr Ti O
+#   1  1  3
+# Direct
+#   0.000000000 0.000000000 0.000000000
+#   0.5000000000 0.5000000000 0.5000000000
+#   0.5000000000 0.5000000000 0.000000000
+#   0.000000000 0.5000000000 0.5000000000
+#   0.5000000000 0.000000000 0.5000000000
+
+> pyclupan -p POSCAR --supercell_size 4 -e 0 1 2 -e 0 1 2 -e 3 4
+```
+
+### More Complex Constraints
+Here is an example demonstrating how composition constraints are applied.
+In this example, ternary configurations on the cation sites and binary configurations on the anion sites are considered for the perovskite structure at the composition of A2BCX5.
+Cations A and B occupy both the first and second cation sublattices, while cation C occupies only the second sublattice in the perovskite structure.
+Anions X occupy the third sublattice, with one-sixth of this sublattice remaining vacant.
+
+```shell
+# > cat POSCAR
+# Perovskite unit cell
+# 1.0
+#   4.000000000  0.000000000  0.000000000
+#   0.000000000  4.000000000  0.000000000
+#   0.000000000  0.000000000  4.000000000
+#   Sr Ti O
+#   1  1  3
+# Direct
+#   0.000000000 0.000000000 0.000000000
+#   0.5000000000 0.5000000000 0.5000000000
+#   0.5000000000 0.5000000000 0.000000000
+#   0.000000000 0.5000000000 0.5000000000
+#   0.5000000000 0.000000000 0.5000000000
+
+> pyclupan -p POSCAR --supercell_size 4 -e 0 1 -e 0 1 2 -e 3 4 --comp 0 2.0 --comp 1 1.0 --comp 2 1.0 --comp 3 5.0 --comp 4 1.0
+```
+Elements 0, 1, and 2 correspond to cations A, B, and C, respectively.
+Element 3 corresponds to the anion X, and element 4 represents vacant anion sites.
+
+## Enumeration of Ionic Derivative Structures
+
+The following example enumerates configurations of cations A(2+) and B(3+) on the first sublattice and configurations of cation C(4+) and D(3+) on the second sublattice in perovskite lattice.
+Only derivative structures satisfying charge neutrality are enumerated.
+
+```shell
+# > cat POSCAR
+# Perovskite unit cell
+# 1.0
+#   4.000000000  0.000000000  0.000000000
+#   0.000000000  4.000000000  0.000000000
+#   0.000000000  0.000000000  4.000000000
+#   Sr Ti O
+#   1  1  3
+# Direct
+#   0.000000000 0.000000000 0.000000000
+#   0.5000000000 0.5000000000 0.5000000000
+#   0.5000000000 0.5000000000 0.000000000
+#   0.000000000 0.5000000000 0.5000000000
+#   0.5000000000 0.000000000 0.5000000000
+
+# element 0: A (2+), element 1: B (3+) on sublattice 1
+# element 2: C (4+), element 3: D (3+) on sublattice 2
+# element 4: X (2-) on sublattice 3
+
+> pyclupan -p POSCAR --supercell_size 4 -e 0 1 -e 2 3 -e 4 --charge 0 2.0 --charge 1 3.0 --charge 2 4.0 --charge 3 3.0 --charge 4 -2.0
+```
+When enumerating structures that satisfy charge neutrality, the charges of all elements are required.

pyclupan-0.1.1.post8/docs/calc_features.md

@@ -0,0 +1,24 @@
+# Cluster Function Calculations
+
+Cluster function values can be calculated using symmetrically independent clusters, specified by the `--clusters` option.
+The calculated cluster functions will be saved to an HDF5 file `pyclupan_features.hdf5`.
+
+When cluster functions are computed for enumerated derivative structures, the `--derivatives` option can be used to specify the files containing the enumerated labelings of those derivative structures.
+
+```shell
+> pyclupan-calc --clusters pyclupan_cluster.yaml --derivatives pyclupan_derivatives_*.yaml
+```
+
+When cluster functions are calculated for sampled structures taken from a set of derivative structures, use the `--sample` option to specify the sampled structures.
+
+```shell
+> pyclupan-calc --clusters pyclupan_cluster.yaml --samples pyclupan_sample_attrs.yaml
+```
+
+If structures in POSCAR format are provided, cluster functions can be calculated as follows.
+```shell
+> pyclupan-calc --clusters pyclupan_cluster.yaml --poscars POSCAR1 POSCAR2 --element_strings Ag Au
+```
+In this case, the element strings must be specified to define their corresponding element indices.
+The order of the element strings is important, as it determines the element indices.
+In this example, the elements Ag and Au are assigned element indices 0 and 1, respectively.

pyclupan-0.1.1.post8/docs/calc_properties.md

@@ -0,0 +1,29 @@
+# Energy Calculations
+
+Using effective cluster interactions obtained from regression, the energies and formation energies for derivative structures can be calculated.
+Derivative structures lying on the convex hull of the formation energies are regarded as
+stable structures in alloy and substitutional systems.
+
+The command-line interface `pyclupan-calc` with the `--ecis` option allows the calculation of energies, formation energies, and convex hull structures.
+The usage of `pyclupan-calc` is similar to that described in [Cluster Function Calculations](calc_features.md).
+In addition to the options used for calculating cluster functions, the `--ecis` option must be provided to specify the effective cluster interactions.
+When the `--ecis` option is given, the energies and formation energies for the specified
+structures and labelings are calculated as follows.
+
+```shell
+> pyclupan-calc --ecis pyclupan_ecis.yaml --clusters pyclupan_cluster.yaml --derivatives pyclupan_derivatives_*
+> pyclupan-calc --ecis pyclupan_ecis.yaml --clusters pyclupan_cluster.yaml --samples pyclupan_sample_attrs.yaml
+> pyclupan-calc --ecis pyclupan_ecis.yaml --clusters pyclupan_cluster.yaml --poscars POSCAR1 POSCAR2 --element_strings Ag Au
+```
+
+After executing these commands, three files are generated:
+- `pyclupan_energies.hdf5` for energy values,
+- `pyclupan_formation_energies.hdf5` for formation energy values, and
+- `pyclupan_convexhull.yaml` for the stable structures on the convex hull.
+
+When calculating formation energies, endmembers are defined automatically.
+If endmembers are provided manually, the structures in POSCAR format can be specified using the additional `--end_poscars` and `--element_strings` options.
+
+```shell
+--end_poscars poscar-end1 poscar-end2 --element_strings Ag Au
+```

pyclupan-0.1.1.post8/docs/cluster_search.md

@@ -0,0 +1,75 @@
+# Enumeration of Independent Clusters and Cluster Function Forms
+
+Using the cluster-search interface, symmetrically nonequivalent clusters, element configurations on clusters, and cluster-function configurations can be enumerated.
+These clusters are used to compute cluster (correlation) functions and to count the number of clusters distinguished by their elemental species.
+
+The input parameters for performing a cluster search include the maximum cluster order, the cutoff distance for each cluster body, and the primitive lattice representation of the target lattice.
+
+
+The maximum cluster order is specified by the `--order` option.
+Cutoff distances are provided using the `--cutoffs` option, listed in order for pairs, triplets, and so on.
+The number of cutoff distances must be equal to the maximum cluster order minus one.
+The primitive lattice is supplied using the `-p` or `--poscar` option in POSCAR format.
+
+
+## Search of Clusters and Binary Cluster Functions on an FCC Lattice
+
+In the following example, unique clusters and cluster-function forms for a binary system on an FCC lattice are enumerated.
+
+```shell
+# > cat fcc-primitive
+# Generated by pyclupan
+# 4.0
+#   0.000000000  0.5000000000  0.5000000000
+#   0.5000000000  0.000000000  0.5000000000
+#   0.5000000000  0.5000000000  0.000000000
+#  Ag
+#   1
+# Direct
+#   0.000000000 0.000000000 0.000000000
+
+> pyclupan-cluster -p fcc-primitive -e 0 1
+> pyclupan-cluster -p fcc-primitive -e 0 1 --order 4 --cutoffs 6.0 6.0 5.0
+> pyclupan-cluster -p fcc-primitive -e 0 1 --order 5 --cutoffs 6.0 6.0 5.0 4.0
+```
+The option `-e 0 1` indicates that binary elements 0 and 1 are considered on the (first) sublattice of the FCC lattice.
+
+## Search of Clusters and Ternary Cluster Functions on an FCC Lattice
+
+The following example is used to enumerate unique clusters and cluster-function forms for a ternary system on an FCC lattice.
+
+```shell
+> pyclupan-cluster -p fcc-primitive -e 0 1 2 --order 4 --cutoffs 6.0 6.0 6.0
+```
+The option `-e 0 1 2` indicates that ternary elements 0, 1, and 2 are considered on the
+FCC lattice.
+
+## Search of Clusters and Cluster Functions on a Lattice with Multiple Sublattices
+In the following example, binary nonequivalent clusters on the anion sites are enumerated in the cubic perovskite structure.
+The elements Sr (index 0) and Ti (index 1) are fixed, and configurations of two elements (indices 2 and 3) are considered on the third sublattice.
+The order of the `-e` options is important for controlling the sublattices on which configurations are considered.
+
+```shell
+# > cat perovskite-unitcell
+# Perovskite unit cell
+# 1.0
+#   4.000000000  0.000000000  0.000000000
+#   0.000000000  4.000000000  0.000000000
+#   0.000000000  0.000000000  4.000000000
+#   Sr Ti O
+#   1  1  3
+# Direct
+#   0.000000000 0.000000000 0.000000000
+#   0.5000000000 0.5000000000 0.5000000000
+#   0.5000000000 0.5000000000 0.000000000
+#   0.000000000 0.5000000000 0.5000000000
+#   0.5000000000 0.000000000 0.5000000000
+
+> pyclupan-cluster -p perovskite-unitcell -e 0 -e 1 -e 2 3 --order 4 --cutoffs 6.0 6.0 6.0
+```
+In the next example, ternary configurations on the cation A and B sublattices and binary configurations on the anion sublattice are considered to enumerate clusters for the perovskite structure.
+Configurations involving three elements (indices 0, 1, and 2) on the first and second sublattices, and two elements (indices 3 and 4) on the third sublattice, are included.
+
+```shell
+> pyclupan-cluster -p perovskite-unitcell -e 0 1 2 -e 0 1 2 -e 3 4 --order 4 --cutoffs 6.0 6.0 6.0
+```

pyclupan-0.1.1.post8/docs/mc.md

@@ -0,0 +1,108 @@
+# Lattice Monte Carlo Simulations
+
+Using effective cluster interactions obtained from regression, lattice Monte Carlo (MC)
+simulations at finite temperatures can be performed.
+These MC simulations evaluate the average configurations and average properties at finite temperatures.
+
+The current command-line interface, `pyclupan-mc`, supports canonical and semi-grand
+canonical MC simulations.
+In addition, simulated annealing for estimating stable configurations is also available.
+
+
+## Required Files and Parameters
+
+To perform MC simulations, the following files are required:
+- The result file from the cluster search, `pyclupan_clusters.yaml`
+- The file from regression, `pyclupan_ecis.yaml`.
+
+Other parameters required for performing MC simulations include:
+- The supercell size, specified with the `--supercell` option
+- The temperatures, specified with the `-t` option
+- The numbers of steps per site used for equilibration and averaging, specified with the `--n_steps` option
+- The composition for canonical MC, specified with the `--comp` option
+- The chemical potentials for semi-grand canonical MC, specified with the `--mu` option
+
+When the number of atoms in the primitive cell differs from that in the conventional
+unit cell, the given primitive cell will be refined using `spglib`.
+In this case, a supercell is constructed by expanding the refined cell, and the expansion size corresponds to the specified supercell size.
+For example, when the FCC primitive cell is provided in `pyclupan_clusters.yaml` and the
+supercell size is specified as 3×3×3, the MC simulation cell is composed of a 3×3×3
+supercell of the FCC conventional cell, which contains four atoms.
+
+The first and second numbers for the `--n_steps` option are the numbers of steps used for equilibration and averaging, respectively.
+
+## Canonical Monte Carlo Simulation
+
+The composition for canonical MC simulations is specified using the `--comp` option.
+The order of the numbers provided with the `--comp` option determines the correspondence
+between the compositions and the element indices.
+For example, if `--comp 0.2 0.5 0.3` is given, the compositions for elements 0, 1, and 2
+are 0.2, 0.5, and 0.3, respectively.
+
+Canonical MC simulations can be initialized using either a random configuration or a user-specified initial configuration.
+
+### Initialization from a Random Configuration
+
+A random configuration is generated based on the composition given by the `--comp` option.
+
+```shell
+# Binary
+> pyclupan-mc --comp 0.5 0.5 --clusters pyclupan_clusters.yaml --ecis pyclupan_ecis.yaml --supercell 3 3 3 --n_steps 100 1000 -t 500
+# Ternary
+> pyclupan-mc --comp 0.25 0.5 0.25 --clusters pyclupan_clusters.yaml --ecis pyclupan_ecis.yaml --supercell 3 3 3 --n_steps 100 1000 -t 500
+```
+
+### Initialization from a Given Initial Configuration
+
+To provide an initial configuration, a `POSCAR` file and element strings are required to
+assign spins corresponding to the elements.
+These element strings must be the same as those used when estimating the ECIs.
+
+```shell
+> pyclupan-mc -p POSCAR --element_strings Ag Au --clusters pyclupan_clusters.yaml --ecis pyclupan_ecis.yaml --supercell 3 3 3 --n_steps 100 1000 -t 500
+```
+
+
+## Semi-grand Canonical Monte Carlo simulation
+
+When the `--mu` option is provided, a semi-grand canonical MC simulation is performed.
+The chemical potential differences, measured from the first active element, are specified
+with this option.
+For example, if `--mu 0.2 -0.2` is given, the chemical potential differences between
+elements 1 and 0, and between elements 2 and 0, are 0.2 and –0.2, respectively.
+
+
+### Initialization from a Random Configuration
+
+A random configuration is generated based on the composition given by the `--comp` option.
+
+```shell
+# Binary
+> pyclupan-mc --mu 0.5 --comp 0.5 0.5 --clusters pyclupan_clusters.yaml --ecis pyclupan_ecis.yaml --supercell 3 3 3 --n_steps 100 1000 -t 500
+# Ternary
+> pyclupan-mc --mu 0.25 0.1 --comp 0.25 0.5 0.25 --clusters pyclupan_clusters.yaml --ecis pyclupan_ecis.yaml --supercell 3 3 3 --n_steps 100 1000 -t 500
+```
+
+### Initialization from a Given Initial Configuration
+
+To provide an initial configuration, a `POSCAR` file and element strings are required to
+assign spins corresponding to the elements.
+These element strings must be the same as those used when estimating the ECIs.
+
+```shell
+> pyclupan-mc --mu 0.5 -p POSCAR --element_strings Ag Au --clusters pyclupan_clusters.yaml --ecis pyclupan_ecis.yaml --supercell 3 3 3 --n_steps 100 1000 -t 500
+```
+
+## Simulated Annealing for Evaluating the Ground-State Structure
+
+To perform simulated annealing for estimating the ground-state structure at a fixed
+composition, the `--simulated_annealing` option can be used.
+In simulated annealing, three temperature parameters must be provided:
+`--temp_init`, `--temp_final`, and `--n_temps`.
+The temperatures are generated using `np.logspace(temp_init, temp_final, n_temps)`.
+
+Simulated annealings can also be initialized using either a random configuration or a user-specified initial configuration.
+
+```shell
+> pyclupan-mc --simulated_annealing --comp 0.5 0.5 --clusters pyclupan_clusters.yaml --ecis pyclupan_ecis.yaml --supercell 2 2 2 --n_steps 100 1000 --temp_init 1000 --temp_final 10 --n_temps 10
+```