microquantum.stdlib.numbers

Standard library: numeric and angle utilities (Phase 117).

Small, dependency-light helpers for the angle arithmetic that shows up everywhere in quantum programming (rotation gates, phase accumulation, gradient shifts):

  • mod_2pi() — reduce an angle to its canonical representative in [0, 2*pi).

  • wrap_angle() — symmetric principal value in [-pi, pi].

  • is_angle_close() — equality modulo 2*pi within a tolerance (two rotations are equivalent when their angles differ by a full turn).

  • is_identity_angle() — whether a rotation by the angle is the identity (its reduced angle is 0 modulo 2*pi).

Numpy scalar types are accepted and coerced to float; NaN and infinities are rejected. Complex numbers and strings are rejected.

Module Contents

microquantum.stdlib.numbers.mod_2pi(angle)[source]

Reduce an angle to its canonical representative in [0, 2*pi).

Parameters:

angle (Any) – Any real-valued angle (int, float or numpy scalar).

Returns:

angle modulo 2*pi in [0, 2*pi). 0.0 stays 0.0.

Raises:

  • TypeError – If angle is complex or not a real number.

  • ValueError – If angle is NaN or infinite.

Return type:

float

microquantum.stdlib.numbers.wrap_angle(angle)[source]

Reduce an angle to its symmetric principal value in [-pi, pi].

Uses math.remainder(), so the result is the numerically closest representative modulo 2*pi: 0.0 maps to 0.0, angles just below pi stay positive and angles just above pi become slightly negative.

Parameters:

angle (Any) – Any real-valued angle (int, float or numpy scalar).

Returns:

The principal value in [-pi, pi].

Raises:

  • TypeError – If angle is complex or not a real number.

  • ValueError – If angle is NaN or infinite.

Return type:

float

microquantum.stdlib.numbers.is_angle_close(left, right, *, tol=1e-10)[source]

Check whether two angles are equal modulo 2*pi within tol.

Two angles are close when rotating either by any whole number of full turns brings them within tol of each other — i.e. the rotations they describe are the same.

Parameters:

  • left (Any) – First real-valued angle.

  • right (Any) – Second real-valued angle.

  • tol (float) – Absolute tolerance on the modulo-2*pi difference.

Returns:

True when the angles describe equivalent rotations.

Raises:

  • TypeError – If an angle is complex or not a real number.

  • ValueError – If an angle is NaN/infinite, or tol is not a real non-negative number.

Return type:

bool

microquantum.stdlib.numbers.is_identity_angle(angle, *, tol=1e-09)[source]

Check whether a rotation by angle equals the identity.

A rotation is the identity when its reduced angle is 0 modulo 2*pi (including a full turn), up to tolerance tol.

Parameters:

  • angle (Any) – Any real-valued angle.

  • tol (float) – Absolute tolerance applied against the reduced angle.

Returns:

True when rotating by angle is (approximately) the identity.

Raises:

  • TypeError – If angle is complex or not a real number.

  • ValueError – If angle is NaN/infinite, or tol is not a real non-negative number.

Return type:

bool