pyfli.phasor.phasorS.phasor_locus_tools#

Acquisition configuration and lifetime helpers built on MonoLocus.

This module belongs to pyfli.phasor.phasorS. It complements MonoLocus with:

Units follow MonoLocus: frequencies in hertz, times in nanoseconds, window lengths as fractions of the laser period.

Functions

_omega_rad_per_ns(frequency_hz, harmonic)

discrete_locus_circle(n_bins[, harmonic])

Centre (gc, sc) and radius r of the circle the binned locus lies on.

lifetime_from_locus(g, s, locus_g, locus_s, ...)

Lifetime of the nearest point of a traced locus, for every phasor.

modulation_lifetime(g, s, frequency_hz[, ...])

Modulation lifetime tau = sqrt(1/m^2 - 1) / omega in nanoseconds, with m^2 = g^2 + s^2.

phase_lifetime(g, s, frequency_hz[, harmonic])

Phase lifetime tau = s / (g * omega) in nanoseconds, with omega the angular frequency of harmonic.

phase_lifetime_gated(g, s, frequency_hz, ...)

Lifetime whose single-gate locus point has the measured phase.

plot_discrete_n_sweep(frequency_hz[, ...])

Binned loci for several numbers of bins, converging to the universal semicircle as the number of bins grows.

Classes

AcquisitionConfig([mode, frequency_hz, ...])

Validated description of an acquisition geometry.

AcquisitionMode(*values)

Acquisition geometries with an analytical mono-exponential locus.
class AcquisitionMode(*values)[source]#

Bases: StrEnum

Acquisition geometries with an analytical mono-exponential locus.

CONTINUOUS = 'continuous'#
DISCRETE = 'discrete'#
GATED_SINGLE = 'gated_single'#
GATED_N = 'gated_n'#
TRUNCATED = 'truncated'#
OFFSET = 'offset'#
class AcquisitionConfig(mode=AcquisitionMode.CONTINUOUS, frequency_hz=80000000.0, harmonic=1, n_bins=256, gate_width_frac=0.5, n_gates=4, t_rec_frac=1.0, t0_frac=0.0)[source]#

Bases: object

Validated description of an acquisition geometry.

Parameters:

  • mode (AcquisitionMode | str) – Acquisition geometry ("continuous", "discrete", "gated_single", "gated_n", "truncated" or "offset").

  • frequency_hz (float) – Laser repetition frequency in hertz.

  • harmonic (int) – Phasor harmonic.

  • n_bins (int) – Number of bins over one period (discrete).

  • gate_width_frac (float) – Gate width as a fraction of the period (gated_single, gated_n).

  • n_gates (int) – Number of equidistant gates over one period (gated_n).

  • t_rec_frac (float) – Recorded window as a fraction of the period (truncated).

  • t0_frac (float) – Excitation offset as a fraction of the period (offset).

mode: AcquisitionMode | str = 'continuous'#
frequency_hz: float = 80000000.0#
harmonic: int = 1#
n_bins: int = 256#
gate_width_frac: float = 0.5#
n_gates: int = 4#
t_rec_frac: float = 1.0#
t0_frac: float = 0.0#
property period_ns: float#

Laser period in nanoseconds.

property omega_rad_per_ns: float#

Angular frequency of the harmonic, in rad/ns.

locus(tau_ns=None, *, tau_max_ns=10.0, n_points=500, draw=False, **kwargs)[source]#

Trace the locus of this geometry with MonoLocus.

Parameters:

  • tau_ns (array_like | None) – Lifetimes in nanoseconds; default n_points values up to tau_max_ns.

  • tau_max_ns (float, int) – Default lifetime grid.

  • n_points (float, int) – Default lifetime grid.

  • draw (bool) – Draw the locus (ax=, title=, color= … are passed on).

  • kwargs (Any)

Returns:

(g, s, tau_ns, ax) as returned by the MonoLocus locus methods.

Return type:

tuple[Any, ]

describe()[source]#

Readable summary of the geometry.

Return type:

str

phase_lifetime(g, s, frequency_hz, harmonic=1)[source]#

Phase lifetime tau = s / (g * omega) in nanoseconds, with omega the angular frequency of harmonic. Exact for mono-exponential decays on the universal semicircle.

Parameters:

  • g (ArrayLike)

  • s (ArrayLike)

  • frequency_hz (float)

  • harmonic (int)

Return type:

ndarray

modulation_lifetime(g, s, frequency_hz, harmonic=1)[source]#

Modulation lifetime tau = sqrt(1/m^2 - 1) / omega in nanoseconds, with m^2 = g^2 + s^2. Exact for mono-exponential decays on the universal semicircle.

Parameters:

  • g (ArrayLike)

  • s (ArrayLike)

  • frequency_hz (float)

  • harmonic (int)

Return type:

ndarray

lifetime_from_locus(g, s, locus_g, locus_s, locus_tau, mask=None)[source]#

Lifetime of the nearest point of a traced locus, for every phasor.

Parameters:

  • g (array_like) – Phasor coordinates (any shape).

  • s (array_like) – Phasor coordinates (any shape).

  • locus_g (array_like) – A locus from MonoLocus or AcquisitionConfig.locus().

  • locus_s (array_like) – A locus from MonoLocus or AcquisitionConfig.locus().

  • locus_tau (array_like) – A locus from MonoLocus or AcquisitionConfig.locus().

  • mask (array_like | None) – Phasors to evaluate; the others (and non-finite phasors) are NaN.

Returns:

Lifetimes in nanoseconds, same shape as g.

Return type:

np.ndarray

phase_lifetime_gated(g, s, frequency_hz, gate_width_frac, harmonic=1, tau_range_ns=(1e-3, 100.0))[source]#

Lifetime whose single-gate locus point has the measured phase.

The standard phase lifetime is biased for a single square gate of width gate_width_frac * T. This solves arg(z_gate(tau)) = arg(g + i s) for tau in tau_range_ns (Brent’s method), phasor by phasor. Phases outside the range of the locus give NaN.

Returns:

Lifetimes in nanoseconds, same shape as g.

Return type:

np.ndarray

Parameters:
discrete_locus_circle(n_bins, harmonic=1)[source]#

Centre (gc, sc) and radius r of the circle the binned locus lies on.

For n_bins equal bins over one period, the phasor of a mono-exponential decay is z = (1 - x) / (1 - x e^{i phi}) with x = exp(-T / (n_bins tau)) and phi = 2 pi harmonic / n_bins; as x goes from 0 to 1 it traces an arc of the circle through (1, 0) and (0, 0) with

gc = 1/2, sc = -tan(phi / 2) / 2, r = 1 / (2 cos(phi / 2)).

The circle tends to the universal semicircle as n_bins grows. When cos(phi / 2) = 0 (e.g. n_bins = 2, harmonic = 1) the locus is the segment [0, 1] and (0.5, 0.0, 0.5) is returned.

Parameters:
Return type:

tuple[float, float, float]

plot_discrete_n_sweep(frequency_hz, n_values=(4, 8, 16, 64, 256), harmonic=1, tau_ns=None, ax=None, cmap='viridis', title=None, figsize=(8, 5.5))[source]#

Binned loci for several numbers of bins, converging to the universal semicircle as the number of bins grows.

Returns:

The axes drawn into.

Return type:

Any

Parameters: