Langesim package

langesim.simulator module

Simulator and Simulation classes

class langesim.simulator.Simulation(tot_sims, dt, tot_steps, noise_scaler, snapshot_step, k, center, results, name='', harmonic_potential=True, force=None, potential=None)[source]

Bases: object

Stores simulation parameters and results. Analyses the results: builds PDF of the simulation results (position, work, etc..)

tot_sims

Total number of individual simulations.

Type

int

dt

time step

Type

float

tot_steps

total steps of the simulation.

Type

int

noise_scaler

brownian noise variance (k_B T). Defaults to 1.0.

Type

float

name

name of the simulation.

Type

str

k

function k(t) that gives the harmonic potential stifness as a function of time.

Type

Callable

center

function center(t) of the harmonic potential as a function of time

Type

Callable

harmonic_potential

True if the potential is harmonic, False otherwise.

Type

bool

force

function force(x,t) applied on the particle at position x at time t.

Type

Callable

potential

function potential(x,t) energy of the particle at position x at time t.

Type

Callable

results

results of the simulations:

results = {
    "times": times, # (ndarray): times where snapshot where taken.
    "x": x,         # (ndarray of shape (tot_sims, tot_snapshots)):
                    # x[sim][ts] is the position of the brownian particle in
                    # simulation number num and snapshot index ts
    "power": power, # (ndarray of shape (tot_sims, tot_snapshots)):
                    # power[sim][ts] is the power into the system
                    # at snapshot ts and simulation sim
    "work": work,   # (ndarray of shape (tot_sims, tot_snapshots)):
                    # work[sim][ts] is the work performed into the
                    # system in simulation sim up to snapshot ts
    "heat": heat,   # (ndarray of shape (tot_sims, tot_snapshots)):
                    # heat[sim][ts] into the system in simulation sim
                    # up to snapshot ts
    "delta_U": delta_U, # (ndarray of shape (tot_sims, tot_snapshots)):
                        # delta_U[sim][ts] is the energy difference
                        # between snapshot = 0 and current snapshot ts
                        # in simulation sim
    "energy": energy,   # (ndarray of shape (tot_sims, tot_snapshots)):
                        # energy[sim][ts] in simulation sim at snapshot ts
}
Type

dict

histogram

histograms of quantities:

histogram = {
    "x": list of histograms of position
    "power": list histogram of power
    "work": list of histogram of work
    "heat": list of histograms of heat
    "delta_U": list of histograms of energy difference between t=0 and time t
    "energy": list of histograms of energy
}
# Example: Simulation.histogram["x"][i] gives the histogram of "x" at time
# snapshot number i.
Type

dict

kde

Kernel Density Estimation of quantities:

kde = {
    "x": list of KDE of position
    "power": list of KDE of power
    "work": list of KDE of work
    "heat": list of KDE of heat
    "delta_U": list of KDE of energy difference between t=0 and time t
    "energy": list of KDE of energy
}
# Example: Simulation.kde["x"][i] gives the KDE of "x" at time snapshot number i.
Type

dict

kde_grid_points_data

KDE evaluated at grid points:

kde_grid_points_data = {
    "x": list of KDE evaluated at grid points of position
    "power": list of KDE evaluated at grid points of power
    "work": list of KDE evaluated at grid points of work
    "heat": list of KDE evaluated at grid points of heat
    "delta_U": list KDE evaluated at grid points of energy difference between t=0 and time t
    "energy": list KDE evaluated at grid points of energy
}
# Example: Simulation.kde_grid_points_data["x"][i] = (x, P(x,t)) gives the KDE evaluated at grid points of "x" at time
snapshot number i.
Type

dict

pdf

probability distribution functions of x, power, work, heat, delta_U, energy:

# Example: pdf["x"](x,t) gives the PDF of position x at time t.
Type

dict

averages

Averages of position, work, heat, power, delta_U and energy:

# Example: averages["x"][i] is the position average at snapshot number i.
Type

dict

average_func

dictionary of function that give the average at a given time:

# Example: average_func["x"](t)= position average at time t.
Type

dict

variances

variances of position, work, heat, power, delta_U and energy:

# Example: variances["x"][i] is the position variance at snapshot number i.
Type

dict

variance_func

variances of position, power, heat, work, energy at time t:

# t. Example: variance_func["x"](t)= position variance at time t.
Type

