laddu-physics 0.21.2

Amplitude analysis tools for Rust
Documentation 
1
2
3
4
5
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
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
81
82
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

use density::{FiniteInterval, Sample};

#[derive(Clone, Copy, Debug)]
/// Mass and importance weight drawn from a [`MassProposal`].
pub struct MassProposalResult {
    /// Proposed invariant mass.
    pub mass: f64,
    /// Inverse proposal-density correction.
    pub weight: f64,
}

/// Invariant-mass proposal for a generated edge.
#[derive(Clone, Copy, Debug, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum MassProposal {
    /// Always use one invariant mass.
    Fixed {
        /// Fixed invariant mass.
        mass: f64,
    },
    /// Sample uniformly between the given bounds, clipped to kinematic support.
    Uniform {
        /// Lower proposal bound.
        low: f64,
        /// Upper proposal bound.
        high: f64,
    },
}

impl MassProposal {
    /// Construct a fixed-mass proposal.
    pub fn fixed(mass: f64) -> Self {
        Self::Fixed { mass }
    }
    /// Construct a uniform mass proposal.
    pub fn uniform(low: f64, high: f64) -> Self {
        Self::Uniform { low, high }
    }

    /// Draw a mass within the supplied kinematic interval.
    ///
    /// # Errors
    ///
    /// Returns [`LadduPhysicsError`] when the kinematic interval or proposal
    /// bounds are non-finite, empty, or exclude a fixed mass.
    pub fn propose(
        &self,
        minimum: f64,
        maximum: f64,
        rng: &mut ProposalRng,
    ) -> LadduPhysicsResult<MassProposalResult> {
        match *self {
            Self::Fixed { mass } => {
                if !mass.is_finite() || mass < minimum || mass > maximum {
                    return Err(LadduPhysicsError::invalid_value(
                        "fixed mass",
                        format!("a finite value in [{minimum}, {maximum}]"),
                        mass,
                    ));
                }
                Ok(MassProposalResult { mass, weight: 1.0 })
            }
            Self::Uniform { low, high } => {
                let interval = uniform_mass_support(low, high, minimum, maximum)?;
                let sample = Sample {
                    value: interval.low() + rng.uniform() * interval.width(),
                    inverse_density: interval.width(),
                };
                Ok(MassProposalResult {
                    mass: sample.value,
                    weight: sample.inverse_density,
                })
            }
        }
    }

    /// Evaluate the proposal density when it is available.
    ///
    /// # Errors
    ///
    /// Returns [`LadduPhysicsError`] when the kinematic interval and uniform
    /// proposal have no valid finite overlap.
    pub fn density(
        &self,
        minimum: f64,
        maximum: f64,
        mass: f64,
    ) -> LadduPhysicsResult<Option<f64>> {
        match *self {
            Self::Fixed { .. } => Ok(None),
            Self::Uniform { low, high } => {
                let interval = uniform_mass_support(low, high, minimum, maximum)?;
                Ok(Some(if interval.contains(mass) {
                    interval.width().recip()
                } else {
                    0.0
                }))
            }
        }
    }
}

impl From<f64> for MassProposal {
    fn from(mass: f64) -> Self {
        Self::fixed(mass)
    }
}

impl From<std::ops::Range<f64>> for MassProposal {
    fn from(range: std::ops::Range<f64>) -> Self {
        Self::uniform(range.start, range.end)
    }
}

fn uniform_mass_support(
    proposal_low: f64,
    proposal_high: f64,
    minimum: f64,
    maximum: f64,
) -> LadduPhysicsResult<FiniteInterval> {
    if !proposal_low.is_finite() || !proposal_high.is_finite() || proposal_high <= proposal_low {
        return Err(LadduPhysicsError::invalid_relation(format!(
            "uniform mass proposal requires finite low < high, got [{proposal_low}, {proposal_high}]"
        )));
    }
    let proposal = FiniteInterval::new(proposal_low, proposal_high)
        .expect("proposal bounds were validated above");
    let Some(allowed) = FiniteInterval::new(minimum, maximum) else {
        return Err(LadduPhysicsError::invalid_relation(format!(
            "uniform mass support [{proposal_low}, {proposal_high}] does not overlap the allowed interval [{minimum}, {maximum}]"
        )));
    };
    let Some(support) = proposal.intersect(allowed) else {
        return Err(LadduPhysicsError::invalid_relation(format!(
            "uniform mass support [{proposal_low}, {proposal_high}] does not overlap the allowed interval [{minimum}, {maximum}]"
        )));
    };
    Ok(support)
}