crc-framework 0.2.6__tar.gz → 0.3.0__tar.gz

{crc_framework-0.2.6 → crc_framework-0.3.0}/Cargo.lock

@@ -43,7 +43,7 @@ dependencies = [
 
 [[package]]
 name = "crc-framework-core"
-version = "0.2.6"
+version = "0.3.0"
 dependencies = [
  "h3o",
  "phf",
@@ -52,7 +52,7 @@ dependencies = [
 
 [[package]]
 name = "crc-framework-rs"
-version = "0.2.6"
+version = "0.3.0"
 dependencies = [
  "crc-framework-core",
  "h3o",

{crc_framework-0.2.6 → crc_framework-0.3.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "crc-framework-rs"
-version = "0.2.6"
+version = "0.3.0"
 edition = "2024"
 rust-version = "1.85"
 description = "Rust-powered Python bindings for the Climate Risk Commons Framework"

{crc_framework-0.2.6 → crc_framework-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crc-framework
-Version: 0.2.6
+Version: 0.3.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
 Classifier: Operating System :: OS Independent
@@ -121,6 +121,31 @@ Kolmogorov–Smirnov p-value. The supported families are `genextreme`,
 diagnostics. Passing a tabulated or fitted distribution is an error: those
 values are not independent observations.
 
+For a standalone L-moment estimate of GEV or Gumbel observations, select the
+estimator explicitly:
+
+```python
+from crc_framework import fit_distribution
+
+result = fit_distribution(annual_extremes, family="genextreme", method="lmoments")
+```
+
+This uses unbiased sample L-moments (Hosking, 1990), with an exact numerical
+solution of the GEV L-skewness equation. It supports `genextreme`, `gumbel_r`
+and `gumbel_l`, requires at least four finite, nonconstant observations, and
+performs no likelihood optimization or automatic family selection. GEV shape
+uses the SciPy convention (`c = -xi`); the finite-mean domain is `c > -1`.
+Degenerate L-skewness is rejected rather than clipped. Fit constraints can
+accept or reject the estimated distribution without refitting it.
+
+The native implementation sorts once, uses compensated sums in scaled and
+centered coordinates, and reuses that sort for diagnostics. Work is O(n log n)
+with O(n) storage. The Python binding releases the GIL during native fitting.
+The returned KS p-value is a descriptive diagnostic, not a calibrated hypothesis
+test after parameter estimation. Defaults and the existing sample fitter are
+unchanged. See [NIST's L-moments reference](https://www.itl.nist.gov/div898/software/dataplot/refman2/auxillar/lmoment.htm)
+for background and the Hosking references.
+
 Use `fit_quantiles` for probability/value knots. It minimizes weighted
 value-space differences between the supplied values and the selected family's
 PPF, requires an explicit family, and reports residual diagnostics rather than

{crc_framework-0.2.6 → crc_framework-0.3.0}/README.md

@@ -95,6 +95,31 @@ Kolmogorov–Smirnov p-value. The supported families are `genextreme`,
 diagnostics. Passing a tabulated or fitted distribution is an error: those
 values are not independent observations.
 
+For a standalone L-moment estimate of GEV or Gumbel observations, select the
+estimator explicitly:
+
+```python
+from crc_framework import fit_distribution
+
+result = fit_distribution(annual_extremes, family="genextreme", method="lmoments")
+```
+
+This uses unbiased sample L-moments (Hosking, 1990), with an exact numerical
+solution of the GEV L-skewness equation. It supports `genextreme`, `gumbel_r`
+and `gumbel_l`, requires at least four finite, nonconstant observations, and
+performs no likelihood optimization or automatic family selection. GEV shape
+uses the SciPy convention (`c = -xi`); the finite-mean domain is `c > -1`.
+Degenerate L-skewness is rejected rather than clipped. Fit constraints can
+accept or reject the estimated distribution without refitting it.
+
+The native implementation sorts once, uses compensated sums in scaled and
+centered coordinates, and reuses that sort for diagnostics. Work is O(n log n)
+with O(n) storage. The Python binding releases the GIL during native fitting.
+The returned KS p-value is a descriptive diagnostic, not a calibrated hypothesis
+test after parameter estimation. Defaults and the existing sample fitter are
+unchanged. See [NIST's L-moments reference](https://www.itl.nist.gov/div898/software/dataplot/refman2/auxillar/lmoment.htm)
+for background and the Hosking references.
+
 Use `fit_quantiles` for probability/value knots. It minimizes weighted
 value-space differences between the supplied values and the selected family's
 PPF, requires an explicit family, and reports residual diagnostics rather than

{crc_framework-0.2.6 → crc_framework-0.3.0}/crates/core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "crc-framework-core"
-version = "0.2.6"
+version = "0.3.0"
 edition = "2024"
 rust-version = "1.85"
 description = "Core distribution and climate-risk algorithms for CRC Framework"

crc_framework-0.3.0/crates/core/src/distribution/lmoments.rs

@@ -0,0 +1,215 @@
+//! Unbiased sample L-moments (Hosking, 1990) for annual extreme families.
+//! One O(n log n) sort, O(n) moment/diagnostic passes, no likelihood optimizer.
+
+use super::{DistributionFamily, FittedDistribution};
+use crate::error::{CrcError, Result};
+
+const EULER: f64 = 0.577_215_664_901_532_9;
+
+// Neumaier summation keeps the signed order-statistic sums accurate.
+#[derive(Default)]
+struct Sum(f64, f64);
+impl Sum {
+    fn add(&mut self, x: f64) {
+        let next = self.0 + x;
+        self.1 += if self.0.abs() >= x.abs() {
+            (self.0 - next) + x
+        } else {
+            (x - next) + self.0
+        };
+        self.0 = next;
+    }
+    fn value(&self) -> f64 {
+        self.0 + self.1
+    }
+}
+
+pub(super) fn fit(
+    samples: &[f64],
+    family: DistributionFamily,
+) -> Result<(FittedDistribution, Vec<f64>)> {
+    if !matches!(
+        family,
+        DistributionFamily::GenExtreme
+            | DistributionFamily::GumbelRight
+            | DistributionFamily::GumbelLeft
+    ) {
+        return Err(CrcError::Unsupported(
+            "L-moments supports genextreme, gumbel_r and gumbel_l only".into(),
+        ));
+    }
+    if samples.len() < 4 || samples.iter().any(|x| !x.is_finite()) {
+        return Err(CrcError::InvalidInput(
+            "L-moments requires at least four finite samples".into(),
+        ));
+    }
+    let mut sorted = samples.to_vec();
+    sorted.sort_unstable_by(f64::total_cmp);
+    if sorted[0] == sorted[sorted.len() - 1] {
+        return Err(CrcError::InvalidInput(
+            "L-moments requires nonconstant samples".into(),
+        ));
+    }
+    // Work in centered, bounded coordinates, avoiding overflow and cancellation
+    // in records with a large offset or a very small physical scale.
+    let magnitude = sorted[0].abs().max(sorted[sorted.len() - 1].abs());
+    let offset = sorted[sorted.len() / 2];
+    let n = sorted.len() as f64;
+    let mut sums = [Sum::default(), Sum::default(), Sum::default()];
+    for (i, &x) in sorted.iter().enumerate() {
+        let i = i as f64;
+        let delta = x - offset;
+        let y = if delta.is_finite() {
+            delta / magnitude
+        } else {
+            x / magnitude - offset / magnitude
+        };
+        let w1 = i / (n - 1.0);
+        let w2 = i * (i - 1.0) / ((n - 1.0) * (n - 2.0));
+        sums[0].add(y);
+        sums[1].add((2.0 * w1 - 1.0) * y);
+        sums[2].add((6.0 * w2 - 6.0 * w1 + 1.0) * y);
+    }
+    let l1 = sums[0].value() / n;
+    let l2 = sums[1].value() / n;
+    let l3 = sums[2].value() / n;
+    if !l2.is_finite() || l2 <= 0.0 {
+        return Err(CrcError::InvalidInput(
+            "L-moments requires positive L-scale".into(),
+        ));
+    }
+    let (shape, location, scale) = match family {
+        DistributionFamily::GumbelRight => {
+            let scale = l2 / std::f64::consts::LN_2;
+            (None, l1 - EULER * scale, scale)
+        }
+        DistributionFamily::GumbelLeft => {
+            let scale = l2 / std::f64::consts::LN_2;
+            (None, l1 + EULER * scale, scale)
+        }
+        DistributionFamily::GenExtreme => gev_parameters(l1, l2, l3 / l2)?,
+        _ => unreachable!(),
+    };
+    let distribution = FittedDistribution::from_parameters(
+        family,
+        shape,
+        location * magnitude + offset,
+        scale * magnitude,
+    )?;
+    Ok((distribution, sorted))
+}
+
+fn gev_skew(shape: f64) -> f64 {
+    if shape.abs() < 1e-8 {
+        // Continuous limit and first derivative at the Gumbel shape.
+        let ratio = 3.0_f64.ln() / std::f64::consts::LN_2;
+        return 2.0 * ratio - 3.0 - ratio * (3.0_f64.ln() - std::f64::consts::LN_2) * shape;
+    }
+    2.0 * (-shape * 3.0_f64.ln()).exp_m1() / (-shape * std::f64::consts::LN_2).exp_m1() - 3.0
+}
+
+fn gev_parameters(l1: f64, l2: f64, skew: f64) -> Result<(Option<f64>, f64, f64)> {
+    if !skew.is_finite() || skew.abs() >= 1.0 {
+        return Err(CrcError::InvalidInput(
+            "GEV L-skewness must be strictly between -1 and 1".into(),
+        ));
+    }
+    // The exact L-skewness equation is monotone for c > -1 (finite mean).
+    // Bisection avoids approximation/clipping of strongly skewed samples.
+    let mut low = -1.0;
+    let mut high = 1.0;
+    for _ in 0..7 {
+        if gev_skew(high) <= skew {
+            break;
+        }
+        high *= 2.0;
+    }
+    if gev_skew(high) > skew {
+        return Err(CrcError::InvalidInput(
+            "GEV L-skewness cannot be resolved numerically".into(),
+        ));
+    }
+    for _ in 0..64 {
+        let mid = (low + high) / 2.0;
+        if mid == low || mid == high {
+            break;
+        }
+        if gev_skew(mid) > skew {
+            low = mid;
+        } else {
+            high = mid;
+        }
+    }
+    let shape = (low + high) / 2.0;
+    if shape.abs() < 1e-10 {
+        let scale = l2 / std::f64::consts::LN_2;
+        return Ok((Some(0.0), l1 - EULER * scale, scale));
+    }
+    let log_gamma = log_gamma_one_plus(shape);
+    let denominator = -(-shape * std::f64::consts::LN_2).exp_m1();
+    let scale = l2 * (shape / denominator) * (-log_gamma).exp();
+    // Algebraically scale*(Gamma(1+c)-1)/c, without gamma overflow.
+    let location = l1 + l2 / denominator * -(-log_gamma).exp_m1();
+    Ok((Some(shape), location, scale))
+}
+
+fn log_gamma_one_plus(x: f64) -> f64 {
+    if x.abs() < 0.01 {
+        // log Gamma(1+x) = -gamma*x + sum (-1)^k zeta(k)*x^k/k.
+        return x
+            * (-EULER
+                + x * (0.822_467_033_424_113_2
+                    + x * (-0.400_685_634_386_531_4
+                        + x * (0.270_580_808_427_784_5
+                            + x * (-0.207_385_551_028_674
+                                + x * (0.169_557_176_997_408_2 - x * 0.144_049_896_768_846_1))))));
+    }
+    // Lanczos in log space; recurrence keeps the argument >= 1, even c -> -1.
+    let z = 1.0 + x;
+    if z < 1.0 {
+        return log_gamma_one_plus(x + 1.0) - z.ln();
+    }
+    let coefficients = [
+        676.520_368_121_885_1,
+        -1_259.139_216_722_402_8,
+        771.323_428_777_653_1,
+        -176.615_029_162_140_6,
+        12.507_343_278_686_905,
+        -0.138_571_095_265_720_12,
+        9.984_369_578_019_572e-6,
+        1.505_632_735_149_311_6e-7,
+    ];
+    let mut a = 0.999_999_999_999_809_9;
+    for (i, coefficient) in coefficients.iter().enumerate() {
+        a += coefficient / (x + i as f64 + 1.0);
+    }
+    let t = x + 7.5;
+    0.918_938_533_204_672_7 + (x + 0.5) * t.ln() - t + a.ln()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn exact_shape_equation_including_heavy_tails() {
+        for shape in [-0.95, -0.7, -0.2, -1e-5, 0.0, 1e-5, 0.2, 1.0, 5.0] {
+            let (actual, _, scale) = gev_parameters(2.0, 1.0, gev_skew(shape)).unwrap();
+            assert!(
+                (actual.unwrap() - shape).abs() < 1e-10,
+                "shape {shape}: {actual:?}"
+            );
+            assert!(scale > 0.0 && scale.is_finite());
+        }
+    }
+    #[test]
+    fn small_scales_and_large_offsets() {
+        for samples in [
+            [1e-20, 2e-20, 3e-20, 4e-20],
+            [1e15, 1e15 + 1.0, 1e15 + 2.0, 1e15 + 3.0],
+            [-1e308, -5e307, 5e307, 1e308],
+        ] {
+            let (fit, _) = fit(&samples, DistributionFamily::GumbelRight).unwrap();
+            assert!(fit.scale.is_finite() && fit.scale > 0.0);
+        }
+    }
+}

{crc_framework-0.2.6 → crc_framework-0.3.0}/crates/core/src/distribution.rs

@@ -7,6 +7,8 @@ use crate::{
     reference::curve_fitting as reference_curve_fitting,
 };
 
+mod lmoments;
+
 const EPS: f64 = 1.0e-12;
 
 pub trait Distribution: Send + Sync {
@@ -856,6 +858,18 @@ pub fn fit_distribution(samples: &[f64], family: Option<DistributionFamily>) ->
         .ok_or_else(|| CrcError::Unsupported("no candidate distribution could be fitted".into()))
 }
 
+/// Fit GEV or Gumbel observations by unbiased sample L-moments.
+///
+/// This is a standalone estimator: no likelihood optimization or family selection.
+/// GEV shape follows the SciPy convention (`c = -xi`).
+pub fn fit_lmoments(samples: &[f64], family: DistributionFamily) -> Result<FitResult> {
+    let (distribution, sorted) = lmoments::fit(samples, family)?;
+    Ok(FitResult {
+        diagnostics: diagnostics_sorted(&sorted, &distribution),
+        distribution,
+    })
+}
+
 pub fn fit_quantiles(
     probabilities: &[f64],
     values: &[f64],
@@ -1057,6 +1071,10 @@ fn reference_diagnostic(diagnostic: reference_curve_fitting::DiagnosticFit) -> R
 fn diagnostics(samples: &[f64], distribution: &dyn Distribution) -> DiagnosticMetrics {
     let mut sorted = samples.to_vec();
     sorted.sort_by(f64::total_cmp);
+    diagnostics_sorted(&sorted, distribution)
+}
+
+fn diagnostics_sorted(sorted: &[f64], distribution: &dyn Distribution) -> DiagnosticMetrics {
     let count = sorted.len() as f64;
     let mut ks: f64 = 0.0;
     let mut squared_error = 0.0;

{crc_framework-0.2.6 → crc_framework-0.3.0}/crates/core/src/lib.rs

@@ -11,7 +11,7 @@ pub use distribution::{
     DiagnosticMetrics, Distribution, DistributionFamily, EmpiricalDistribution, FitResult,
     FittedDistribution, HurdleDistribution, HurdleQuantileFitDiagnostics, HurdleQuantileFitResult,
     Interpolation, PointMassDistribution, QuantileFitDiagnostics, QuantileFitResult,
-    TabulatedDistribution, Tail, fit_hurdle_quantiles, fit_quantiles,
+    TabulatedDistribution, Tail, fit_hurdle_quantiles, fit_lmoments, fit_quantiles,
 };
 pub use error::{CrcError, Result};
 pub use metrics::{

{crc_framework-0.2.6 → crc_framework-0.3.0}/python/crc_framework/_core.pyi

@@ -122,7 +122,7 @@ def hurdle_distribution(
     atom_probability: float,
     atom_location: float = ...,
 ) -> NativeDistribution: ...
-def fit(samples: Sequence[float], family: Optional[str] = ...) -> NativeFitResult: ...
+def fit(samples: Sequence[float], family: Optional[str] = ..., *, method: str = ...) -> NativeFitResult: ...
 def fit_candidates(samples: Sequence[float]) -> List[NativeFitResult]: ...
 def fit_quantiles(
     probabilities: Sequence[float],

{crc_framework-0.2.6 → crc_framework-0.3.0}/python/crc_framework/distributions/fitting.py

@@ -158,9 +158,21 @@ def fit_distribution(
     *,
     candidates: Optional[Sequence[DistributionFamily]] = None,
     selector: str = "ks",
+    method: str = "default",
     constraints: Optional[Union[FitConstraints, Mapping[str, float]]] = None,
 ) -> FitResult:
-    """Fit explicitly; metric functions never call this automatically."""
+    """Fit observations explicitly; metrics never fit automatically.
+
+    ``method="default"`` preserves the existing sample fitter.
+    ``method="lmoments"`` uses unbiased sample L-moments for an explicit
+    ``genextreme``, ``gumbel_r`` or ``gumbel_l`` family, without optimization.
+    GEV shape uses the SciPy convention (c = -xi). Automatic family selection
+    and candidate lists are unavailable for L-moments.
+    """
+    if method not in ("default", "lmoments"):
+        raise ValueError(f"unknown fitting method {method!r}")
+    if method == "lmoments" and (family == "auto" or candidates is not None):
+        raise ValueError("L-moments fitting requires an explicit family and no candidates")
     if selector != "ks":
         raise ValueError("only the 'ks' selector is currently supported")
     active_constraints = (
@@ -168,6 +180,11 @@ def fit_distribution(
         if isinstance(constraints, Mapping)
         else constraints
     )
+    if method == "lmoments":
+        result = _result(_core.fit(_samples(data), family, method=method))
+        if active_constraints is not None and not active_constraints.accepts(result):
+            raise ValueError("L-moments fit does not satisfy the requested constraints")
+        return result
     if candidates is not None or active_constraints is not None:
         allowed = (
             set(candidates)

{crc_framework-0.2.6 → crc_framework-0.3.0}/src/lib.rs

@@ -354,17 +354,36 @@ fn hurdle_distribution(
 }
 
 #[pyfunction]
-#[pyo3(signature = (samples, family=None))]
-fn fit(samples: Vec<f64>, family: Option<&str>) -> PyResult<PyFitResult> {
+#[pyo3(signature = (samples, family=None, *, method="default"))]
+fn fit(
+    py: Python<'_>,
+    samples: Vec<f64>,
+    family: Option<&str>,
+    method: &str,
+) -> PyResult<PyFitResult> {
     let family = family
         .map(|name| {
             DistributionFamily::from_name(name)
                 .ok_or_else(|| PyValueError::new_err(format!("unknown distribution family {name}")))
         })
         .transpose()?;
-    crc_framework_core::distribution::fit_distribution(&samples, family)
-        .map(fit_result_py)
-        .map_err(py_error)
+    let result = match method {
+        "default" => {
+            py.detach(|| crc_framework_core::distribution::fit_distribution(&samples, family))
+        }
+        "lmoments" => {
+            let family = family.ok_or_else(|| {
+                PyValueError::new_err("L-moments fitting requires an explicit family")
+            })?;
+            py.detach(|| crc_framework_core::distribution::fit_lmoments(&samples, family))
+        }
+        _ => {
+            return Err(PyValueError::new_err(format!(
+                "unknown fitting method {method}"
+            )));
+        }
+    };
+    result.map(fit_result_py).map_err(py_error)
 }
 
 #[pyfunction]

crc_framework-0.3.0/tests/test_lmoments.py

@@ -0,0 +1,138 @@
+"""Independent numerical references for the standalone native estimator."""
+
+import math
+
+import numpy as np
+import pytest
+from crc_framework import EmpiricalDistribution, FitConstraints, fit_distribution
+
+
+# Unbiased PWMs evaluated separately in NumPy, with the exact GEV L-skewness
+# equation solved by SciPy brentq and parameters evaluated with scipy.special.gamma.
+# No SciPy runtime dependency is needed to check these fixed reference cases.
+@pytest.mark.parametrize(
+    "samples, expected",
+    [
+        (
+            [1, 2, 3, 4, 5, 6, 7, 8],
+            (0.2837755261699676, 3.5673697128875066, 2.6485046284617866),
+        ),
+        (
+            [0, 0, 1, 3, 8, 15, 30, 100],
+            (-0.6906224839693698, 2.5435518253418365, 6.22052453291623),
+        ),
+        (
+            [1, 2, 2, 3, 5, 8, 13, 21, 34, 55],
+            (-0.46999345573819784, 4.659674734457967, 6.785717967583603),
+        ),
+        (
+            [-100, -30, -15, -8, -3, -1, 0, 0],
+            (2.343489515427684, -6.78103358608292, 16.64903073472396),
+        ),
+    ],
+)
+def test_gev_reference_parameters(samples, expected):
+    fit = fit_distribution(samples, "genextreme", method="lmoments")
+    d = fit.distribution
+    np.testing.assert_allclose([d.shape, d.location, d.scale], expected, rtol=2e-12)
+    assert all(math.isfinite(x) for x in vars(fit.diagnostics).values())
+    # Sorting is internal and the estimator is deterministic.
+    other = fit_distribution(
+        samples[::-1], "genextreme", method="lmoments"
+    ).distribution
+    assert (d.shape, d.location, d.scale) == (other.shape, other.location, other.scale)
+
+
+def test_gumbel_analytic_and_reflected_fit():
+    # For [1,...,8], L1 = 4.5 and unbiased L2 = 1.5.
+    d = fit_distribution(list(range(1, 9)), "gumbel_r", method="lmoments").distribution
+    scale = 1.5 / math.log(2)
+    assert d.scale == pytest.approx(scale, rel=1e-14)
+    assert d.location == pytest.approx(4.5 - 0.5772156649015329 * scale, rel=1e-14)
+    reflected = fit_distribution(
+        list(range(-8, 0)), "gumbel_l", method="lmoments"
+    ).distribution
+    assert reflected.location == pytest.approx(-d.location)
+    assert reflected.scale == pytest.approx(d.scale)
+
+
+@pytest.mark.parametrize("shape", [-0.4, -0.2, 0.0, 0.2, 1.2])
+def test_recovers_population_quantiles(shape):
+    from crc_framework import FittedDistribution
+
+    original = FittedDistribution("genextreme", shape=shape, location=10, scale=3)
+    data = original.quantiles((np.arange(20000) + 0.5) / 20000)
+    fitted = fit_distribution(data, "genextreme", method="lmoments").distribution
+    # Heavy tails converge slowly; compare return levels within the sample record.
+    np.testing.assert_allclose(
+        fitted.quantiles([0.5, 0.9, 0.99]),
+        original.quantiles([0.5, 0.9, 0.99]),
+        rtol=0.035,
+    )
+
+
+@pytest.mark.parametrize("family", ["genextreme", "gumbel_r", "gumbel_l"])
+@pytest.mark.parametrize("scale, offset", [(1e-20, 0), (1e20, 1e22), (0.1, 1e5)])
+def test_affine_equivariance(family, scale, offset):
+    values = np.array([0, 0, 1, 3, 8, 15, 30, 100], dtype=float)
+    base = fit_distribution(values, family, method="lmoments").distribution
+    actual = fit_distribution(
+        values * scale + offset, family, method="lmoments"
+    ).distribution
+    assert actual.shape == pytest.approx(base.shape, abs=1e-10)
+    assert actual.location == pytest.approx(base.location * scale + offset, rel=1e-10)
+    assert actual.scale == pytest.approx(base.scale * scale, rel=1e-10)
+
+
+@pytest.mark.parametrize(
+    "samples", [[], [1, 2, 3], [2] * 8, [0, 1, 2, np.nan], [0, 1, 2, np.inf]]
+)
+def test_invalid_records(samples):
+    with pytest.raises(ValueError):
+        fit_distribution(samples, "genextreme", method="lmoments")
+
+
+def test_explicit_policy_and_constraints():
+    values = EmpiricalDistribution([1, 2, 3, 4, 5, 6, 7, 8])
+    with pytest.raises(ValueError, match="explicit family"):
+        fit_distribution(values, method="lmoments")
+    with pytest.raises(ValueError, match="no candidates"):
+        fit_distribution(values, "gumbel_r", candidates=["gumbel_r"], method="lmoments")
+    with pytest.raises(ValueError, match="supports"):
+        fit_distribution(values, "genpareto", method="lmoments")
+    with pytest.raises(ValueError, match="unknown fitting method"):
+        fit_distribution(values, "gumbel_r", method="not-an-estimator")
+    fit_distribution(
+        values,
+        "gumbel_r",
+        method="lmoments",
+        constraints=FitConstraints(minimum_value=0),
+    )
+    with pytest.raises(ValueError, match="constraints"):
+        fit_distribution(
+            values,
+            "gumbel_r",
+            method="lmoments",
+            constraints=FitConstraints(maximum_value=0),
+        )
+
+
+def test_heavy_tail_estimate_converges_with_record_length():
+    from crc_framework import FittedDistribution
+
+    original = FittedDistribution("genextreme", shape=-0.8, location=10, scale=3)
+    target = original.ppf(0.99)
+    errors = []
+    for n in (1000, 20000):
+        values = original.quantiles((np.arange(n) + 0.5) / n)
+        estimated = fit_distribution(
+            values, "genextreme", method="lmoments"
+        ).distribution
+        errors.append(abs(estimated.ppf(0.99) - target))
+    assert errors[1] < errors[0]
+
+
+@pytest.mark.parametrize("values", [[0, 0, 0, 1], [0, 1, 1, 1]])
+def test_degenerate_skewness_is_rejected(values):
+    with pytest.raises(ValueError, match="L-skewness"):
+        fit_distribution(values, "genextreme", method="lmoments")