Metadata-Version: 2.5
Name: structuretoolkit
Version: 0.0.46
Summary: build, analyse and visualise atomistic structures for materials science
Project-URL: Homepage, https://github.com/pyiron/structuretoolkit
Project-URL: Documentation, https://github.com/pyiron/structuretoolkit
Project-URL: Repository, https://github.com/pyiron/structuretoolkit
Author-email: Jan Janssen <janssen@mpie.de>
License: BSD 3-Clause License
        
        Copyright (c) 2018, Max-Planck-Institut für Eisenforschung GmbH - Computational Materials Design (CM) Department
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        * Redistributions of source code must retain the above copyright notice, this
          list of conditions and the following disclaimer.
        
        * 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.
        
        * 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.
License-File: LICENSE
Keywords: pyiron
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.15,>=3.10
Requires-Dist: ase<=3.29.0,>=3.24.0
Requires-Dist: numpy<=2.5.3,>=1.23.5
Requires-Dist: scipy<=1.18.0,>=1.15.0
Provides-Extra: clusters
Requires-Dist: scikit-learn==1.8.0; extra == 'clusters'
Provides-Extra: dscribe
Requires-Dist: dscribe==2.1.2; extra == 'dscribe'
Provides-Extra: grainboundary
Requires-Dist: aimsgb<=1.1.1,>=1.0.2; extra == 'grainboundary'
Requires-Dist: pymatgen<=2026.5.4,>=2026.3.23; extra == 'grainboundary'
Provides-Extra: matplotlib
Requires-Dist: matplotlib==3.11.1; extra == 'matplotlib'
Provides-Extra: mp-api
Requires-Dist: mp-api==0.45.15; extra == 'mp-api'
Requires-Dist: pymatgen<=2026.5.4,>=2026.3.23; extra == 'mp-api'
Provides-Extra: nglview
Requires-Dist: nglview<=4.0.1,>=2.7.7; extra == 'nglview'
Provides-Extra: phonopy
Requires-Dist: phonopy<=4.4.0,>=2.21.2; extra == 'phonopy'
Requires-Dist: spglib==2.7.0; extra == 'phonopy'
Provides-Extra: plotly
Requires-Dist: plotly<=7.0.0,>=6.0.0; extra == 'plotly'
Provides-Extra: pyscal
Requires-Dist: pyscal3<=3.3.2,>=3.2.5; extra == 'pyscal'
Provides-Extra: surface
Requires-Dist: pymatgen<=2026.5.4,>=2026.3.23; extra == 'surface'
Requires-Dist: spglib==2.7.0; extra == 'surface'
Provides-Extra: symmetry
Requires-Dist: spglib==2.7.0; extra == 'symmetry'
Description-Content-Type: text/markdown

# structuretoolkit 

