.. _LMDBFormat:

lmdb format
===========

Class: :class:`LMDBFormat <dpdata.lmdb.format.LMDBFormat>`


Class for handling the LMDB format, which stores atomic configurations in a
Lightning Memory-Mapped Database (LMDB).

This format is optimized for machine learning workflows where fast, random
access to a large number of frames is required. All frames from multiple
systems (with potentially different numbers of atoms) are stored in a
single LMDB database file.

Both single systems and multiple systems are supported via the standard
``dpdata`` APIs.














.. rubric:: Examples

**Saving a single LabeledSystem**

>>> import dpdata
>>> system = dpdata.LabeledSystem("path/to/input.vasp", fmt="vasp/outcar")
>>> system.to("lmdb", "my_single_system.lmdb")

**Loading a single LabeledSystem**

>>> loaded_system = dpdata.LabeledSystem("my_single_system.lmdb", fmt="lmdb")

**Saving multiple systems to a single LMDB database**

>>> import dpdata
>>> system_1 = dpdata.LabeledSystem("path/to/system1/OUTCAR", fmt="vasp/outcar")
>>> system_2 = dpdata.LabeledSystem("path/to/system2/OUTCAR", fmt="vasp/outcar")
>>> multi_systems_obj = dpdata.MultiSystems(system_1, system_2)
>>> multi_systems_obj.to("lmdb", "my_multi_system_db.lmdb")

**Loading multiple systems from a single LMDB database**

>>> import dpdata
>>> loaded_multi_systems = dpdata.MultiSystems.from_file("my_multi_system_db.lmdb", fmt="lmdb")


Conversions
-----------

.. _LMDBFormat_from_system:

Convert from this format to System
``````````````````````````````````

.. py:function:: dpdata.System(file_name, fmt: Literal['lmdb'] = None) -> dpdata.system.System
   :noindex:
.. py:function:: dpdata.System.from_lmdb(file_name) -> dpdata.system.System
   :noindex:

   
Load data for a single System from an LMDB database.





:Returns:

    System
        converted system















.. _LMDBFormat_to_system:

Convert from System to this format
``````````````````````````````````

.. py:function:: dpdata.System.to(fmt: Literal['lmdb'], file_name)
   :noindex:
.. py:function:: dpdata.System.to_lmdb(file_name)
   :noindex:

   
Save a single System to an LMDB database.




















.. _LMDBFormat_to_labeled_system:

Convert from LabeledSystem to this format
`````````````````````````````````````````

.. py:function:: dpdata.LabeledSystem.to(fmt: Literal['lmdb'], file_name)
   :noindex:
.. py:function:: dpdata.LabeledSystem.to_lmdb(file_name)
   :noindex:

   
Save a single LabeledSystem to an LMDB database.




















.. _LMDBFormat_from_labeled_system:

Convert from this format to LabeledSystem
`````````````````````````````````````````

.. py:function:: dpdata.LabeledSystem(file_name, fmt: Literal['lmdb'] = None) -> dpdata.system.LabeledSystem
   :noindex:
.. py:function:: dpdata.LabeledSystem.from_lmdb(file_name) -> dpdata.system.LabeledSystem
   :noindex:

   
Load data for a single LabeledSystem from an LMDB database.





:Returns:

    LabeledSystem
        converted system















.. _LMDBFormat_from_multi_systems:

Convert from this format to MultiSystems
````````````````````````````````````````

.. py:function:: dpdata.MultiSystems.from_lmdb(file_name, map_size=1000000000) -> dpdata.system.MultiSystems
   :noindex:

   
Load multiple systems from a single LMDB database.


:Parameters:

    **file_name** : str
        The path to the LMDB database directory.

    **map_size** : int, optional
        Maximum size of the LMDB database in bytes.



:Returns:

    MultiSystems
        converted system















.. _LMDBFormat_to_multi_systems:

Convert from MultiSystems to this format
````````````````````````````````````````

.. py:function:: dpdata.MultiSystems.to(fmt: Literal['lmdb'], directory, map_size=1000000000, frame_idx_fmt='012d') -> dpdata.system.MultiSystems
   :noindex:
.. py:function:: dpdata.MultiSystems.to_lmdb(directory, map_size=1000000000, frame_idx_fmt='012d') -> dpdata.system.MultiSystems
   :noindex:

   
Implement MultiSystems.to for LMDB format.


:Parameters:

    **directory** : str
        directory of system

    **map_size** : int, optional
        Maximum size of the LMDB database in bytes. Default is 1GB.

    **frame_idx_fmt** : str, optional
        The format string used to encode the frame index as a key. Default is "012d".



:Returns:

    MultiSystems
        this system