Molfra Analyzer Analysis

molfra (molecular fragment) analysis utilities.

This module provides molecule-level and system-level analysis tools for ReaxFF molfra.out and molfra_ig.out files via MolFraHandler.

Typical use cases include:

tracking molecular species counts over time
converting molecule occurrence tables between wide and long formats
extracting system totals (molecules, atoms, mass) versus iteration or time
identifying and characterizing the largest (slab) molecule in the system

`atoms_in_the_largest_molecule_long_format(handler)`

Return per-element atom counts for the largest molecule at each iteration (long format).

Works on

MolFraHandler — molfra.out / molfra_ig.out

Parameters:

Name	Type	Description	Default
`handler`	`MolFraHandler`	Parsed molecular fragment handler.	required

Returns:

Type	Description
`DataFrame`	Long-form table with columns: `iter`, `element`, `freq`.

Examples:

>>> df = atoms_in_the_largest_molecule_long_format(h)

`atoms_in_the_largest_molecule_wide_format(handler)`

Return per-element atom counts for the largest molecule at each iteration (wide format).

Works on

MolFraHandler — molfra.out / molfra_ig.out

Parameters:

Name	Type	Description	Default
`handler`	`MolFraHandler`	Parsed molecular fragment handler.	required

Returns:

Type	Description
`DataFrame`	Wide table with columns: `iter` and one column per element symbol (e.g. `Al`, `N`, `O`), containing atom counts.

Examples:

>>> df = atoms_in_the_largest_molecule_wide_format(h)

`get_molfra_data_long_format(handler, *, molecules=None, iters=None, by_index=False, fill_value=0)`

Return molecule occurrence counts across iterations (long format).

Works on

MolFraHandler — molfra.out / molfra_ig.out

Parameters:

Name	Type	Description	Default
`handler`	`MolFraHandler`	Parsed molecular fragment handler.	required
`molecules`	`Optional[Iterable[str]]`	Same meaning as in :func:`get_occurrences_wide`.	`None`
`iters`	`Optional[Iterable[str]]`	Same meaning as in :func:`get_occurrences_wide`.	`None`
`by_index`	`Optional[Iterable[str]]`	Same meaning as in :func:`get_occurrences_wide`.	`None`
`fill_value`	`Optional[Iterable[str]]`	Same meaning as in :func:`get_occurrences_wide`.	`None`

Returns:

Type	Description
`DataFrame`	Long-form table with columns: `iter`, `molecular_formula`, `freq`.

Examples:

>>> df = get_molfra_data_long_format(h, molecules=["H2O"])

`get_molfra_data_wide_format(handler, *, molecules=None, iters=None, by_index=False, fill_value=0)`

Return molecule occurrence counts across iterations (wide format).

Works on

MolFraHandler — molfra.out / molfra_ig.out

Parameters:

Name	Type	Description	Default
`handler`	`MolFraHandler`	Parsed molecular fragment handler.	required
`molecules`	`iterable of str`	Molecular formulas to include (e.g. `"H2O"`, `"CO2"`). If None, all detected molecules are included.	`None`
`iters`	`sequence of int`	Iteration numbers to include.	`None`
`by_index`	`bool`	If True, interpret `iters` as indices into the unique iteration list.	`False`
`fill_value`	`int`	Value used when a requested molecule is absent at an iteration.	`0`

Returns:

Type	Description
`DataFrame`	Wide table with columns: `iter` and one column per molecule containing occurrence counts.

Examples:

>>> df = get_molfra_data_wide_format(h, molecules=["H2O", "OH"], iters=[0, 100])

`get_molfra_totals_vs_axis(handler, *, xaxis='iter', control_file='control', quantities=('total_molecules', 'total_atoms', 'total_molecular_mass'))`

Return system-level totals versus a chosen x-axis.

Works on

MolFraHandler — molfra.out / molfra_ig.out

Parameters:

Name	Type	Description	Default
`handler`	`MolFraHandler`	Parsed molecular fragment handler with totals data available.	required
`xaxis`	`('iter', 'frame', 'time')`	X-axis to use. `time` conversion uses the control file.	`"iter"`
`control_file`	`str`	Path to the ReaxFF control file for time conversion.	`"control"`
`quantities`	`iterable of str`	Totals to include (e.g. `total_molecules`, `total_atoms`, `total_molecular_mass`).	`('total_molecules', 'total_atoms', 'total_molecular_mass')`

Returns:

Type	Description
`DataFrame`	Table with one column for the x-axis and one column per requested quantity.

Examples:

>>> df = get_molfra_totals_vs_axis(h, xaxis="time")

`largest_molecule_by_individual_mass(handler)`

Identify the molecule type with the largest individual mass at each iteration.

This is typically the main slab or backbone molecule.

Works on

MolFraHandler — molfra.out / molfra_ig.out

Parameters:

Name	Type	Description	Default
`handler`	`MolFraHandler`	Parsed molecular fragment handler.	required

Returns:

Type	Description
`DataFrame`	Table with columns: `iter`, `molecular_formula`, `molecular_mass`.

Examples:

>>> df = largest_molecule_by_individual_mass(h)