Skip to content

angle Module

Protocol for an angular distribution. The only predefined distribution available is uniform.

PolarArbitrary

An arbitrary, finite-precision polar angular distribution in the CM frame

Define an arbitrary probability distribution for the polar angle using an array of uniformly-spaced angles and their probabilities, as well as the spacing of the angle values. We then sample from the distribution and smear the output angle within the spacing.

Note: If your distribution is defined using any of the pre-defined distributions, you should favor using those over PolarArbitrary. Sampling of arbitrary functions comes with a runtime performance penalty. That is: do not use this to sample from a uniform distribution.

Parameters:

Name Type Description Default
angles ndarray

The array of lower angle values. Each angle corresponds to a bin covering angle + bin_width. Angles should be in units of radians.

 required
probabilities ndarray

The probability of a given angle bin. Should sum to 1.0

 required
angle_bin_width float

The width of the angle bins in radians

 required

Attributes:

Name Type Description
angle_width float

The angle bin width in radians
probs ndarray

The probability of a given angle bin
angles ndarray

The array of lower angle values. Each angle corresponds to a bin covering angle + bin_width. Angles should be in units of radians.

Methods:

Name Description
sample

Sample the distribution, returning a polar angle in radians
Source code in src/attpc_engine/kinematics/angle.py 
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
class PolarArbitrary:
    """An arbitrary, finite-precision polar angular distribution in the CM frame

    Define an arbitrary probability distribution for the polar angle using an
    array of uniformly-spaced angles and their probabilities, as well as the spacing
    of the angle values. We then sample from the distribution and smear the output angle
    within the spacing.

    Note: If your distribution is defined using *any* of the pre-defined distributions,
    you should favor using those over PolarArbitrary. Sampling of arbitrary functions
    comes with a runtime performance penalty. That is: do not use this to sample from a
    uniform distribution.

    Parameters
    ----------
    angles: numpy.ndarray
        The array of *lower* angle values. Each angle corresponds to a bin covering
        angle + bin_width. Angles should be in units of radians.
    probabilities: numpy.ndarray
        The probability of a given angle bin. Should sum to 1.0
    angle_bin_width: float
        The width of the angle bins in radians

    Attributes
    ----------
    angle_width: float
        The angle bin width in radians
    probs: numpy.ndarray
        The probability of a given angle bin
    angles: numpy.ndarray
        The array of *lower* angle values. Each angle corresponds to a bin covering
        angle + bin_width. Angles should be in units of radians.

    Methods
    -------
    sample(rng)
        Sample the distribution, returning a polar angle in radians
    """

    def __init__(
        self,
        angles: np.ndarray,
        probabilities: np.ndarray,
        angle_bin_width: float,
    ):
        if np.sum(probabilities) > 1.0:
            raise ValueError(
                f"The sum of the probabilities passed to PolarArbitrary should be 1.0. Yours sum to {np.sum(probabilities)}"
            )
        self.angle_width = angle_bin_width
        self.probs = probabilities
        self.angles = angles

    def sample(self, rng: Generator) -> float:
        """Sample the distribution, returning a polar angle in radians

        Parameters
        ----------
        rng: numpy.random.Generator
            The random number generator

        Returns
        -------
        float
            The sampled angle in radians
        """
        return (
            rng.choice(self.angles, p=self.probs)
            + rng.uniform(0.0, 1.0) * self.angle_width
        )

sample(rng)

Sample the distribution, returning a polar angle in radians

Parameters:

Name Type Description Default
rng Generator

The random number generator

 required

Returns:

Type Description
float

The sampled angle in radians
Source code in src/attpc_engine/kinematics/angle.py 
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
def sample(self, rng: Generator) -> float:
    """Sample the distribution, returning a polar angle in radians

    Parameters
    ----------
    rng: numpy.random.Generator
        The random number generator

    Returns
    -------
    float
        The sampled angle in radians
    """
    return (
        rng.choice(self.angles, p=self.probs)
        + rng.uniform(0.0, 1.0) * self.angle_width
    )

