ffta.simulation package¶

Module contents¶

ffta.simulation.broadband_drive¶

class ffta.simulation.broadband_drive.BroadbandPulse(can_params, force_params, sim_params, chirp_lo=10, chirp_hi=1000000.0)¶

Bases: Cantilever

force(t, t0=0, tau=0)¶

Force on the cantilever at a given time.

Parameters

t (float) – time in seconds:
t0 –
tau –

Returns

Force on the cantilever at a given time, in N/kg.

Return type

float

ffta.simulation.cantilever¶

simulate.py: Contains Cantilever class.

class ffta.simulation.cantilever.Cantilever(can_params={}, force_params={}, sim_params={})

Bases: object

Damped Driven Harmonic Oscillator Simulator for AFM Cantilevers. Simulates a DDHO with given parameters.

This class contains the functions needed to simulate. To create a class that simulates a subset, it needs to overload the following functions: force(self, t) omega(self, t) dZdt(self, t) if the given ODE form will not work

amp

Amplitude of the cantilever in meters.

Type: float

beta

Damping factor of the cantilever in rad/s.

Type: float

delta

Initial phase of the cantilever in radians.

Type: float

delta_freq

Frequency shift of the cantilever under excitation.

Type: float

mass

Mass of the cantilever in kilograms.

Type: float

Z

ODE integration result, sampled at sampling_rate. Default integration is at 100 MHz.

Type: ndarray

t_Z

Time axis based on the provided total time and sampling rate

Type: ndarray

f_Z

Frequency axis based on the provided sampling rate

Type: ndarray

Method

------

simulate(trigger_phase=180): Simulates the cantilever motion with excitation happening at the given phase.

See also

pixel: Pixel processing for FF-trEFM data.

Examples

>>> from ffta.simulation import cantilever
>>> from ffta.simulation.utils import load
>>>
>>> params_file = '../examples/sim_params.cfg'
>>> params = load.simulation_configuration(params_file)
>>>
>>> c = cantilever.Cantilever(*params)
>>> Z, infodict = c.simulate()
>>> c.analyze()
>>> c.analyze(roi=0.004) # can change the parameters as desired

To correctly construct this, Cantilever requires the following parameters passed in the dictionaries can_params, force_params, and sim_params. Note: the dictionaries are functionally the same, you could leave force_params and sim_params blank and only create can_params.

Minimum parameters needed:

amp = float (in m) or:

amp_invols = float (in m/V) soft_amp = float (in V)

drive_freq = float (in Hz) res_freq = float (in Hz) k = float (in N/m) q_factor = float total_time = float (in seconds)

Parameters

can_params (dict) – Parameters for cantilever properties. The dictionary contains: amp_invols = float (in m/V) def_invols = float (in m/V) soft_amp = float (in V) drive_freq = float (in Hz) res_freq = float (in Hz) k = float (in N/m) q_factor = float
force_params (dict) – Parameters for forces. The dictionary contains: es_force = float (in N) delta_freq = float (in Hz) tau = float (in seconds) v_dc = float (in Volts) v_ac = float (in Volts) v_cpd = float (in Volts) dCdz = float (in F/m)
sim_params (dict) – Parameters for simulation. The dictionary contains: trigger = float (in seconds) total_time = float (in seconds) sampling_rate = int (in Hz)

analyze(plot=True, **kwargs)

Converts output to a Pixel class and analyzes

Parameters

plot (bool, optional) – If True, calls Pixel.plot() to display the results
kwargs –

Returns

Return type

Pixel object

create_parameters(params={}, can_params={}, fit_params={})

Creates a Pixel class-compatible parameters and cantilever parameters Dict

Parameters

params (dict, optional) – Contains analysis parameters for the Pixel cass
can_params (dict, optional) – Contains cantilever parameters for the Pixel class. These data are optional for the analysis.
fit_params (dict, optional) – Contains various parameters for fitting and analysis. See Pixel class.

dZ_dt(Z, t=0)

Takes the derivative of the given Z with respect to time.

Parameters

Z ((2, ) array_like) – Z[0] is the cantilever position, and Z[1] is the cantilever velocity.
t – time

:type t : float

Returns: Zdot[0] is the cantilever velocity, and Zdot[1] is the cantilever acceleration.
Rtype Zdot: (2, ) array_like

downsample(target_rate=10000000.0)

Downsamples the cantilever output. Used primarily to match experiments or for lower computational load

This will overwrite the existing output with the downsampled verison

Parameters: target_rate (int) – The sampling rate for the signal to be converted to. 1e7 = 10 MHz

force(t, t0=0, tau=0)

Force on the cantilever at a given time.

Parameters

t (float) – time in seconds
t0 –
tau –

Returns

Force on the cantilever at a given time, in N/kg.

Return type

float

omega(t, t0=0, tau=0)

Resonance frequency behavior

Parameters

t (float) – time in seconds
t0 –
tau –

Returns

Resonance frequency of the cantilever at a given time, in rad/s.

set_conditions(trigger_phase=180)

Sets initial conditions and other simulation parameters.

Parameters: trigger_phase (float, optional) – Trigger phase is in degrees and wrt cosine. Default value is 180.

