liftmath 1.5.0__py3-none-any.whl

liftmath/__init__.py

@@ -0,0 +1,253 @@
+"""liftmath - evidence-based strength training math, pure Python stdlib.
+
+This package is the calculator, not the coach. It estimates one-rep maxes
+(with an RPE/RIR axis, and a weighted-bodyweight-movement variant for
+pull-ups/dips), builds percentage-based load charts, looks up and audits
+weekly volume landmarks per muscle group, ramps a mesocycle, tracks double
+progression, sets protein/calorie/macro targets (including a lean-mass-based
+Cunningham TDEE alternative and bulk/cut rate targets), computes body
+composition (FFMI, Navy tape body-fat %, Jackson-Pollock skinfold + Siri),
+tracks session load/monotony/strain and tonnage (volume-load), scores
+relative strength (Wilks original + 2020, DOTS, IPF GL, McCulloch age
+adjustment), scores squat/bench/deadlift lift-ratio symmetry, computes
+training maxes and named program templates (5/3/1, GZCLP, nSuns), does
+plate/warm-up math (including a finite-inventory plate solver), looks up
+Prilepin's table and INOL, recommends powerlifting meet attempts, detects
+e1RM PRs, tracks gym-culture milestones (clubs), and estimates muscle-gain
+rate. Every formula and heuristic is cited in the module it lives in, with
+an explicit evidence-tier note (established / emerging / speculative /
+practitioner consensus) wherever the provenance isn't a straightforward
+peer-reviewed finding. A plain-English glossary (`glossary.py`) defines
+every piece of jargon this package uses, beginner-friendly first and
+technical second.
+
+None of this is medical or nutrition advice. See the README.
+"""
+
+from liftmath._serialize import to_dict, to_json
+from liftmath.attempts import (
+    OPENER_PCT,
+    OPENER_RANGE_PCT,
+    SECOND_PCT,
+    SECOND_RANGE_PCT,
+    THIRD_PCT,
+    AttemptSelection,
+    attempt_selection,
+)
+from liftmath.bodycomp import FfmiResult, NavyBodyFatResult, ffmi, navy_body_fat
+from liftmath.bodyweight import MOVEMENTS, WeightedBodyweightEstimate, weighted_bodyweight_one_rm
+from liftmath.bulkcut import TIERS, RateTarget, rate_target
+from liftmath.clubs import CULTURE_CAVEAT, ClubProgress, ClubsReport, evaluate_clubs
+from liftmath.gainrate import (
+    ARAGON_HELMS_MONTHLY_PCT_BW,
+    LEVELS,
+    MCDONALD_YEARLY_LB,
+    GainRateEstimate,
+    gain_rate,
+)
+from liftmath.glossary import GLOSSARY, Term, glossary_entry
+from liftmath.loads import load_chart, pct_to_reps, reps_to_pct, target_load
+from liftmath.macros import CunninghamTdee, MacroTargets, cunningham_tdee, macro_targets
+from liftmath.mesocycle import ramp_mesocycle
+from liftmath.onerm import OneRmEstimate, estimate_one_rm
+from liftmath.plates import InventoryPlateLoad, PlateLoad, load_plates, load_plates_from_inventory
+from liftmath.pr import PrCheck, check_pr
+from liftmath.prilepin import (
+    PRILEPIN_CAVEAT,
+    ZONES,
+    InolGroup,
+    InolResult,
+    PrilepinZone,
+    SchemeEvaluation,
+    classify_weekly_inol,
+    classify_workout_inol,
+    evaluate_scheme,
+    inol_of_set,
+    inol_total,
+    zone_for_pct,
+)
+from liftmath.program import ExerciseSet, audit_program
+from liftmath.progression import ProgressionStep, next_progression_step
+from liftmath.rpe import (
+    RepsRpeEstimate,
+    RpeEstimate,
+    pct_1rm_from_reps_and_rir,
+    pct_1rm_from_reps_and_rpe,
+    rir_to_rpe,
+    rpe_from_reps_and_pct,
+    rpe_to_rir,
+)
+from liftmath.sessionload import WeeklyLoad, session_load, weekly_load
+from liftmath.skinfold import (
+    SkinfoldResult,
+    jackson_pollock_men_3site,
+    jackson_pollock_men_7site,
+    jackson_pollock_women_3site,
+    jackson_pollock_women_7site,
+    siri_bodyfat_pct,
+)
+from liftmath.standards import (
+    MastersScore,
+    StrengthScore,
+    dots_score,
+    ipf_gl_points,
+    mcculloch_coefficient,
+    mcculloch_score,
+    score,
+    wilks_original_score,
+    wilks_score,
+)
+from liftmath.symmetry import EXPECTED_RATIOS, LiftRatio, SymmetryReport, score_symmetry
+from liftmath.templates import (
+    T1_STAGES,
+    T2_STAGES,
+    GzclpSession,
+    NsunsDay,
+    ProgramSet,
+    ProgramWeek,
+    TrainingMax,
+    gzclp_next_session,
+    nsuns_day,
+    program_531,
+    round_to_increment,
+    training_max,
+)
+from liftmath.tiers import (
+    MEN_TOTAL_KG,
+    TIER_NAMES,
+    WOMEN_TOTAL_KG,
+    TierResult,
+    TierThresholds,
+    classify_tier,
+    thresholds_at_bodyweight,
+)
+from liftmath.tonnage import TonnageReport, TonnageSet, session_tonnage
+from liftmath.volume import LANDMARKS, MUSCLES, band_for, describe_band, resolve_muscle
+from liftmath.warmup import warmup_ramp
+
+__version__ = "1.5.0"
+
+__all__ = [
+    "estimate_one_rm",
+    "OneRmEstimate",
+    "pct_to_reps",
+    "reps_to_pct",
+    "load_chart",
+    "target_load",
+    "LANDMARKS",
+    "MUSCLES",
+    "band_for",
+    "describe_band",
+    "resolve_muscle",
+    "audit_program",
+    "ExerciseSet",
+    "ramp_mesocycle",
+    "macro_targets",
+    "MacroTargets",
+    "cunningham_tdee",
+    "CunninghamTdee",
+    "load_plates",
+    "PlateLoad",
+    "load_plates_from_inventory",
+    "InventoryPlateLoad",
+    "warmup_ramp",
+    "score",
+    "StrengthScore",
+    "wilks_score",
+    "wilks_original_score",
+    "dots_score",
+    "ipf_gl_points",
+    "mcculloch_coefficient",
+    "mcculloch_score",
+    "MastersScore",
+    "ffmi",
+    "FfmiResult",
+    "navy_body_fat",
+    "NavyBodyFatResult",
+    "session_load",
+    "weekly_load",
+    "WeeklyLoad",
+    "weighted_bodyweight_one_rm",
+    "WeightedBodyweightEstimate",
+    "MOVEMENTS",
+    "next_progression_step",
+    "ProgressionStep",
+    "rate_target",
+    "RateTarget",
+    "TIERS",
+    "pct_1rm_from_reps_and_rpe",
+    "pct_1rm_from_reps_and_rir",
+    "rpe_from_reps_and_pct",
+    "rpe_to_rir",
+    "rir_to_rpe",
+    "RpeEstimate",
+    "RepsRpeEstimate",
+    "score_symmetry",
+    "SymmetryReport",
+    "LiftRatio",
+    "EXPECTED_RATIOS",
+    "round_to_increment",
+    "training_max",
+    "TrainingMax",
+    "program_531",
+    "ProgramWeek",
+    "ProgramSet",
+    "gzclp_next_session",
+    "GzclpSession",
+    "T1_STAGES",
+    "T2_STAGES",
+    "nsuns_day",
+    "NsunsDay",
+    "thresholds_at_bodyweight",
+    "classify_tier",
+    "TierThresholds",
+    "TierResult",
+    "TIER_NAMES",
+    "MEN_TOTAL_KG",
+    "WOMEN_TOTAL_KG",
+    "to_dict",
+    "to_json",
+    "GLOSSARY",
+    "Term",
+    "glossary_entry",
+    "zone_for_pct",
+    "evaluate_scheme",
+    "PrilepinZone",
+    "SchemeEvaluation",
+    "ZONES",
+    "inol_of_set",
+    "inol_total",
+    "classify_workout_inol",
+    "classify_weekly_inol",
+    "InolGroup",
+    "InolResult",
+    "PRILEPIN_CAVEAT",
+    "attempt_selection",
+    "AttemptSelection",
+    "OPENER_PCT",
+    "SECOND_PCT",
+    "THIRD_PCT",
+    "OPENER_RANGE_PCT",
+    "SECOND_RANGE_PCT",
+    "jackson_pollock_men_3site",
+    "jackson_pollock_men_7site",
+    "jackson_pollock_women_3site",
+    "jackson_pollock_women_7site",
+    "siri_bodyfat_pct",
+    "SkinfoldResult",
+    "session_tonnage",
+    "TonnageSet",
+    "TonnageReport",
+    "check_pr",
+    "PrCheck",
+    "evaluate_clubs",
+    "ClubProgress",
+    "ClubsReport",
+    "CULTURE_CAVEAT",
+    "gain_rate",
+    "GainRateEstimate",
+    "LEVELS",
+    "ARAGON_HELMS_MONTHLY_PCT_BW",
+    "MCDONALD_YEARLY_LB",
+    "__version__",
+]

