Metadata-Version: 2.4
Name: atomforge-py
Version: 0.1.0
Summary: Python interface for AtomForge: load, edit, and view atomic structures
Author: AtomForge Contributors
Author-email: AtomForge Contributors <albert.hzbn@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/albert-hzbn/AtomForge
Project-URL: Repository, https://github.com/albert-hzbn/AtomForge
Project-URL: Bug Tracker, https://github.com/albert-hzbn/AtomForge/issues
Keywords: atomforge,atoms,crystal,materials,structure,viewer
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.8
Description-Content-Type: text/x-rst
Provides-Extra: ase
Requires-Dist: ase>=3.22; extra == "ase"
Dynamic: author
Dynamic: requires-python

atomforge — Python interface for AtomForge
==========================================

Load, programmatically edit, and launch the AtomForge GUI to view atomic
structures directly from Python.

Quick-start
-----------

.. code-block:: python

    import atomforge as af

    # Load any format (XYZ/extXYZ natively; CIF/VASP/PDB via ase extra)
    s = af.load("crystal.cif")

    # Build from scratch
    s2 = af.Structure()
    s2.set_cell(2.87, 2.87, 2.87)   # BCC iron unit cell
    s2.add_atom("Fe", 0.0,   0.0,   0.0)
    s2.add_atom("Fe", 1.435, 1.435, 1.435)

    # Supercell + open in the AtomForge GUI (non-blocking)
    s2.repeat(4, 4, 4).view()

    # Edit and save
    s2.translate(1, 0, 0).save("shifted.xyz")

Formats
-------
XYZ and extended-XYZ are handled natively with no dependencies.
CIF, VASP/POSCAR, PDB, LAMMPS, mol2, and all other ASE-supported formats
are available via the ``ase`` extra::

    pip install "atomforge[ase]"

Viewing
-------
``structure.view()`` serialises the structure to a temporary XYZ file and
launches the AtomForge executable as a detached subprocess.  Set the
``ATOMFORGE_PATH`` environment variable to the full path of ``AtomForge.exe``
if it is not on PATH.
