NaNIsaac docs

Appearance

Python API ​

Signatures and docstrings of the public functions and classes in qoraphasecu at main (47735ce), read from the source without importing it. The guides on this site say how the pieces fit together; this page is for looking up an argument.

qoraphasecu.api ​

``reconstruct``: array in, reconstruction out, shaped like ``qoraphase.reconstruct``.

Reconstruction ​

python
@dataclass(frozen=True)
class Reconstruction:
    object: np.ndarray
    support: np.ndarray
    errors: np.ndarray
One reconstructed object, defined up to a global phase, a translation and a twin.

Reconstruction.amplitude ​

python
@property
def amplitude(self) -> np.ndarray

Reconstruction.phase ​

python
@property
def phase(self) -> np.ndarray

Reconstruction.error ​

python
@property
def error(self) -> float
Final Fourier error; the ranking key.

Reconstruction.to_qoraphase ​

python
def to_qoraphase(self)
The same run as a ``qoraphase.Reconstruction``; ``errors`` becomes ``metrics``.

Ensemble ​

python
@dataclass(frozen=True)
class Ensemble:
    runs: tuple
The runs of a multi-start reconstruction, not mutually aligned.

Ensemble.ranking ​

python
@property
def ranking(self) -> tuple
Run indices ordered best (lowest error) first.

Ensemble.best ​

python
@property
def best(self) -> Reconstruction

Ensemble.to_qoraphase ​

python
def to_qoraphase(self, problem=None)
A ``qoraphase.Ensemble`` of the runs, for its ``align`` and ``average``.

Pass the ``qoraphase.CDI`` of the measurement as *problem* to have
``average`` score the mean against it, as QoraPhase's own ensembles do.

cuda_available ​

python
def cuda_available() -> bool

autocorrelation_support ​

python
def autocorrelation_support(intensity, threshold: float=0.1) -> np.ndarray
Loose support from the thresholded autocorrelation; shrinkwrap tightens it.

aligned_error ​

python
def aligned_error(a, reference) -> float
``||a - reference|| / ||reference||`` after removing shift, global phase and twin.

reconstruct ​

python
def reconstruct(
    intensity,
    *,
    support=None,
    mask=None,
    recipe=None,
    starts: int = 1,
    batch: int | None = None,
    seed: int | None = None,
    init=None,
    support_threshold: float = 0.1,
    backend: Literal['auto', 'cpu', 'cuda'] = 'auto',
    variant: Literal['naive', 'fused', 'graph', 'batched', 'half', 'callback', 'mixed'] = 'batched',
    sync_every: int = 10,
) -> Reconstruction | Ensemble
Array in, reconstruction out.

Args:
    intensity: measured intensity, center-origin, 2D or 3D.
    support: boolean, ``True`` inside the object. ``None`` derives an
        autocorrelation support.
    mask: boolean, ``True`` marks *unusable* pixels.
    recipe: a :class:`Recipe`, or a QoraPhase recipe or stage (converted by
        :func:`from_qoraphase`). ``None`` uses :func:`default_recipe`.
    starts: number of random starts; >1 returns an :class:`Ensemble`.
    batch: starts per batched cuFFT plan (``variant="batched"``); ``None``
        puts all of them in one.
    seed: seed of the random starting phases; ``None`` means 0.
    init: starting object, center-origin, instead of random phases: one array
        of the intensity's shape for every start, or one per start stacked as
        ``(starts, *shape)``. It is cut to the support first, as in QoraPhase.
    backend: ``"auto"`` picks CUDA when a device is present.
    variant: CUDA optimisation step, see docs/OPTIMIZATION.md.

qoraphasecu.interop ​

Conversion to and from QoraPhase objects (tested against ``qoraphase==0.1.0``).

``qoraphase`` is imported only inside these functions: it pulls in JAX, which
QoraPhaseCU does not otherwise need.

is_qoraphase ​

python
def is_qoraphase(obj) -> bool
True for QoraPhase stages, user subclasses included.

from_qoraphase ​

python
def from_qoraphase(recipe) -> Recipe
Convert a QoraPhase recipe, or a single QoraPhase stage, into a :class:`Recipe`.

Raises ``TypeError`` for a stage without a QoraPhaseCU counterpart, which
includes subclasses of the built-in stages: their ``step`` may differ.

qoraphasecu.recipe ​

Recipe stages with the names and defaults of QoraPhase.

A recipe flattens to a list of operation tuples for the C++ engine; ``repeat``
and ``detwin`` expand in place there, as in the C++ API.

ER ​

python
@dataclass(frozen=True)
class ER:
    n: int
``x <- P_S P_M x``.

ER.ops ​

python
def ops(self)

HIO ​

python
@dataclass(frozen=True)
class HIO:
    n: int
    beta: float = 0.9
``x <- P_M x`` inside the support, ``x - beta P_M x`` outside.

HIO.ops ​

python
def ops(self)

RAAR ​

python
@dataclass(frozen=True)
class RAAR:
    n: int
    beta: float = 0.9
``x <- (beta/2)(R_S R_M x + x) + (1 - beta) P_M x``.

RAAR.ops ​

python
def ops(self)

Shrinkwrap ​

python
@dataclass(frozen=True)
class Shrinkwrap:
    threshold: float = 0.3
    sigma: float = 1.0
    method: Literal['max', 'rms'] = 'max'
Threshold the Gaussian-blurred magnitude; ``method`` is ``"max"`` or ``"rms"``.

Shrinkwrap.ops ​

python
def ops(self)

Recipe ​

python
class Recipe:
    def __init__(self, *stages)
Ordered sequence of stages. Code order is execution order.

Recipe.ops ​

python
def ops(self)

repeat ​

python
def repeat(n: int, *stages) -> _Repeat
``repeat(10, RAAR(50), Shrinkwrap())``

detwin ​

python
def detwin(*stages, axis: int=0) -> _Detwin
Run *stages* against the support cut at its centre of mass, then restore it.

default_recipe ​

python
def default_recipe() -> Recipe
RAAR, a detwin pass, then shrinkwrapped RAAR and ER: QoraPhase's default.

Each project section is built from that project’s docs/ directory.

Isaac Yong