sequince.transforms

sequince.transforms#

Coordinate transforms used to manipulate particle states during mutation.

Attributes#

`logger`
`Bounds`

Classes#

`UnitIntervalMapping`	Mapping between the open unit interval and the real line.
`LogitMapping`	Map the unit interval to the real line with a stabilized logit.
`CauchitMapping`	Map the unit interval to the real line with a Cauchy quantile.
`ProbitMapping`	Map the unit interval to the real line with a normal quantile.
`ParticleTransform`	Coordinate transform interface for particle mutation.
`IdentityTransform`	No-op transform that simply returns the input particles.
`FlowTransform`	Adapt a normalizing flow to the `ParticleTransform` interface.
`AffineTransform`	Standardize coordinates using batch mean and variance statistics.
`WhiteningTransform`	Whiten a complete Euclidean particle vector with an affine transform.
`BoundedToUnitHypercubeTransform`	Linearly rescale specified coordinates into the unit hypercube.
`BoundedToUnboundedTransform`	Send bounded coordinates to the real line independently.
`PeriodicBoundaryTransform`	Wrap selected periodic coordinates, optionally centering their mean.
`CompositeTransform`	Compose multiple transforms while tracking cumulative log-Jacobians.

Functions#

`select_transform_auxiliary`(auxiliary, selection, *, ...)	Apply a particle selection to particle-aligned auxiliary array leaves.
`has_particle_aligned_auxiliary`(auxiliary, *, n_particles)	Return whether an auxiliary pytree contains particle-aligned arrays.
`get_unit_interval_mapping`(mapping)	Resolve a built-in mapping name or validate a mapping strategy object.
`get_prebuilt_transform`(name, **kwargs)	Return a prebuilt particle transform by name.

Module Contents#

sequince.transforms.logger#

sequince.transforms.Bounds#

sequince.transforms.select_transform_auxiliary(auxiliary, selection, *, n_particles)[source]#

Apply a particle selection to particle-aligned auxiliary array leaves.

Every array leaf satisfying leaf.ndim > 0 and leaf.shape[0] == n_particles is particle-aligned and receives selection. Other leaves are returned unchanged; this shape convention assigns no additional semantics to them.

Parameters:

auxiliary (Any)
selection (Any)
n_particles (int)

Return type:

Any

sequince.transforms.has_particle_aligned_auxiliary(auxiliary, *, n_particles)[source]#

Return whether an auxiliary pytree contains particle-aligned arrays.

Parameters:

auxiliary (Any)
n_particles (int)

Return type:

bool

class sequince.transforms.UnitIntervalMapping[source]#

Bases: Protocol

Mapping between the open unit interval and the real line.

Implementations return the elementwise log absolute determinant alongside transformed values. They must preserve the Array API namespace of their input.

forward(values)[source]#: Map values in (0, 1) to the real line.

inverse(values)[source]#: Map values on the real line back to (0, 1).

class sequince.transforms.LogitMapping[source]#

Map the unit interval to the real line with a stabilized logit.

Parameters:: eps (float, default=1e-6) – Clamp values to [eps, 1 - eps] before applying the logit.

eps: float = 1e-06#

forward(values)[source]#

inverse(values)[source]#

class sequince.transforms.CauchitMapping[source]#

Map the unit interval to the real line with a Cauchy quantile.

Parameters:: eps (float, default=1e-6) – Clamp values to [eps, 1 - eps] before applying the quantile.

eps: float = 1e-06#

forward(values)[source]#

inverse(values)[source]#

class sequince.transforms.ProbitMapping[source]#

Map the unit interval to the real line with a normal quantile.

Parameters:: eps (float, default=1e-6) – Clamp values to [eps, 1 - eps] before applying the quantile.

eps: float = 1e-06#

forward(values)[source]#

inverse(values)[source]#

sequince.transforms.get_unit_interval_mapping(mapping)[source]#

Resolve a built-in mapping name or validate a mapping strategy object.

Parameters:: mapping (str | UnitIntervalMapping)
Return type:: UnitIntervalMapping

class sequince.transforms.ParticleTransform[source]#

Coordinate transform interface for particle mutation.

Use fit() to optionally adapt internal statistics using the particle cloud. forward() returns transformed particles, log-Jacobian values, and auxiliary data. inverse() undoes the forward transform.

clone()[source]#

Return type:: ParticleTransform