[![Pipeline](https://github.com/pyiron/structuretoolkit/actions/workflows/pipeline.yml/badge.svg)](https://github.com/pyiron/structuretoolkit/actions/workflows/pipeline.yml)
[![codecov](https://codecov.io/gh/pyiron/structuretoolkit/graph/badge.svg?token=B6I4OACKND)](https://codecov.io/gh/pyiron/structuretoolkit)
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/pyiron/structuretoolkit/HEAD)

`structuretoolkit` extends the [`ase.atoms.Atoms`](https://wiki.fysik.dtu.dk/ase/ase/atoms.html) class from the
[Atomic Simulation Environment (ASE)](https://wiki.fysik.dtu.dk/ase/) with a large collection of additional
functions for **building**, **analysing** and **visualising** atomistic structures in materials science. It does
not introduce a structure class of its own &ndash; every function takes an `ase.atoms.Atoms` object as input and,
where applicable, returns one again, so `structuretoolkit` combines freely with the rest of the ASE ecosystem
(`ase.build`, ASE calculators, ASE I/O, ...). `structuretoolkit` also powers the structure-analysis backend of
[`pyiron_atomistics`](https://github.com/pyiron/pyiron_atomistics), where the same functions are available as
methods directly on the structure object.

## Example

```python
import structuretoolkit as stk
from ase.build import bulk

structure = bulk("Al", cubic=True)
stk.analyse.get_adaptive_cna_descriptors(structure)
stk.plot3d(structure)
```

## Features 
### Analysis
* `stk.analyse.get_neighbors()` - find the nearest neighbors of every atom, by count or cutoff radius, periodic-boundary-aware
* `stk.analyse.get_neighborhood()` - find the nearest neighbors of an arbitrary point in space, e.g. an interstitial site
* `stk.analyse.get_equivalent_atoms()` - label atoms that map onto each other under the structure's symmetry operations
* `stk.analyse.get_steinhardt_parameters()` - compute rotationally invariant Steinhardt bond-orientational order parameters
* `stk.analyse.get_centro_symmetry_descriptors()` - compute the centrosymmetry parameter, large for atoms near a defect
* `stk.analyse.get_diamond_structure_descriptors()` - identify cubic/hexagonal diamond local environments
* `stk.analyse.get_adaptive_cna_descriptors()` - classify local crystal structure (fcc/hcp/bcc/icosahedral/other) via common neighbor analysis
* `stk.analyse.get_voronoi_volumes()` - compute the Voronoi cell volume of every atom
* `stk.analyse.find_solids()` - count how many atoms are "solid" vs. "liquid"-like, e.g. for melting-point calculations
* `stk.analyse.get_mean_positions()` - average atomic positions across periodic boundary conditions
* `stk.analyse.get_average_of_unique_labels()` - average values that share the same (possibly repeated) integer label
* `stk.analyse.get_interstitials()` - locate interstitial sites of a given coordination number (e.g. tetrahedral, octahedral)
* `stk.analyse.get_layers()` - group atoms into layers along the cell directions or arbitrary planes
* `stk.analyse.get_voronoi_vertices()` - compute the Voronoi vertices of the (periodic) structure
* `stk.analyse.get_voronoi_neighbors()` - find pairs of atoms sharing a Voronoi facet
* `stk.analyse.get_delaunay_neighbors()` - find pairs of atoms sharing a Delaunay tetrahedron
* `stk.analyse.get_cluster_positions()` - cluster nearby positions together via DBSCAN
* `stk.analyse.get_strain()` - compute the per-atom Lagrangian strain tensor relative to a reference structure

### Build
* `stk.build.get_grainboundary_info()` - list the geometrically possible grain boundaries (by CSL sigma value) for a rotation axis
* `stk.build.grainboundary()` - build a bicrystal grain-boundary structure for a chosen sigma value and plane
* `stk.build.high_index_surface()` - build a stepped/kinked high-index surface slab
* `stk.build.get_high_index_surface_info()` - derive the Miller index for a given terrace/step/kink orientation
* `stk.build.sqs_structures()` - generate special quasirandom structures (SQS) for disordered alloys
* `stk.build.B2()` - build a cubic AB B2 (CsCl-type) intermetallic structure
* `stk.build.C14()` - build a hexagonal AB2 C14 Laves phase structure
* `stk.build.C15()` - build a cubic AB2 C15 Laves phase structure
* `stk.build.C36()` - build a hexagonal AB2 C36 Laves phase structure
* `stk.build.D03()` - build a cubic AB3 D03 structure

### Visualize 
* `stk.visualize.plot3d()` - render an `Atoms` object in 3d, via NGLView or plotly

### Common 
* `stk.common.ase_to_pymatgen()` - convert an `ase.atoms.Atoms` object to a `pymatgen.core.Structure`
* `stk.common.pymatgen_to_ase()` - convert a `pymatgen.core.Structure` back to an `ase.atoms.Atoms` object
* `stk.common.pymatgen_read_from_file()` - read a structure file directly into an `ase.atoms.Atoms` object via pymatgen
* `stk.common.ase_to_pyscal()` - convert an `ase.atoms.Atoms` object to a `pyscal3.core.System`
* `stk.common.apply_strain()` - apply a homogeneous strain to a structure's cell, and its atoms
* `stk.common.center_coordinates_in_unit_cell()` - wrap atomic coordinates back into the unit cell
* `stk.common.get_extended_positions()` - repeat atoms across the periodic boundary to include neighbor images
* `stk.common.get_vertical_length()` - get the height of the cell perpendicular to each face
* `stk.common.get_wrapped_coordinates()` - wrap arbitrary Cartesian coordinates into the periodic cell
* `stk.common.select_index()` - get the indices of atoms of a given chemical element

## Documentation 

* [structuretoolkit](https://structuretoolkit.readthedocs.io/en/latest/README.html)
  * [Example](https://structuretoolkit.readthedocs.io/en/latest/README.html#example)
  * [Features](https://structuretoolkit.readthedocs.io/en/latest/README.html#features)
* [Introduction](https://structuretoolkit.readthedocs.io/en/latest/introduction.html)
  * [How the package is organised](https://structuretoolkit.readthedocs.io/en/latest/introduction.html#how-the-package-is-organised)
  * [Helpers and converters](https://structuretoolkit.readthedocs.io/en/latest/introduction.html#structuretoolkit-common-helpers-and-converters)
  * [Analysing existing structures](https://structuretoolkit.readthedocs.io/en/latest/introduction.html#structuretoolkit-analyse-analysing-existing-structures)
  * [Constructing new structures](https://structuretoolkit.readthedocs.io/en/latest/introduction.html#structuretoolkit-build-constructing-new-structures)
  * [Looking at structures](https://structuretoolkit.readthedocs.io/en/latest/introduction.html#structuretoolkit-visualize-looking-at-structures)
  * [Where to go from here](https://structuretoolkit.readthedocs.io/en/latest/introduction.html#where-to-go-from-here)
* [Interface](https://structuretoolkit.readthedocs.io/en/latest/api.html)