Metadata-Version: 2.4
Name: atomlib
Version: 0.4
Summary: A modern, extensible library for creating atomic structures
Author-email: Colin Gilgenbach <hexane@mit.edu>
License-Expression: MPL-2.0
Project-URL: Repository, https://github.com/hexane360/atomlib.git
Project-URL: Documentation, https://hexane360.github.io/atomlib/
Keywords: science,atoms,materials,chemistry
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: click~=8.1
Requires-Dist: numpy<2.3.0,>=1.22
Requires-Dist: scipy~=1.8
Requires-Dist: polars~=1.31.0
Requires-Dist: matplotlib~=3.5
Requires-Dist: requests~=2.28
Requires-Dist: lxml~=5.0
Requires-Dist: typing-extensions~=4.4
Requires-Dist: importlib_resources>=5.0
Provides-Extra: dev
Requires-Dist: pytest>=6.2.4; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: coveragepy-lcov>=0.1.1; extra == "dev"
Requires-Dist: nbmake>=1.4.1; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs==1.6.1; extra == "docs"
Requires-Dist: mkdocs-material==9.5.40; extra == "docs"
Requires-Dist: mkdocstrings[python]==0.26.1; extra == "docs"
Requires-Dist: markdown-include==0.8.1; extra == "docs"
Requires-Dist: mike==2.1.3; extra == "docs"
Requires-Dist: black>=24.3.0; extra == "docs"
Dynamic: license-file

# atomlib: A modern, extensible library for creating atomic structures
[![][ci-badge]][ci-url] [![][commit-badge]][commit-url] [![][docs-stable-badge]][docs-stable-url] [![][docs-dev-badge]][docs-dev-url]

`atomlib` is a package for creating, modifying, and controlling atomic structures. It draws heavy inspiration from previous tools like [Atomsk][atomsk] and [ASE][ase], but attempts to provide a cleaner, more consistent interface that can be used from Python or a command line.

`atomlib` has minimal dependencies: `numpy`, `scipy`, and `polars` are required for core atom structure manipulation, and `click` is required for command line functionality.

## Atomic representation & supported properties

Atomic structures are stored as `polars` DataFrames, providing a clean, immutable interface that maximizes expressiveness and minimizes errors.
For formats that allow arbitrary properties, these properties can be passed through transparently. `atomlib` has first-class support for fractional occupancy, Debye-Waller factors, atomic forces, and labels.

Translational symmetry is stored in `Cell` objects, which represent a fully generic cell. Atoms can be modified in any coordinate system that makes sense (global, local real-space, cell fraction, box fraction, etc.). Support for non-translational symmetry operations is limited at this point.

For more information, check out the example notebooks and the API documentation.

## Currently supported file formats

File format support is still a work in progress. Where possible, parsers are implemented from scratch in-repo.
Most formats are implemented in two steps: Parsing to an intermediate representation which preserves all format-specific information, and then conversion to the generic `Atoms` & `AtomCell` types for manipulation & display.
This means you can write your own code to utilize advanced format features even if they're not supported out of the box.

| Format                 | Ext.    | Read               | Write              | Notes |
| :--------------------- | :------ | :----------------: | :----------------: | :---- |
| [CIF][cif]             | .cif    | :white_check_mark: | :white_check_mark: | CIF1 & CIF2. Isotropic B-factor only |
| [XCrysDen][xsf]        | .xsf    | :white_check_mark: | :white_check_mark: |       |
| [AtomEye CFG][cfg]     | .cfg    | :white_check_mark: | :white_check_mark: | Currently basic format only |
| [Basic XYZ][xyz]       | .xyz    | :white_check_mark: | :white_check_mark: |       |
| [Ext. XYZ][xyz]        | .exyz   | :white_check_mark: | :white_check_mark: | Arbitrary properties not implemented |
| [Special XYZ][xyz]     | .sxyz   | :x:                | :x:                | To be implemented |
| [LAMMPS Data][lmp]     | .lmp    | :white_check_mark: | :white_check_mark: |       |
| [Quantum Espresso][qe] | .qe     | :x:                | :white_check_mark: | pw.x format  |
| [pyMultislicer][pyM]   | .mslice | :white_check_mark: | :white_check_mark: | Currently XML format only |

[atomsk]: https://atomsk.univ-lille.fr/
[ase]: https://wiki.fysik.dtu.dk/ase/
[cif]: https://www.iucr.org/resources/cif
[xsf]: http://www.xcrysden.org/doc/XSF.html
[cfg]: https://atomsk.univ-lille.fr/doc/en/format_cfg.html
[xyz]: https://atomsk.univ-lille.fr/doc/en/format_xyz.html
[lmp]: https://docs.lammps.org/read_data.html
[qe]: https://www.quantum-espresso.org/Doc/INPUT_PW.html
[pyM]: https://github.com/LeBeauGroup/pyMultislicer

[ci-badge]: https://github.com/hexane360/atomlib/workflows/CI/badge.svg
[ci-url]: https://github.com/hexane360/atomlib/actions?query=workflow%3ACI
[docs-dev-badge]: https://img.shields.io/badge/docs-dev-blue
[docs-dev-url]: https://hexane360.github.io/atomlib/dev/
[docs-stable-badge]: https://img.shields.io/badge/docs-stable-blue
[docs-stable-url]: https://hexane360.github.io/atomlib/latest/
[commit-badge]: https://img.shields.io/github/last-commit/hexane360/atomlib
[commit-url]: https://github.com/hexane360/atomlib/commits
