sulfur_simulation package

A set of tools for phonon simulations.

sulfur_simulation.SULFUR_IS_COOL = True

A statement about sulfur simulations.

Submodules

sulfur_simulation.cache module

class sulfur_simulation.cache.CachedFunction(function: Callable[P, R], path: Path | Callable[P, Path | None] | None, *, default_call: CallType = 'load_or_call_cached')

Bases: Generic[P, R]

A function wrapper which is used to cache the output.

call_cached(*args: P.args, **kw: P.kwargs) → R

Call the function, and save the result to the cache.

call_uncached(*args: P.args, **kw: P.kwargs) → R

Call the function, without using the cache.

load_or_call_cached(*args: P.args, **kw: P.kwargs) → R

Call the function cached, using the cached data if available.

load_or_call_uncached(*args: P.args, **kw: P.kwargs) → R

Call the function uncached, using the cached data if available.

sulfur_simulation.cache.cached(path: Path | None, *, default_call: Literal['load_or_call_cached', 'load_or_call_uncached', 'call_uncached', 'call_cached'] = 'load_or_call_cached') → Callable[[Callable[P, R]], CachedFunction[P, R]]

sulfur_simulation.cache.cached(path: Callable[P, Path | None], *, default_call: Literal['load_or_call_cached', 'load_or_call_uncached', 'call_uncached', 'call_cached'] = 'load_or_call_cached') → Callable[[Callable[P, R]], CachedFunction[P, R]]

Cache the response of the function at the given path using pickle.

Parameters

pathPath | Callable[P, Path]

The file to read.

Returns

Callable[[Callable[P, R]], Callable[P, R]]

sulfur_simulation.cache.timed(f: Callable[P, R]) → Callable[P, R]

Log the time taken for f to run.

Parameters

fCallable[P, R]

The function to time

Returns

Callable[P, R]

The decorated function

sulfur_simulation.hopping_calculator module

class sulfur_simulation.hopping_calculator.BaseRate

Bases: ABC

Return grid of baserates.

abstract property grid: ndarray[tuple[int, int], dtype[floating]]

Generate grid of baserates.

class sulfur_simulation.hopping_calculator.BaseRateHoppingCalculator(*, baserate: BaseRate, temperature: float, lattice_directions: tuple[ndarray, ndarray])

Bases: HoppingCalculator

Class for calculating hopping probabilities in a square lattice.

get_hopping_probabilities(positions: ndarray[tuple[int, int], dtype[bool]]) → ndarray[tuple[int, int], dtype[floating]]

Get hopping probabilities.

property normalized_directions: tuple[ndarray, ndarray]

Normalize lattice directions.

class sulfur_simulation.hopping_calculator.HexagonalBaseRate(*, rate: float)

Bases: BaseRate

Baserates for hopping.

property grid: ndarray[tuple[int, int], dtype[floating]]

Generate grid of baserates.

rate: float

class sulfur_simulation.hopping_calculator.HoppingCalculator

Bases: ABC

Abstract base class for calculating hopping probabilities.

abstractmethod get_hopping_probabilities(positions: ndarray) → ndarray

Get hopping probabilities.

class sulfur_simulation.hopping_calculator.InteractingHoppingCalculator(*, baserate: BaseRate, temperature: float, lattice_directions: tuple[np.ndarray, np.ndarray], interaction: Callable[[float], float], cutoff_potential: float = 1.6e-22)

Bases: BaseRateHoppingCalculator

Hopping Calculator with a Lennard Jones potential between particles in a square lattice.

class sulfur_simulation.hopping_calculator.LineDefectHoppingCalculator(*, baserate: BaseRate, temperature: float, lattice_directions: tuple[ndarray, ndarray])

Bases: BaseRateHoppingCalculator

Hopping Calculator for a line defect in a square lattice.

class sulfur_simulation.hopping_calculator.SquareBaseRate(*, straight_rate: float, diagonal_rate: float = 0)

Bases: BaseRate

Baserates for hopping.

diagonal_rate: float = 0

Baserate for moving diagonally in a square lattice

property grid: ndarray[tuple[int, int], dtype[floating]]

Generate grid of baserates.

straight_rate: float

Baserate for moving horizontally or vertically in a square lattice

sulfur_simulation.hopping_calculator.get_lennard_jones_potential(sigma: float, epsilon: float, cutoff_energy: float = 1.9e-20) → Callable[[float], float]

Take float and return Lennard Jones potential.

…math:::

