API Reference

This page gathers the full autodoc output for every Python module that ships with generate_InitCond, including the lightweight helpers inside the analysis package.

Core pipeline utilities 

fix_datafiles

This module provides functionality to post-process a LAMMPS data file generated by Moltemplate. Specifically, it finds the line indicating the number of bond types, changes it from ‘2’ to ‘3’, and inserts a new line specifying extra bonds per atom.

Usage (command line):: python fix_datafiles.py <datafile>

Example

python fix_datafiles.py b70_N200_L500.data

fix_datafiles.fix_data_file(file_path: str) → None[source]

Read a LAMMPS data file and modify its bond type section.

The function looks for the line containing “2 bond types”, replaces that “2” with “3”, and then inserts a line “50 extra bond per atom” immediately after. All other lines are left unchanged.

Parameters:: file_path (str) – Path to the LAMMPS data file to be modified.
Raises:: FileNotFoundError – If the given file does not exist.

LT_writer

Generate Moltemplate (.lt) files and corresponding monomer XYZ files for polymer chains based on a specified segment pattern.

The script reads two command-line arguments:

n (int): Number of repeats of the segment pattern per polymer.
pat (str): A string of digits ‘1’ and ‘2’ representing sticker/spacer beads.

It produces:

polyA_n<n>.lt and polyB_n<n>.lt: Moltemplate definitions for A-type and B-type polymers.
polyA_n<n>_mono.xyz and polyB_n<n>_mono.xyz: Monomer geometry in XYZ format.

Usage (command line):

python LT_writer.py <n> <seg_pattern>

Example

python LT_writer.py 10 2212212

LT_writer.write_poly_lt(mol_name: str, bead_sequence: ndarray, type_names: dict[int, str], mass_map: dict[int, float]) → None[source]

Write a Moltemplate (.lt) file defining a polymer chain and its connectivity.

Parameters:

mol_name (str) – Base name for the Moltemplate file (e.g., “polyA_n10”).
bead_sequence (np.ndarray) – 1D array of bead types (integers).
type_names (dict[int, str]) – Mapping from bead type integer to Moltemplate atom name.
mass_map (dict[int, float]) – Mapping from bead type integer to atomic mass.

Output:

Creates a file “<mol_name>.lt” defining:

Masses for each bead type.
Atom definitions and charges (charges are set to 0 by default).
Bond definitions between consecutive beads.
Angle definitions between triplets of beads.

LT_writer.write_xyz(mol_name: str, bead_sequence: ndarray, type_names: dict[int, str]) → None[source]

Write a monomer geometry in XYZ format.

Parameters:

mol_name (str) – Base name for the output file (e.g., “polyA_n10”).
bead_sequence (np.ndarray) – 1D array of bead types (integers).
type_names (dict[int, str]) – Mapping from bead type integer to atom name.

Output:: Creates a file “<mol_name>_mono.xyz” listing coordinates along the x-axis, one bead every 5 Å, all with y=z=0.

writePackmolInput

writePackmolInput.generate_packmol_input(n, NA, NB, L, inp_file, outfile)[source]: Generate a Packmol input script that places NA A-chains and NB B-chains in a cube of half-length L.

writeSysLT

writeSysLT.generate_syslt(n, NA, NB, L, fName)[source]: Create a Moltemplate .lt file that imports polyA_n<n>.lt and polyB_n<n>.lt, defines NA and NB copies, and writes the Data Boundary block.

updateColVar

Compute the radius of gyration (Rg) from a Packmol-generated XYZ file, and update a colvars template file accordingly. The script reads: 1. xyz_file : Packmol output XYZ (e.g., “IC_tmp.xyz”) 2. colvars_template: Path to a template .colvars file (e.g., “N400_Rg_L700.colvars”) 3. L : Box half-length (integer) 4. n : Number of repeats of the segment pattern 5. NA : Number of A-type chains 6. NB : Number of B-type chains 7. seg_pattern : Segment pattern string (e.g., “2212212”)

It writes out a new colvars file named “N200_Rg_L<L>.colvars”.

updateColVar.calc_RadGy(posArr)[source]

Compute the center of mass and radius of gyration (Rg) for a set of positions.

Parameters:

posArr (np.ndarray) – An (N,3) array of atomic coordinates.

Returns:

com (np.ndarray): A length-3 array representing the center-of-mass.
Rg (float): The radius of gyration (Å).

Return type:

tuple

updateColVar.fixAtomNumbers(n, NA, NB, seg)[source]

Construct the ‘atomNumbers’ line for the colvars file, listing atom indices at half-chain boundaries.

Each polymer chain has length len(seg) * n. We insert a number for every half-chain.

Parameters:

