AtomicSystem

class AtomicSystem(system_dict)

Bases: EditMixin, IOMixin, TopologyMixin, ForceFieldMixin

Container storing the complete atomic system representation.

The class stores atomic coordinates, topology information (bonds, angles, dihedrals and impropers), simulation box parameters, atomic masses and charges, and force field parameters.

It is designed to represent the content of a LAMMPS data file and provides utilities for editing, analyzing and exporting atomistic systems.

Parameters:

system_dictdict[str, Any]

Dictionary containing the complete system data. See cemd.core._format.SYSTEM_DICT_FORMAT for the authoritative, machine-checked list of required and optional keys; in summary:

Required keys:

• atomspandas.DataFrame

  Per-atom data (type, charge, x, y, z), indexed by atom id.

• boxsequence

  Simulation box, in any format accepted by set_box().

• masses, chargesdict

  Per-atom-type masses and charges.

Optional keys:

• bonds, angles, dihedrals, improperspandas.DataFrame or None

  Topology tables (atom_1..atom_N columns plus a “type” column).

• velocitiespandas.DataFrame or None

  Atomic velocities (vx, vy, vz).

• atom_stylestr

  LAMMPS atom style (default “full”).

• Force-field keys/params, as produced by ForceFieldKeys.to_system_dict() and ForceFieldParams.to_system_dict().

Attributes

atoms	(pandas.DataFrame) Atomic information including coordinates, atom types and charges.
bonds	(pandas.DataFrame or None) Bond topology information.
angles	(pandas.DataFrame or None) Angle topology information.
dihedrals	(pandas.DataFrame or None) Dihedral topology information.
impropers	(pandas.DataFrame or None) Improper topology information.
velocities	(pandas.DataFrame or None) Atomic velocities when available.
forcefield_keys	(ForceFieldKeys) Centralized mapping between system types (atoms, bonds, etc.) and database keys.
forcefield_params	(ForceFieldParams) Centralized storage for all force field parameters (pair, bond, angle, dihedral, improper).

Properties

AtomicSystem.box	Lattice parameters [a, b, c, alpha, beta, gamma].
AtomicSystem.volume	Return the volume of the simulation box.
AtomicSystem.density	Return the system density.
AtomicSystem.total_charge	Return the total system charge.
AtomicSystem.total_mass	Return the total system mass.
AtomicSystem.masses	Return atomic masses associated with atom types (read-only).
AtomicSystem.charges	Return atomic charges associated with atom types (read-only).
AtomicSystem.elements	Return a mapping of atom types to their elemental symbols (read-only).
AtomicSystem.ff_keys	Return force-field keys for active topology types.
AtomicSystem.ff_params	Return force-field parameters for active topology types.
AtomicSystem.num_atoms	Return the number of atoms.
AtomicSystem.num_bonds	Return the number of bonds.
AtomicSystem.num_angles	Return the number of angles.
AtomicSystem.num_dihedrals	Return the number of dihedrals.
AtomicSystem.num_impropers	Return the number of impropers.
AtomicSystem.num_atom_types	Return the number of atom types.
AtomicSystem.num_bond_types	Return the number of bond types.
AtomicSystem.num_angle_types	Return the number of angle types.
AtomicSystem.num_dihedral_types	Return the number of dihedral types.
AtomicSystem.num_improper_types	Return the number of improper types.
AtomicSystem.atom_types	Return the list of unique atom types.
AtomicSystem.bond_types	Return the list of unique bond types.
AtomicSystem.angle_types	Return the list of unique angle types.
AtomicSystem.dihedral_types	Return the list of unique dihedral types.
AtomicSystem.improper_types	Return the list of unique improper types.

Inspection

AtomicSystem.summary	Print a complete summary of the AtomicSystem.
AtomicSystem.get_count	Calculate the exact number of atoms for a specific type.
AtomicSystem.get_center_of_mass	Calculates the center of mass (COM) of the system.
AtomicSystem.copy	Create an independent deep copy of the atomic system.
AtomicSystem.view	Visualize the current system in VMD, with an optional trajectory.

Input/Output