V(r) = 4 * epsilon * ((sigma / r) ** 12 - (sigma / r) ** 6)

Sigma = radius where potential = 0 Epsilon = minimum potential reached

sulfur_simulation.isf module

class sulfur_simulation.isf.ISFParameters(*, delta_k_max: float = 6.283185307179586, params: SimulationParameters, form_factor: float = 1)

Bases: object

Parameters for plotting results of simulation.

property delta_k_array: ndarray

All delta_k values.

delta_k_max: float = 6.283185307179586

The max value of delta_k

form_factor: float = 1

Prefactor for scattered amplitude

property n_delta_k: int

Number of delta_k values.

params: SimulationParameters

Simulation parameters.

sulfur_simulation.isf.get_all_amplitudes(isf_params: ISFParameters, results: list[SimulationResult]) → list[np.ndarray[tuple[int, int], np.dtype[np.complex128]]]

Get amplitudes for all runs and return as a list.

sulfur_simulation.isf.get_amplitudes(isf_params: ISFParameters, positions: ndarray[tuple[int, int, int], dtype[bool]]) → ndarray[tuple[int, int], dtype[complex128]]

Return summed complex amplitudes for each delta_k (rows) and timestep (columns).

sulfur_simulation.isf.get_dephasing_rates(amplitudes: list[ndarray[tuple[int, int], dtype[complex128]]], t: ndarray) → ndarray

Calculate dephasing rates for all amplitudes.

sulfur_simulation.isf.plot_dephasing_rates(dephasing_rates: np.ndarray, delta_k: np.ndarray, *, ax: Axes | None = None) → tuple[Figure | SubFigure, Axes]

Plot dephasing rates against delta_k values.

sulfur_simulation.isf.plot_isf(x: list[np.ndarray[tuple[int, int], np.dtype[np.complex128]]], isf_params: ISFParameters, delta_k_index: int, t: np.ndarray, *, ax: Axes | None = None) → tuple[Figure | SubFigure, Axes]

Plot autocorrelation data with an exponential curve fit on a given axis.

sulfur_simulation.scattering_calculation module

class sulfur_simulation.scattering_calculation.SimulationParameters(*, n_timesteps: int, lattice_dimension: tuple[int, int], n_particles: int, hopping_calculator: HoppingCalculator)

Bases: object

Parameters for simulating diffusion.

hopping_calculator: HoppingCalculator

property initial_positions: ndarray

Initial particle positions.

Raises

ValueError

If the number of particles exceeds the number of lattice spaces.

lattice_dimension: tuple[int, int]

Dimension of lattice

n_particles: int

The number of particles

n_timesteps: int

Number of timesteps

property times: ndarray

Times for simulation.

class sulfur_simulation.scattering_calculation.SimulationResult(*, positions: ndarray[tuple[int, int, int], dtype[bool]], jump_count: ndarray[tuple[int], dtype[int64]], attempted_jump_counter: ndarray[tuple[int], dtype[int64]])

Bases: object

Results of a simulation.

attempted_jump_counter: ndarray[tuple[int], dtype[int64]]

The number of jumps attempted

jump_count: ndarray[tuple[int], dtype[int64]]

The number of successful jumps in each direction

positions: ndarray[tuple[int, int, int], dtype[bool]]

The particles’ positions at each timestep

sulfur_simulation.scattering_calculation.run_simulation(n_runs: int, params: SimulationParameters, rng: Generator | None = None) → list[SimulationResult]

Run multiple simulations and return the results as a list.

sulfur_simulation.show_simulation module

sulfur_simulation.show_simulation.animate_particle_positions(all_positions: NDArray[np.bool_], lattice_dimension: tuple[int, int], timesteps: NDArray[np.float64], lattice_vectors: tuple[NDArray[np.float64], NDArray[np.float64]]) → animation.FuncAnimation

Animate particle positions on a skewed lattice defined by two lattice vectors.

sulfur_simulation.show_simulation.get_timeframe_str(positions: np.ndarray[tuple[int, int], np.dtype[np.bool_]], timestep: int, params: SimulationParameters) → str

Print a preview of positions at specified timestep. Works for small grids.

sulfur_simulation.show_simulation.plot_mean_jump_rates(results: list[SimulationResult], ax: Axes | None = None) → tuple[Figure | SubFigure, Axes]

Plot attempted and successful jump counts.

sulfur_simulation.util module

sulfur_simulation.util.get_figure(ax: Axes | None = None) → tuple[Figure | SubFigure, Axes]

Get a figure and axes for plotting.