dict

__init__(tot_sims, dt, tot_steps, noise_scaler, snapshot_step, k, center, results, name='', harmonic_potential=True, force=None, potential=None)[source]

Initializes the Simulation class with parameters and raw results

Parameters

  • tot_sims (int) – total number of simulations.

  • dt (float) – time step.

  • tot_steps (int) – number of steps of each simulation.

  • noise_scaler (float) – brownian noise scale k_B T. Defaults to 1.0.

  • snapshot_step (int) – a snapshot of simulation has been saved each snapshot_step time.

  • k (float function) – stiffness of the potential

  • center (float function) – center of the potential

  • results (tuple) –

    results in the form (times, x, power, work, heat, delta_U, energy) where:

    times (ndarray):

    ndarray of times where snapshot where taken.

    x (ndarray of shape (tot_sims, tot_snapshots)):

    x[sim][ts] is the position of the brownian particle in simulation number num and snapshot ts

    power (ndarray of shape (tot_sims, tot_snapshots)):

    power[sim][ts] is the power into the system at snapshot ts and simulation sim

    work (ndarray of shape (tot_sims, tot_snapshots)):

    work[sim][ts] is the work performed into the system in simulation sim up to snapshot ts

    heat (ndarray of shape (tot_sims, tot_snapshots)):

    heat[sim][ts] into the system in simulation sim up to snapshot ts

    delta_U (ndarray of shape (tot_sims, tot_snapshots)):

    delta_U[sim][ts] is the energy difference between snapshot = 0 and current snapshot ts in simulation sim

    energy (ndarray of shape (tot_sims, tot_snapshots)):

    energy[sim][ts] in simulation sim at snapshot ts

  • name (string, optional) – name of the simulation

  • harmonic_potential (boolean, optional) – True if the potential is harmonic

  • force (float function(x,t), optional) – force when the potential is not harmonic

  • potential (float function(x,t), optional) – potential when the potential is not harmonic

analyse()[source]

Builds all histograms, PDF, averages and variances

animate_pdf(quantity, x_range=[-3.0, 3.0], y_range=[0, 1.5], bins=300, show_x_eq_distrib=None)[source]

Shows an animation of the evolution of the PDF of a quantity

Parameters

  • quantity (string) – quantity to animate its PDF. Must be in [“x”, “power”, “work”, “heat”, “delta_U”, “energy”]

  • x_range (list, optional) – range for the quantity in the PDF. Defaults to [-3.0, 3.0].

  • y_range (list, optional) – range for the PDF value. Defaults to [0, 1.5].

  • bins (int, optional) – bins for the histogram. Defaults to 300.

  • show_x_eq_distrib (boolean, optional) – if True the instantaneous

  • None. (equilibrium position distribution is shown. Defaults to) –

Raises

ValueError – if quantity is not in [“x”, “power”, “work”, “heat”, “delta_U”, “energy”]

Returns

animation of the PDF

Return type

plotly.graph_objects.figure

build_averages(quantity)[source]

Computes the average of a quantity. The average at time t (with corresponding time_index of the snapshot) is stored in averages[quantity][time_index] A function giving the average as a function of time is created and stored in average_func(quantity)

Parameters

quantity (string) – quantity to build its averages. Should be in [“x”, “power”, “work”, “heat”, “delta_U”, “energy”]

Raises

ValueError – if quantity is not in [“x”, “power”, “work”, “heat”, “delta_U”, “energy”]

build_histogram(quantity, bins=300, q_range=None)[source]

Builds the histogram of a quantity

Parameters

  • quantity (string) – quantity to build its histogram. Should be in [“x”, “power”, “work”, “heat”, “delta_U”, “energy”]

  • bins (int, optional) – bins for the histogram. Defaults to 300.

  • q_range (list, optional) – range for the quantity. Defaults to None for automatic range. Not using automatic range can introduce bugs in the histograms if there are outliers.

build_kde(quantity, bw='scott', grid_points=None)[source]

Builds the Kernel Density Estimation (KDE) of a quantity at each time snapshot. The KDE is stored in self.kde[quantity] and the KDE evaluated at grid_points is stored in self.kde_grid_points_data[quantity] (to be used in PDF interpolation)

