csslib 1.2__tar.gz

csslib-1.2/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

csslib-1.2/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: csslib
+Version: 1.2
+Summary: CSSlib is an open-source code for building configuration search space (CSS) of disordered crystals, loading of the CSS dataset obtained, local/remote MPI or SLURM calculations and data visualization.
+Author: A.V. Krautsou, A.A. Solovykh
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENCE
+Requires-Dist: jupyter<=1.1.1,>=1.0.0
+Requires-Dist: matplotlib<=3.10.8,>=3.10.7
+Requires-Dist: numpy<=2.4.2,>=1.26.4
+Requires-Dist: pandas<3.0,>=2.3.2
+Requires-Dist: paramiko>=4.0.0
+Requires-Dist: plotly<=6.5.2,>=6.3.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pymatgen==2025.6.14
+Requires-Dist: pymatgen-analysis-defects==2025.1.18
+Requires-Dist: scipy<1.17.1,>=1.15.3
+Requires-Dist: scp>=0.15.0
+Requires-Dist: tqdm<=4.67.3,>=4.67.1
+Requires-Dist: networkx<=3.6.1,>=3.4.2
+Dynamic: license-file
+
+# Welcome to CSSlib 👋
+![License](https://img.shields.io/github/license/AIRI-Institute/CSSlib?style=flat&logo=opensourceinitiative&logoColor=white&color=blue) ![Version](https://img.shields.io/badge/version-1.2-orange.svg?cacheSeconds=2592000)
+
+<p align="center">
+  <img src="./logo.jpg" width="30%" title="CSSlib" alt="CSSlib"/>
+</p>
+
+CSSlib is an open-source code for building configuration search space (CSS) of disordered crystals, loading of the CSS dataset obtained, local/remote MPI or SLURM calculations and data visualization.
+
+## Table of content
+- [Installation](#installation)
+- [Contributors](#contributors)
+- [Tutorial](#tutorial)
+- [References & Citing](#references--citing)
+
+## Installation
+**CSSlib** can be installed through 
+1) the **pip** package manager (in the virtual environment):
+```sh
+pip install csslib
+```
+2) the **git clone** command:
+```sh
+git clone https://github.com/AIRI-Institute/CSSlib.git CSSlib
+cd CSSlib
+pip install .
+```
+3) the **uv** package manager:
+```sh
+uv venv .venv
+source .venv/bin/activate
+uv pip install csslib
+```
+
+**CSSlib** by default requires **Supercell** program. Details on **Supercell** installation can be found at the corresponding [website](https://orex.github.io/supercell/download/).
+
+As a calculator for quantum mechanical calculations, **CSSlib** assumes the use of the [VASP](https://www.vasp.at/) (Vienna Ab initio Simulation Package) software package. Also there is an optional dependency for the [QuantumEspresso](http://www.quantum-espresso.org) simulation package which can be installed after the normal installation as:
+```sh
+pip install --group espresso .
+```
+or 
+```sh
+uv sync --group espresso
+```
+
+## Contributors
+- Aleksey Krautsou
+- Aleksandr Solovykh
+
+## Tutorial
+The best way to learn how to use **CSSlib** is through the tutorial notebook located at the [tests directory](tests/csslib_example.ipynb) or at the [google collab](https://colab.research.google.com/drive/1OzYe7QXuL-BYXROnEh7hvuIW08xGlZO2?usp=sharing).
+
+## References & Citing
+If you use this code, please consider citing works that actively used the CSS approach, which resulted in the creation of this library:
+
+1. A.V. Krautsou, I.S. Humonen, V.D. Lazarev, R.A. Eremin, S.A. Budennyy<br/>
+   "Impact of crystal structure symmetry in training datasets on GNN-based energy assessments for chemically disordered CsPbI<sub>3</sub>"<br/>
+   https://doi.org/10.1038/s41598-025-92669-3
+2. N.A. Matsokin, R.A. Eremin, A.A. Kuznetsova, I.S. Humonen, A.V. Krautsou, V.D. Lazarev, Y.Z. Vassilyeva, A.Y. Pak, S.A. Budennyy, A.G. Kvashnin, A.A. Osiptsov<br/>
+   "Discovery of chemically modified higher tungsten boride by means of hybrid GNN/DFT approach"<br/>
+   https://doi.org/10.1038/s41524-025-01628-z
+3. R.A. Zaripov, R.A. Eremin, I.S. Humonen, A.V. Krautsou, V.V. Kuznetsov, K.E. GermanS, S.A. Budennyy, S.V. Levchenko</br>
+   "First-principles data-driven approach for assessment of stability of Tc-C systems"</br>
+   https://doi.org/10.1016/j.actamat.2025.121704

csslib-1.2/README.md

@@ -0,0 +1,64 @@
+# Welcome to CSSlib 👋
+![License](https://img.shields.io/github/license/AIRI-Institute/CSSlib?style=flat&logo=opensourceinitiative&logoColor=white&color=blue) ![Version](https://img.shields.io/badge/version-1.2-orange.svg?cacheSeconds=2592000)
+
+<p align="center">
+  <img src="./logo.jpg" width="30%" title="CSSlib" alt="CSSlib"/>
+</p>
+
+CSSlib is an open-source code for building configuration search space (CSS) of disordered crystals, loading of the CSS dataset obtained, local/remote MPI or SLURM calculations and data visualization.
+
+## Table of content
+- [Installation](#installation)
+- [Contributors](#contributors)
+- [Tutorial](#tutorial)
+- [References & Citing](#references--citing)
+
+## Installation
+**CSSlib** can be installed through 
+1) the **pip** package manager (in the virtual environment):
+```sh
+pip install csslib
+```
+2) the **git clone** command:
+```sh
+git clone https://github.com/AIRI-Institute/CSSlib.git CSSlib
+cd CSSlib
+pip install .
+```
+3) the **uv** package manager:
+```sh
+uv venv .venv
+source .venv/bin/activate
+uv pip install csslib
+```
+
+**CSSlib** by default requires **Supercell** program. Details on **Supercell** installation can be found at the corresponding [website](https://orex.github.io/supercell/download/).
+
+As a calculator for quantum mechanical calculations, **CSSlib** assumes the use of the [VASP](https://www.vasp.at/) (Vienna Ab initio Simulation Package) software package. Also there is an optional dependency for the [QuantumEspresso](http://www.quantum-espresso.org) simulation package which can be installed after the normal installation as:
+```sh
+pip install --group espresso .
+```
+or 
+```sh
+uv sync --group espresso
+```
+
+## Contributors
+- Aleksey Krautsou
+- Aleksandr Solovykh
+
+## Tutorial
+The best way to learn how to use **CSSlib** is through the tutorial notebook located at the [tests directory](tests/csslib_example.ipynb) or at the [google collab](https://colab.research.google.com/drive/1OzYe7QXuL-BYXROnEh7hvuIW08xGlZO2?usp=sharing).
+
+## References & Citing
+If you use this code, please consider citing works that actively used the CSS approach, which resulted in the creation of this library:
+
+1. A.V. Krautsou, I.S. Humonen, V.D. Lazarev, R.A. Eremin, S.A. Budennyy<br/>
+   "Impact of crystal structure symmetry in training datasets on GNN-based energy assessments for chemically disordered CsPbI<sub>3</sub>"<br/>
+   https://doi.org/10.1038/s41598-025-92669-3
+2. N.A. Matsokin, R.A. Eremin, A.A. Kuznetsova, I.S. Humonen, A.V. Krautsou, V.D. Lazarev, Y.Z. Vassilyeva, A.Y. Pak, S.A. Budennyy, A.G. Kvashnin, A.A. Osiptsov<br/>
+   "Discovery of chemically modified higher tungsten boride by means of hybrid GNN/DFT approach"<br/>
+   https://doi.org/10.1038/s41524-025-01628-z
+3. R.A. Zaripov, R.A. Eremin, I.S. Humonen, A.V. Krautsou, V.V. Kuznetsov, K.E. GermanS, S.A. Budennyy, S.V. Levchenko</br>
+   "First-principles data-driven approach for assessment of stability of Tc-C systems"</br>
+   https://doi.org/10.1016/j.actamat.2025.121704

csslib-1.2/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "csslib"
+version = "1.2"
+authors = [
+  { name="A.V. Krautsou" },
+  { name="A.A. Solovykh" },
+]
+readme = "README.md"
+description = "CSSlib is an open-source code for building configuration search space (CSS) of disordered crystals, loading of the CSS dataset obtained, local/remote MPI or SLURM calculations and data visualization."
+requires-python = ">=3.10, <3.14"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "jupyter >=1.0.0, <= 1.1.1",
+    "matplotlib >=3.10.7, <= 3.10.8",
+    "numpy >=1.26.4, <= 2.4.2",
+    "pandas >=2.3.2, < 3.0",
+    "paramiko >= 4.0.0",
+    "plotly >=6.3.1, <= 6.5.2",
+    "pydantic >=2.12.5",
+    "pymatgen ==2025.6.14",
+    "pymatgen-analysis-defects ==2025.1.18",
+    "scipy >=1.15.3, <1.17.1",
+    "scp >= 0.15.0",
+    "tqdm >=4.67.1, <= 4.67.3",
+    "networkx >=3.4.2, <= 3.6.1",
+]
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[dependency-groups]
+espresso = [
+    "pymatgen-io-espresso @ git+https://github.com/Griffin-Group/pymatgen-io-espresso",
+]
+all = [
+    {include-group = "espresso"},
+]

csslib-1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

csslib-1.2/src/csslib/__init__.py

@@ -0,0 +1,11 @@
+"""Main csslib file."""
+
+from csslib.css import *
+from csslib.tools import *
+from csslib.config import *
+
+from csslib.css import __all__ as __css_all__
+from csslib.tools import __all__ as __tools_all__
+from csslib.config import __all__ as __config_all__
+
+__all__ = __css_all__ + __tools_all__ + __config_all__

csslib-1.2/src/csslib/config.py

@@ -0,0 +1,153 @@
+"""Module with pydantic model classes for configs validation (Config, Substitution) and overview functions with information about available 
+config fields and the example config."""
+
+__all__ = [
+    'get_available_config_fields',
+    'get_example_config'
+]
+
+from csslib.logging_ import get_config_logger
+from pydantic import BaseModel, ConfigDict
+
+logger = get_config_logger()
+
+class Substitution(BaseModel):
+    """
+        Substitution field pydantic scheme class of the config.
+        
+        Fields:
+            specie_to_substitute (str): the chemical element that must be replaced.
+            substitute_with (str): the chemical element that will replace the original chemical element.
+            substitution_low_limit (float): lower boundary of the substitution. Restrictions: >= 0 and < 1. Example: 0.05.
+            substitution_high_limit (float): higher boundary of the substitution. Restrictions: > 0, <= 1 and > substitution_low_limit. Example: 0.5.
+        
+        Fields that must be empty:
+            substitution_low_limit_natoms (int): the minimum number of atoms that must be replaced.
+            substitution_high_limit_natoms (int): the maximum number of atoms that must be replaced.
+            indices_to_substitute (list[int]): the list of atom indices that must be replaced.
+            substitute_with_labels (list[str]): labels of chemical elements that will replace the original chemical elements.
+            labels_to_substitute (list[str]): labels of chemical elements that must be replaced.
+    """
+    model_config = ConfigDict(extra="forbid")
+    specie_to_substitute: str
+    substitute_with: str
+    substitution_low_limit: float
+    substitution_high_limit: float
+    substitution_low_limit_natoms: int | None = None
+    substitution_high_limit_natoms: int | None = None
+    indices_to_substitute: list[int] | None = None
+    substitute_with_labels: list[str] | None = None
+    labels_to_substitute: list[str] | None = None
+
+    def __repr__(self):
+        message = '\n    Substitution(\n'
+        message += f'      specie_to_substitute="{self.specie_to_substitute}",\n'
+        message += f'      substitute_with="{self.substitute_with}",\n'
+        message += f'      substitution_low_limit={self.substitution_low_limit},\n'
+        message += f'      substitution_high_limit={self.substitution_high_limit},\n    )'
+        return message
+      
+    def __str__(self):
+        return self.__repr__()
+
+
+class Config(BaseModel):
+    """
+        Config pydantic scheme class.
+        
+        Fields:
+            result_dir (str): a full or relative path to the results directory.
+            structure_filename (str): a full or relative path to the .cif initial structure file.
+            supercell (str, optional): system replication numbers in the following format: "2x1x1", "2x2x1", ... Defaults to "1x1x1".
+            num_workers (int, optional): the number of parallel processes. Defaults to 1.
+            fictive_atoms (list): list with fictive atom names. Must be filled. If there are no one fictive atom type in the system fictive_atoms should be [].  
+            substitution (list[Substitutions], optional): list of required substitutions for the system.
+    """
+    model_config = ConfigDict(extra="forbid")
+    result_dir: str
+    structure_filename: str
+    supercell: str = "1x1x1"
+    num_workers: int = 1
+    fictive_atoms: list
+    substitution: list[Substitution] | None = None
+    
+    @classmethod
+    def model_validate_json(cls, json_data: str | bytes | bytearray,):
+        model = super().model_validate_json(json_data)
+        logger.info(f"The following config is read:\n{model}")
+        return model
+    
+    def __repr__(self):
+        message = 'Config(\n'
+        message += f'  result_dir="{self.result_dir}",\n'
+        message += f'  structure_filename="{self.structure_filename}",\n'
+        message += f'  supercell="{self.supercell}",\n'
+        message += f'  num_workers={self.num_workers},\n'
+        message += f'  fictive_atoms={self.fictive_atoms},\n'
+        message += f'  substitution=['
+        if self.substitution is not None:
+            for indx, subst in enumerate(self.substitution):
+                message += subst.__repr__()
+                if len(self.substitution) > 1 and indx != len(self.substitution) - 1:
+                    message += ','
+                if indx == len(self.substitution) - 1:
+                    message += '\n  '
+        message += f']\n)\n'
+        return message
+      
+    def __str__(self):
+        return self.__repr__()
+
+
+def get_available_config_fields():
+    """
+        Prints all possible config field names.
+    """
+    message = '\nList of available config fields:\n'
+    message += '  - "result_dir" - full or relative path to the results directory (mandatory)\n'
+    message += '  - "structure_filename" - full or relative path to the .cif initial structure file (mandatory)\n'
+    message += '  - "supercell" - system replication numbers in the following format: "2x1x1", "2x2x1", ... (optional, default value - "1x1x1")\n'
+    message += '  - "num_workers" - number of parallel processes (optional, default value - 1)\n'
+    message += '  - "fictive_atoms" - list with fictive atom names. Must be filled. If there are no one fictive atom type in the system fictive_atoms should be [] (mandatory)\n'
+    message += '  - "substitution" - list of required substitutions for the system (optional). The field has the following subfields:\n'
+    message += '    - "specie_to_substitute" - string with a chemical element which should be replaced (mandatory)\n'
+    message += '    - "substitute_with" - string with with a chemical element that will replace the original chemical element (mandatory)\n'
+    message += '    - "substitution_low_limit" - float value containing lower boundary of the substitution (mandatory). Example: 0.05\n'
+    message += '    - "substitution_high_limit" - float value containing higher boundary of the substitution (mandatory). Example: 0.5\n'
+    message += '    Internal parameters:\n'
+    message += '    - "substitution_low_limit_natoms"\n'
+    message += '    - "substitution_high_limit_natoms"\n'
+    message += '    - "indices_to_substitute"\n'
+    message += '    - "substitute_with_labels"\n'
+    message += '    - "labels_to_substitute"\n'
+    message += 'Example config can be obtained by the `get_example_config` function of `csslib.config`.\n'
+    logger.info(message)
+
+
+def get_example_config():
+    """
+        Prints example config.
+    """
+    message = '''
+{
+  "result_dir": "path-to-directory-with-results",
+  "structure_filename": "path-to-cif-file",
+  "supercell": "1x1x1",
+  "num_workers":  1,
+  "fictive_atoms": ['X', 'N'],
+  "substitution": [
+    {
+      "specie_to_substitute": "X",
+      "substitute_with": "Y",
+      "substitution_low_limit": 0.0,
+      "substitution_high_limit": 0.05
+    },
+    {
+      "specie_to_substitute": "E",
+      "substitute_with": "N",
+      "substitution_low_limit": 0.0,
+      "substitution_high_limit": 0.06
+    }
+  ]
+}'''
+    logger.info(message)