n (int) – Number of repeats of the segment pattern per chain.
NA (int) – Number of A-type chains.
NB (int) – Number of B-type chains.
seg (list[int]) – List of bead types (e.g., [2,2,1,2,2,1,2]).

Returns:

A formatted “atomNumbers { … }” string with newline.

Return type:

str

updateColVar.getBoxDim(posArr)[source]

Compute the extents (x_length, y_length, z_length) of the bounding box from given positions.

Parameters:: posArr (np.ndarray) – An (N,3) array of coordinates.
Returns:: (x_length, y_length, z_length), each rounded to nearest integer.
Return type:: tuple[int, int, int]

updateColVar.parseXYZfile(file)[source]

Read a Packmol-generated XYZ file and return an (N,3) array of float coordinates.

The first two lines (atom count and comment) are skipped; parsing begins at line 3.

Parameters:: file (str) – Path to the XYZ file.
Returns:: An (N,3) array of floating-point coordinates.
Return type:: np.ndarray

updateColVar.updateCV(cvfile, Rg, L, n, NA, NB, seg)[source]

Read a colvars template file, adjust Rg-dependent parameters, and write a new colvars file.

Replacements performed: - ‘upperBoundary’ → Rg + 10 - ‘upperWalls’ → Rg + 5 - ‘atomNumbers’ → newly generated line via fixAtomNumbers()

Parameters:

cvfile (str) – Path to the template .colvars file.
Rg (float) – Computed radius of gyration.
L (str or int) – Box half-length (used in output filename).
n (str or int) – Number of repeats of the segment pattern.
NA (str or int) – Number of A-type chains.
NB (str or int) – Number of B-type chains.
seg (str) – Segment pattern string (e.g., “2212212”).

Writes:: “N200_Rg_L<L>.colvars” with updated boundary and atomNumbers lines.

updateInput

Modify a LAMMPS input template file to set correct filenames and colvars references, and then generate a SLURM submission script.

Usage:

python updateInput.py <template_input_file> <L>

Where:

template_input_file (str): Path to a LAMMPS .in template (e.g., “Template_input.in”).
L (int): Box half-length (used to name output files).

The script performs:

Replace “variable fName string …” → “b70_N200_L<L>”.
Replace “read_data …” → “b70_N200_L<L>.data extra/special/per/atom 50”.
Replace “fix CV_Rg …” → “N200_Rg_L<L>.colvars”.
Write out “b70_N200_L<L>.in”.
Write a SLURM script “submit_b70_N200_L<L>.sh”.

updateInput.writeInputFile(file, L)[source]

Read the LAMMPS input template and substitute the appropriate filenames.

After substitution, writes the new file “b70_N200_L<L>.in”.

Parameters:

file (str) – Path to the template .in file.
L (int) – Box half-length to include in filenames.

Behavior:

Locates a line starting with “variable fName string” and replaces the value with “b70_N200_L<L>”.
Locates the “read_data” line and replaces it with “read_data b70_N200_L<L>.data extra/special/per/atom 50”.
Locates the “fix CV_Rg all colvars” line and replaces it with “fix CV_Rg all colvars N200_Rg_L<L>.colvars output ${fName}”.

updateInput.writeSubmitScript(L)[source]

Generate a SLURM submission script named “submit_b70_N200_L<L>.sh” for LAMMPS.

The submission script requests:

Job name: L<L>_b70
28 MPI tasks
Walltime: 3 days
Partition: sapphire
400 MB per CPU
Output to “%x_%j.out” and error to “%x_%j.err”
Email to name@organization.edu on job END

Parameters:: L (int) – Box half-length (used to form input filename and job name).

Analysis helpers 

plot_PE

Small helper to plot potential energy vs. simulation step from a single LAMMPS Thermo_<foo>.dat file.

Typical usage

>>> from analysis.plot_PE import plot_pe
>>> plot_pe("Thermo_example.dat")   # show the figure

Only one public function is provided so that the module appears cleanly in the API Reference.

analysis.plot_PE.plot_pe(file_path: str | Path, ax: Axes | None = None) → Axes[source]

Plot potential energy (column 3) as a function of timestep (column 0).

Parameters:

file_path – Path to a Thermo_<foo>.dat file.
ax – Existing axis to draw on, or None (create new).

Returns:

Axis containing the plotted line.

Return type:

matplotlib.axes.Axes

plot_BSF

Plot the Bonded-Sticker Fraction (BSF) – i.e. the percentage of newly formed cross-links – from a single thermo file that contains a running bonds column.

Only one public helper is exposed so the module slots cleanly into Sphinx autodoc.

analysis.plot_BSF.plot_bsf(file_path: str | Path, og_bonds: int, max_bonds: int, ax: Axes | None = None) → Axes[source]

