Functions

pylion defines a number of functions that can be used to configure a simulation. They all return dictionaries that you can append to a Simulation().

pylion.functions.efield(uid, ex, ey, ez)

Adds a uniform, time-independent e-field to the simulation. ex, ey, ez are the magnitudes of the electric field in V/m.

See Also: http://lammps.sandia.gov/doc/fix_efield.html

Parameters:

• ex – x component of electric field

• ey – y component of electric field

• ez – z component of electric field

pylion.functions.placeions(ions, positions)

Places the given ions at the (x, y, z) coordinates specified.

Example:

>>> ions = {'mass': 40, 'charge': 1}
>>> positions = [[1e-4, -0.5e-5, 0], [1e-4, 0, 0], [1e-4, 0.5e-5, 0]]
>>> placeions(ions, positions)

Parameters:

• ions – dict with keys ‘charge’, ‘mass’

• positions – list of (x, y , z) coodrinates of each ion

pylion.functions.createioncloud(ions, radius, number)

Creates a cloud of ions that can be added to the trap. LAMMPS does have a function that can create ions in a cloud-like configuration, but it requires a lattice to be declared, and is prone to overlapping ions. As a result, we instead calculate individual positions and palce them by hand.

Parameters:

• ions – dict with keys ‘charge’, ‘mass’

• radius – radius of cloud

• number – number of atoms

pylion.functions.evolve(steps)

Evolves the lammps simulation for a certain number of steps.

See Also: http://lammps.sandia.gov/doc/run.html

Example:

>>> evolve(1e6)

Parameters:

steps – number of steps

pylion.functions.thermalvelocities(temperature, zerototalmomentum=True)

Sets the velocities of the ions to those given by a thermal distribution of input temperature (Kelvin). Set zeroTotalMom to ‘True’ if the resulting ensemble should have zero total linear momentum.

Example:

>>> thermalVelocities(300, zerototalmomentum=False)

See Also: http://lammps.sandia.gov/doc/velocity.html

Parameters:

• temperature – temperature of thermal distribution

• zerototalmomentum – boolean

pylion.functions.minimise(etol, ftol, maxiter, maxeval, maxdist)

Perform an energy minimization of the system, by iteratively adjusting atom coordinates. The system is minimized by evolving the equations of motion with large damping, which saps energy from it. The maximum distance an atom can move in an iteration step is determined by maxdist. The minimisation is terminated when one of the following criteria is met:

1. energy difference between steps less than etol.

2. total force is less than ftol

3. the number of iterations exceeds maxiter

4. the number of force evaluations exceeds maxeval

See Also: http://lammps.sandia.gov/doc/minimize.html

Parameters:

• etol – energy difference tolerance

• ftol – force tolerance

• maxiter – maximum number of iterations

• maxeval – maximum number of force evaluations

• maxdist – maximum distance atoms can move

pylion.functions.ionneutralheating(uid, ions, rate)

Average heating effect due to collision of ions with background gas. Applies a small velocity kick to atoms each timestep using a normal veolcity distribution.

Parameters:

• ions – species to apply the kicks to

• rate – heating rate

pylion.functions.langevinbath(uid, temperature, dampingtime, seed=1337)

Creates a langevin bath of a given temperature. The langevin bath applies a damping force to each atom proportional to its velocity plus a stochastic, white noise force of a magnitude such that after a time significantly longer than the ‘dampingtime’ the system will thermalise to the specified temperature. The damping time is the time taken for velocity to relax to 1/e of its initial value in a zero temperature bath.

See Also: lasercool, http://lammps.sandia.gov/doc/fix_langevin.html

Parameters:

• temperature – temperature

• dampingtime – effectively defines coupling strength to the bath

pylion.functions.lasercool(uid, ions, k)

Simulates laser cooling of a particular ion species by damping the velocity of the ions. kx, ky, kz define the strength of the damping force, which is of the form \(f_i = - k_i * v_i\).

See Also: langevinbath

Parameters:

• ions – select species of ions

• k – (kx, ky, kz) laser wavevector

pylion.functions.linearpaultrap(uid, trap, ions=None, all=True)

Applies an oscillating electric field to atoms. The characterisation of the trap follows Berkeland et al. (1998). ‘trap’ shoud be a dictionary with the following items:

• ‘radius’, of the trap in meters

• ‘length’, of the trap in meters

• ‘kappa’, is a geometric factor defined in Berkeland et al.

• ‘frequency’, should be in Hz, not radians per second.

• ‘voltage’, is the voltage of the rf electrodes

• ‘endcapvoltage’, the voltage of the endcaps

The are also three optional parameters: - ‘anisotropy’, is used to imbalance fields in x and y directions, such that V_y = anisotropy * V_x. Defaults to 1. - ‘offset’, moves the center of the trap away from the rf-null axis. Defaults to (0, 0). - ‘pseudo’, boolean to choose between the full rf trap or the corresponding pseudopoential. Defaults to False.

‘frequency’ and ‘voltage’ can be specified as vectors, in which case a multi-frequency Paul trap is created.

As the pseudopotential is dependent on the charge:mass ratio of the ion, this fix requires that an ‘ions’ dict be supplied unless the ‘all’ parameter is True.

See Also: http://tf.nist.gov/general/pdf/1226.pdf

Parameters:

• trap – dictionary containing trap parameters

• ions – species to be used for pseudopotential

• all – boolean that chooses beteween the pseudopotential applied to all the ions in the simulation or just a single species

pylion.functions.endcappaultrap(uid, trap)

Endcap type ion trap with cylindrical symmetry. ‘trap’ shoud be a dictionary with the following items:

• ‘z0’, endcap distance is 2*z0, in meters