fit(particles, context=None, *, rng=None)[source]#

Return a transform fitted to the supplied particles.

Parameters:: rng (sequince.utils.random.RNGLike)

forward(particles, context=None, *, rng=None)[source]#

Return the identity mapping, zero log-determinants, and no auxiliary.

Parameters:: rng (sequince.utils.random.RNGLike)

inverse(values, context=None, *, auxiliary=None, rng=None)[source]#

Return the identity mapping plus zero log-determinants.

Parameters:: rng (sequince.utils.random.RNGLike)

class sequince.transforms.IdentityTransform[source]#

Bases: ParticleTransform

No-op transform that simply returns the input particles.

class sequince.transforms.FlowTransform[source]#

Bases: ParticleTransform

Adapt a normalizing flow to the ParticleTransform interface.

flow: sequince.flows.NormalizingFlow#

fit_kwargs: Mapping[str, Any] | None = None#

clone()[source]#

Return type:: FlowTransform

state_dict()[source]#

load_state_dict(state)[source]#

fit(particles, context=None, *, rng=None)[source]#

Return a transform fitted to the supplied particles.

Parameters:: rng (sequince.utils.random.RNGLike)

forward(particles, context=None, *, rng=None)[source]#

Return the identity mapping, zero log-determinants, and no auxiliary.

Parameters:: rng (sequince.utils.random.RNGLike)

inverse(values, context=None, *, auxiliary=None, rng=None)[source]#

Return the identity mapping plus zero log-determinants.

Parameters:: rng (sequince.utils.random.RNGLike)

class sequince.transforms.AffineTransform[source]#

Bases: ParticleTransform

Standardize coordinates using batch mean and variance statistics.

Parameters:

eps (float, default=1e-6) – Small positive value added to the variance to avoid division by zero.
columns (Sequence[int] | None, optional) – Indices that should be standardized. When None every column is transformed jointly.

eps: float = 1e-06#

columns: Sequence[int] | None = None#

fit(particles, context=None, *, rng=None)[source]#

Return a transform fitted to the supplied particles.

Parameters:: rng (sequince.utils.random.RNGLike)

forward(particles, context=None, *, rng=None)[source]#

Return the identity mapping, zero log-determinants, and no auxiliary.

Parameters:: rng (sequince.utils.random.RNGLike)

inverse(values, context=None, *, auxiliary=None, rng=None)[source]#

Return the identity mapping plus zero log-determinants.

Parameters:: rng (sequince.utils.random.RNGLike)

class sequince.transforms.WhiteningTransform[source]#

Bases: ParticleTransform

Whiten a complete Euclidean particle vector with an affine transform.

The transform is fitted to a particle population and maps its coordinates according to z = L**-1 (x - mean), where L L.T is a regularized estimate of the population covariance. It is intended to be composed after any problem-specific transforms which unwrap periodic coordinates or otherwise make the representation suitable for Euclidean linear algebra.

Parameters:: eps (float, default=1e-6) – Relative diagonal regularization. Each variance receives eps times its own scale. Exactly constant directions receive a smaller floor tied to the largest variance and the precision of the array dtype. Values below machine precision are promoted to machine precision.

eps: float = 1e-06#

fit(particles, context=None, *, rng=None)[source]#

Return a transform fitted to the unweighted particle population.

Parameters:: rng (sequince.utils.random.RNGLike)

forward(particles, context=None, *, rng=None)[source]#

Return the identity mapping, zero log-determinants, and no auxiliary.

Parameters:: rng (sequince.utils.random.RNGLike)

inverse(values, context=None, *, auxiliary=None, rng=None)[source]#

Return the identity mapping plus zero log-determinants.

Parameters:: rng (sequince.utils.random.RNGLike)

class sequince.transforms.BoundedToUnitHypercubeTransform[source]#

Bases: ParticleTransform

Linearly rescale specified coordinates into the unit hypercube.

Parameters:: bounds (Mapping[int, tuple[float, float]]) – Dictionary mapping column indices to (lower, upper) bounds. Each lower bound must be strictly smaller than the corresponding upper bound.

bounds: Bounds#

forward(particles, context=None, *, rng=None)[source]#

Return the identity mapping, zero log-determinants, and no auxiliary.

Parameters:: rng (sequince.utils.random.RNGLike)

inverse(values, context=None, *, auxiliary=None, rng=None)[source]#

