KBI Calculator

Calculator for Kirkwood-Buff Integrals (KBIs) as a function of composition.

This calculator operates on a SystemCollection that contains molecular dynamics properties from structure and energy files. Additional inputs are key parameters used for the KBI corrections provided in KBIntegrator.

class kbkit.kbi.calculator.KBICalculator(systems: SystemCollection, weight_type: Literal['none', 'u0', 'u1', 'u2', 'geometric'] = 'geometric', errors: Literal['raise', 'warn', 'ignore'] = 'warn', force: bool = False)[source]

Bases: object

KBI calculator for system collections.

Parameters:

  • systems (SystemCollection) – SystemCollection object for set of systems.

  • weight_type (str, optional) – Type of weight function for finite-volume corrections. Options: (‘none’,’u0’,’u1’,’u2’,’geometric’)

  • errors (Literal["raise", "warn", "ignore"], optional) – Error mode for handling KBIConvergenceErrors. Only for weight_type='geometric'.

  • force (bool, optional) – If KBIConvergenceError is raised, warns user and returns KBI for weight_type='u2'. Only for weight_type='geometric'.

kbi(units: str = 'nm^3/molecule') → PropertyResult[source]

Computes Kirkwood-Buff integrals for molecular systems, if charges are present in SystemCollection return electrolyte_kbi() otherwise residue_kbi() is returned.

Parameters:

units (str, optional) – Units to compute KBI in, molar volume units.

Returns:

KBI Matrix with shape (composition x components x components).

Return type:

PropertyResult

residue_kbi(units: str = 'nm^3/molecule') → PropertyResult[source]

Computes Kirkwood-Buff integrals for molecular systems using RDF data.

Interfaces with RdfParser and KBIntegrator to extract pairwise KBIs and populate metadata.

Parameters:

units (str, optional) – Units to compute KBI in, molar volume units.

Returns:

  • PropertyResult – KBI Matrix with shape (composition x components x components).

  • .. note:: –

    • If an RDF directory is missing, the corresponding system’s values remain NaN, if ignore_convergence_errors is True.

    • Populates metadata with KBIntegrator object for each RDF file.

See also

KBIntegrator

electrolyte_kbi(units: str = 'nm^3/molecule') → PropertyResult[source]

Build the transformed KBI matrix for salts + molecules.

Here we implement the approach to convert distinguishable ions into indistinguishable salts through applying the electroneutrality principle according to the approach by Ploetz (2025).

Parameters:

units (str, optional) – Units to compute KBI in, molar volume units.

Returns:

KBI Matrix with shape (composition x neutral components x neutral components).

Return type:

PropertyResult

Notes

Electrolyte KBI applys corrections to transform KBI for ions into neutral species accounting for charge neutrality, sing mole fraction weighted combinations of cation and anion contributions.

Salt-salt KBI, \(G_{II'}\), are computed from ion-ion KBIs according to:

\[G_{II'} = x_{+}x_{+'}G_{++'} + x_{+}x_{-'}G_{+-'} + x_{+'}x_{-}G_{+'-} + x_{-}x_{-'}G_{--'}\]
\[\begin{split}\begin{aligned} x_{+} &= \frac{n_{+}}{n_{+} + n_{-}} \\ x_{-} &= \frac{n_{-}}{n_{+} + n_{-}} \\ x_{+'} &= \frac{n_{+'}}{n_{+'} + n_{-'}} \\ x_{-'} &= \frac{n_{-'}}{n_{+'} + n_{-'}} \\ \end{aligned}\end{split}\]

Salt-molecule KBI, \(G_{iI}\), are computed from molecule-ion KBIs according to:

\[G_{iI} = x_{+}G_{i+} + x_{-}G_{i-}\]
where:

  • \(I\) and \(I'\) represent two salts.

  • \(x_{+/-}\) represent the mole fraction of the cation/anion between two ions in a given salt.

  • \(i\) represents a neutral molecule.

kbi_plotter() → KBIAnalysisPlotter[source]

Create a KBIAnalysisPlotter for visualizing RDF integration and KBI convergence.

Parameters:

molecule_map (dict[str, str], optional) – dictionary mapping molecule names to desired molecule labels in figures.

Returns:

Plotter instance for inspecting KBI process.

Return type:

KBIAnalysisPlotter

References