stochkin.boundaries

Mirror-reflection and clipping boundary helpers.

Stochastic_Estimation.boundaries

Small, picklable boundary-condition helpers.

Why this module exists

Several workflows in this project (cropped FES domains, ROI sampling, MFPT estimation) need a consistent way to keep trajectories inside a rectangular box.

The mirror-reflection rule is: if a coordinate exits [lo, hi] it is reflected back in (possibly multiple times if the step overshoots by more than the box size).

Notes

  • For overdamped dynamics, reflection acts only on positions.

  • For underdamped dynamics, if you reflect a coordinate you should also flip the corresponding velocity component (elastic reflection). This is provided by reflect_position_velocity().

stochkin.boundaries.reflect_scalar(x, lo, hi)[source]

Mirror-reflect a scalar into [lo, hi].

Returns:

  • x_reflected (float)

  • n_flips (int) – Number of reflections performed (parity matters for velocity flips).

Parameters:
Return type:

Tuple[float, int]

stochkin.boundaries.apply_bounds(x, bounds, mode='reflect')[source]

Enforce rectangular bounds on a position vector.

Parameters:

  • x (array_like, shape (d,))

  • bounds (sequence of (lo, hi), length d) – Example for 2D: ((xlo, xhi), (ylo, yhi)). If None, returns x unchanged.

  • mode ({'reflect', 'clip'})

Returns:

x_new

Return type:

ndarray, shape (d,)

stochkin.boundaries.reflect_position_velocity(x, v, bounds)[source]

Reflect position into bounds and flip velocity components accordingly.

This is a simple elastic wall model compatible with mirror reflection. It is useful for keeping underdamped trajectories inside a cropped box.

Parameters:

  • x (array_like, shape (d,))

  • v (array_like, shape (d,))

  • bounds (sequence of (lo, hi), length d)

Returns:

x_new, v_new

Return type:

ndarrays