sawg: document

This commit is contained in:
Robert Jördens 2016-12-04 16:50:49 +01:00
parent d6f6ebf066
commit 39becd0b4e
1 changed files with 62 additions and 6 deletions

View File

@ -5,6 +5,18 @@ from artiq.language.types import TInt32, TInt64, TFloat
class Spline: class Spline:
"""Spline interpolating RTIO channel.
One knot of a polynomial basis spline (B-spline) :math:`u(t)`
is defined by the coefficients :math:`u_n` up to order :math:`n = k`.
If the knot is evaluated starting at time :math:`t_0`, the output
:math:`u(t)` for :math:`t > t_0, t_0` is:
.. math::
u(t) = \sum_{n=0}^k \frac{u_n}{n!} (t - t_0)^n
= u_0 + u_1 (t - t_0) + \frac{u_2}{2} (t - t_0)^2 + \dots
"""
kernel_invariants = {"channel", "core", "scale", "width", kernel_invariants = {"channel", "core", "scale", "width",
"time_width", "time_scale"} "time_width", "time_scale"}
@ -19,14 +31,20 @@ class Spline:
@portable(flags={"fast-math"}) @portable(flags={"fast-math"})
def to_mu(self, value: TFloat) -> TInt32: def to_mu(self, value: TFloat) -> TInt32:
"""Convert floating point `value` from physical units to 32 bit
integer machine units."""
return int32(round(value*self.scale)) return int32(round(value*self.scale))
@portable(flags={"fast-math"}) @portable(flags={"fast-math"})
def from_mu(self, value: TInt32) -> TFloat: def from_mu(self, value: TInt32) -> TFloat:
"""Convert 32 bit integer `value` from machine units to floating point
physical units."""
return value/self.scale return value/self.scale
@portable(flags={"fast-math"}) @portable(flags={"fast-math"})
def to_mu64(self, value: TFloat) -> TInt64: def to_mu64(self, value: TFloat) -> TInt64:
"""Convert floating point `value` from physical units to 64 bit
integer machine units."""
return int64(round(value*self.scale)) return int64(round(value*self.scale))
@kernel @kernel
@ -60,6 +78,15 @@ class Spline:
@portable(flags={"fast-math"}) @portable(flags={"fast-math"})
def pack_coeff_mu(self, coeff, packed): # TList(TInt64), TList(TInt32) def pack_coeff_mu(self, coeff, packed): # TList(TInt64), TList(TInt32)
"""Pack coefficients into RTIO data
:param coeff: TList(TInt64) list of machine units spline coefficients.
Lowest (zeroth) order first. The coefficient list is zero-extended
by the RTIO gateware.
:param packed: TList(TInt32) list for packed RTIO data. Must be
pre-allocated. Length in bits is
`n*width + (n - 1)*n//2*time_width`
"""
pos = 0 pos = 0
for i in range(len(coeff)): for i in range(len(coeff)):
wi = self.width + i*self.time_width wi = self.width + i*self.time_width
@ -80,6 +107,13 @@ class Spline:
@portable(flags={"fast-math"}) @portable(flags={"fast-math"})
def coeff_to_mu(self, coeff, coeff64): # TList(TFloat), TList(TInt64) def coeff_to_mu(self, coeff, coeff64): # TList(TFloat), TList(TInt64)
"""Convert a floating point list of coefficients into a 64 bit
integer (preallocated).
:param coeff: TList(TFloat) list of coefficients in physical units.
:param coeff64: TList(TInt64) preallocated list of coefficients in
machine units.
"""
for i in range(len(coeff)): for i in range(len(coeff)):
vi = coeff[i] * self.scale vi = coeff[i] * self.scale
for j in range(i): for j in range(i):
@ -94,6 +128,12 @@ class Spline:
coeff64[1] += ci // 6 >> 2*self.time_width coeff64[1] += ci // 6 >> 2*self.time_width
def coeff_as_packed_mu(self, coeff64): def coeff_as_packed_mu(self, coeff64):
"""Pack 64 bit integer machine units coefficients into 32 bit integer
RTIO data list.
This is a host-only method that can be used to generate packed
spline knot data to be frozen into kernels at compile time.
"""
n = len(coeff64) n = len(coeff64)
width = n*self.width + (n - 1)*n//2*self.time_width width = n*self.width + (n - 1)*n//2*self.time_width
packed = [int32(0)] * ((width + 31)//32) packed = [int32(0)] * ((width + 31)//32)
@ -101,6 +141,12 @@ class Spline:
return packed return packed
def coeff_as_packed(self, coeff): def coeff_as_packed(self, coeff):
"""Convert floating point spline coefficients into 32 bit integer
packed data.
This is a host-only method that can be used to generate packed
spline knot data to be frozen into kernels at compile time.
"""
coeff64 = [int64(0)] * len(coeff) coeff64 = [int64(0)] * len(coeff)
self.coeff_to_mu(coeff, coeff64) self.coeff_to_mu(coeff, coeff64)
return self.coeff_as_packed_mu(coeff64) return self.coeff_as_packed_mu(coeff64)
@ -109,6 +155,12 @@ class Spline:
def set_coeff(self, coeff): # TList(TFloat) def set_coeff(self, coeff): # TList(TFloat)
"""Set spline coefficients. """Set spline coefficients.
Missing coefficients (high order) are zero-extended byt the RTIO
gateware.
If more coefficients are supplied than the gateware supports the extra
coefficients are ignored.
:param value: List of floating point spline knot coefficients, :param value: List of floating point spline knot coefficients,
lowest order (constant) coefficient first. Units are the lowest order (constant) coefficient first. Units are the
unit of this spline's value times increasing powers of 1/s. unit of this spline's value times increasing powers of 1/s.
@ -126,10 +178,14 @@ class Spline:
order: TInt32): order: TInt32):
"""Initiate an interpolated value change. """Initiate an interpolated value change.
The third order interpolation is constrained to have zero first For zeroth order (step) interpolation, the step is at
order derivative at both start and stop. `start + duration/2`.
For zeroth order (step) interpolation, the step is at duration/2. First order interpolation corresponds to a linear value ramp from
`start` to `stop` over `duration`.
The third order interpolation is constrained to have zero first
order derivative at both `start` and `stop`.
For first order and third order interpolation (linear and cubic) For first order and third order interpolation (linear and cubic)
the interpolator needs to be stopped (or fed a new spline knot) the interpolator needs to be stopped (or fed a new spline knot)
@ -137,9 +193,9 @@ class Spline:
This method advances the timeline by `duration`. This method advances the timeline by `duration`.
:param start: Initial value of the change. :param start: Initial value of the change. In physical units.
:param stop: Final value of the change. :param stop: Final value of the change. In physical units.
:param duration: Duration of the interpolation. :param duration: Duration of the interpolation. In physical units.
:param order: Order of the interpolation. Only 0, 1, :param order: Order of the interpolation. Only 0, 1,
and 3 are valid: step, linear, cubic. and 3 are valid: step, linear, cubic.
""" """