sequince.transforms =================== .. py:module:: sequince.transforms .. autoapi-nested-parse:: Coordinate transforms used to manipulate particle states during mutation. Attributes ---------- .. autoapisummary:: sequince.transforms.logger sequince.transforms.Bounds Classes ------- .. autoapisummary:: sequince.transforms.UnitIntervalMapping sequince.transforms.LogitMapping sequince.transforms.CauchitMapping sequince.transforms.ProbitMapping sequince.transforms.ParticleTransform sequince.transforms.IdentityTransform sequince.transforms.FlowTransform sequince.transforms.AffineTransform sequince.transforms.WhiteningTransform sequince.transforms.BoundedToUnitHypercubeTransform sequince.transforms.BoundedToUnboundedTransform sequince.transforms.PeriodicBoundaryTransform sequince.transforms.CompositeTransform Functions --------- .. autoapisummary:: sequince.transforms.select_transform_auxiliary sequince.transforms.has_particle_aligned_auxiliary sequince.transforms.get_unit_interval_mapping sequince.transforms.get_prebuilt_transform Module Contents --------------- .. py:data:: logger .. py:data:: Bounds .. py:function:: select_transform_auxiliary(auxiliary, selection, *, n_particles) 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. .. py:function:: has_particle_aligned_auxiliary(auxiliary, *, n_particles) Return whether an auxiliary pytree contains particle-aligned arrays. .. py:class:: UnitIntervalMapping Bases: :py:obj:`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. .. py:method:: forward(values) Map values in ``(0, 1)`` to the real line. .. py:method:: inverse(values) Map values on the real line back to ``(0, 1)``. .. py:class:: LogitMapping Map the unit interval to the real line with a stabilized logit. :param eps: Clamp values to ``[eps, 1 - eps]`` before applying the logit. :type eps: float, default=1e-6 .. py:attribute:: eps :type: float :value: 1e-06 .. py:method:: forward(values) .. py:method:: inverse(values) .. py:class:: CauchitMapping Map the unit interval to the real line with a Cauchy quantile. :param eps: Clamp values to ``[eps, 1 - eps]`` before applying the quantile. :type eps: float, default=1e-6 .. py:attribute:: eps :type: float :value: 1e-06 .. py:method:: forward(values) .. py:method:: inverse(values) .. py:class:: ProbitMapping Map the unit interval to the real line with a normal quantile. :param eps: Clamp values to ``[eps, 1 - eps]`` before applying the quantile. :type eps: float, default=1e-6 .. py:attribute:: eps :type: float :value: 1e-06 .. py:method:: forward(values) .. py:method:: inverse(values) .. py:function:: get_unit_interval_mapping(mapping) Resolve a built-in mapping name or validate a mapping strategy object. .. py:class:: ParticleTransform Coordinate transform interface for particle mutation. Use :meth:`fit` to optionally adapt internal statistics using the particle cloud. :meth:`forward` returns transformed particles, log-Jacobian values, and auxiliary data. :meth:`inverse` undoes the forward transform. .. py:method:: clone() .. py:method:: fit(particles, context=None, *, rng = None) Return a transform fitted to the supplied ``particles``. .. py:method:: forward(particles, context=None, *, rng = None) Return the identity mapping, zero log-determinants, and no auxiliary. .. py:method:: inverse(values, context=None, *, auxiliary=None, rng = None) Return the identity mapping plus zero log-determinants. .. py:class:: IdentityTransform Bases: :py:obj:`ParticleTransform` No-op transform that simply returns the input particles. .. py:class:: FlowTransform Bases: :py:obj:`ParticleTransform` Adapt a normalizing flow to the ``ParticleTransform`` interface. .. py:attribute:: flow :type: sequince.flows.NormalizingFlow .. py:attribute:: fit_kwargs :type: Mapping[str, Any] | None :value: None .. py:method:: clone() .. py:method:: state_dict() .. py:method:: load_state_dict(state) .. py:method:: fit(particles, context=None, *, rng = None) Return a transform fitted to the supplied ``particles``. .. py:method:: forward(particles, context=None, *, rng = None) Return the identity mapping, zero log-determinants, and no auxiliary. .. py:method:: inverse(values, context=None, *, auxiliary=None, rng = None) Return the identity mapping plus zero log-determinants. .. py:class:: AffineTransform Bases: :py:obj:`ParticleTransform` Standardize coordinates using batch mean and variance statistics. :param eps: Small positive value added to the variance to avoid division by zero. :type eps: float, default=1e-6 :param columns: Indices that should be standardized. When ``None`` every column is transformed jointly. :type columns: Sequence[int] | None, optional .. py:attribute:: eps :type: float :value: 1e-06 .. py:attribute:: columns :type: Sequence[int] | None :value: None .. py:method:: fit(particles, context=None, *, rng = None) Return a transform fitted to the supplied ``particles``. .. py:method:: forward(particles, context=None, *, rng = None) Return the identity mapping, zero log-determinants, and no auxiliary. .. py:method:: inverse(values, context=None, *, auxiliary=None, rng = None) Return the identity mapping plus zero log-determinants. .. py:class:: WhiteningTransform Bases: :py:obj:`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. :param eps: 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. :type eps: float, default=1e-6 .. py:attribute:: eps :type: float :value: 1e-06 .. py:method:: fit(particles, context=None, *, rng = None) Return a transform fitted to the unweighted particle population. .. py:method:: forward(particles, context=None, *, rng = None) Return the identity mapping, zero log-determinants, and no auxiliary. .. py:method:: inverse(values, context=None, *, auxiliary=None, rng = None) Return the identity mapping plus zero log-determinants. .. py:class:: BoundedToUnitHypercubeTransform Bases: :py:obj:`ParticleTransform` Linearly rescale specified coordinates into the unit hypercube. :param bounds: Dictionary mapping column indices to ``(lower, upper)`` bounds. Each lower bound must be strictly smaller than the corresponding upper bound. :type bounds: Mapping[int, tuple[float, float]] .. py:attribute:: bounds :type: Bounds .. py:method:: forward(particles, context=None, *, rng = None) Return the identity mapping, zero log-determinants, and no auxiliary. .. py:method:: inverse(values, context=None, *, auxiliary=None, rng = None) Return the identity mapping plus zero log-determinants. .. py:class:: BoundedToUnboundedTransform Bases: :py:obj:`BoundedToUnitHypercubeTransform` Send bounded coordinates to the real line independently. :param bounds: Dictionary of coordinate bounds, as defined in :class:`BoundedToUnitHypercubeTransform`. :type bounds: Mapping[int, tuple[float, float]] :param mapping: Built-in mapping name or an object implementing ``forward`` and ``inverse``. Built-in options are ``"logit"``, ``"cauchit"``, and ``"probit"``. :type mapping: str | UnitIntervalMapping, default="logit" .. py:attribute:: mapping :type: str | UnitIntervalMapping :value: 'logit' .. py:method:: forward(particles, context=None, *, rng = None) Return the identity mapping, zero log-determinants, and no auxiliary. .. py:method:: inverse(values, context=None, *, auxiliary=None, rng = None) Return the identity mapping plus zero log-determinants. .. py:class:: PeriodicBoundaryTransform Bases: :py:obj:`ParticleTransform` Wrap selected periodic coordinates, optionally centering their mean. :param bounds: Map from index to ``(lower, upper)`` bounds defining the periodic interval for each coordinate. :type bounds: Mapping[int, tuple[float, float]] :param centering: With ``None`` (default), only wrap into the configured interval. With ``"circular-mean"``, first call :meth:`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 :func:`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. :type centering: {None, "circular-mean", "angular-mean"}, optional .. py:attribute:: bounds :type: Bounds .. py:attribute:: centering :type: Literal['circular-mean', 'angular-mean', 'circular_mean', 'angular_mean'] | None :value: None .. py:method:: fit(particles, context = None, *, rng = None) 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. .. py:method:: forward(particles, context=None, *, rng = None) Return the identity mapping, zero log-determinants, and no auxiliary. .. py:method:: inverse(values, context=None, *, auxiliary=None, rng = None) Return the identity mapping plus zero log-determinants. .. py:class:: CompositeTransform Bases: :py:obj:`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. :param transforms: Ordered sequence of transforms to apply. The forward pass executes transforms from first to last, while the inverse pass applies them in reverse. :type transforms: Sequence[ParticleTransform] .. py:attribute:: transforms :type: Sequence[ParticleTransform] .. py:method:: clone() .. py:method:: fit(particles, context=None, *, rng = None) Return a transform fitted to the supplied ``particles``. .. py:method:: forward(particles, context=None, *, rng = None) Return the identity mapping, zero log-determinants, and no auxiliary. .. py:method:: inverse(values, context=None, *, auxiliary=None, rng = None) Return the identity mapping plus zero log-determinants. .. py:function:: get_prebuilt_transform(name, **kwargs) Return a prebuilt particle transform by name. :param name: Name of the desired transform. Supported options are ``"identity"``, ``"affine"``, ``"whitening"``, ``"bounded_to_unit_hypercube"``, ``"bounded_to_unbounded"``, and ``"periodic_boundary"``. :type name: str :param \*\*kwargs: Additional keyword arguments passed to the transform constructor. :returns: The requested particle transform instance. :rtype: ParticleTransform