Parameters

  • quantity (string) – quantity to build its KDE. Should be in [“x”, “power”, “work”, “heat”, “delta_U”, “energy”]

  • bw (string, optional) – bandwidth for the KDE. Defaults to “scott”. For other options see KDEpy.FFTKDE documentation.

  • grid_points (int, optional) – number of grid points for the evaluation of the KDE. Defaults to None (automatic).

build_pdf(quantity, bins=300, q_range=None, method='kde', bw='scott', grid_points=None)[source]

Builds the probability density function (PDF) for a quantity. The PDF is build and function is defined to access it in self.pdf(quantity)

Parameters

  • quantity (string) – quantity to build its pdf. Should be in [“x”, “power”, “work”, “heat”, “delta_U”, “energy”]

  • bins (int, optional) – bins for the histogram. Defaults to 300.

  • q_range (list, optional) – range for the quantity. Defaults to None for automatic range. Not using automatic range can introduce bugs in the histograms if there are outliers.

  • method (string, optional) – method to build the PDF. Defaults to “kde” for Kernel Density Estimation. Other method is “legacy” which interpolate the histogram.

  • bw (string, optional) – bandwidth for the KDE. Defaults to “scott”. For other options see KDEpy.FFTKDE documentation. Not used if method is “legacy”.

  • grid_points (int, optional) – number of grid points for the KDE. Defaults to None (automatic). Not used if method is “legacy”.

Raises

  • ValueError – if quantity is not in [“x”, “power”, “work”, “heat”, “delta_U”, “energy”]

  • ValueError – if method is not in [“kde”, “legacy”]

build_variances(quantity)[source]

Computes the variance of a quantity. The variance at time t (with corresponding time_index of the snapshot) is stored in variances[quantity][time_index] A function giving the variance as a function of time is created and stored in variance_func(quantity)

Parameters

quantity (string) – quantity to build its variances. Should be in [“x”, “power”, “work”, “heat”, “delta_U”, “energy”]

Raises

ValueError – if quantity is not in [“x”, “power”, “work”, “heat”, “delta_U”, “energy”]

classmethod load(filename)[source]

Loads a simulation from file

Parameters

filename (string) – filename of the simulation to load

Returns

the loaded simulation

Return type

Simulation

plot_average(quantity, t_range=None, y_range=None, t_label='t', y_label=None)[source]

Plots <quantity> as a function of time

Parameters

  • quantity (string) – quantity to plot. Should be in [“x”, “power”, “work”, “heat”, “delta_U”, “energy”]

  • t_array (np.array) – time axis array

  • y_array (np.array) – quantity to plot array

  • t_range (list, optional) – t range. Defaults to Autoscale.

  • y_range (list, optional) – y range. Defaults to Autoscale.

  • t_label (str, optional) – label for t axis. Defaults to ‘t’.

  • y_label (str, optional) – label for y axis. Defaults to ‘’.

Raises

ValueError – if quantity is not in [“x”, “power”, “work”, “heat”, “delta_U”, “energy”]

Returns

plot of the quantity

Return type

plotly.graph_objects.figure

plot_sim(quantity: str, sim_list: List[int], sim_labels=None, t_range=None, y_range=None, t_label='t', y_label=None)[source]

Plots quantity as a function of time for simulations listed in sim_list

Parameters

  • quantity (str) – quantity to plot. Should be in [“x”, “power”, “work”, “heat”, “delta_U”, “energy”]

  • sim_list (list of int) – list of the simulation numbers to plot.

  • sim_labels (list of str, optional) – list of labels for each trace in the plot. Defaults to None.

  • t_array (np.array) – time axis array

  • y_array (np.array) – quantity to plot array

  • t_range (list, optional) – t range. Defaults to Autoscale.

  • y_range (list, optional) – y range. Defaults to Autoscale.

  • t_label (str, optional) – label for t axis. Defaults to ‘t’.

  • y_label (str, optional) – label for y axis. Defaults to ‘’.

Raises

ValueError – if quantity is not in [“x”, “power”, “work”, “heat”, “delta_U”, “energy”]

Returns

plot of the quantity

Return type

plotly.graph_objects.figure

plot_variance(quantity, t_range=None, y_range=None, t_label='t', y_label=None)[source]

Plots the variance of quantity as a function of time

