Skip to content

excitation Module

Protocol for an excitation (i.e. state or level) distribution in energy. Predefined distributions available are normal or uniform.

ExcitationBreitWigner

Represents the sampling parameters for a nuclear excitation with the energy sampled from the relativistic Breit-Wigner distribution.

Beware that this excitation class is slower than the others because it uses scipy for its relativistic Breit Wigner distribution.

Parameters:

Name Type Description Default
rest_mass float

The rest mass of the nucleus that is excited in MeV.

 required
centroid float

The state mean/centroid value in MeV.

 required
width float

Width of the state in MeV.

 required

Attributes:

Name Type Description
rest_mass float

The rest mass of the nucleus that is excited in MeV.
centroid float

The state mean/centroid value in MeV.
width float

Width of the state in MeV.

Methods:

Name Description
sample

Sample the energy distribution of the excitation.
Source code in src/attpc_engine/kinematics/excitation.py 
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
class ExcitationBreitWigner:
    """Represents the sampling parameters for a nuclear excitation with the energy
    sampled from the relativistic Breit-Wigner distribution.

    Beware that this excitation class is slower than the others because it uses
    scipy for its relativistic Breit Wigner distribution.

    Parameters
    ----------
    rest_mass: float
        The rest mass of the nucleus that is excited in MeV.
    centroid: float
        The state mean/centroid value in MeV.
    width: float
        Width of the state in MeV.

    Attributes
    ----------
    rest_mass: float
        The rest mass of the nucleus that is excited in MeV.
    centroid: float
        The state mean/centroid value in MeV.
    width: float
        Width of the state in MeV.

    Methods
    -------
    sample(rng)
        Sample the energy distribution of the excitation.
    """

    def __init__(
        self,
        rest_mass: float,
        centroid: float,
        width: float,
    ):
        self.rest_mass = rest_mass
        self.centroid = centroid
        self.width = width

    def sample(self, rng: Generator) -> float:
        """Sample the energy distribution of the excitation.

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

        Returns
        -------
        float
            The sampled value
        """
        rho = (self.rest_mass + self.centroid) / self.width
        total_energy = rel_breitwigner.rvs(rho, scale=self.width, random_state=rng)
        excitation_energy = total_energy - self.rest_mass
        return excitation_energy

sample(rng)

Sample the energy distribution of the excitation.

Parameters:

Name Type Description Default
rng Generator

The random number generator

 required

Returns:

Type Description
float

The sampled value
Source code in src/attpc_engine/kinematics/excitation.py 
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
def sample(self, rng: Generator) -> float:
    """Sample the energy distribution of the excitation.

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

    Returns
    -------
    float
        The sampled value
    """
    rho = (self.rest_mass + self.centroid) / self.width
    total_energy = rel_breitwigner.rvs(rho, scale=self.width, random_state=rng)
    excitation_energy = total_energy - self.rest_mass
    return excitation_energy

ExcitationDistribution

Bases: Protocol

Definition of a nuclear excitation with a specified energy distribution

Methods:

Name Description
sample

Sample the distribution
Source code in src/attpc_engine/kinematics/excitation.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
class ExcitationDistribution(Protocol):
    """Definition of a nuclear excitation with a specified energy
    distribution

    Methods
    -------
    sample(rng)
        Sample the distribution
    """

    def sample(self, rng: Generator) -> float:  # type: ignore
        """Sample the energy distribution of the excitation.

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

        Returns
        -------
        float
            The sampled value
        """
        pass

sample(rng)

Sample the energy distribution of the excitation.

Parameters:

Name Type Description Default
rng Generator

The random number generator

 required

Returns:

Type Description
float

The sampled value
Source code in src/attpc_engine/kinematics/excitation.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
def sample(self, rng: Generator) -> float:  # type: ignore
    """Sample the energy distribution of the excitation.

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

    Returns
    -------
    float
        The sampled value
    """
    pass

ExcitationGaussian

Represents the sampling parameters for a nuclear excitation with the energy sampled as a gaussian distribution.

Parameters:

Name Type Description Default
centroid float

The state mean/centroid value in MeV.

 0.0
width float

The state FWHM value in MeV.

 0.0

Attributes:

Name Type Description
centroid float

The state mean/centroid value in MeV
width float

The state FWHM value in MeV
sigma float

The state std. deviation in MeV

Methods:

Name Description
sample

Sample the energy distribution of the excitation.
Source code in src/attpc_engine/kinematics/excitation.py 
32
33
34
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 ExcitationGaussian:
    """Represents the sampling parameters for a nuclear excitation with the energy
    sampled as a gaussian distribution.

    Parameters
    ----------
    centroid: float
        The state mean/centroid value in MeV.
    width: float
        The state FWHM value in MeV.

    Attributes
    ----------
    centroid: float
        The state mean/centroid value in MeV
    width: float
        The state FWHM value in MeV
    sigma: float
        The state std. deviation in MeV

    Methods
    -------
    sample(rng)
        Sample the energy distribution of the excitation.
    """

    def __init__(
        self,
        centroid: float = 0.0,
        width: float = 0.0,
    ):
        self.centroid = centroid
        self.width = width  # FWHM
        self.sigma = self.width / 2.355

    def sample(self, rng: Generator) -> float:
        """Sample the energy distribution of the excitation.

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

        Returns
        -------
        float
            The sampled value
        """
        return rng.normal(self.centroid, self.sigma)

sample(rng)

Sample the energy distribution of the excitation.

Parameters:

Name Type Description Default
rng Generator

The random number generator

 required

Returns:

Type Description
float

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

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

    Returns
    -------
    float
        The sampled value
    """
    return rng.normal(self.centroid, self.sigma)

ExcitationUniform

Represents the sampling parameters for a nuclear excitation with the energy sampled as a flat distribution.

Parameters:

Name Type Description Default
min_value float

The minimum value of the range.

 0.0
max_value float

The maximum value of the range.

 0.0

Attributes:

Name Type Description
min_value float

The minimum value of the range
max_value float

The maximum value of the range

Methods:

Name Description
sample

Sample the energy distribution of the excitation.
Source code in src/attpc_engine/kinematics/excitation.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
class ExcitationUniform:
    """Represents the sampling parameters for a nuclear excitation with the energy
    sampled as a flat distribution.

    Parameters
    ----------
    min_value: float
        The minimum value of the range.
    max_value: float
        The maximum value of the range.

    Attributes
    ----------
    min_value: float
        The minimum value of the range
    max_value: float
        The maximum value of the range

    Methods
    -------
    sample(rng)
        Sample the energy distribution of the excitation.
    """

    def __init__(
        self,
        min_value: float = 0.0,
        max_value: float = 0.0,
    ):
        self.min_value = min_value
        self.max_value = max_value

    def sample(self, rng: Generator) -> float:
        """Sample the energy distribution of the excitation.

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

        Returns
        -------
        float
            The sampled value
        """
        return rng.uniform(self.min_value, self.max_value)

sample(rng)

Sample the energy distribution of the excitation.

Parameters:

Name Type Description Default
rng Generator

The random number generator

 required

Returns:

Type Description
float

The sampled value
Source code in src/attpc_engine/kinematics/excitation.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
def sample(self, rng: Generator) -> float:
    """Sample the energy distribution of the excitation.

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

    Returns
    -------
    float
        The sampled value
    """
    return rng.uniform(self.min_value, self.max_value)