liftmath/__main__.py

@@ -0,0 +1,8 @@
+"""Allows `python -m liftmath ...` in addition to the installed `liftmath` console script."""
+
+import sys
+
+from liftmath.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

liftmath/_serialize.py

@@ -0,0 +1,47 @@
+"""Shared dataclass -> dict/JSON helper for the public result types.
+
+Every public function in liftmath returns a plain @dataclass (OneRmEstimate,
+MacroTargets, PlateLoad, LoadChart, ...). This module turns any of them into a
+plain dict (or a JSON string) suitable for logging, an API response, or the
+CLI's --json flag, without callers having to hand-roll dataclasses.asdict()
+and remember to include the read-only @property values (like PlateLoad.exact
+or OneRmEstimate.is_exact) that asdict() alone would drop.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+from typing import Any
+
+
+def to_dict(obj: Any) -> Any:
+    """Recursively convert a dataclass (or a list/dict/tuple of them) to plain dicts.
+
+    Nested dataclasses, lists, dicts, and tuples are all handled. Read-only
+    properties defined on a dataclass (e.g. `is_exact`, `exact`, `achievable`)
+    are included alongside its fields so the JSON output carries the same
+    derived info the human-readable CLI text does. Tuples are converted to
+    lists (JSON has no tuple type).
+    """
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        result = {f.name: to_dict(getattr(obj, f.name)) for f in dataclasses.fields(obj)}
+        for name in dir(type(obj)):
+            attr = getattr(type(obj), name, None)
+            if isinstance(attr, property) and name not in result:
+                result[name] = to_dict(getattr(obj, name))
+        return result
+    if isinstance(obj, dict):
+        return {k: to_dict(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [to_dict(v) for v in obj]
+    return obj
+
+
+def to_json(obj: Any, **kwargs: Any) -> str:
+    """Serialize a dataclass (or nested structure of them) straight to a JSON string.
+
+    Extra keyword arguments are passed through to `json.dumps` (e.g. `indent=2`).
+    """
+    kwargs.setdefault("indent", 2)
+    return json.dumps(to_dict(obj), **kwargs)

liftmath/attempts.py

@@ -0,0 +1,128 @@
+"""Powerlifting meet attempt selection: opener/second/third as a % of your goal third.
+
+Two numbers, shown side by side rather than picked as one "correct" answer:
+    HEADLINE (peer-reviewed): opener ~91% / second ~96% / third 100% of the
+        goal third-attempt weight.
+    COACH-CONSENSUS RANGE: opener 88-93%, second 93-97% - the wider band
+        practitioner sources actually work within, alongside the headline
+        study numbers.
+
+Sources:
+    Travis, S.K., Zourdos, M.C., Bazyler, C.D. (2021). Weight Selection
+        Attempts of Elite Classic Powerlifters. Perceptual and Motor Skills,
+        128(1), 507-521. DOI: 10.1177/0031512520967608. Lifters (66 men, 43
+        women) who successfully completed ALL NINE attempts at an IPF
+        Classic World Championship, 2012-2019: opener (A1) ~= 91% of the
+        eventual third attempt (A3); A1->A2 jump ~= +5%; A2->A3 jump ~= +3%.
+        Net: opener ~91% of A3, second ~96%, third = 100% by definition.
+    van den Hoek, D.J. et al. (2022). What are the odds? Identifying factors
+        related to competitive success in powerlifting. BMC Sports Science,
+        Medicine and Rehabilitation, 14, 110. DOI: 10.1186/s13102-022-00505-2.
+        10,599 Australian competition entries (2010-2019) - a fully
+        independent dataset/federation from Travis et al. Doesn't publish
+        matching clean percentages, but independently supports the same
+        "aggressive-but-not-reckless attempt selection tracks with winning"
+        direction (winners' openers were heavier than non-winners' by a
+        meaningful margin across all three lifts, both sexes).
+    StrengthLog. "Powerlifting Competition Attempt Calculator & Meet
+        Strategy." strengthlog.com - cites the Travis et al. figures as its
+        basis, layered on coach Matt Gary's 2017 European Powerlifting
+        Conference presentation and the stated practices of coaches Boris
+        Sheiko, Bryce Lewis, and Alexander Eriksson; this is the source for
+        the coach-consensus range above.
+
+Evidence grade: peer-reviewed for the headline %, cross-corroborated by a
+second independent peer-reviewed dataset on outcome direction (not the exact
+numbers), plus wide practitioner overlap - one of the better-sourced items
+in this library.
+
+Rounding: opener/second/third are rounded to the NEAREST achievable plate
+increment (5lb / 2.5kg by default, via `templates.round_to_increment`) - an
+implementation choice of this module, not part of either source (neither
+publishes a rounding convention). Pass `increment` to override, or call
+`templates.round_to_increment` yourself with `direction="down"` for a more
+conservative (never-rounds-up) opener.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from liftmath.templates import DEFAULT_INCREMENT, round_to_increment
+
+# Travis, Zourdos & Bazyler (2021) headline percentages of the goal third attempt.
+OPENER_PCT = 0.91
+SECOND_PCT = 0.96
+THIRD_PCT = 1.00
+
+# Coach-consensus practitioner range (StrengthLog, citing Matt Gary / Boris
+# Sheiko / Bryce Lewis / Alexander Eriksson) - see module docstring.
+OPENER_RANGE_PCT = (0.88, 0.93)
+SECOND_RANGE_PCT = (0.93, 0.97)
+
+
+@dataclass
+class AttemptSelection:
+    """Opener/second/third recommendation for one lift, from a goal third attempt."""
+
+    lift: str
+    goal_third: float
+    unit: str
+    increment: float
+    opener: float
+    second: float
+    third: float
+    opener_range_low: float
+    opener_range_high: float
+    second_range_low: float
+    second_range_high: float
+
+
+def attempt_selection(
+    goal_third: float,
+    *,
+    lift: str = "lift",
+    unit: str = "lb",
+    increment: float | None = None,
+) -> AttemptSelection:
+    """Recommend opener/second/third attempts from a goal third-attempt weight.
+
+    Args:
+        goal_third: the weight you're aiming to hit (or exceed) on your
+            THIRD attempt - every other attempt is computed as a % of it.
+            If you only have an e1RM, pass that (e.g. from `onerm.
+            estimate_one_rm(...).consensus`) as a reasonable stand-in.
+        lift: label only (e.g. "squat", "bench", "deadlift") - not validated
+            against a fixed list; call this once per lift.
+        unit: "lb" or "kg" - selects the default rounding increment.
+        increment: rounding increment; defaults to 5lb / 2.5kg (see
+            `templates.DEFAULT_INCREMENT`, the same defaults Wendler's
+            training max uses in this library).
+
+    Raises:
+        ValueError: if goal_third <= 0, or unit isn't "lb"/"kg" while
+            `increment` is left as its unit-based default.
+    """
+    if goal_third <= 0:
+        raise ValueError("goal_third must be > 0")
+    if increment is None:
+        if unit not in DEFAULT_INCREMENT:
+            raise ValueError(f"unit must be one of {tuple(DEFAULT_INCREMENT)}, got {unit!r}")
+        increment = DEFAULT_INCREMENT[unit]
+
+    def rounded(pct: float) -> float:
+        return round_to_increment(goal_third * pct, increment, direction="nearest")
+
+    return AttemptSelection(
+        lift=lift,
+        goal_third=goal_third,
+        unit=unit,
+        increment=increment,
+        opener=rounded(OPENER_PCT),
+        second=rounded(SECOND_PCT),
+        third=rounded(THIRD_PCT),
+        opener_range_low=rounded(OPENER_RANGE_PCT[0]),
+        opener_range_high=rounded(OPENER_RANGE_PCT[1]),
+        second_range_low=rounded(SECOND_RANGE_PCT[0]),
+        second_range_high=rounded(SECOND_RANGE_PCT[1]),
+    )