PolarDistribution

Bases: Protocol

Protocol for defining a reaction polar angle distribution in the CM frame

Note that for polar angle distributions, the coordinate to sample is cos(polar) not polar (to cover solid angle uniformly). This means that the valid domain of these distributions is [0.0, pi]

Methods:

Name Description
sample

Sample the distribution. Returns angle in radians
Source code in src/attpc_engine/kinematics/angle.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
class PolarDistribution(Protocol):
    """Protocol for defining a reaction polar angle distribution in the CM frame

    Note that for polar angle distributions, the coordinate to sample
    is cos(polar) not polar (to cover solid angle uniformly). This means
    that the valid domain of these distributions is [0.0, pi]

    Methods
    -------
    sample(rng)
        Sample the distribution. Returns angle in radians
    """

    def sample(self, rng: Generator) -> float:  # type: ignore
        """Sample the distribution, returning a polar angle in radians

        Parameters
        ----------
        rng: numpy.random.Generator
            The random number generator

        Returns
        -------
        float
            The sampled angle in radians
        """
        pass

sample(rng)

Sample the distribution, returning a polar angle in radians

Parameters:

Name Type Description Default
rng Generator

The random number generator

 required

Returns:

Type Description
float

The sampled angle in radians
Source code in src/attpc_engine/kinematics/angle.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
def sample(self, rng: Generator) -> float:  # type: ignore
    """Sample the distribution, returning a polar angle in radians

    Parameters
    ----------
    rng: numpy.random.Generator
        The random number generator

    Returns
    -------
    float
        The sampled angle in radians
    """
    pass

PolarUniform

A uniform polar angle distribution in the CM frame

Note that for polar angle distributions, the coordinate to sample is cos(polar) not polar. This means that the valid domain of these distributions is [0.0, pi]

Parameters:

Name Type Description Default
angle_min float

The minimum polar angle in radians

 required
angle_max float

The maximum polar angle in radians

 required

Attributes:

Name Type Description
cos_angle_min float

The minimum cos(polar)
cos_angle_max float

The maximum cos(polar)

Methods:

Name Description
sample

Sample the distribution, returning a polar angle in radians
Source code in src/attpc_engine/kinematics/angle.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
class PolarUniform:
    """A uniform polar angle distribution in the CM frame

    Note that for polar angle distributions, the coordinate to sample
    is cos(polar) not polar. This means that the valid domain of these
    distributions is [0.0, pi]

    Parameters
    ----------
    angle_min: float
        The minimum polar angle in radians
    angle_max: float
        The maximum polar angle in radians

    Attributes
    ----------
    cos_angle_min: float
        The minimum cos(polar)
    cos_angle_max: float
        The maximum cos(polar)

    Methods
    -------
    sample(rng)
        Sample the distribution, returning a polar angle in radians
    """

    def __init__(self, angle_min: float, angle_max: float):
        # cos(polar) flips the min/max order
        self.cos_angle_min = np.cos(angle_max)
        self.cos_angle_max = np.cos(angle_min)

    def sample(self, rng: Generator) -> float:
        """Sample the distribution, returning a polar angle in radians

        Parameters
        ----------
        rng: numpy.random.Generator
            The random number generator

        Returns
        -------
        float
            The sampled angle in radians
        """
        return np.arccos(rng.uniform(self.cos_angle_min, self.cos_angle_max))

sample(rng)

Sample the distribution, returning a polar angle in radians

Parameters:

Name Type Description Default
rng Generator

The random number generator

 required

Returns:

Type Description
float

The sampled angle in radians
Source code in src/attpc_engine/kinematics/angle.py 
67
68
69
70
71
72
73
74
75
76
77
78
79
80
def sample(self, rng: Generator) -> float:
    """Sample the distribution, returning a polar angle in radians

    Parameters
    ----------
    rng: numpy.random.Generator
        The random number generator

    Returns
    -------
    float
        The sampled angle in radians
    """
    return np.arccos(rng.uniform(self.cos_angle_min, self.cos_angle_max))