• ‘etaRF’, efficiency parameter for RF voltage

• ‘etaDC’, efficiency parameter for DC voltage

• ‘eps’, radial asymmetry parameter

• ‘frequency’, rf voltage frequency, in Hz

• ‘voltageRF’, is the RF voltage of the electrodes

• ‘voltageDC’, is the DC voltage of the electrodes

• ‘RFeps3’ third-order trap nonlinearity

• ‘RFeps4’ fourth-order trap nonlinearity

The trap potential in an endcap type trap with endcap distance \(2z_0\) driven by an rf voltage \(V_{RF}cos(\Omega t)\) and dc voltage \(V_{DC}\) is ‘[Lindvall2022] <https://doi.org/10.1063/5.0106633>’_

\[\phi(x, y, z)= {\eta_{DC}V_{DC} + \eta_{RF}V_{RF}cos(\Omega t) \over 4z_0^2 }((1-\epsilon)x^2+(1+\epsilon)y^2-2z^2),\]

where \(\epsilon \ll 1\) breaks the radial symmetry, and \(\eta_{RF}, \eta_{DC}\approx 1\) are efficiency parameters. The stability parameters are (\(Q\) and \(m\) are the charge and mass of the trapped ion)

\[ \begin{align}\begin{aligned}q_z = {2\eta_{RF} V_{RF} Q \over m \Omega^2 z_0^2 }, a_z = -{4\eta_{DC} V_{DC} Q \over m \Omega^2 z_0^2 }\\q_x = -(1 - \epsilon){q_z \over 2}, a_x = -(1 - \epsilon){a_z \over 2 }\\q_y = -(1 + \epsilon){q_z \over 2}, a_y = -(1 + \epsilon){a_z \over 2 }\end{aligned}\end{align} \]

The secular frequencies (for each axis \(i=x, y, z\)) are

\[\omega_i = \beta_i {\Omega \over 2}\]

With a low order approximation \(\beta_i \approx \sqrt{a_i+{q_i^2\over 2}}\), valid when \(a_i \ll q_i^2 \ll 1\). A higher order approximation is

\[\beta_i^2 = a_i + ( {1 \over 2}+ {1 \over 2}a_i)q_i^2 + ( {25 \over 128}+ {273 \over 512}a_i)q_i^4 + ( {317 \over 2304}+ {59525 \over 82944}a_i)q_i^6\]

Parameters:

trap – dictionary containing trap parameters

pylion.functions.endcap_aq(trap, ion)

Mathieu stability parameters \(a_i\) and \(q_i\) for endcap trap.

\(q_i\) is proportional to the applied RF-voltage, and \(a_i\) proportional to the applied DC-voltage.

Parameters:

• trap – dict defining endcap paul trap

• ion – dict defining trapped ion mass and´ charge

Returns:

tuple of (ax, ay, az), (qx, qy, qz)

sum(ai) = 0 required by Laplace equation

\[ \begin{align}\begin{aligned}q_z = {2\eta_{RF} V_{RF} Q \over m \Omega^2 z_0^2 }, a_z = -{4\eta_{DC} V_{DC} Q \over m \Omega^2 z_0^2 }\\q_x = -(1 - \epsilon){q_z \over 2}, a_x = -(1 - \epsilon){a_z \over 2 }\\q_y = -(1 + \epsilon){q_z \over 2}, a_y = -(1 + \epsilon){a_z \over 2 }\end{aligned}\end{align} \]

pylion.functions.endcap_beta(a, q, high_order=True)

Secular frequency parameter Beta.

Parameters

afloat

Mathieu equation stability parameter.

qfloat

Mathieu equation stability parameter.

high_orderbool, optional

Use high-order approximation. The default is True.

Returns

float

Beta corresponding to input a, q.

High order approximation:

\[\beta_{i,HO}^2 = a_i + ( {1 \over 2}+ {1 \over 2}a_i)q_i^2 + ( {25 \over 128}+ {273 \over 512}a_i)q_i^4 + ( {317 \over 2304}+ {59525 \over 82944}a_i)q_i^6\]

Low order approximation:

\[\beta_{i,LO}^2 = a_i + {q_i^2 \over 2}\]

pylion.functions.endcap_secular(trap, ion, high_order=True)

Compute secular frequencies for endcap-type paul trap.

Parameters

trapdict

endcap-type Paul trap definition.

iondict

trapped ion mass and charge.

high_orderbool, optional

Use high-order approximation. The default is True.

Returns

f_seculartuple(float)

secular frequencies (X, Y, Z)

\[\omega_i = \beta_i {\Omega \over 2}\]

pylion.functions.timeaverage(uid, steps, variables)

A variable in LAMMPS representing a time averaged quantity over a number of steps.

Parameters:

• steps – number of steps to average over

• variables – list of variables to be averaged

pylion.functions.squaresum(uid, variables)

Creates a lammps variable that calculates the square sum of the input variables.

Parameters:

variables – list of variables

pylion.functions.dump(uid, filename, variables, steps=10)

Dumps variables from lammps into files for analysis.

Parameters:

• filename – name of output file

• variables – list of variables to be written

• steps – variables are written every steps

Also two helper functions that are not meant to be appended to the simulation:

pylion.functions.trapaqtovoltage(ions, trap, a, q)

Calculates trap voltages for given a, q parameters.

Returns:

tuple of (voltage, endcapvoltage)

pylion.functions.readdump(filename)

Reads data from the given dump file. The dump should be a file with atom quantities in the order id vargout, e.g. id vx vy vz.

Parameters:

filename – name of input file

Returns:

a tuple of (steps, data). The shape of data is (steps, ions, (x, y, z)).