liftmath/bodycomp.py

@@ -0,0 +1,190 @@
+"""Body composition: FFMI (Kouri 1995) and Navy tape-measure body-fat % (Hodgdon & Beckett 1984).
+
+Both are stdlib-only (`math.log10`), field-expedient estimates - good for
+tracking a trend over time, not a clinical body-composition reading.
+
+Sources:
+    Kouri, E.M., Pope, H.G., Katz, D.L., Oliva, P. (1995). Fat-free mass
+        index in users and nonusers of anabolic-androgenic steroids.
+        Clinical Journal of Sport Medicine, 5(4), 223-228.
+        FFMI = lean_mass_kg / height_m^2. Normalized to a 1.80m reference
+        height: normalized_FFMI = FFMI + 6.3 * (1.80 - height_m).
+        Study population: 157 male athletes (74 non-users, 83 steroid
+        users). Non-users' normalized FFMI topped out at 25.0 in this
+        sample; historical (1939-1959) "Mr. America" winners averaged 25.4.
+        Evidence grade: established as a descriptive reference from a real
+        measured sample with a clear reported ceiling, but emerging/soft as
+        a hard "natural limit" claim - n=157, all-male, one era/population,
+        no cross-cultural or test-retest replication reported in the source,
+        and genetics/frame/measurement variance mean individuals can
+        legitimately sit above or below 25 without doping. Treat the 25.0
+        line as "a reference ceiling from one 1995 sample," not a law.
+    Hodgdon, J.A., Beckett, M.B. (1984). Prediction of percent body fat for
+        U.S. Navy men and women from body circumferences and height. Naval
+        Health Research Center, Report No. 84-11.
+        Men:   BF% = 86.010*log10(waist-neck) - 70.041*log10(height) + 36.76
+        Women: BF% = 163.205*log10(waist+hip-neck) - 97.684*log10(height) - 78.387
+        All circumferences and height in inches. Waist at the navel, neck
+        below the larynx, hip at the widest point (women only).
+        Evidence grade: established as a field-expedient estimate -
+        validated against hydrostatic weighing at r~=0.90 in the source
+        study, but with a reported standard error of ~3-4 percentage points
+        vs. underwater weighing, so the output should be read as a band
+        ("~18% +/- 3-4"), not a precise figure. That error band is a
+        SAMPLE-AVERAGE figure, not constant across the whole range: this is
+        a regression fit to the Navy's own sample, and like any regression
+        it fits worst at the tails of that sample - a circumference-based
+        estimate tracks fat mass least tightly on bodies that are already
+        very lean or unusually muscular (roughly under ~12% or over ~25%
+        body fat), where the reported +/-3-4 point band is optimistic.
+        `NavyBodyFatResult.less_reliable_at_extremes` flags this range;
+        treat the number there as a rough trend line, not even the usual
+        band.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+_FFMI_REFERENCE_HEIGHT_M = 1.80
+_FFMI_NATURAL_CEILING = 25.0  # Kouri 1995 non-user sample ceiling, normalized FFMI
+
+_SEXES = ("male", "female")
+
+
+@dataclass
+class FfmiResult:
+    """Fat-free mass index for one height/weight/bodyfat combination."""
+
+    weight_kg: float
+    height_m: float
+    bodyfat_pct: float
+    lean_mass_kg: float
+    ffmi: float
+    normalized_ffmi: float
+
+    @property
+    def above_natural_reference_ceiling(self) -> bool:
+        """True if normalized FFMI exceeds Kouri 1995's 25.0 non-user sample ceiling.
+
+        This is a reference point from one 1995 sample of 157 male athletes,
+        not a hard physiological law - individuals can legitimately sit above
+        or below it without doping. See module docstring.
+        """
+        return self.normalized_ffmi > _FFMI_NATURAL_CEILING
+
+
+def ffmi(weight_kg: float, height_m: float, bodyfat_pct: float) -> FfmiResult:
+    """Compute FFMI and height-normalized FFMI (Kouri et al., 1995).
+
+    Args:
+        weight_kg: total bodyweight, kilograms.
+        height_m: height, meters.
+        bodyfat_pct: body-fat percentage as a whole number (e.g. 15 for 15%).
+
+    Raises:
+        ValueError: if weight_kg or height_m aren't positive, or bodyfat_pct
+            isn't in [0, 100).
+    """
+    if weight_kg <= 0:
+        raise ValueError("weight_kg must be > 0")
+    if height_m <= 0:
+        raise ValueError("height_m must be > 0")
+    if not 0 <= bodyfat_pct < 100:
+        raise ValueError("bodyfat_pct must be in [0, 100)")
+
+    lean_mass_kg = weight_kg * (1 - bodyfat_pct / 100.0)
+    raw_ffmi = lean_mass_kg / height_m**2
+    normalized = raw_ffmi + 6.3 * (_FFMI_REFERENCE_HEIGHT_M - height_m)
+
+    return FfmiResult(
+        weight_kg=weight_kg,
+        height_m=height_m,
+        bodyfat_pct=bodyfat_pct,
+        lean_mass_kg=lean_mass_kg,
+        ffmi=raw_ffmi,
+        normalized_ffmi=normalized,
+    )
+
+
+@dataclass
+class NavyBodyFatResult:
+    """Navy tape-measure body-fat % estimate (Hodgdon & Beckett 1984)."""
+
+    sex: str
+    height_in: float
+    neck_in: float
+    waist_in: float
+    hip_in: float | None
+    bodyfat_pct: float
+
+    @property
+    def error_band_pct(self) -> float:
+        """Reported standard error vs. hydrostatic weighing, +/- percentage points."""
+        return 3.5
+
+    @property
+    def less_reliable_at_extremes(self) -> bool:
+        """True below ~12% or above ~25% body fat, where this regression fits worst.
+
+        The Hodgdon & Beckett regression was fit across the Navy's own
+        sample and is least accurate at the tails of that fit - a very lean
+        or unusually muscular body pushes the real error wider than the
+        reported +/-3-4 point band (see module docstring). Read the result
+        as a rough trend line in this range, not the usual band.
+        """
+        return self.bodyfat_pct < 12.0 or self.bodyfat_pct > 25.0
+
+
+def navy_body_fat(
+    sex: str,
+    height_in: float,
+    neck_in: float,
+    waist_in: float,
+    hip_in: float | None = None,
+) -> NavyBodyFatResult:
+    """Estimate body-fat % from circumference measurements (Hodgdon & Beckett, 1984).
+
+    Args:
+        sex: "male" or "female".
+        height_in: height, inches.
+        neck_in: neck circumference below the larynx, inches.
+        waist_in: waist circumference at the navel, inches.
+        hip_in: hip circumference at the widest point, inches. Required for
+            "female", ignored for "male".
+
+    Raises:
+        ValueError: if sex isn't "male"/"female", any measurement isn't
+            positive, hip_in is missing for "female", or the log10 argument
+            would be non-positive (e.g. waist <= neck for men).
+    """
+    if sex not in _SEXES:
+        raise ValueError(f"sex must be one of {_SEXES}, got {sex!r}")
+    for name, value in (("height_in", height_in), ("neck_in", neck_in), ("waist_in", waist_in)):
+        if value <= 0:
+            raise ValueError(f"{name} must be > 0")
+
+    if sex == "male":
+        span = waist_in - neck_in
+        if span <= 0:
+            raise ValueError("waist_in must be greater than neck_in")
+        bf = 86.010 * math.log10(span) - 70.041 * math.log10(height_in) + 36.76
+    else:
+        if hip_in is None:
+            raise ValueError("hip_in is required for sex='female'")
+        if hip_in <= 0:
+            raise ValueError("hip_in must be > 0")
+        span = waist_in + hip_in - neck_in
+        if span <= 0:
+            raise ValueError("waist_in + hip_in must be greater than neck_in")
+        bf = 163.205 * math.log10(span) - 97.684 * math.log10(height_in) - 78.387
+
+    return NavyBodyFatResult(
+        sex=sex,
+        height_in=height_in,
+        neck_in=neck_in,
+        waist_in=waist_in,
+        hip_in=hip_in,
+        bodyfat_pct=bf,
+    )