Plot % stickers bonded vs time from a single Thermo_*.dat file.

Parameters:

file_path – Thermo file that ends with a bonds column.
og_bonds – Number of permanent covalent bonds (baseline to subtract).
max_bonds – Maximum possible new bonds (denominator for 100 % normalisation).
ax – Optional axis to draw on.

Returns:

Axis containing the BSF trace.

Return type:

matplotlib.axes.Axes

Raises:

ValueError – If the thermofile has fewer than five columns.

Notes

The BSF at timestep i is computed as:

BSF_i = (bonds_i - og_bonds) / max_bonds * 100

where bonds_i is taken from the last column of the thermo line.

plot_SD

Sticker Dissociation Events helper.

Reads a BondData_<foo>.dat file that stores cumulative formation and break counts; this function plots per-interval dissociation events.

analysis.plot_SD.plot_sd(file_path: str | Path, ax: Axes | None = None) → Axes[source]

Plot sticker dissociation events (Δ broken bonds per thermo dump).

Parameters:

file_path –

Path to BondData_<foo>.dat with three columns:

timestep
cumulative formed bonds
cumulative broken bonds

ax – Optional axis.

Returns:

Axis with a bar chart (or line) of dissociation events vs step.

Return type:

matplotlib.axes.Axes

plot_cSize

Compute a cluster-size distribution (in molecules) from one LAMMPS *.DATA snapshot and display it as a bar chart.

For simplicity the connectivity is extracted directly from the “Bonds” section; no fancy spatial search is performed.

analysis.plot_cSize._read_snapshot(file_path: Path) → Tuple[List[int], List[Tuple[int, int]]][source]

analysis.plot_cSize.plot_csize(data_file: str | Path, ax: Axes | None = None) → Axes[source]

Plot the fraction of molecules in clusters of size s for one snapshot.

Parameters:

data_file – LAMMPS *.DATA snapshot (with Atoms/Bonds sections).
ax – Optional Matplotlib axis.

Returns:

Bar chart of y(s).

Return type:

matplotlib.axes.Axes

Notes

Cluster size here means number of molecules (mol IDs) in the connected component.
Uses networkx for the connected-component search.

plot_radialDist

Volume-normalised radial density of stickers (types 1 & 3) and spacers (types 2 & 4) from a single LAMMPS *.DATA snapshot.

The function

reads atomic coordinates,
finds the geometric centre,
bins distances into spherical shells (default 30),
normalises by shell volume and by total sticker / spacer count,
plots two lines on the same axis.

analysis.plot_radialDist._geometry(atoms)[source]

analysis.plot_radialDist._load_atoms(file_path: Path) → List[Tuple[int, float, float, float]][source]: Return list of tuples (type, x, y, z).

analysis.plot_radialDist.plot_radial_distribution(data_file: str | Path, nbins: int = 30, ax: Axes | None = None) → Axes[source]

Plot volume-normalised radial distribution for one snapshot.

Parameters:

data_file – LAMMPS snapshot (*.DATA) with coordinates.
nbins – Number of spherical shells between r=0 and r_max.
ax – Optional axis.

Returns:

Axis with two lines (stickers & spacers).

Return type:

matplotlib.axes.Axes

plot_pair_bonds

Plot a histogram of the number of type-1 ⇄ type-3 sticker bonds between every pair of chains in a single LAMMPS final_state_*.DATA snapshot.

Typical usage

>>> from analysis.plot_pair_bonds import plot_pair_bond_hist
>>> plot_pair_bond_hist("final_state_Run1.DATA")       # shows the figure

analysis.plot_pair_bonds._build_chain_multigraph(snapshot: Path) → MultiGraph[source]: Return a MultiGraph whose nodes are molecule IDs and whose parallel edges correspond to bonds joining a type-1 atom and a type-3 atom that belong to two different molecules.

analysis.plot_pair_bonds.plot_pair_bond_hist(snapshot_file: str | Path, *, bins: int | Iterable[float] | str = 'auto', ax: Axes | None = None) → Axes[source]

Histogram the multiplicity of type-1⇄type-3 sticker bonds for each neighbouring chain pair.

X-axis → # of parallel sticker bonds between a pair of chains Y-axis → # of chain pairs exhibiting that count

plot_cSizeBSF

Quick helper to visualise cluster size vs bound-sticker fraction (BSF) for one LAMMPS final_state_*.DATA snapshot.

Typical usage

>>> from analysis.plot_cSizeBSF import plot_cSizeBSF
>>> plot_bsf("final_state_Run1.DATA")     # shows the figure

The helper is intentionally lightweight: no CLI, no batch mode – just one function that returns the Matplotlib Axes so the caller can style or save the figure as desired.