Parameters

  • quantity (string) – quantity to plot. Should be in [“x”, “power”, “work”, “heat”, “delta_U”, “energy”]

  • t_array (np.array) – time axis array

  • y_array (np.array) – quantity to plot array

  • t_range (list, optional) – t range. Defaults to Autoscale.

  • y_range (list, optional) – y range. Defaults to Autoscale.

  • t_label (str, optional) – label for t axis. Defaults to ‘t’.

  • y_label (str, optional) – label for y axis. Defaults to ‘’.

Raises

ValueError – if quantity is not in [“x”, “power”, “work”, “heat”, “delta_U”, “energy”]

Returns

plot of the quantity

Return type

plotly.graph_objects.figure

result_labels = ['x', 'power', 'work', 'heat', 'delta_U', 'energy']
save(filename)[source]

Saves the simulation

Parameters

filename (string) – filename where the simulation is saved

class langesim.simulator.Simulator(tot_sims=1000, dt=0.001, tot_steps=10000, noise_scaler=1.0, snapshot_step=100, k=None, center=None, harmonic_potential=True, force=None, potential=None, initial_distribution=None)[source]

Bases: object

Simulator class for Langevin dynamics of a harmonic oscillator with variable potential. Encapsulates the simulator, perform simulations, analyses them and store results of simulations.

tot_sims

default total number of simulations to run per batch.

Type

int

dt

default time step.

Type

float

tot_steps

default total steps of the simulation

Type

int

noise_scaler

default brownian noise variance (k_B T).

Type

float

k

function k(t) that gives the harmonic potential stifness as a function of time.

Type

Callable

center

function center(t) of the harmonic potential as a function of time

Type

Callable

harmonic_potential

True if the potential is harmonic, False otherwise.

Type

bool

force

function force(x,t) applied on the particle at position x at time t.

Type

Callable

potential

function potential(x,t) energy of the particle at position x at time t.

Type

Callable

initial_distribution

function without arguments that samples the initial distribution of the particles.

Type

Callable

simulator

numba JIT function that performs simulations.

Type

numba.Dispatcher

simulations_performed

number of batches of simulations that the Simulator has done. It is the number of times that Simulator.run() has been called.

simulation

list of Simulation objects that contain the results of the simulations that have been runned.

Type

list

__init__(tot_sims=1000, dt=0.001, tot_steps=10000, noise_scaler=1.0, snapshot_step=100, k=None, center=None, harmonic_potential=True, force=None, potential=None, initial_distribution=None)[source]

Initializes the Simulator

Parameters

  • tot_sims (int, optional) – total number of simulations. Defaults to 1000.

  • dt (float, optional) – time step. Defaults to 0.001.

  • tot_steps (int, optional) – total steps of each simulation. Defaults to 10000.

  • noise_scaler (float, optional) – brownian noise scale k_B T. Defaults to 1.0.

  • snapshot_step (int, optional) – save a snapshot of simulation at each snapshot_step time. Defaults to 100.

  • k (float function, optional) – stiffness function k(t) of the potential. Defaults to k(t)=1.0.

  • center (float function, optional) – center function of the potential. Defaults to center(t)=0.0.

  • harmonic_potential (boolean, optional) – If True: the external potential is harmonic with stiffness k(t) and center(t). If False the external force is given by the force argument or the the external potential is given by potential argument

  • force (float function(x,t), optional) – the external force

  • potential (float function(x,t), optional) – the external potential

  • initial_distribution (float function(), optional) – initial condition for x(0). Default: sampled from Boltzmann factor at time 0: exp(-U(x,0))

analyse(sim_num=None)[source]

Performs the analysis of simulation number sim_num

Parameters

sim_num (int, optional) – simulation number. Defaults to last simulation performed.

run(tot_sims=None, dt=None, tot_steps=None, noise_scaler=None, snapshot_step=None, name='')[source]

Runs a batch of tot_sim simulations and appends the results to Simulator.simulation list.

Parameters

  • tot_sims (int, optional) – total number of simulations.

  • dt (float, optional) – time step.

  • tot_steps (int, optional) – total steps of each simulation.

  • noise_scaler (float, optional) – brownian noise scale k_B T.

  • snapshot_step (int, optional) – save a snapshot of simulation at each snapshot_step time.

  • name (str, optional) – name of the simulation

langesim.simulator.make_simulator(tot_sims=1000, dt=0.001, tot_steps=10000, noise_scaler=1.0, snapshot_step=100, k=None, center=None, harmonic_potential=True, force=None, potential=None, initial_distribution=None)[source]

