atompack.ase_bridge
===================

.. py:module:: atompack.ase_bridge

.. autoapi-nested-parse::

   ASE conversion helpers for atompack.



Functions
---------

.. autoapisummary::

   atompack.ase_bridge.to_ase
   atompack.ase_bridge.to_ase_batch
   atompack.ase_bridge.from_ase
   atompack.ase_bridge.add_ase_batch


Module Contents
---------------

.. py:function:: to_ase(molecule, *, attach_calc=True, calc_mode='singlepoint', copy_info=True, copy_arrays=True)

   Convert an atompack molecule to ``ase.Atoms``.

   The conversion reads directly from the molecule getters, so it works for
   both owned and view-backed molecules without going through ``molecule.atoms()``.
   That keeps the path compatible with lazy SOA-backed molecules, although ASE
   object creation still requires Python/NumPy allocations.

   Mapping rules:

   - ``positions`` and ``atomic_numbers`` always become the ASE geometry.
   - ``cell`` and ``pbc`` are copied when present.
   - ``velocities`` are attached with ``atoms.set_velocities(...)``.
   - ``energy``, ``forces``, ``stress``, and ``charges`` are attached through
     an ASE calculator when ``attach_calc=True``. ``calc_mode="singlepoint"``
     preserves ASE's snapshot semantics, while ``calc_mode="nocopy"`` is
     faster but does not snapshot the atoms state.
   - Custom properties shaped like per-atom arrays are stored in
     ``atoms.arrays`` when ``copy_arrays=True``.
   - Remaining custom properties are stored in ``atoms.info`` when
     ``copy_info=True``.

   Parameters
   ----------
   molecule : atompack.Molecule
       Molecule to convert.
   attach_calc : bool, default=True
       Attach supported builtin results through an ASE calculator.
   calc_mode : {"singlepoint", "nocopy", "none"}, default="singlepoint"
       Calculator attachment mode. ``"singlepoint"`` uses ASE's standard
       snapshotting calculator, ``"nocopy"`` skips the internal atoms copy for
       higher throughput, and ``"none"`` suppresses calculator attachment.
   copy_info : bool, default=True
       Copy non-array custom properties into ``atoms.info``.
   copy_arrays : bool, default=True
       Copy per-atom custom arrays into ``atoms.arrays``.

   Returns
   -------
   ase.Atoms
       Converted ASE object.


.. py:function:: to_ase_batch(source, indices=None, *, attach_calc=True, calc_mode='singlepoint', copy_info=True, copy_arrays=True)

   Convert many atompack molecules to ASE Atoms efficiently.


.. py:function:: from_ase(atoms, energy=None, forces=None, charges=None, velocities=None, cell=None, stress=None, copy_info=True, copy_arrays=True, info=None)

   Convert one ASE Atoms object to an atompack Molecule.

   Custom values from ``atoms.info``, ``atoms.arrays``, calculator results,
   and explicit ``info=`` overrides are stored as molecule-scope properties.
   Array shape is not used to infer atom-property scope during ingestion.


.. py:function:: add_ase_batch(db, atoms_list, *, copy_info=True, copy_arrays=True, info=None, batch_size=512)

   Write many ASE Atoms objects efficiently, preserving supported metadata.