analysis.plot_cSizeBSF._clusters_with_bsf(id2mol: dict[int, int], id2type: dict[int, int], bonds: list[tuple[int, int]]) → list[tuple[int, float]][source]

Identify clusters and compute their BSF.

Returns:: Each tuple is (cluster_size_in_chains, bsf).
Return type:: list[tuple[int, float]]

analysis.plot_cSizeBSF._parse_snapshot(path: Path) → tuple[dict[int, int], dict[int, int], list[tuple[int, int]]][source]

Read a LAMMPS *.DATA file and extract minimal topology.

Returns:

id2mol (dict[int, int]) – Atom-ID → molecule-ID.
id2type (dict[int, int]) – Atom-ID → atom type.
bonds (list[tuple[int, int]]) – List of bonded atom pairs as ID tuples (order doesn’t matter).

analysis.plot_cSizeBSF.plot_cSizeBSF(snapshot_file: str | Path, ax: Axes | None = None, colour: str = 'tab:blue') → Axes[source]

Scatter-plot cluster size vs bound-sticker fraction for one snapshot.

Parameters:

snapshot_file – Path to a final_state_*.DATA file.
ax – Existing Matplotlib Axes to draw on. If None (default) a new Figure + Axes is created.
colour – Matplotlib-compatible colour for the markers.

Returns:

The axis containing the plotted data.

Return type:

matplotlib.axes.Axes

plot_sticker_dist

Quick helper to plot the inter-molecular type-1/3 distance histogram for one or several LAMMPS final_state_*.DATA snapshots.

Typical usage

>>> from analysis.plot_sticker_dist import plot_sticker_hist
>>> plot_sticker_hist("final_state_Run1.DATA")                 # single file
>>> plot_sticker_hist([
...     "restart_term/final_state_Ens_0.30_Es_8.00.DATA",
...     "restart_uniform/final_state_Ens_0.30_Es_8.00.DATA",
... ], bins_w=0.2, max_r=900)                                  # overlay

The helper is intentionally lightweight: no CLI, no batch mode – just one function that returns the Matplotlib Axes so the caller can style or save the figure as desired.

analysis.plot_sticker_dist._distances_between_molecules(mol_ids: ndarray, coords: ndarray) → ndarray[source]: Return a 1-D array of distances between atoms that sit on different molecule IDs.

analysis.plot_sticker_dist._type13_atoms(path: Path) → tuple[ndarray, ndarray][source]

Return (molecule IDs, coordinates) for atoms of type 1 or 3.

If < 2 such atoms are present, raises ValueError.

Overlay raw-count histograms of type-1/3 inter-molecular distances.

Parameters:

snapshots – A single path or a sequence of paths to final_state_*.DATA files.
bins_w – Bin width Δr in σ (default 0.2).
max_r – Maximum distance considered (default 900 σ).
log_scale – If True, apply log-scale to the y-axis.
labels – Optional legend labels; by default the parent folder names.
ax – Existing Matplotlib Axes to draw on. If None a new one is created.

Returns:

The axis containing the plotted histograms.

Return type:

matplotlib.axes.Axes

plot_neighCount

Quick helper to visualise the chain-neighbour histogram for one LAMMPS final_state_*.DATA snapshot.

Typical usage

>>> from analysis.plot_neighCount import plot_neighbour_hist
>>> plot_neighbour_hist("final_state_Run1.DATA")   # shows the figure

The helper is intentionally lightweight: no CLI, no batch mode – just one function that returns the Matplotlib Axes so the caller can style or save the figure as desired.

analysis.plot_neighCount._build_chain_graph(snapshot: Path) → MultiGraph[source]: Parse a LAMMPS *.DATA file and return a graph whose nodes are molecules (chains) and whose edges are type-3 bonds connecting atoms in different molecules.

analysis.plot_neighCount.plot_neighbour_hist(snapshot_file: str | Path, ax: Axes | None = None, colour: str = 'tab:blue') → Axes[source]

Bar-plot the degree distribution (# neighbours per chain) for one snapshot.

Parameters:

snapshot_file – Path to a final_state_*.DATA file.
ax – Existing Matplotlib Axes to draw on. If None (default) a new Figure + Axes is created.
colour – Matplotlib bar colour.

Returns:

The axis containing the plotted histogram.

Return type:

matplotlib.axes.Axes

API Reference

Core pipeline utilities

fix_datafiles

LT_writer

writePackmolInput

writeSysLT

updateColVar

updateInput

Analysis helpers

plot_PE

plot_BSF

plot_SD

plot_cSize

plot_radialDist

plot_pair_bonds

Typical usage

plot_cSizeBSF

Typical usage

plot_sticker_dist

Typical usage

plot_neighCount

Typical usage

Core pipeline utilities 

Analysis helpers 