API

Note

This section is under construction! Check back soon.

Estimators

fibermc.estimators.sample(key: ~jax.Array, bounds: ~jax.Array, num_fibers: int, fiber_length: float, dtype: type = <class 'jax.numpy.float32'>) → Array

Samples fibers according to a jointly uniform distribution over the starts of the fibers and their angle; the endpoints are then determined by the fibers length.

Parameters:

• key (np.ndarray) – Psuedo-random number generation key/seed array (via jax.random.PRNGKey).

• bounds (np.ndarray [4,]) – Rectilinear sampling domain specified by a 4-array with elements corresponding to (min_x, min_y, max_y, max_y).

• num_fibers (int [>0]) – Strictly positive number of fibers to sample.

• length (float [>0]) – Strictly positive fiber length.

• dtype (type) – Numeric type to use for the fibers (default: FP64).

Returns:

fibers – An ndarray of shape (num_fibers, 2, 2) containing the fibers along axis 0. For each fiber, the start point is the first row of the (2, 2) array and the end point is the second row.

Return type:

np.ndarray

fibermc.estimators.estimate_field_area(field: callable, fibers: Array, params: dict, negative: bool = True) → Array

Estimates the total area for which a scalar field takes on positive/negative value (negative, by default).

Parameters:

• field (callable[[...], float]) – Scalar real-valued callable which takes auxiliary data params and fiber endpoints as input argument(s); if fibers are dimension 2 for example, field takes np.ndarrays of size 2 and params to produce a real-valued output.

• fibers (np.ndarray) – np.ndarray of shape (num_fibers, fiber_dim, fiber_dim) of fibers.

• params (tuple) – Auxiliary data provided to the field (e.g., parameters).

• negative (bool) – Estimate the total area for which field takes on negative values, if True; if instead False, estimate the area for which field takes on positive values.

Returns:

• total_area (np.ndarray) – Nonnegative Monte Carlo estimate of the total fiber area for which field takes on negative/positive values (negative by default).

• Note (this estimator assumes that field changes sign on a lengthscale larger than the length of each)

• fiber.

fibermc.estimators.estimate_hull_area(fibers: Array, hull: Array) → Array

Uses fiber Monte Carlo to estimate the area of a convex shape; assuming fibers are sampled from an extended domain. See estimators.estimate_hull_intersection_length.

fibermc.estimators.clip_to_field(field: callable, fibers: Array, params: dict, negative: bool = True) → Array

Geometry Utilities

fibermc.geometry_utils.clip_inside_convex_hull(fibers: Array, hull: Array) → Array

Wraps src.utils.geometry_utils._clip_inside_convex_hull and applies the clipping parameters to the fibers.

Graphics Utilities

fibermc.graphics_utils.create_pixel_hull(pixel_coordinate: ~jax.Array, ccw: bool = True, dtype=<class 'jax.numpy.float32'>) → Array

Create a pixel hull (i.e., a (4, 2) array with the vertices associated with a square convex hull) given a coordinate representing its location.

Parameters:

• pixel_coordinate (np.ndarray) – a length 2 array encoding the location (in terms of row/column) of the pixel for which to create a hull.

• ccw (bool) – whether to orient the hull counter-clockwise (default: True).

• dtype (type) – numeric type for the values comprising the resultant pixel hull (default: np.float32).

Returns:

pixel_hull – array containing 4 vertices of length 2 comprising the convex hull of the pixel.

Return type:

np.ndarray

Implicit Differentiation

fibermc.implicit_differentiation.bind_solver(f: callable) → callable

Jax Utilities

fibermc.geometry_utils.clip_inside_convex_hull(fibers: Array, hull: Array) → Array

Wraps src.utils.geometry_utils._clip_inside_convex_hull and applies the clipping parameters to the fibers.