Return the identity mapping plus zero log-determinants.

Parameters:: rng (sequince.utils.random.RNGLike)

class sequince.transforms.BoundedToUnboundedTransform[source]#

Bases: BoundedToUnitHypercubeTransform

Send bounded coordinates to the real line independently.

Parameters:

bounds (Mapping[int, tuple[float, float]]) – Dictionary of coordinate bounds, as defined in BoundedToUnitHypercubeTransform.
mapping (str | UnitIntervalMapping, default="logit") – Built-in mapping name or an object implementing forward and inverse. Built-in options are "logit", "cauchit", and "probit".

mapping: str | UnitIntervalMapping = 'logit'#

forward(particles, context=None, *, rng=None)[source]#

Return the identity mapping, zero log-determinants, and no auxiliary.

Parameters:: rng (sequince.utils.random.RNGLike)

inverse(values, context=None, *, auxiliary=None, rng=None)[source]#

Return the identity mapping plus zero log-determinants.

Parameters:: rng (sequince.utils.random.RNGLike)

class sequince.transforms.PeriodicBoundaryTransform[source]#

Bases: ParticleTransform

Wrap selected periodic coordinates, optionally centering their mean.

Parameters:

bounds (Mapping[int, tuple[float, float]]) – Map from index to (lower, upper) bounds defining the periodic interval for each coordinate.
centering ({None, "circular-mean", "angular-mean"}, optional) – With None (default), only wrap into the configured interval. With "circular-mean", first call fit() to estimate the unweighted circular mean of each selected coordinate. Forward values are offsets from that mean in [-width / 2, width / 2); inverse values are restored to [lower, upper). Uses scipy.stats.circmean(); when the mean resultant vector is zero, the center is implementation-defined, as in SciPy. "angular-mean" is an alias for "circular-mean". Underscore spellings ("circular_mean" and "angular_mean") are also accepted.

bounds: Bounds#

centering: Literal['circular-mean', 'angular-mean', 'circular_mean', 'angular_mean'] | None = None#

fit(particles, context=None, *, rng=None)[source]#

Return a fitted copy using a cloud of shape (n_particles, n_dims).

Circular-mean fitting requires a nonempty floating-point cloud and uses the configured interval width as the period.

Parameters:

particles (sequince.typing.Array)
context (Any)
rng (sequince.utils.random.RNGLike)

Return type:

PeriodicBoundaryTransform

forward(particles, context=None, *, rng=None)[source]#

Return the identity mapping, zero log-determinants, and no auxiliary.

Parameters:: rng (sequince.utils.random.RNGLike)

inverse(values, context=None, *, auxiliary=None, rng=None)[source]#

Return the identity mapping plus zero log-determinants.

Parameters:: rng (sequince.utils.random.RNGLike)

class sequince.transforms.CompositeTransform[source]#

Bases: ParticleTransform

Compose multiple transforms while tracking cumulative log-Jacobians.

Forward auxiliary data is a tuple with exactly one entry per component, including None entries. Inversion validates this shape and supplies entries to their components in reverse transform order. A supplied RNG is resolved once and advanced sequentially across components, which avoids reusing functional random keys.

Parameters:: transforms (Sequence[ParticleTransform]) – Ordered sequence of transforms to apply. The forward pass executes transforms from first to last, while the inverse pass applies them in reverse.

transforms: Sequence[ParticleTransform]#

clone()[source]#

fit(particles, context=None, *, rng=None)[source]#

Return a transform fitted to the supplied particles.

Parameters:: rng (sequince.utils.random.RNGLike)

forward(particles, context=None, *, rng=None)[source]#

Return the identity mapping, zero log-determinants, and no auxiliary.

Parameters:: rng (sequince.utils.random.RNGLike)

inverse(values, context=None, *, auxiliary=None, rng=None)[source]#

Return the identity mapping plus zero log-determinants.

Parameters:: rng (sequince.utils.random.RNGLike)

sequince.transforms.get_prebuilt_transform(name, **kwargs)[source]#

Return a prebuilt particle transform by name.

Parameters:

name (str) – Name of the desired transform. Supported options are "identity", "affine", "whitening", "bounded_to_unit_hypercube", "bounded_to_unbounded", and "periodic_boundary".
**kwargs – Additional keyword arguments passed to the transform constructor.

Returns:

The requested particle transform instance.

Return type:

ParticleTransform