simulate(trigger_phase=180, Z0=None)

Simulates the cantilever motion.

Parameters

trigger_phase (float, optional) – Trigger phase is in degrees and wrt cosine. Default value is 180.
Z0 (list, optional) – Z0 = [z0, v0], the initial position and velocity If not specified, is calculated from the analytical solution to DDHO (using “set_conditions”)

Returns

tuple (Z, infodict) WHERE array_like Z is Cantilever position in Volts, in format (n_points, 1) dict infodict is information about the ODE solver.

ffta.simulation.electric_drive¶

simulate.py: Contains Cantilever class.

class ffta.simulation.electric_drive.ElectricDrive(can_params, force_params, sim_params, v_array=[], v_step=nan, func=<function single_exp>, func_args=[])¶

Bases: Cantilever

dc_step(t, t0)¶

Adds a DC step at the trigger point for electrical drive simulation

Parameters

t (float) – Time in seconds.
t0 (float) – Event time in seconds.

Returns

Return type

force(t, t0, tau)¶

Force on the cantilever at a given time. It contains driving force and electrostatic force.

Parameters

t (float) – time in seconds
t0 (float) – event time in seconds:
tau (float) – Decay constant in the exponential function, in seconds.

Returns

Force on the cantilever at a given time, in N/kg.

Return type

float

omega(t, t0, tau)¶

Exponentially decaying resonance frequency.

Parameters

t (float) – time in seconds
t0 (float) – Event time in seconds.
tau (float) – Decay constant in the exponential function, in seconds.

Returns

Resonance frequency of the cantilever at a given time, in rad/s.

Return type

float

set_conditions(trigger_phase=180)¶

Sets initial conditions and other simulation parameters. Using 2w given the squared term in electric driving

Parameters: trigger_phase (float, optional) – Trigger phase is in degrees and wrt cosine. Default value is 180.

ffta.simulation.utils.excitation¶

Contains excitation functions used in simulations.

These functions all assume an output scaled from 0 to 1. In MechanicalDrive, these would all be passed to omega0 and to to Fe to change with these time-dependent conditions, where t is passed relative to the trigger Cantilever.trigger

ffta.simulation.utils.excitation.bi_exp(t, tau1, tau2)¶: Resonance frequency exhibits bi-exponential decay to a new offset

ffta.simulation.utils.excitation.single_exp(t, tau)¶

Resonance frequency exhibits single exponential decay to a new offset

Parameters

t (float or ndarray) – Time axis
tau (float) – Time constant for decay

ffta.simulation.utils.excitation.step(t)¶: Heaviside function

ffta.simulation.utils.excitation.str_exp(t, tau, beta)¶: Resonance frequency exhibits stretched exponential decay to a new offset

ffta.simulation.utils.load¶

Created on Tue May 12 11:23:17 2020

@author: Raj

ffta.simulation.utils.load.params_from_experiment(can_params_file, params_cfg)¶

Generates a simulation-compatible configuration given a Cantilever Parameters file (typically acquired in the experiment) and a Params.cfg file saved with FFtrEFM data

can_paramsstring: Path to cantilever parameters file (from Force Calibration tab)
params_cfgstring: Path to parameters.cfg file (from FFtrEFM experiment, in the data folder)

ffta.simulation.utils.load.simulation_configuration(path, is_url=False)¶

Reads an ASCII file with relevant parameters for simulation.

Parameters

path (string) – Path to ASCII file.
is_url (bool, optional) – Set to True if path is a URL

Returns

can_params (dict) – Parameters for cantilever properties. The dictionary contains:

amp_invols = float (in m/V) def_invols = float (in m/V) soft_amp = float (in V) drive_freq = float (in Hz) res_freq = float (in Hz) k = float (in N/m) q_factor = float
force_params (dict) – Parameters for forces. The dictionary contains:

es_force = float (in N) delta_freq = float (in Hz) tau = float (in seconds) v_dc = float (in V) v_ac = float (in V) v_cpd = float (in V) dcdz = float (in F/m)
sim_params (dict) – Parameters for simulation. The dictionary contains:

trigger = float (in seconds) total_time = float (in seconds) sampling_rate = int (in Hz)

ffta.simulation.mechanical_drive¶

class ffta.simulation.mechanical_drive.MechanicalDrive(can_params, force_params, sim_params, v_array=[], func=<function single_exp>, func_args=[])¶

Bases: Cantilever

Damped Driven Harmonic Oscillator Simulator for AFM Cantilevers under Mechanial drive (i.e. conventional DDHO)

Simulates a DDHO under excitation with given parameters and a change to resonance and electrostatic force

Time-dependent change can be specified in two ways:

explicitly defining v_array, a scale from 0 to 1 of the same length as
the desired integration
using a defined function and parameter, passed to parameter “func”
This approach will call self.func(t, *self.func_args) By default, this will call excitation.single_exp, a single exponential decay. For this approach to work, you must supply or set self.func_args = []

Z¶

ODE integration of the DDHO response

Type: ndarray

Method¶

------

simulate(trigger_phase=180)¶: Simulates the cantilever motion with excitation happening at the given phase.