AtomicSystem.from_file	Load a system from a file.
AtomicSystem.from_smiles	Create from SMILES string.
AtomicSystem.from_cod	Load a structure from the Crystallography Open Database.
AtomicSystem.from_pubchem	Load a molecule from PubChem.
AtomicSystem.from_mda	Create from MDAnalysis Universe or AtomGroup.
AtomicSystem.from_pmg	Create from Pymatgen Structure.
AtomicSystem.to_mda	Convert this AtomicSystem instance to an MDAnalysis Universe.
AtomicSystem.to_pmg	Convert to Pymatgen Structure.
AtomicSystem.write	Write the system to a file.

Topology

AtomicSystem.set_types	Assign new types to atoms via a mapping {old_type: new_type}.
AtomicSystem.set_type2atoms	Assign a new type to a specific subset of atoms.
AtomicSystem.set_types_from_elements	Reset atom types to their corresponding chemical elements, inferred from mass.
AtomicSystem.set_topology	Apply a predefined style or custom rule(s) to the system.
AtomicSystem.remove_all_connections	Remove all bonds, angles, dihedrals and impropers from the system.
AtomicSystem.remove_connection_types	Remove specific connection types from the system.
AtomicSystem.keep_connection_types	Keep only the specified connection types and remove all others.
AtomicSystem.guess_connections	Guess angles, dihedrals and/or impropers directly from existing bonds.
AtomicSystem.guess_angles	Guess only angles from existing bonds.
AtomicSystem.guess_dihedrals	Guess only dihedrals from existing bonds.
AtomicSystem.guess_impropers	Guess only impropers from existing bonds.
AtomicSystem.add_bond	Add a bond between two atoms.
AtomicSystem.add_angle	Add an angle between three atoms.
AtomicSystem.add_dihedral	Add a dihedral between four atoms.
AtomicSystem.add_improper	Add an improper between four atoms.

Force Field

AtomicSystem.set_masses	Set or update the atomic masses for the system and the atoms DataFrame.
AtomicSystem.set_charges	Set or update the charges for the atomic system and the atoms DataFrame.
AtomicSystem.neutralize_charge	Neutralize the system by spreading its excess charge over atom types.
AtomicSystem.set_ff_from_database
AtomicSystem.explore_ff_database	Interactive Forcefield Explorer using the prompt_toolkit UI pattern.
AtomicSystem.set_pair_params	Set pair-interaction parameters for two atom types.
AtomicSystem.set_bond_params
AtomicSystem.set_angle_params
AtomicSystem.set_dihedral_params
AtomicSystem.set_improper_params
AtomicSystem.apply_pair_mixing_rules	Calculate missing cross-interaction parameters.
AtomicSystem.set_ff_keys	Set or update force-field keys for atom and connectivity types.
AtomicSystem.set_atom_ff_keys
AtomicSystem.set_bond_ff_keys
AtomicSystem.set_angle_ff_keys
AtomicSystem.set_dihedral_ff_keys
AtomicSystem.set_improper_ff_keys

Modifiers

AtomicSystem.add_structure	Add a structure on top of this system.
AtomicSystem.add_liquid_layer	Add a liquid layer on top of this system.
AtomicSystem.add_droplet	Add a hemispherical liquid droplet on top of this system.
AtomicSystem.add_atom	Add a single atom.
AtomicSystem.add_atoms	Add multiple atoms to the system in a single operation.
AtomicSystem.protonate_atom	Add a proton to a single atom.
AtomicSystem.protonate_atoms	Add protons to multiple atoms in a single operation.
AtomicSystem.remove_atom	Remove a single atom.
AtomicSystem.remove_atoms	Remove specified atoms from the system and update topology accordingly.
AtomicSystem.set_atom_position	Modify the coordinates of a single atom using a vector (x, y, z).
AtomicSystem.set_box	Assign a new box to the system and compute all representations.
AtomicSystem.orthogonalize	Attempt to transform a triclinic (skewed) box into an orthogonal one.
AtomicSystem.unskew	Unskew the box if the non-diagonal parameters of the box matrix \(|H_{i,j}| > H_{j,j}\) for \(i \neq j\) by adding \(\pm H_{j,:}\) to \(H_{i,:}\) while \(|H_{i,j}| > H_{j,j}\).
AtomicSystem.replicate	Replicate the system by integer factors along the lattice vectors (a, b, c).
AtomicSystem.wrap	Wraps all atoms back into the simulation box [0, L] using Periodic Boundary Conditions.
AtomicSystem.center_on_com	Translates the system so its center of mass is at the center of the box.