IonicConductivity¶

class IonicConductivity(md_trajectory, start_time=None, end_time=None, atom_selection=None, anisotropy=None, ignore_measurement_data=None, time_resolution=None, info_panel=None)¶

Constructor for the IonicConductivity object.

Parameters:

md_trajectory (MDTrajectory | AtomicConfiguration) – The MDTrajectory from which the ionic conductivity is calculated.
start_time (PhysicalQuantity of type time) – The start time.
Default: 0.0 * fs.
end_time (PhysicalQuantity of type time) – The end time.
Default: The last time frame.
atom_selection (PeriodicTableElement | str | list of ints | list of PeriodicTableElement or str) – Only include contributions from this selection. The atoms can be selected by element i.e. PeriodicTableElement, tag or a list of atomic indices.
Default: All atoms.
anisotropy (list of type int | int | None) – The list of Cartesian directions (x=0, y=1, z=2) to calculate the anisotropic ionic conductivity in or a single Cartesian direction. By default an isotropic calculation is performed.
Default: None.
ignore_measurement_data (bool) – Whether or not to use stored measurement data.
Default: False.
time_resolution (PhysicalQuantity of type time) – The time interval between snapshots in the MD trajectory that are included in the analysis.
info_panel (InfoPanel (Plot2D)) – Info panel to show the calculation progress.
Default: No info panel.

chargeCurrentAutocorrelation()¶

Returns:: The autocorrelation of the charge current.
Return type:: PhysicalQuantity of type squared charge velocity.

data()¶

Returns:: The ionic conductivity values.
Return type:: PhysicalQuantity of type conductance per time.

times()¶

Returns:: Return the times of the Green-Kubo integral.
Return type:: PhysicalQuantity of type time.

Usage Examples¶

Calculate the ionic conductivity of lithium atoms in a battery electrolyte.

# Load in an equilibrated initial configuration with calculator
bulk_configuration = nlread('Battery_Electrolyte.hdf5')[-1]

# Calculate the trajectory, including charge current measurements
method = NVTNoseHoover(
    time_step=1*femtoSecond,
    reservoir_temperature=340*Kelvin,
    thermostat_timescale=100*femtoSecond,
    heating_rate=0*Kelvin/picoSecond,
    chain_length=3,
    initial_velocity=ConfigurationVelocities(remove_center_of_mass_momentum=True),
)

constraints = [FixCenterOfMass()]
measurement_names = ['charge_current', 'charge_current_components']

md_trajectory = MolecularDynamics(
    bulk_configuration,
    constraints=constraints,
    trajectory_filename='Battery_Electrolyte_Trajectory.hdf5',
    steps=10000000,
    trajectory_interval=10000,
    measurement_hook=MDMeasurement(measurement_names, call_interval=10),
    method=method
)

# Calculate the ionic conductivity
self_diffusion = IonicConductivity(
    md_trajectory,
    atom_selection=Lithium
)

# Get the times in ps and the conductivity values in Siemens/Meter.
times        = self_diffusion.times()
conductivity = self_diffusion.data()

# Plot the diffusion coefficient calculated with different time limits
model = Plot.PlotModel(ps, Siemens/Meter)
model.title().setText('Ionic Conductivity of Lithium Electrolyte')
model.xAxis().setLabel('Time')
model.yAxis().setLabel('Conductivity')
model.legend().setVisible(False)

# Add diffusion integral
line = Plot.Line(times, conductivity)
line.setColor('blue')

# Add average
average = Plot.Average()
line.addItem(average)
max_time = times[-1]
average.setBounds(max_time*0.1, max_time*0.9)
average.setColor('red')

# Add line to the plot
model.addItem(line)

# Set limits and show the plot
model.setLimits()
Plot.show(model)

ionic_conductivity.py

Notes¶

The IonicConductivity \(\sigma\) is calculated from the ionic current auto-correlation function using the Green-Kubo expression:

\[\sigma = \frac{1}{3k_BTV} \int_0^\infty d\tau \langle \mathbf{j}_i(t) \mathbf{j}_i(t+\tau) \rangle\]

Here the ensemble average \(<...>\) averages over time origins \(t\). The ionic current \(\mathbf{j}(t)\) is given as the sum of the individual charge velocities:

\[\mathbf{j}(t) = \sum_i^N q_i \mathbf{v}_i(t)\]

The atomic charges are taken from the atomic partial charges assigned to each atom. These need to be set in the MDTrajectory used for the analysis.

When calculating quantities using Green-Kubo expressions, it is important that the trajectory both contains a short enough time step to be able to determine the decay in the auto-correlation function, as well as a long enough time scale to encompass the auto-correlation time length and provide enough time origins for accurate sampling. When calculating the ionic conductivity, ideally as the charge current auto-correlation decreases to zero, the above integral should converge to a static value at longer time scales. Practically however, longer times in the auto-correlation function corresponds to fewer time origins in the ensemble average. This increases the sampling error and can lead to non-convergence in the charge current auto-correlation functions and subsequently the ionic conductivity.

As in each time point only a single sum of charge currents is required, it is possible to save this data in an MDTrajectory as a measurement. This can be used to increase the frequency of data without significantly increasing the size of the trajectory. To add this measurement during a molecular dynamics simulation the measurements charge_current and charge_current_component can be used. The first saves just the total charge current to the MDTrajectory, while the second saves individual charge currents for each element and tag in the configuration. This is useful for calculating the ionic conductivity of different components of the system. When the MDTrajectory is loaded by the IonicConductivity analysis it looks for these two measurements, and if present the ionic conductivity is calculated from these. Setting the argument ignore_measurement_data to True forces the analysis to be performed from just the configurations contained in the trajectory.

The IonicConductivity analysis method returns the calculated ionic conductivity using different time limits. The optimal value of the ionic conductivity is usually taken in the region where the auto-correlation has decayed sufficiently for the integral to converge, and also there are enough time origins for accurate sampling. The auto-correlation time scale can vary significantly depending on the potential acting on the atoms.

By default, all elements are taken into account, but a specified selection can be given as well. The atom_selection parameter accepts an element, a tag name, or a list of atom indices to select which charge currents are included in the calculation. This can be useful for when only certain atoms should be included in the analysis, such as when there are constrained atoms in the system that excluded. It is also possible to select to only calculate ionic conductivity in specific Cartesian directions using the anisotropy argument. This can be useful in cases such as calculating the ionic conductivity of atoms between two surfaces.