From 3fb7627a491c12f57f6f3157d44b5afc977192f3 Mon Sep 17 00:00:00 2001 From: clpetix Date: Wed, 19 Mar 2025 08:51:26 -0500 Subject: [PATCH 01/30] Fix project name typo. --- doc/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 49d2741..e9e3fa0 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -13,7 +13,7 @@ # -- Project information ----------------------------------------------------- -project = "lammmpsio" +project = "lammpsio" year = datetime.date.today().year copyright = f"2021-{year}, Auburn University" author = "Michael P. Howard" From 4bb18067273b3d164c767812d7ad30a926014c12 Mon Sep 17 00:00:00 2001 From: clpetix Date: Wed, 19 Mar 2025 09:29:54 -0500 Subject: [PATCH 02/30] Add community guidelines section with contribution instructions --- doc/source/guide/guidelines.rst | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 doc/source/guide/guidelines.rst diff --git a/doc/source/guide/guidelines.rst b/doc/source/guide/guidelines.rst new file mode 100644 index 0000000..12f7e34 --- /dev/null +++ b/doc/source/guide/guidelines.rst @@ -0,0 +1,27 @@ +==================== +Community Guidelines +==================== + +We ask that you please review and adhere to our `Code of Conduct`_. + + +Reporting Issues +================ +If you encounter any bugs or issues while using ``lammpsio``, please report them +on our `GitHub Issues page`_. + +Contributing +============= +We welcome contributions to ``lammpsio`` via GitHub pull requests. We ask that +you please open an issue first to discuss your proposed changes before +submitting a pull request. This helps us to understand the context of your +changes and to ensure that they mesh well with the existing codebase. + +Seeking Help +============ +If you have questions or need help using ``lammpsio``, please feel free to reach +out to us via our `GitHub Discussions page`_. + +.. _Code of Conduct: http://github.com/mphowardlab/lammpsio/blob/main/CODE_OF_CONDUCT.md +.. _GitHub Issues page: http://github.com/mphowardlab/lammpsio/issues +.. _GitHub Discussions page: http://github.com/mphowardlab/lammpsio/discussions From 7d6d8d745e6b7fae141b4073e752f2066d5ebc4f Mon Sep 17 00:00:00 2001 From: clpetix Date: Wed, 19 Mar 2025 09:30:37 -0500 Subject: [PATCH 03/30] Add statement of need to landing page. --- doc/source/index.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/source/index.rst b/doc/source/index.rst index db5c178..e0f3f20 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,7 +1,12 @@ lammpsio documentation ====================== -Tools for working with LAMMPS data and dump files. +Tools for working with LAMMPS data and dump files. This package provides +a Python interface for reading and writing LAMMPS data files, as well as +tools for parsing LAMMPS dump files. It also allows for easy conversion +between HOOMD-Blue's GSD format and LAMMPS data files. It is designed to +be easy to use and flexible, allowing users to work with LAMMPS files +in a variety of ways that improve workflow efficiency and reproducibility. .. toctree:: @@ -11,6 +16,7 @@ Tools for working with LAMMPS data and dump files. guide/install guide/examples/index guide/release + guide/guidelines guide/license guide/credits From 3197ed1e3a5d15aeb4caf0b6f7056f33b0475120 Mon Sep 17 00:00:00 2001 From: clpetix Date: Mon, 14 Apr 2025 12:53:20 -0500 Subject: [PATCH 04/30] Update copyright year to 2025. --- LICENSE | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/LICENSE b/LICENSE index 4c295f6..14a0229 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright (c) 2021-2024, Auburn University +Copyright (c) 2021-2025, Auburn University All rights reserved. From fb2e8ad5d59d0e5d0572937c39f1b630ae7e452e Mon Sep 17 00:00:00 2001 From: clpetix Date: Mon, 14 Apr 2025 14:43:35 -0500 Subject: [PATCH 05/30] Add overview sections to API docs. --- doc/source/api/box.rst | 8 ++++++++ doc/source/api/data.rst | 8 ++++++++ doc/source/api/dump.rst | 8 ++++++++ doc/source/api/snapshot.rst | 8 ++++++++ doc/source/api/topology.rst | 13 +++++++++++++ 5 files changed, 45 insertions(+) diff --git a/doc/source/api/box.rst b/doc/source/api/box.rst index e4b0c3e..76eacf2 100644 --- a/doc/source/api/box.rst +++ b/doc/source/api/box.rst @@ -1,6 +1,14 @@ box --- +Overview +======== + +.. autosummary:: + :nosignatures: + + lammpsio.box.Box + .. automodule:: lammpsio.box :members: :show-inheritance: diff --git a/doc/source/api/data.rst b/doc/source/api/data.rst index 97b526c..4fdaa77 100644 --- a/doc/source/api/data.rst +++ b/doc/source/api/data.rst @@ -1,6 +1,14 @@ data ---- +Overview +======== + +.. autosummary:: + :nosignatures: + + lammpsio.data.DataFile + .. automodule:: lammpsio.data :members: :show-inheritance: diff --git a/doc/source/api/dump.rst b/doc/source/api/dump.rst index dc0874f..3d2e63f 100644 --- a/doc/source/api/dump.rst +++ b/doc/source/api/dump.rst @@ -1,6 +1,14 @@ dump ---- +Overview +======== + +.. autosummary:: + :nosignatures: + + lammpsio.dump.DumpFile + .. automodule:: lammpsio.dump :members: :show-inheritance: diff --git a/doc/source/api/snapshot.rst b/doc/source/api/snapshot.rst index 09dcd73..14b938a 100644 --- a/doc/source/api/snapshot.rst +++ b/doc/source/api/snapshot.rst @@ -1,6 +1,14 @@ snapshot -------- +Overview +======== + +.. autosummary:: + :nosignatures: + + lammpsio.snapshot.Snapshot + .. automodule:: lammpsio.snapshot :members: :show-inheritance: diff --git a/doc/source/api/topology.rst b/doc/source/api/topology.rst index 7e427db..dbbfc98 100644 --- a/doc/source/api/topology.rst +++ b/doc/source/api/topology.rst @@ -1,6 +1,19 @@ topology -------- +Overview +======== + +.. autosummary:: + :nosignatures: + + lammpsio.topology.Angles + lammpsio.topology.Bonds + lammpsio.topology.Dihedrals + lammpsio.topology.Impropers + lammpsio.topology.LabelMap + lammpsio.topology.Topology + .. automodule:: lammpsio.topology :members: :show-inheritance: From 680d240cf80fb4080f5c6b846597fbc9391af82d Mon Sep 17 00:00:00 2001 From: clpetix Date: Mon, 14 Apr 2025 15:41:23 -0500 Subject: [PATCH 06/30] Add examples to Box class. --- src/lammpsio/box.py | 44 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-) diff --git a/src/lammpsio/box.py b/src/lammpsio/box.py index 1e4e09a..0c2c0a4 100644 --- a/src/lammpsio/box.py +++ b/src/lammpsio/box.py @@ -21,6 +21,21 @@ class Box: Tilt factors ``xy``, ``xz``, and ``yz`` for a triclinic box. Default of ``None`` is a strictly orthorhombic box. + Examples + -------- + Construct a triclinic simulation box:: + + box = lammpsio.Box([-5.0, -10.0, 0.0], [1.0, 10.0, 8.0], [1.0, -2.0, 0.5]) + + >>> print(box.low) + [-5.0, -10.0, 0.0] + + >>> print(box.high) + [1.0, 10.0, 8.0] + + >>> print(box.tilt) + [1.0, -2.0, 0.5] + """ def __init__(self, low, high, tilt=None): @@ -50,6 +65,18 @@ def cast(cls, value): :class:`Box` A simulation box matching the array. + Examples + -------- + Construct an orthorhombic simulation box by casting an array:: + + box = lammpsio.Box.cast([-5.0, -10.0, 0.0, 1.0, 10.0, 8.0]) + + >>> print(box.low) + [-5.0, -10.0, 0.0] + + >>> print(box.high) + [1.0, 10.0, 8.0] + """ if isinstance(value, Box): return value @@ -65,7 +92,10 @@ def cast(cls, value): @property def low(self): - """:class:`numpy.ndarray`: Box low.""" + """:class:`numpy.ndarray`: Box low. + + The low of the box is used as the origin of the box. + """ return self._low @low.setter @@ -77,7 +107,10 @@ def low(self, value): @property def high(self): - """:class:`numpy.ndarray`: Box high.""" + """:class:`numpy.ndarray`: Box high. + + The high of the box is used to compute the edge lengths of the box. + """ return self._high @high.setter @@ -89,7 +122,12 @@ def high(self, value): @property def tilt(self): - """:class:`numpy.ndarray`: Box tilt factors.""" + """:class:`numpy.ndarray`: Box tilt factors. + + The tilt factors, ``xy``, ``xz``, and ``yz`` are used to define the + shape of the box. The default of ``None`` is a strictly orthorhombic. + + """ return self._tilt @tilt.setter From 28aeaf9797da1215a4950129d4ecad1e4abdbca9 Mon Sep 17 00:00:00 2001 From: clpetix Date: Tue, 15 Apr 2025 10:36:42 -0500 Subject: [PATCH 07/30] Make doc strings consistent formatting for booleans. --- src/lammpsio/dump.py | 2 +- src/lammpsio/snapshot.py | 26 +++++++++++++------------- src/lammpsio/topology.py | 20 ++++++++++++-------- 3 files changed, 26 insertions(+), 22 deletions(-) diff --git a/src/lammpsio/dump.py b/src/lammpsio/dump.py index 9800e90..3102f5d 100644 --- a/src/lammpsio/dump.py +++ b/src/lammpsio/dump.py @@ -35,7 +35,7 @@ class DumpFile: Schema for the contents of the file. Defaults to ``None``, which means to read it from the file. sort_ids : bool - If true, sort the particles by ID in each snapshot. + If ``True``, sort the particles by ID in each snapshot. copy_from : :class:`Snapshot` If specified, copy fields that are missing in the dump file but are set in a reference :class:`Snapshot`. The fields that can be copied are ``typeid``, diff --git a/src/lammpsio/snapshot.py b/src/lammpsio/snapshot.py index adfe773..1d7c807 100644 --- a/src/lammpsio/snapshot.py +++ b/src/lammpsio/snapshot.py @@ -373,7 +373,7 @@ def has_id(self): Returns ------- bool - True if particle IDs have been initialized. + ``True`` if particle IDs have been initialized. """ return self._id is not None @@ -405,7 +405,7 @@ def has_position(self): Returns ------- bool - True if positions have been initialized. + ``True`` if positions have been initialized. """ return self._position is not None @@ -437,7 +437,7 @@ def has_image(self): Returns ------- bool - True if images have been initialized. + ``True`` if images have been initialized. """ return self._image is not None @@ -469,7 +469,7 @@ def has_velocity(self): Returns ------- bool - True if velocities have been initialized. + ``True`` if velocities have been initialized. """ return self._velocity is not None @@ -501,7 +501,7 @@ def has_molecule(self): Returns ------- bool - True if molecule tags have been initialized. + ``True`` if molecule tags have been initialized. """ return self._molecule is not None @@ -551,7 +551,7 @@ def has_typeid(self): Returns ------- bool - True if types have been initialized. + ``True`` if types have been initialized. """ return self._typeid is not None @@ -583,7 +583,7 @@ def has_charge(self): Returns ------- bool - True if charges have been initialized. + ``True`` if charges have been initialized. """ return self._charge is not None @@ -615,7 +615,7 @@ def has_mass(self): Returns ------- bool - True if masses have been initialized. + ``True`` if masses have been initialized. """ return self._mass is not None @@ -654,7 +654,7 @@ def has_bonds(self): Returns ------- bool - True if bonds is initialized and there is at least one bond. + ``True`` if bonds is initialized and there is at least one bond. """ return self._bonds is not None and self._bonds.N > 0 @@ -679,7 +679,7 @@ def has_angles(self): Returns ------- bool - True if angles is initialized and there is at least one angle. + ``True`` if angles is initialized and there is at least one angle. """ return self._angles is not None and self._angles.N > 0 @@ -704,7 +704,7 @@ def has_dihedrals(self): Returns ------- bool - True if dihedrals is initialized and there is at least one dihedral. + ``True`` if dihedrals is initialized and there is at least one dihedral. """ return self._dihedrals is not None and self._dihedrals.N > 0 @@ -729,7 +729,7 @@ def has_impropers(self): Returns ------- bool - True if impropers is initialized and there is at least one improper. + ``True`` if impropers is initialized and there is at least one improper. """ return self._impropers is not None and self._impropers.N > 0 @@ -742,7 +742,7 @@ def reorder(self, order, check_order=True): order : list New order of indexes. check_order : bool - If true, validate the new ``order`` before applying it. + If ``True``, validate the new ``order`` before applying it. """ # sanity check the sorting order before applying it diff --git a/src/lammpsio/topology.py b/src/lammpsio/topology.py index e237f61..1413334 100644 --- a/src/lammpsio/topology.py +++ b/src/lammpsio/topology.py @@ -62,7 +62,7 @@ def has_id(self): Returns ------- bool - True if connection IDs have been initialized. + ``True`` if connection IDs have been initialized. """ return self._id is not None @@ -94,7 +94,7 @@ def has_typeid(self): Returns ------- bool - True if connection typeids have been initialized. + ``True`` if connection typeids have been initialized. """ return self._typeid is not None @@ -126,7 +126,7 @@ def has_members(self): Returns ------- bool - True if particle members have been initialized. + ``True`` if particle members have been initialized. """ return self._members is not None @@ -172,7 +172,7 @@ def reorder(self, order, check_order=True): order : list New order of indexes. check_order : bool - If true, validate the new ``order`` before applying it. + If ``True``, validate the new ``order`` before applying it. """ # sanity check the sorting order before applying it @@ -201,7 +201,8 @@ class Bonds(Topology): N : int Number of bonds. num_types : int - Number of bond types. + Number of bond types. Default of ``None`` means + the number of types is determined from the unique typeids. """ @@ -217,7 +218,8 @@ class Angles(Topology): N : int Number of angles. num_types : int - Number of angle types. + Number of Angle types. Default of ``None`` means + the number of types is determined from the unique typeids. """ @@ -233,7 +235,8 @@ class Dihedrals(Topology): N : int Number of diehdrals. num_types : int - Number of dihedral types. + Number of Dihedral types. Default of ``None`` means + the number of types is determined from the unique typeids. """ @@ -249,7 +252,8 @@ class Impropers(Topology): N : int Number of improper dihedrals. num_types : int - Number of improper dihedral types. + Number of improper dihedral types. Default of ``None`` means + the number of types is determined from the unique typeids. """ From 75b0378ae25fec418a39a597f03943192a4c8e26 Mon Sep 17 00:00:00 2001 From: clpetix Date: Thu, 17 Apr 2025 10:40:00 -0500 Subject: [PATCH 08/30] Remove redundant :class: statements in docs. --- doc/source/guide/credits.rst | 2 +- doc/source/index.rst | 8 +++----- src/lammpsio/box.py | 4 ++-- src/lammpsio/dump.py | 8 ++++---- src/lammpsio/snapshot.py | 10 +++++----- 5 files changed, 15 insertions(+), 17 deletions(-) diff --git a/doc/source/guide/credits.rst b/doc/source/guide/credits.rst index 166d5bb..01ec5b0 100644 --- a/doc/source/guide/credits.rst +++ b/doc/source/guide/credits.rst @@ -5,4 +5,4 @@ Credits * Michael P. Howard * Mayukh Kundu * Philipp Leclercq -* C. Levi Petix +* C\. Levi Petix diff --git a/doc/source/index.rst b/doc/source/index.rst index e0f3f20..0641ee3 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,11 +1,9 @@ lammpsio documentation ====================== -Tools for working with LAMMPS data and dump files. This package provides -a Python interface for reading and writing LAMMPS data files, as well as -tools for parsing LAMMPS dump files. It also allows for easy conversion -between HOOMD-Blue's GSD format and LAMMPS data files. It is designed to -be easy to use and flexible, allowing users to work with LAMMPS files +lammpsio provides a Python interface for reading and writing LAMMPS +data and dump files. It also enables interconversion with HOOMD-blue's +GSD format. This flexible package enables users to work with LAMMPS files in a variety of ways that improve workflow efficiency and reproducibility. diff --git a/src/lammpsio/box.py b/src/lammpsio/box.py index 0c2c0a4..3955204 100644 --- a/src/lammpsio/box.py +++ b/src/lammpsio/box.py @@ -45,7 +45,7 @@ def __init__(self, low, high, tilt=None): @classmethod def cast(cls, value): - """Cast an array to a :class:`Box`. + """Cast an array to a `Box`. If ``value`` has 6 elements, it is unpacked as an orthorhombic box:: @@ -62,7 +62,7 @@ def cast(cls, value): Returns ------- - :class:`Box` + `Box` A simulation box matching the array. Examples diff --git a/src/lammpsio/dump.py b/src/lammpsio/dump.py index 3102f5d..6ef8bd8 100644 --- a/src/lammpsio/dump.py +++ b/src/lammpsio/dump.py @@ -36,9 +36,9 @@ class DumpFile: it from the file. sort_ids : bool If ``True``, sort the particles by ID in each snapshot. - copy_from : :class:`Snapshot` + copy_from : `Snapshot` If specified, copy fields that are missing in the dump file but are set in - a reference :class:`Snapshot`. The fields that can be copied are ``typeid``, + a reference `Snapshot`. The fields that can be copied are ``typeid``, ``molecule``, ``charge``, and ``mass``. """ @@ -60,12 +60,12 @@ def create(cls, filename, schema, snapshots): Path to dump file. schema : dict Schema for the contents of the file. - snapshots : :class:`Snapshot` or list + snapshots : `Snapshot` or list One or more snapshots to write to the dump file. Returns ------- - :class:`DumpFile` + `DumpFile` The object representing the new dump file. """ diff --git a/src/lammpsio/snapshot.py b/src/lammpsio/snapshot.py index 1d7c807..6701ee2 100644 --- a/src/lammpsio/snapshot.py +++ b/src/lammpsio/snapshot.py @@ -14,7 +14,7 @@ class Snapshot: ---------- N : int Number of particles in configuration. - box : :class:`Box` + box : `Box` Simulation box. step : int Simulation time step counter. Default of ``None`` means @@ -58,7 +58,7 @@ def from_hoomd_gsd(cls, frame): Returns ------- - :class:`Snapshot` + `Snapshot` Snapshot created from HOOMD GSD frame. dict A map from the :attr:`Snapshot.typeid` to the HOOMD type. @@ -343,7 +343,7 @@ def N(self): @property def box(self): - """:class:`Box`: Simulation box.""" + """`Box`: Simulation box.""" return self._box @property @@ -782,12 +782,12 @@ def _set_type_id(lammps_typeid, gsd_typeid, label_map): List of LAMMPS typeids to be mapped (one-indexed). gsd_typeid : list List of HOOMD GSD typeids to be updated (zero-indexed). - label_map : :class:`LabelMap` + label_map : `LabelMap` LabelMap for connection type mapping LAMMPS typeids to HOOMD GSD types. Returns: ------- - :class:`LabelMap` + `LabelMap` LabelMap mapping LAMMPS typeids to HOOMD GSD types. LabelMap is created mapping typeids to str(typeids) if not provided. """ From 97e134934121ce562f9253ceccb42dfa70342cac Mon Sep 17 00:00:00 2001 From: clpetix Date: Thu, 17 Apr 2025 10:52:32 -0500 Subject: [PATCH 09/30] Make API documentation 1 landing page. --- .../api/api reference/lammpsio.Angles.rst | 35 ++++++++++++ .../api/api reference/lammpsio.Bonds.rst | 35 ++++++++++++ doc/source/api/api reference/lammpsio.Box.rst | 29 ++++++++++ .../api/api reference/lammpsio.DataFile.rst | 31 ++++++++++ .../api/api reference/lammpsio.Dihedrals.rst | 35 ++++++++++++ .../api/api reference/lammpsio.DumpFile.rst | 29 ++++++++++ .../api/api reference/lammpsio.Impropers.rst | 35 ++++++++++++ .../api/api reference/lammpsio.LabelMap.rst | 36 ++++++++++++ .../api/api reference/lammpsio.Snapshot.rst | 56 +++++++++++++++++++ doc/source/api/api.rst | 19 +++++++ doc/source/api/box.rst | 14 ----- doc/source/api/data.rst | 14 ----- doc/source/api/dump.rst | 14 ----- doc/source/api/snapshot.rst | 14 ----- doc/source/api/topology.rst | 19 ------- doc/source/index.rst | 12 +--- 16 files changed, 341 insertions(+), 86 deletions(-) create mode 100644 doc/source/api/api reference/lammpsio.Angles.rst create mode 100644 doc/source/api/api reference/lammpsio.Bonds.rst create mode 100644 doc/source/api/api reference/lammpsio.Box.rst create mode 100644 doc/source/api/api reference/lammpsio.DataFile.rst create mode 100644 doc/source/api/api reference/lammpsio.Dihedrals.rst create mode 100644 doc/source/api/api reference/lammpsio.DumpFile.rst create mode 100644 doc/source/api/api reference/lammpsio.Impropers.rst create mode 100644 doc/source/api/api reference/lammpsio.LabelMap.rst create mode 100644 doc/source/api/api reference/lammpsio.Snapshot.rst create mode 100644 doc/source/api/api.rst delete mode 100644 doc/source/api/box.rst delete mode 100644 doc/source/api/data.rst delete mode 100644 doc/source/api/dump.rst delete mode 100644 doc/source/api/snapshot.rst delete mode 100644 doc/source/api/topology.rst diff --git a/doc/source/api/api reference/lammpsio.Angles.rst b/doc/source/api/api reference/lammpsio.Angles.rst new file mode 100644 index 0000000..f0fc746 --- /dev/null +++ b/doc/source/api/api reference/lammpsio.Angles.rst @@ -0,0 +1,35 @@ +lammpsio.Angles +=============== + +.. currentmodule:: lammpsio + +.. autoclass:: Angles + + + .. automethod:: __init__ + + + .. rubric:: Methods + + .. autosummary:: + + ~Angles.__init__ + ~Angles.has_id + ~Angles.has_members + ~Angles.has_typeid + ~Angles.reorder + + + + + + .. rubric:: Attributes + + .. autosummary:: + + ~Angles.N + ~Angles.id + ~Angles.members + ~Angles.num_types + ~Angles.type_label + ~Angles.typeid diff --git a/doc/source/api/api reference/lammpsio.Bonds.rst b/doc/source/api/api reference/lammpsio.Bonds.rst new file mode 100644 index 0000000..4cbcbdb --- /dev/null +++ b/doc/source/api/api reference/lammpsio.Bonds.rst @@ -0,0 +1,35 @@ +lammpsio.Bonds +============== + +.. currentmodule:: lammpsio + +.. autoclass:: Bonds + + + .. automethod:: __init__ + + + .. rubric:: Methods + + .. autosummary:: + + ~Bonds.__init__ + ~Bonds.has_id + ~Bonds.has_members + ~Bonds.has_typeid + ~Bonds.reorder + + + + + + .. rubric:: Attributes + + .. autosummary:: + + ~Bonds.N + ~Bonds.id + ~Bonds.members + ~Bonds.num_types + ~Bonds.type_label + ~Bonds.typeid diff --git a/doc/source/api/api reference/lammpsio.Box.rst b/doc/source/api/api reference/lammpsio.Box.rst new file mode 100644 index 0000000..482ee56 --- /dev/null +++ b/doc/source/api/api reference/lammpsio.Box.rst @@ -0,0 +1,29 @@ +lammpsio.Box +============ + +.. currentmodule:: lammpsio + +.. autoclass:: Box + + + .. automethod:: __init__ + + + .. rubric:: Methods + + .. autosummary:: + + ~Box.__init__ + ~Box.cast + + + + + + .. rubric:: Attributes + + .. autosummary:: + + ~Box.high + ~Box.low + ~Box.tilt diff --git a/doc/source/api/api reference/lammpsio.DataFile.rst b/doc/source/api/api reference/lammpsio.DataFile.rst new file mode 100644 index 0000000..9897db4 --- /dev/null +++ b/doc/source/api/api reference/lammpsio.DataFile.rst @@ -0,0 +1,31 @@ +lammpsio.DataFile +================= + +.. currentmodule:: lammpsio + +.. autoclass:: DataFile + + + .. automethod:: __init__ + + + .. rubric:: Methods + + .. autosummary:: + + ~DataFile.__init__ + ~DataFile.create + ~DataFile.read + + + + + + .. rubric:: Attributes + + .. autosummary:: + + ~DataFile.known_bodies + ~DataFile.known_headers + ~DataFile.unknown_bodies + ~DataFile.unknown_headers diff --git a/doc/source/api/api reference/lammpsio.Dihedrals.rst b/doc/source/api/api reference/lammpsio.Dihedrals.rst new file mode 100644 index 0000000..868445b --- /dev/null +++ b/doc/source/api/api reference/lammpsio.Dihedrals.rst @@ -0,0 +1,35 @@ +lammpsio.Dihedrals +================== + +.. currentmodule:: lammpsio + +.. autoclass:: Dihedrals + + + .. automethod:: __init__ + + + .. rubric:: Methods + + .. autosummary:: + + ~Dihedrals.__init__ + ~Dihedrals.has_id + ~Dihedrals.has_members + ~Dihedrals.has_typeid + ~Dihedrals.reorder + + + + + + .. rubric:: Attributes + + .. autosummary:: + + ~Dihedrals.N + ~Dihedrals.id + ~Dihedrals.members + ~Dihedrals.num_types + ~Dihedrals.type_label + ~Dihedrals.typeid diff --git a/doc/source/api/api reference/lammpsio.DumpFile.rst b/doc/source/api/api reference/lammpsio.DumpFile.rst new file mode 100644 index 0000000..b27a327 --- /dev/null +++ b/doc/source/api/api reference/lammpsio.DumpFile.rst @@ -0,0 +1,29 @@ +lammpsio.DumpFile +================= + +.. currentmodule:: lammpsio + +.. autoclass:: DumpFile + + + .. automethod:: __init__ + + + .. rubric:: Methods + + .. autosummary:: + + ~DumpFile.__init__ + ~DumpFile.create + + + + + + .. rubric:: Attributes + + .. autosummary:: + + ~DumpFile.copy_from + ~DumpFile.filename + ~DumpFile.schema diff --git a/doc/source/api/api reference/lammpsio.Impropers.rst b/doc/source/api/api reference/lammpsio.Impropers.rst new file mode 100644 index 0000000..0755ced --- /dev/null +++ b/doc/source/api/api reference/lammpsio.Impropers.rst @@ -0,0 +1,35 @@ +lammpsio.Impropers +================== + +.. currentmodule:: lammpsio + +.. autoclass:: Impropers + + + .. automethod:: __init__ + + + .. rubric:: Methods + + .. autosummary:: + + ~Impropers.__init__ + ~Impropers.has_id + ~Impropers.has_members + ~Impropers.has_typeid + ~Impropers.reorder + + + + + + .. rubric:: Attributes + + .. autosummary:: + + ~Impropers.N + ~Impropers.id + ~Impropers.members + ~Impropers.num_types + ~Impropers.type_label + ~Impropers.typeid diff --git a/doc/source/api/api reference/lammpsio.LabelMap.rst b/doc/source/api/api reference/lammpsio.LabelMap.rst new file mode 100644 index 0000000..96dcb8e --- /dev/null +++ b/doc/source/api/api reference/lammpsio.LabelMap.rst @@ -0,0 +1,36 @@ +lammpsio.LabelMap +================= + +.. currentmodule:: lammpsio + +.. autoclass:: LabelMap + + + .. automethod:: __init__ + + + .. rubric:: Methods + + .. autosummary:: + + ~LabelMap.__init__ + ~LabelMap.clear + ~LabelMap.get + ~LabelMap.items + ~LabelMap.keys + ~LabelMap.pop + ~LabelMap.popitem + ~LabelMap.setdefault + ~LabelMap.update + ~LabelMap.values + + + + + + .. rubric:: Attributes + + .. autosummary:: + + ~LabelMap.typeid + ~LabelMap.types diff --git a/doc/source/api/api reference/lammpsio.Snapshot.rst b/doc/source/api/api reference/lammpsio.Snapshot.rst new file mode 100644 index 0000000..a15000d --- /dev/null +++ b/doc/source/api/api reference/lammpsio.Snapshot.rst @@ -0,0 +1,56 @@ +lammpsio.Snapshot +================= + +.. currentmodule:: lammpsio + +.. autoclass:: Snapshot + + + .. automethod:: __init__ + + + .. rubric:: Methods + + .. autosummary:: + + ~Snapshot.__init__ + ~Snapshot.from_hoomd_gsd + ~Snapshot.has_angles + ~Snapshot.has_bonds + ~Snapshot.has_charge + ~Snapshot.has_dihedrals + ~Snapshot.has_id + ~Snapshot.has_image + ~Snapshot.has_impropers + ~Snapshot.has_mass + ~Snapshot.has_molecule + ~Snapshot.has_position + ~Snapshot.has_typeid + ~Snapshot.has_velocity + ~Snapshot.reorder + ~Snapshot.to_hoomd_gsd + + + + + + .. rubric:: Attributes + + .. autosummary:: + + ~Snapshot.N + ~Snapshot.angles + ~Snapshot.bonds + ~Snapshot.box + ~Snapshot.charge + ~Snapshot.dihedrals + ~Snapshot.id + ~Snapshot.image + ~Snapshot.impropers + ~Snapshot.mass + ~Snapshot.molecule + ~Snapshot.num_types + ~Snapshot.position + ~Snapshot.type_label + ~Snapshot.typeid + ~Snapshot.velocity diff --git a/doc/source/api/api.rst b/doc/source/api/api.rst new file mode 100644 index 0000000..af6a2dc --- /dev/null +++ b/doc/source/api/api.rst @@ -0,0 +1,19 @@ +API +--- + +Overview +======== + +.. autosummary:: + :nosignatures: + :toctree: api reference + + lammpsio.Box + lammpsio.DataFile + lammpsio.DumpFile + lammpsio.Snapshot + lammpsio.Angles + lammpsio.Bonds + lammpsio.Dihedrals + lammpsio.Impropers + lammpsio.LabelMap diff --git a/doc/source/api/box.rst b/doc/source/api/box.rst deleted file mode 100644 index 76eacf2..0000000 --- a/doc/source/api/box.rst +++ /dev/null @@ -1,14 +0,0 @@ -box ---- - -Overview -======== - -.. autosummary:: - :nosignatures: - - lammpsio.box.Box - -.. automodule:: lammpsio.box - :members: - :show-inheritance: diff --git a/doc/source/api/data.rst b/doc/source/api/data.rst deleted file mode 100644 index 4fdaa77..0000000 --- a/doc/source/api/data.rst +++ /dev/null @@ -1,14 +0,0 @@ -data ----- - -Overview -======== - -.. autosummary:: - :nosignatures: - - lammpsio.data.DataFile - -.. automodule:: lammpsio.data - :members: - :show-inheritance: diff --git a/doc/source/api/dump.rst b/doc/source/api/dump.rst deleted file mode 100644 index 3d2e63f..0000000 --- a/doc/source/api/dump.rst +++ /dev/null @@ -1,14 +0,0 @@ -dump ----- - -Overview -======== - -.. autosummary:: - :nosignatures: - - lammpsio.dump.DumpFile - -.. automodule:: lammpsio.dump - :members: - :show-inheritance: diff --git a/doc/source/api/snapshot.rst b/doc/source/api/snapshot.rst deleted file mode 100644 index 14b938a..0000000 --- a/doc/source/api/snapshot.rst +++ /dev/null @@ -1,14 +0,0 @@ -snapshot --------- - -Overview -======== - -.. autosummary:: - :nosignatures: - - lammpsio.snapshot.Snapshot - -.. automodule:: lammpsio.snapshot - :members: - :show-inheritance: diff --git a/doc/source/api/topology.rst b/doc/source/api/topology.rst deleted file mode 100644 index dbbfc98..0000000 --- a/doc/source/api/topology.rst +++ /dev/null @@ -1,19 +0,0 @@ -topology --------- - -Overview -======== - -.. autosummary:: - :nosignatures: - - lammpsio.topology.Angles - lammpsio.topology.Bonds - lammpsio.topology.Dihedrals - lammpsio.topology.Impropers - lammpsio.topology.LabelMap - lammpsio.topology.Topology - -.. automodule:: lammpsio.topology - :members: - :show-inheritance: diff --git a/doc/source/index.rst b/doc/source/index.rst index 0641ee3..962bd7f 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -9,7 +9,6 @@ in a variety of ways that improve workflow efficiency and reproducibility. .. toctree:: :maxdepth: 1 - :caption: User guide guide/install guide/examples/index @@ -17,13 +16,4 @@ in a variety of ways that improve workflow efficiency and reproducibility. guide/guidelines guide/license guide/credits - -.. toctree:: - :maxdepth: 1 - :caption: API reference - - api/box - api/data - api/dump - api/snapshot - api/topology + api/api.rst From 4b17744faa77a6f918f62422241fd06f4de8b366 Mon Sep 17 00:00:00 2001 From: clpetix Date: Thu, 17 Apr 2025 10:54:49 -0500 Subject: [PATCH 10/30] Add installation instructions for conda. --- doc/source/guide/install.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/source/guide/install.rst b/doc/source/guide/install.rst index e290b82..3f1e776 100644 --- a/doc/source/guide/install.rst +++ b/doc/source/guide/install.rst @@ -8,6 +8,10 @@ The easiest way to get ``lammpsio`` is from PyPI using ``pip``: pip install lammpsio +or from conda-forge using ``conda`` or ``mamba``: +.. code:: bash + + conda install -c conda-forge lammpsio Building from source ==================== From e5250ea19a3fa87bfcce42f2005d0918de0b0369 Mon Sep 17 00:00:00 2001 From: clpetix Date: Mon, 21 Apr 2025 11:10:24 -0500 Subject: [PATCH 11/30] Submodule topology rather than individual topology types. --- .../api/api reference/lammpsio.Angles.rst | 35 ------------------ .../api/api reference/lammpsio.Bonds.rst | 35 ------------------ .../api/api reference/lammpsio.Dihedrals.rst | 35 ------------------ .../api/api reference/lammpsio.Impropers.rst | 35 ------------------ .../api/api reference/lammpsio.LabelMap.rst | 36 ------------------- .../api/api reference/lammpsio.topology.rst | 25 +++++++++++++ doc/source/api/api.rst | 6 +--- 7 files changed, 26 insertions(+), 181 deletions(-) delete mode 100644 doc/source/api/api reference/lammpsio.Angles.rst delete mode 100644 doc/source/api/api reference/lammpsio.Bonds.rst delete mode 100644 doc/source/api/api reference/lammpsio.Dihedrals.rst delete mode 100644 doc/source/api/api reference/lammpsio.Impropers.rst delete mode 100644 doc/source/api/api reference/lammpsio.LabelMap.rst create mode 100644 doc/source/api/api reference/lammpsio.topology.rst diff --git a/doc/source/api/api reference/lammpsio.Angles.rst b/doc/source/api/api reference/lammpsio.Angles.rst deleted file mode 100644 index f0fc746..0000000 --- a/doc/source/api/api reference/lammpsio.Angles.rst +++ /dev/null @@ -1,35 +0,0 @@ -lammpsio.Angles -=============== - -.. currentmodule:: lammpsio - -.. autoclass:: Angles - - - .. automethod:: __init__ - - - .. rubric:: Methods - - .. autosummary:: - - ~Angles.__init__ - ~Angles.has_id - ~Angles.has_members - ~Angles.has_typeid - ~Angles.reorder - - - - - - .. rubric:: Attributes - - .. autosummary:: - - ~Angles.N - ~Angles.id - ~Angles.members - ~Angles.num_types - ~Angles.type_label - ~Angles.typeid diff --git a/doc/source/api/api reference/lammpsio.Bonds.rst b/doc/source/api/api reference/lammpsio.Bonds.rst deleted file mode 100644 index 4cbcbdb..0000000 --- a/doc/source/api/api reference/lammpsio.Bonds.rst +++ /dev/null @@ -1,35 +0,0 @@ -lammpsio.Bonds -============== - -.. currentmodule:: lammpsio - -.. autoclass:: Bonds - - - .. automethod:: __init__ - - - .. rubric:: Methods - - .. autosummary:: - - ~Bonds.__init__ - ~Bonds.has_id - ~Bonds.has_members - ~Bonds.has_typeid - ~Bonds.reorder - - - - - - .. rubric:: Attributes - - .. autosummary:: - - ~Bonds.N - ~Bonds.id - ~Bonds.members - ~Bonds.num_types - ~Bonds.type_label - ~Bonds.typeid diff --git a/doc/source/api/api reference/lammpsio.Dihedrals.rst b/doc/source/api/api reference/lammpsio.Dihedrals.rst deleted file mode 100644 index 868445b..0000000 --- a/doc/source/api/api reference/lammpsio.Dihedrals.rst +++ /dev/null @@ -1,35 +0,0 @@ -lammpsio.Dihedrals -================== - -.. currentmodule:: lammpsio - -.. autoclass:: Dihedrals - - - .. automethod:: __init__ - - - .. rubric:: Methods - - .. autosummary:: - - ~Dihedrals.__init__ - ~Dihedrals.has_id - ~Dihedrals.has_members - ~Dihedrals.has_typeid - ~Dihedrals.reorder - - - - - - .. rubric:: Attributes - - .. autosummary:: - - ~Dihedrals.N - ~Dihedrals.id - ~Dihedrals.members - ~Dihedrals.num_types - ~Dihedrals.type_label - ~Dihedrals.typeid diff --git a/doc/source/api/api reference/lammpsio.Impropers.rst b/doc/source/api/api reference/lammpsio.Impropers.rst deleted file mode 100644 index 0755ced..0000000 --- a/doc/source/api/api reference/lammpsio.Impropers.rst +++ /dev/null @@ -1,35 +0,0 @@ -lammpsio.Impropers -================== - -.. currentmodule:: lammpsio - -.. autoclass:: Impropers - - - .. automethod:: __init__ - - - .. rubric:: Methods - - .. autosummary:: - - ~Impropers.__init__ - ~Impropers.has_id - ~Impropers.has_members - ~Impropers.has_typeid - ~Impropers.reorder - - - - - - .. rubric:: Attributes - - .. autosummary:: - - ~Impropers.N - ~Impropers.id - ~Impropers.members - ~Impropers.num_types - ~Impropers.type_label - ~Impropers.typeid diff --git a/doc/source/api/api reference/lammpsio.LabelMap.rst b/doc/source/api/api reference/lammpsio.LabelMap.rst deleted file mode 100644 index 96dcb8e..0000000 --- a/doc/source/api/api reference/lammpsio.LabelMap.rst +++ /dev/null @@ -1,36 +0,0 @@ -lammpsio.LabelMap -================= - -.. currentmodule:: lammpsio - -.. autoclass:: LabelMap - - - .. automethod:: __init__ - - - .. rubric:: Methods - - .. autosummary:: - - ~LabelMap.__init__ - ~LabelMap.clear - ~LabelMap.get - ~LabelMap.items - ~LabelMap.keys - ~LabelMap.pop - ~LabelMap.popitem - ~LabelMap.setdefault - ~LabelMap.update - ~LabelMap.values - - - - - - .. rubric:: Attributes - - .. autosummary:: - - ~LabelMap.typeid - ~LabelMap.types diff --git a/doc/source/api/api reference/lammpsio.topology.rst b/doc/source/api/api reference/lammpsio.topology.rst new file mode 100644 index 0000000..2421160 --- /dev/null +++ b/doc/source/api/api reference/lammpsio.topology.rst @@ -0,0 +1,25 @@ +lammpsio.topology +================= + +.. automodule:: lammpsio.topology + + + + + + + + + + + + .. rubric:: Classes + + .. autosummary:: + + Angles + Bonds + Dihedrals + Impropers + LabelMap + Topology diff --git a/doc/source/api/api.rst b/doc/source/api/api.rst index af6a2dc..420a83a 100644 --- a/doc/source/api/api.rst +++ b/doc/source/api/api.rst @@ -12,8 +12,4 @@ Overview lammpsio.DataFile lammpsio.DumpFile lammpsio.Snapshot - lammpsio.Angles - lammpsio.Bonds - lammpsio.Dihedrals - lammpsio.Impropers - lammpsio.LabelMap + lammpsio.topology From 0e932a9a61bbdc92e3ac865cfacc87ae78b5b163 Mon Sep 17 00:00:00 2001 From: clpetix Date: Mon, 28 Apr 2025 13:25:56 -0500 Subject: [PATCH 12/30] Fix formatting of class references in docstrings --- src/lammpsio/data.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/lammpsio/data.py b/src/lammpsio/data.py index c411f13..34d64d6 100644 --- a/src/lammpsio/data.py +++ b/src/lammpsio/data.py @@ -91,7 +91,7 @@ def create(cls, filename, snapshot, atom_style=None): ---------- filename : str Path to data file. - snapshot : :class:`Snapshot` + snapshot : `Snapshot` Snapshot to write to file. atom_style : str Atom style to use for data file. Defaults to ``None``, which means the @@ -99,7 +99,7 @@ def create(cls, filename, snapshot, atom_style=None): Returns ------- - :class:`DataFile` + `DataFile` The object representing the new data file. Raises @@ -300,7 +300,7 @@ def read(self): Returns ------- - :class:`Snapshot` + `Snapshot` Snapshot from the data file. Raises From df2434f6d6cceb08a437024b698444de8911e927 Mon Sep 17 00:00:00 2001 From: clpetix Date: Mon, 19 May 2025 16:29:55 -0500 Subject: [PATCH 13/30] Add sybil testing to documentation. --- src/lammpsio/box.py | 20 +++++++++----------- src/lammpsio/conftest.py | 24 ++++++++++++++++++++++++ 2 files changed, 33 insertions(+), 11 deletions(-) create mode 100644 src/lammpsio/conftest.py diff --git a/src/lammpsio/box.py b/src/lammpsio/box.py index 3955204..9330963 100644 --- a/src/lammpsio/box.py +++ b/src/lammpsio/box.py @@ -23,18 +23,18 @@ class Box: Examples -------- - Construct a triclinic simulation box:: + + Construct a triclinic simulation box: + + .. code-block:: python box = lammpsio.Box([-5.0, -10.0, 0.0], [1.0, 10.0, 8.0], [1.0, -2.0, 0.5]) - >>> print(box.low) - [-5.0, -10.0, 0.0] + assert numpy.allclose(box.low, [-5.0, -10.0, 0.0]) - >>> print(box.high) - [1.0, 10.0, 8.0] + assert numpy.allclose(box.high, [1.0, 10.0, 8.0]) - >>> print(box.tilt) - [1.0, -2.0, 0.5] + assert numpy.allclose(box.tilt, [1.0, -2.0, 0.5]) """ @@ -71,11 +71,9 @@ def cast(cls, value): box = lammpsio.Box.cast([-5.0, -10.0, 0.0, 1.0, 10.0, 8.0]) - >>> print(box.low) - [-5.0, -10.0, 0.0] + assert numpy.allclose(box.low, [-5.0, -10.0, 0.0]) - >>> print(box.high) - [1.0, 10.0, 8.0] + assert numpy.allclose(box.high, [1.0, 10.0, 8.0]) """ if isinstance(value, Box): diff --git a/src/lammpsio/conftest.py b/src/lammpsio/conftest.py new file mode 100644 index 0000000..e14a32a --- /dev/null +++ b/src/lammpsio/conftest.py @@ -0,0 +1,24 @@ +import numpy +import sybil +import sybil.parsers.rest + +import lammpsio + + +def setup_sybil_tests(namespace): + """Sybil setup function.""" + # Common imports. + namespace["numpy"] = numpy + namespace["lammpsio"] = lammpsio + + +if sybil is not None: + pytest_collect_file = sybil.Sybil( + parsers=[ + sybil.parsers.rest.PythonCodeBlockParser(), + sybil.parsers.rest.SkipParser(), + ], + pattern="*.py", + setup=setup_sybil_tests, + fixtures=["tmp_path"], + ).pytest() From 69ad6e733b6e16cb34ac4edc3b3fb24f3905f87c Mon Sep 17 00:00:00 2001 From: mayukhkundu14 <79770572+mayukh33@users.noreply.github.com> Date: Mon, 19 May 2025 23:47:29 -0500 Subject: [PATCH 14/30] Ensure doc test runs when sybil is installed --- src/lammpsio/conftest.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/lammpsio/conftest.py b/src/lammpsio/conftest.py index e14a32a..a97fce7 100644 --- a/src/lammpsio/conftest.py +++ b/src/lammpsio/conftest.py @@ -1,6 +1,11 @@ import numpy -import sybil -import sybil.parsers.rest + +try: + import sybil + import sybil.parsers.rest + +except ImportError: + sybil = None import lammpsio From 0502450344859d11db59526d95425cee4cab8a38 Mon Sep 17 00:00:00 2001 From: mayukhkundu14 <79770572+mayukh33@users.noreply.github.com> Date: Tue, 20 May 2025 22:50:14 -0500 Subject: [PATCH 15/30] Add sybil to requirements.txt --- requirements.txt | 1 + src/lammpsio/box.py | 4 +++- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 1382eda..bf0b474 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,2 +1,3 @@ numpy packaging +sybil \ No newline at end of file diff --git a/src/lammpsio/box.py b/src/lammpsio/box.py index 9330963..a6cdfa6 100644 --- a/src/lammpsio/box.py +++ b/src/lammpsio/box.py @@ -67,7 +67,9 @@ def cast(cls, value): Examples -------- - Construct an orthorhombic simulation box by casting an array:: + Construct an orthorhombic simulation box by casting an array: + + .. code-block:: python box = lammpsio.Box.cast([-5.0, -10.0, 0.0, 1.0, 10.0, 8.0]) From 3c4df672882738939fd0518891cc55ab6755057f Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 21 May 2025 03:53:29 +0000 Subject: [PATCH 16/30] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index bf0b474..79ac141 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,3 @@ numpy packaging -sybil \ No newline at end of file +sybil From e33942179ec51a9160e6be2b0722a2af1792d5e2 Mon Sep 17 00:00:00 2001 From: mayukhkundu14 <79770572+mayukh33@users.noreply.github.com> Date: Tue, 20 May 2025 23:09:13 -0500 Subject: [PATCH 17/30] Minor fix --- requirements.txt | 1 - tests/requirements.txt | 1 + 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 79ac141..1382eda 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,2 @@ numpy packaging -sybil diff --git a/tests/requirements.txt b/tests/requirements.txt index 69a6b01..72bd04e 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -1,2 +1,3 @@ pytest>=8 pytest-lazy-fixtures>=1.1.1 +sybil From e77577dbd3fe1a891c24a40f0f7f539fd0ee7db3 Mon Sep 17 00:00:00 2001 From: mayukhkundu14 <79770572+mayukh33@users.noreply.github.com> Date: Tue, 20 May 2025 23:16:30 -0500 Subject: [PATCH 18/30] Add example to the data module --- src/lammpsio/data.py | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/src/lammpsio/data.py b/src/lammpsio/data.py index 34d64d6..4320e4a 100644 --- a/src/lammpsio/data.py +++ b/src/lammpsio/data.py @@ -39,6 +39,27 @@ class DataFile: unknown_bodies : list Data file body sections that will be ignored. + Example + ------- + + Create and read a data file: + + .. code-block:: python + + filename = tmp_path / "atoms.data" + + box = lammpsio.Box([-5.0, -10.0, 0.0], [1.0, 10.0, 8.0], [1.0, -2.0, 0.5]) + + snap = lammpsio.Snapshot(3, box, 10) + + data = lammpsio.DataFile.create(filename, snap, "atomic") + + assert filename.exists + + snap_2 = data.read() + + assert snap_2.N == snap.N + """ def __init__(self, filename, atom_style=None): From c281b462a1396005563be3fe1b2735f962935995 Mon Sep 17 00:00:00 2001 From: mayukhkundu14 <79770572+mayukh33@users.noreply.github.com> Date: Tue, 20 May 2025 23:17:04 -0500 Subject: [PATCH 19/30] Add example to the dump module --- src/lammpsio/dump.py | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/src/lammpsio/dump.py b/src/lammpsio/dump.py index 6ef8bd8..aaeef2e 100644 --- a/src/lammpsio/dump.py +++ b/src/lammpsio/dump.py @@ -41,6 +41,31 @@ class DumpFile: a reference `Snapshot`. The fields that can be copied are ``typeid``, ``molecule``, ``charge``, and ``mass``. + Example + ------- + + Create and read a dump file: + + .. code-block:: python + + filename = tmp_path / "atoms.data" + + box = lammpsio.Box([-5.0, -10.0, 0.0], [1.0, 10.0, 8.0], [1.0, -2.0, 0.5]) + + snap = lammpsio.Snapshot(3, box, 10) + + schema = {"id": 0, "position": (1, 2, 3)} + + f = lammpsio.DumpFile.create(filename, schema, snap) + + assert filename.exists + + f = lammpsio.DumpFile(filename, schema) + + read_snap = [s for s in f] + + assert read_snap[0].N == snap.N + """ def __init__(self, filename, schema=None, sort_ids=True, copy_from=None): From b073323cbc05e9cc3e7a36784b2ef27be1567667 Mon Sep 17 00:00:00 2001 From: mayukhkundu14 <79770572+mayukh33@users.noreply.github.com> Date: Thu, 22 May 2025 16:10:31 -0500 Subject: [PATCH 20/30] Move confest.py to root dir. --- src/lammpsio/conftest.py => conftest.py | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename src/lammpsio/conftest.py => conftest.py (100%) diff --git a/src/lammpsio/conftest.py b/conftest.py similarity index 100% rename from src/lammpsio/conftest.py rename to conftest.py From 6ba53b56d90ec10f69eccd76e87b5967dd348840 Mon Sep 17 00:00:00 2001 From: mayukhkundu14 <79770572+mayukh33@users.noreply.github.com> Date: Fri, 23 May 2025 15:11:00 -0500 Subject: [PATCH 21/30] Add documentation for snapshot --- src/lammpsio/snapshot.py | 290 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 276 insertions(+), 14 deletions(-) diff --git a/src/lammpsio/snapshot.py b/src/lammpsio/snapshot.py index 6701ee2..ba17847 100644 --- a/src/lammpsio/snapshot.py +++ b/src/lammpsio/snapshot.py @@ -25,6 +25,17 @@ class Snapshot: step : int Simulation time step counter. + Example + ------- + + Create snapshot using a triclinic box: + + .. code-block:: python + + box = lammpsio.Box([-5.0, -10.0, 0.0], [1.0, 10.0, 8.0], [1.0, -2.0, 0.5]) + + snap = lammpsio.Snapshot(3, box, 10) + """ def __init__(self, N, box, step=None, num_types=None): @@ -63,6 +74,23 @@ def from_hoomd_gsd(cls, frame): dict A map from the :attr:`Snapshot.typeid` to the HOOMD type. + Example + ------- + + Create snapshot from a GSD file: + + .. code-block:: python + + import gsd.hoomd + + frame = gsd.hoomd.Frame() + + frame.configuration.box = [4, 5, 6, 0.1, 0.2, 0.3] + + frame.particles.N = 3 + + snap_2, type_map = lammpsio.Snapshot.from_hoomd_gsd(frame) + """ # ensures frame is well formed and that we have NumPy arrays frame.validate() @@ -216,6 +244,15 @@ def to_hoomd_gsd(self, type_map=None): :class:`gsd.hoomd.Frame` Converted HOOMD GSD frame. + Example + ------- + + Convert snapshot to a GSD file: + + .. code-block:: python + + frame = snap_2.to_hoomd_gsd() + """ if _compatibility.gsd_version is None: raise ImportError("GSD package not found") @@ -338,17 +375,42 @@ def to_hoomd_gsd(self, type_map=None): @property def N(self): - """int: Number of particles.""" + """int: Number of particles. + + Example + ------- + .. code-block:: python + + num_particles = snap.N + + """ return self._N @property def box(self): - """`Box`: Simulation box.""" + """`Box`: Simulation box. + + Example + ------- + .. code-block:: python + + snap.box + + """ return self._box @property def id(self): - """:class:`numpy.ndarray`: Particle IDs.""" + """:class:`numpy.ndarray`: Particle IDs. + + Example + ------- + + .. code-block:: python + + snap.id = [2, 0, 1] + + """ if not self.has_id(): self._id = numpy.arange(1, self.N + 1) return self._id @@ -375,12 +437,29 @@ def has_id(self): bool ``True`` if particle IDs have been initialized. + Example + ------- + .. code-block:: python + + snap.has_id() + """ return self._id is not None @property def position(self): - """:class:`numpy.ndarray`: Positions.""" + """:class:`numpy.ndarray`: Positions. + + Example + ------- + + .. code-block:: python + + snap.position = [[0.1, 0.2, 0.3], + [-0.4, -0.5, -0.6], + [0.7, 0.8, 0.9]] + + """ if not self.has_position(): self._position = numpy.zeros((self.N, 3), dtype=float) return self._position @@ -407,12 +486,28 @@ def has_position(self): bool ``True`` if positions have been initialized. + Example + ------- + + .. code-block:: python + + snap.has_position() + """ return self._position is not None @property def image(self): - """:class:`numpy.ndarray`: Images.""" + """:class:`numpy.ndarray`: Images. + + Example + ------- + + .. code-block:: python + + snap.image = [[1, 2, 3], [-4, -5, -6], [7, 8, 9]] + + """ if not self.has_image(): self._image = numpy.zeros((self.N, 3), dtype=int) return self._image @@ -439,12 +534,30 @@ def has_image(self): bool ``True`` if images have been initialized. + Example + ------- + + .. code-block:: python + + snap.has_image() + """ return self._image is not None @property def velocity(self): - """:class:`numpy.ndarray`: Velocities.""" + """:class:`numpy.ndarray`: Velocities. + + Example + ------- + + .. code-block:: python + + snap.velocity = [[-3, -2, -1], + [6, 5, 4], + [9, 8, 7]] + + """ if not self.has_velocity(): self._velocity = numpy.zeros((self.N, 3), dtype=float) return self._velocity @@ -471,6 +584,13 @@ def has_velocity(self): bool ``True`` if velocities have been initialized. + Example + ------- + + .. code-block:: python + + snap.has_velocity() + """ return self._velocity is not None @@ -503,6 +623,13 @@ def has_molecule(self): bool ``True`` if molecule tags have been initialized. + Example + ------- + + .. code-block:: python + + snap.has_molecule() + """ return self._molecule is not None @@ -526,7 +653,16 @@ def num_types(self, value): @property def typeid(self): - """:class:`numpy.ndarray`: Types.""" + """:class:`numpy.ndarray`: Types. + + Example + ------- + + .. code-block:: python + + snap.typeid = [2, 1, 2] + + """ if not self.has_typeid(): self._typeid = numpy.ones(self.N, dtype=int) return self._typeid @@ -553,12 +689,28 @@ def has_typeid(self): bool ``True`` if types have been initialized. + Example + ------- + + .. code-block:: python + + snap.has_typeid() + """ return self._typeid is not None @property def charge(self): - """:class:`numpy.ndarray`: Charges.""" + """:class:`numpy.ndarray`: Charges. + + Example + ------- + + .. code-block:: python + + snap.charge = [-1, 0, 1] + + """ if not self.has_charge(): self._charge = numpy.zeros(self.N, dtype=float) return self._charge @@ -585,12 +737,28 @@ def has_charge(self): bool ``True`` if charges have been initialized. + Example + ------- + + .. code-block:: python + + snap.has_charge() + """ return self._charge is not None @property def mass(self): - """:class:`numpy.ndarray`: Masses.""" + """:class:`numpy.ndarray`: Masses. + + Example + ------- + + .. code-block:: python + + snap.mass = [3, 2, 3] + + """ if not self.has_mass(): self._mass = numpy.ones(self.N, dtype=float) return self._mass @@ -617,12 +785,31 @@ def has_mass(self): bool ``True`` if masses have been initialized. + Example + ------- + + .. code-block:: python + + snap.has_mass() + """ return self._mass is not None @property def type_label(self): - """LabelMap: Labels for particle typeids.""" + """LabelMap: Labels for particle typeids. + + Example + ------- + + .. code-block ::python + + label_map = lammpsio.topology.LabelMap({1: "typeA", 2: "typeB"}) + + snap.type_label = LabelMap(map=label_map) + + + """ return self._type_label @type_label.setter @@ -636,7 +823,16 @@ def type_label(self, value): @property def bonds(self): - """Bonds: Bond data.""" + """Bonds: Bond data. + + Example + ------- + + .. code-block:: python + + snap.bonds = lammpsio.topology.Bonds(N=6, num_types=2) + + """ return self._bonds @bonds.setter @@ -656,12 +852,30 @@ def has_bonds(self): bool ``True`` if bonds is initialized and there is at least one bond. + + Example + ------- + + .. code-block:: python + + snap.has_bonds() + """ return self._bonds is not None and self._bonds.N > 0 @property def angles(self): - """Angles: Angle data.""" + """Angles: Angle data. + + + Example + ------- + + .. code-block:: python + + snap.angles = lammpsio.topology.Angles(N=4, num_types=2) + + """ return self._angles @angles.setter @@ -681,12 +895,28 @@ def has_angles(self): bool ``True`` if angles is initialized and there is at least one angle. + Example + ------- + + .. code-block:: python + + snap.has_angles() + """ return self._angles is not None and self._angles.N > 0 @property def dihedrals(self): - """Dihedrals: Dihedral data.""" + """Dihedrals: Dihedral data. + + Example + ------- + + .. code-block:: python + + snap.dihedrals = lammpsio.topology.Dihedrals(N=2, num_types=2) + + """ return self._dihedrals @dihedrals.setter @@ -706,12 +936,28 @@ def has_dihedrals(self): bool ``True`` if dihedrals is initialized and there is at least one dihedral. + Example + ------- + + .. code-block:: python + + snap.has_dihedrals() + """ return self._dihedrals is not None and self._dihedrals.N > 0 @property def impropers(self): - """Impropers: Improper data.""" + """Impropers: Improper data. + + Example + ------- + + .. code-block:: python + + snap.impropers = lammpsio.topology.Impropers(N=2, num_types=2) + + """ return self._impropers @impropers.setter @@ -731,6 +977,13 @@ def has_impropers(self): bool ``True`` if impropers is initialized and there is at least one improper. + Example + ------- + + .. code-block:: python + + snap.has_impropers() + """ return self._impropers is not None and self._impropers.N > 0 @@ -744,6 +997,15 @@ def reorder(self, order, check_order=True): check_order : bool If ``True``, validate the new ``order`` before applying it. + Example + ------- + + .. code-block:: python + + bond_id = [0, 3, 1, 4, 2, 5] + + snap.bonds.reorder(numpy.sort(bond_id), check_order=True) + """ # sanity check the sorting order before applying it if check_order and self.N > 1: From 0e1c759cef24449ab1a74412a9b53ea80e505d14 Mon Sep 17 00:00:00 2001 From: mayukhkundu14 <79770572+mayukh33@users.noreply.github.com> Date: Fri, 23 May 2025 15:11:30 -0500 Subject: [PATCH 22/30] Minor fix to box documentation --- src/lammpsio/box.py | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/src/lammpsio/box.py b/src/lammpsio/box.py index a6cdfa6..27d9a40 100644 --- a/src/lammpsio/box.py +++ b/src/lammpsio/box.py @@ -30,12 +30,6 @@ class Box: box = lammpsio.Box([-5.0, -10.0, 0.0], [1.0, 10.0, 8.0], [1.0, -2.0, 0.5]) - assert numpy.allclose(box.low, [-5.0, -10.0, 0.0]) - - assert numpy.allclose(box.high, [1.0, 10.0, 8.0]) - - assert numpy.allclose(box.tilt, [1.0, -2.0, 0.5]) - """ def __init__(self, low, high, tilt=None): @@ -73,10 +67,6 @@ def cast(cls, value): box = lammpsio.Box.cast([-5.0, -10.0, 0.0, 1.0, 10.0, 8.0]) - assert numpy.allclose(box.low, [-5.0, -10.0, 0.0]) - - assert numpy.allclose(box.high, [1.0, 10.0, 8.0]) - """ if isinstance(value, Box): return value From fca1059066c54021bfa97511d5e5445770ba2711 Mon Sep 17 00:00:00 2001 From: mayukhkundu14 <79770572+mayukh33@users.noreply.github.com> Date: Fri, 23 May 2025 15:21:22 -0500 Subject: [PATCH 23/30] Modify data documentation --- src/lammpsio/data.py | 42 +++++++++++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 15 deletions(-) diff --git a/src/lammpsio/data.py b/src/lammpsio/data.py index 4320e4a..5307f9b 100644 --- a/src/lammpsio/data.py +++ b/src/lammpsio/data.py @@ -39,26 +39,13 @@ class DataFile: unknown_bodies : list Data file body sections that will be ignored. + Example ------- - Create and read a data file: - .. code-block:: python - filename = tmp_path / "atoms.data" - - box = lammpsio.Box([-5.0, -10.0, 0.0], [1.0, 10.0, 8.0], [1.0, -2.0, 0.5]) - - snap = lammpsio.Snapshot(3, box, 10) - - data = lammpsio.DataFile.create(filename, snap, "atomic") - - assert filename.exists - - snap_2 = data.read() - - assert snap_2.N == snap.N + data = lammpsio.DataFile(tmp_path / "atoms.data", atom_style="atomic") """ @@ -128,6 +115,22 @@ def create(cls, filename, snapshot, atom_style=None): ValueError If all masses are not the same for a given type. + Example + ------- + + Create a data file: + + .. code-block:: python + + box = lammpsio.Box([-5.0, -10.0, 0.0], + [1.0, 10.0, 8.0], + [1.0, -2.0, 0.5]) + + snap = lammpsio.Snapshot(3, box, 10) + + data = lammpsio.DataFile.create(tmp_path / "atoms.data", + snap, atom_style="atomic") + """ # extract mass by type @@ -331,6 +334,15 @@ def read(self): ValueError If :attr:`atom_style` is not specified and not set in file. + Example + ------- + + Read a data file: + + .. code-block:: python + + snap = data.read() + """ with open(self.filename) as f: # initialize snapshot from header From 89cc9ba9f0128c73280fd2365a75342cc59cdbb3 Mon Sep 17 00:00:00 2001 From: mayukhkundu14 <79770572+mayukh33@users.noreply.github.com> Date: Fri, 23 May 2025 15:26:08 -0500 Subject: [PATCH 24/30] Modify the dump file documentation --- src/lammpsio/dump.py | 35 +++++++++++++++++------------------ 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/src/lammpsio/dump.py b/src/lammpsio/dump.py index aaeef2e..8c9646d 100644 --- a/src/lammpsio/dump.py +++ b/src/lammpsio/dump.py @@ -44,27 +44,11 @@ class DumpFile: Example ------- - Create and read a dump file: + Read a dump file: .. code-block:: python - filename = tmp_path / "atoms.data" - - box = lammpsio.Box([-5.0, -10.0, 0.0], [1.0, 10.0, 8.0], [1.0, -2.0, 0.5]) - - snap = lammpsio.Snapshot(3, box, 10) - - schema = {"id": 0, "position": (1, 2, 3)} - - f = lammpsio.DumpFile.create(filename, schema, snap) - - assert filename.exists - - f = lammpsio.DumpFile(filename, schema) - - read_snap = [s for s in f] - - assert read_snap[0].N == snap.N + f = lammpsio.DumpFile(tmp_path / "atoms.lammpstrj", schema=None) """ @@ -93,6 +77,21 @@ def create(cls, filename, schema, snapshots): `DumpFile` The object representing the new dump file. + Example + ------- + + Create a dump file: + + .. code-block:: python + + box = lammpsio.Box([-5.0, -10.0, 0.0], [1.0, 10.0, 8.0], [1.0, -2.0, 0.5]) + + snap = lammpsio.Snapshot(3, box, 10) + + schema = {"id": 0, "position": (1, 2, 3)} + + f = lammpsio.DumpFile.create(tmp_path /"atoms.lammpstrj", schema, snap) + """ # map out the schema into a dump row # each entry is a tuple: (column, (attribute, index)) From 80e54690016dc79e872b003e70a0f17e1d01aba5 Mon Sep 17 00:00:00 2001 From: mayukhkundu14 <79770572+mayukh33@users.noreply.github.com> Date: Fri, 23 May 2025 15:34:02 -0500 Subject: [PATCH 25/30] Ensure doc test runs if gsd.hoomd is not installed --- conftest.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/conftest.py b/conftest.py index a97fce7..efc59a8 100644 --- a/conftest.py +++ b/conftest.py @@ -16,6 +16,11 @@ def setup_sybil_tests(namespace): namespace["numpy"] = numpy namespace["lammpsio"] = lammpsio + try: + import gsd.hoomd + except ImportError: + gsd.hoomd = None + if sybil is not None: pytest_collect_file = sybil.Sybil( From 9e3b4fd131efc624f2bf1adc3b51299a8d1a9069 Mon Sep 17 00:00:00 2001 From: mayukhkundu14 <79770572+mayukh33@users.noreply.github.com> Date: Fri, 23 May 2025 16:31:14 -0500 Subject: [PATCH 26/30] Modify snapshot doc to ensure doc test runs --- conftest.py | 7 ++----- src/lammpsio/snapshot.py | 2 -- 2 files changed, 2 insertions(+), 7 deletions(-) diff --git a/conftest.py b/conftest.py index efc59a8..83fcaf1 100644 --- a/conftest.py +++ b/conftest.py @@ -1,3 +1,4 @@ +import gsd import numpy try: @@ -15,11 +16,7 @@ def setup_sybil_tests(namespace): # Common imports. namespace["numpy"] = numpy namespace["lammpsio"] = lammpsio - - try: - import gsd.hoomd - except ImportError: - gsd.hoomd = None + namespace["gsd"] = gsd if sybil is not None: diff --git a/src/lammpsio/snapshot.py b/src/lammpsio/snapshot.py index ba17847..85a287c 100644 --- a/src/lammpsio/snapshot.py +++ b/src/lammpsio/snapshot.py @@ -81,8 +81,6 @@ def from_hoomd_gsd(cls, frame): .. code-block:: python - import gsd.hoomd - frame = gsd.hoomd.Frame() frame.configuration.box = [4, 5, 6, 0.1, 0.2, 0.3] From bd53a4e23b093a03e01886cba87923de785df487 Mon Sep 17 00:00:00 2001 From: mayukhkundu14 <79770572+mayukh33@users.noreply.github.com> Date: Fri, 23 May 2025 17:01:00 -0500 Subject: [PATCH 27/30] Modify documentation confest to run doc test --- conftest.py | 13 +++++++++++-- src/lammpsio/snapshot.py | 6 ++++-- 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/conftest.py b/conftest.py index 83fcaf1..03a7aae 100644 --- a/conftest.py +++ b/conftest.py @@ -1,4 +1,3 @@ -import gsd import numpy try: @@ -10,13 +9,23 @@ import lammpsio +try: + import gsd.hoomd + + has_gsd = True +except ModuleNotFoundError: + has_gsd = False + def setup_sybil_tests(namespace): """Sybil setup function.""" # Common imports. namespace["numpy"] = numpy namespace["lammpsio"] = lammpsio - namespace["gsd"] = gsd + if has_gsd: + namespace["frame"] = gsd.hoomd.Frame() + else: + namespace["frame"] = 0 if sybil is not None: diff --git a/src/lammpsio/snapshot.py b/src/lammpsio/snapshot.py index 85a287c..e599671 100644 --- a/src/lammpsio/snapshot.py +++ b/src/lammpsio/snapshot.py @@ -79,9 +79,9 @@ def from_hoomd_gsd(cls, frame): Create snapshot from a GSD file: - .. code-block:: python + .. skip: next if(frame == 0, reason="gsd.hoomd not installed") - frame = gsd.hoomd.Frame() + .. code-block:: python frame.configuration.box = [4, 5, 6, 0.1, 0.2, 0.3] @@ -247,6 +247,8 @@ def to_hoomd_gsd(self, type_map=None): Convert snapshot to a GSD file: + .. skip: next if(frame == 0, reason="gsd.hoomd not installed") + .. code-block:: python frame = snap_2.to_hoomd_gsd() From 973b088e38d7b1eb8c3315d7f5878f06ddfb8d38 Mon Sep 17 00:00:00 2001 From: mayukhkundu14 <79770572+mayukh33@users.noreply.github.com> Date: Tue, 27 May 2025 15:56:46 -0500 Subject: [PATCH 28/30] Add description to data module --- src/lammpsio/data.py | 63 ++++++++++++++++++++------------------------ 1 file changed, 29 insertions(+), 34 deletions(-) diff --git a/src/lammpsio/data.py b/src/lammpsio/data.py index 5307f9b..c87ec2c 100644 --- a/src/lammpsio/data.py +++ b/src/lammpsio/data.py @@ -14,7 +14,35 @@ def _readline(file_, require=False): class DataFile: - """LAMMPS data file. + """A LAMMPS data file is represented by a `DataFile`. + It can be created by the following syntax: + + .. code-block:: python + + box = lammpsio.Box([-5.0, -10.0, 0.0], + [1.0, 10.0, 8.0], + [1.0, -2.0, 0.5]) + + snap = lammpsio.Snapshot(3, box, 10) + + data = lammpsio.DataFile.create(tmp_path / "atoms.data", + snap, atom_style="atomic") + + The file must be explicitly `read()` to get a `Snapshot`: + + .. code-block:: python + + snap = data.read() + + The `atom_style` will be read from the comment in the Atoms section + of the file. If it is not present, it must be specified in the `DataFile`. + If `atom_style` is specified and also present in the file, the two must match + or an error will be raised. + + There are many sections that can be stored in a data file, but `lammpsio` does + not currently understand all of them. You can check `DataFile.known_headers`, + `DataFile.unknown_headers`, `DataFile.known_bodies` and `DataFile.unknown_bodies` + for lists of what is currently supported. Parameters ---------- @@ -39,14 +67,6 @@ class DataFile: unknown_bodies : list Data file body sections that will be ignored. - - Example - ------- - - .. code-block:: python - - data = lammpsio.DataFile(tmp_path / "atoms.data", atom_style="atomic") - """ def __init__(self, filename, atom_style=None): @@ -115,22 +135,6 @@ def create(cls, filename, snapshot, atom_style=None): ValueError If all masses are not the same for a given type. - Example - ------- - - Create a data file: - - .. code-block:: python - - box = lammpsio.Box([-5.0, -10.0, 0.0], - [1.0, 10.0, 8.0], - [1.0, -2.0, 0.5]) - - snap = lammpsio.Snapshot(3, box, 10) - - data = lammpsio.DataFile.create(tmp_path / "atoms.data", - snap, atom_style="atomic") - """ # extract mass by type @@ -334,15 +338,6 @@ def read(self): ValueError If :attr:`atom_style` is not specified and not set in file. - Example - ------- - - Read a data file: - - .. code-block:: python - - snap = data.read() - """ with open(self.filename) as f: # initialize snapshot from header From 2d50991cde9766919f58ff6c7990b70a450218a5 Mon Sep 17 00:00:00 2001 From: mayukhkundu14 <79770572+mayukh33@users.noreply.github.com> Date: Tue, 27 May 2025 16:00:59 -0500 Subject: [PATCH 29/30] Add description for snapshot module --- src/lammpsio/snapshot.py | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/src/lammpsio/snapshot.py b/src/lammpsio/snapshot.py index e599671..d6725e0 100644 --- a/src/lammpsio/snapshot.py +++ b/src/lammpsio/snapshot.py @@ -8,7 +8,10 @@ class Snapshot: - """Particle configuration. + """ + The particle configuration is stored in a `Snapshot`. A `Snapshot` holds the + data for *N* particles, the simulation `Box`, and the timestep. The `Box` follows + the LAMMPS conventions for its shape and bounds. Parameters ---------- @@ -19,16 +22,15 @@ class Snapshot: step : int Simulation time step counter. Default of ``None`` means time step is not specified. - - Attributes - ---------- - step : int - Simulation time step counter. + num_types : int + Number of particle types. If `num_types is None`, + then the number of types is deduced from `typeid`. Example ------- - Create snapshot using a triclinic box: + Here is a 3-particle configuration in an triclinic box + centered at the origin at step 10: .. code-block:: python From 792f73643eca9e0a9b7eccfe4a0a13aa03bd0c66 Mon Sep 17 00:00:00 2001 From: mayukhkundu14 <79770572+mayukh33@users.noreply.github.com> Date: Tue, 27 May 2025 16:22:40 -0500 Subject: [PATCH 30/30] Add description for topology module --- doc/source/conf.py | 2 ++ src/lammpsio/topology.py | 55 +++++++++++++++++++++++++++++++++++++--- 2 files changed, 54 insertions(+), 3 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index e9e3fa0..55fb60f 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -65,6 +65,8 @@ autosummary_generate = True +autodoc_member_order = "bysource" + autodoc_default_options = {"inherited-members": None, "special-members": False} # -- Options for intersphinx ------------------------------------------------- diff --git a/src/lammpsio/topology.py b/src/lammpsio/topology.py index 1413334..dc793c8 100644 --- a/src/lammpsio/topology.py +++ b/src/lammpsio/topology.py @@ -6,7 +6,11 @@ class Topology: - """Particle topology. + """ + The topology (bond information) can be stored in `Bonds`, `Angles`, `Dihedrals`, + and `Impropers` objects. All these objects function similarly, differing only in the + number of particles that are included in a connection (2 for a bond, 3 for an angle, + 4 for a dihedral or improper). Each connection has an associated `id` and `typeid`. Parameters ---------- @@ -204,6 +208,14 @@ class Bonds(Topology): Number of bond types. Default of ``None`` means the number of types is determined from the unique typeids. + Example + ------- + Create bonds: + + .. code-block:: python + + bonds = lammpsio.topology.Bonds(N=2, num_types=2) + """ def __init__(self, N, num_types=None): @@ -221,6 +233,14 @@ class Angles(Topology): Number of Angle types. Default of ``None`` means the number of types is determined from the unique typeids. + Example + ------- + Create angles: + + .. code-block:: python + + angles = lammpsio.topology.Angles(N=2, num_types=2) + """ def __init__(self, N, num_types=None): @@ -233,11 +253,19 @@ class Dihedrals(Topology): Parameters ---------- N : int - Number of diehdrals. + Number of dihedrals. num_types : int Number of Dihedral types. Default of ``None`` means the number of types is determined from the unique typeids. + Example + ------- + Create dihedrals: + + .. code-block:: python + + dihedrals = lammpsio.topology.Dihedrals(N=2, num_types=2) + """ def __init__(self, N, num_types=None): @@ -255,6 +283,15 @@ class Impropers(Topology): Number of improper dihedral types. Default of ``None`` means the number of types is determined from the unique typeids. + + Example + ------- + Create dihedrals: + + .. code-block:: python + + impropers = lammpsio.topology.Impropers(N=2, num_types=2) + """ def __init__(self, N, num_types=None): @@ -262,13 +299,25 @@ def __init__(self, N, num_types=None): class LabelMap(collections.abc.MutableMapping): - """Label map between typeids and types. + """ + A `LabelMap` is effectively a dictionary associating a label (type) with a + particle's or connection's typeid. These labels can be useful for tracking + the meaning of typeids. They are also automatically used when interconverting + with HOOMD GSD files that require such labels. Parameters ---------- map : dict Map of typeids to types. + Example + ------- + Create `LabelMaps`: + + .. code-block:: python + + label = lammpsio.topology.LabelMap({1: "typeA", 2: "typeB"}) + """ def __init__(self, map=None):