quadrants.lang.field

Classes

Field	Quadrants field class.
ScalarField	Quadrants scalar field with SNode implementation.
BitpackedFields	Quadrants bitpacked fields, where fields with quantized types are packed together.

Module Contents

class quadrants.lang.field.Field(_vars)

Quadrants field class.

A field is constructed by a list of field members. For example, a scalar field has 1 field member, while a 3x3 matrix field has 9 field members. A field member is a Python Expr wrapping a C++ FieldExpression.

Parameters:

vars (List[Expr]) – Field members.

vars

host_accessors = None

grad = None

dual = None

property snode

Gets representative SNode for info purposes.

Returns:

Representative SNode (SNode of first field member).

Return type:

SNode

property shape: tuple[int, Ellipsis]

property layout

Canonical-axis-permutation tuple, or None for identity.

Mirrors Ndarray.layout: returns the same value the caller passed to qd.tensor(..., layout=...) (or None if that kwarg was omitted / was the identity permutation). Lets downstream code introspect the physical layout without having to know which backend produced the tensor.

Fields constructed directly via qd.field(..., order=...) also report their layout here — the order= axis-string is translated into an integer permutation and stashed on the same _qd_layout attribute that layout-tagged ndarrays use.

property dtype: quadrants._lib.core.quadrants_python.DataTypeCxx

parent(n=1)

n (int): the number of levels going up from the representative SNode.

has_grad() → bool

Whether this field’s adjoint (reverse-mode gradient) SNode is allocated.

self.grad is non-None for every real-dtype field (the wrapper is allocated up-front so qd.root.lazy_grad() can populate it later); the actual placed-or-not signal is whether the underlying SNode has been placed via needs_grad=True, qd.root.lazy_grad(), or an explicit qd.root.dense(...).place(field.grad). Mirrors self.snode.ptr.has_adjoint().

has_dual() → bool

Whether this field’s dual (forward-mode gradient) SNode is allocated.

Same semantics as has_grad() for the dual companion. Mirrors self.snode.ptr.has_dual().

abstract fill(val: int | float) → None

abstract to_numpy(dtype: quadrants._lib.core.quadrants_python.DataTypeCxx | None = None, *, copy=True)

Converts self to a numpy array.

Parameters:

copy – True (default) returns an independent copy, False requires zero-copy or raises, None uses zero-copy when available and falls back to a copy otherwise.

Returns:

The result numpy array.

Return type:

numpy.ndarray

abstract to_torch(device=None, *, copy=True)

Converts self to a torch tensor.

Parameters:

• device (torch.device, optional) – The desired device of returned tensor.

• copy – True (default) returns an independent copy, False requires zero-copy or raises, None uses zero-copy when available and falls back to a copy otherwise.

Returns:

The result torch tensor.

Return type:

torch.tensor

abstract from_numpy(arr)

Loads all elements from a numpy array.

The shape of the numpy array needs to be the same as self.

Parameters:

arr (numpy.ndarray) – The source numpy array.

from_torch(arr)

Loads all elements from a torch tensor.

The shape of the torch tensor needs to be the same as self.

Parameters:

arr (torch.tensor) – The source torch tensor.

copy_from(other: Field) → None

Copies all elements from another field.

The shape of the other field needs to be the same as self.

abstract to_dlpack(versioned=False)

class quadrants.lang.field.ScalarField(var)

Bases: Field

Quadrants scalar field with SNode implementation.

Parameters:

var (Expr) – Field member.

to_dlpack(versioned=False)

Export this field as a DLPack capsule.

Parameters:

versioned – If True, emit a DLPack v1 DLManagedTensorVersioned capsule ("dltensor_versioned", flags=0). NumPy >= 2.1 can consume v1 capsules and returns writable arrays; NumPy 2.0 marks v0 capsules read-only; NumPy < 2.1 cannot consume v1 capsules at all. If False (default), emit a v0 DLManagedTensor ("dltensor"), required by torch.utils.dlpack.from_dlpack.

Note: caller is responsible for calling qd.sync() between modifying the field and reading it.

fill(val)

Fills this scalar field with a specified value.

to_numpy(dtype=None, *, copy=True)

Converts this field to a numpy.ndarray.

Parameters:

• dtype – Optional target numpy dtype.

• copy – True (default) returns an independent copy, False requires zero-copy or raises, None uses zero-copy when available and falls back to a copy otherwise.

to_torch(device=None, *, copy=True)

Converts this field to a torch.Tensor.

Parameters:

• device – Optional torch device for the returned tensor.

• copy – True (default) returns an independent copy, False requires zero-copy or raises, None uses zero-copy when available and falls back to a copy otherwise.

from_numpy(arr)

Copies the data from a numpy.ndarray into this field.

class quadrants.lang.field.BitpackedFields(max_num_bits)

Quadrants bitpacked fields, where fields with quantized types are packed together.

Parameters:

max_num_bits (int) – Maximum number of bits all fields inside can occupy in total. Only 32 or 64 is allowed.

fields = []

bit_struct_type_builder

place(*args, shared_exponent=False)

Places a list of fields with quantized types inside.

Parameters:

• *args (List[Field]) – A list of fields with quantized types to place.

• shared_exponent (bool) – Whether the fields have a shared exponent.