Makes a numba compiled njit langevin simulator of a brownian particle in an external time variable potential or force

Parameters

  • tot_sims (int, optional) – default total number of simulations. Defaults to 1000.

  • dt (float, optional) – default time step. Defaults to 0.001.

  • tot_steps (int, optional) – default number of steps of each simulation. Defaults to 10000.

  • noise_scaler (float, optional) – brownian noise variance k_B T. Defaults to 1.0.

  • snapshot_step (int, optional) – save a snapshot of simulation at each snapshot_step time. Defaults to 100.

  • k (float function, optional) – stiffness function k(t) of the potential. Defaults to k(t)=1.0.

  • center (float function, optional) – center function of the potential. Defaults to center(t)=0.0.

  • harmonic_potential (boolean, optional) – If True: the external potential is harmonic with stiffness k(t) and center(t). If False the external force is given by the force argument or the the external potential is given by potential argument

  • force (float function(x,t), optional) – the external force

  • potential (float function(x,t), optional) – the external potential

  • initial_distribution (float function(), optional) – initial condition for x(0). Default: sampled from Boltzmann factor at time 0: exp(-U(x,0))

Returns

numba JIT compiled function that performs simulations

Return type

numba.Dispatcher

langesim.graphic_utilities module

Graphics utilities to plot the simulations results.

langesim.graphic_utilities.animate_simulation(times, xst, x_range=[-3.0, 6.0], y_range=[0, 1.5], bins=300, x_label='x', y_label='P(x,t)', show_x_eq_distrib=True, k=None, center=None, harmonic_potential=True, potential=None)[source]

Plot and animates a simulation data results

Parameters

  • times (list of float) – list of times where snapshots where taken

  • xst (list of list of float) – list of snapshots of many simulations. Should have shape (tot_sims, tot_snapshots)

  • x_range (list, optional) – range of the data to plot. Defaults to [-3.0, 6.0].

  • y_range (list, optional) – range of the histogram of xst. Defaults to [0, 1.5].

  • bins (int, optional) – bins to compute histogram of xst. Defaults to 300.

  • x_label (str, optional) – label for xst in the plot. Defaults to ‘x’.

  • y_label (str, optional) – label for the probability density of xst. Defaults to ‘P(x,t)’.

  • show_x_eq_distrib (bool, optional) – show the equilibrium distribution corresponding to a harmonic oscilator with center(t) and stiffness k(t). Defaults to True.

  • k (float function, optional) – stiffness function of the potential. Defaults to k(t)=1.0.

  • center (float function, optional) – center function of the potential. Defaults to center(t)=0.0.

  • harmonic_potential – True if working with a harmonic potential

  • potential – potential energy to use when harmonic_potential=False

Returns

animation of the simulation data

Return type

plotly.graph_objects.figure

langesim.graphic_utilities.plot_quantity(t_array, y_array, t_range=None, y_range=None, t_label='t', y_label='', scatter_label=None)[source]

Plots y_array as function of t_array

Parameters

  • t_array (np.array) – time axis array

  • y_array (np.array) – quantity to plot array

  • t_range (list, optional) – t range. Defaults to Autoscale.

  • y_range (list, optional) – y range. Defaults to Autoscale.

  • t_label (str, optional) – label for t axis. Defaults to ‘t’.

  • y_label (str, optional) – label for y axis. Defaults to ‘’.

Returns

the plot of the quantity

Return type

plotly.graph_objects.figure

langesim.sampler module

Sampler to generate random samples distributed according to a given arbitrary probability density function (pdf). It uses the inverse transform sampling method.

Adapted from:

langesim.sampler.make_sampler(pdf, range=(-25, 25), bins=1000000)[source]

Generates a sampler of random samples distributed with pdf using the inverse transform sampling method.

Parameters

  • pdf (function(x)) – probability density function to draw the samples. Does not need to be normalized

  • range (tuple, optional) – range for the random variable values. Defaults to (-25,25).

  • bins (int, optional) – bins to build the discretized inverse cumulative distribution function. Defaults to 1 000 000.

Returns

samplers that provide random numbers distributed with the given pdf.

sampler_single() returns one single value.

sampler_multi(n) return n random values.

Return type

sampler_single, sampler_multi (tuple of functions)