Skip to content

The Design & Diagnostics Laboratory

A core philosophy of caltib is complete transparency. The modern reform engines (L1–L6) are not black boxes with arbitrary magic numbers. The library includes the exact mathematical tools used to derive, optimize, and validate every parameter in the system. Anyone can verify our constants or use these tools to design their own calendar engine.

Laboratory Dependencies

To access these modules, ensure you have installed the optional laboratory dependencies: pip install "caltib[tools]" (for design/charting) and pip install "caltib[ephemeris]" (for JPL DE422 integration).

1. The "Ground Truth" Ephemeris Layer

All parameter design and diagnostic testing must be measured against physical reality. caltib natively supports two interchangeable standards of truth:

  • The Analytical Reference (REF): A lightweight, highly precise, built-in implementation of truncated ELP2000/Meeus series algorithms. It allows the tools to run anywhere without heavy downloads or external dependencies.
  • The JPL Integration (DE422): By supplying JPL .bsp files, the tools seamlessly swap to evaluating exact NASA numerical integrations for absolute astronomical proof.
# Calculate true solar longitude, Equation of Time, and precise sunrise
caltib solar --jd-utc 2461072.5 --lat 29.65 --lon 91.11

# Compare an engine's output natively against the JPL ephemeris
caltib diag offsets --engine l3 --ephem de422

2. Calendar Design Tools

These commands automatically process modern astronomical rates and compress them into the highly optimized rational fractions, integer tables, and minimax polynomials used by the reform engines.

  • caltib rational-params: Uses continued fractions to generate optimal rational convergents for mean orbital motions, balancing precision with computational limits.
  • caltib sine-table: Generates perfectly scaled, FPU-free integer sine-tables for evaluating the Equation of Center in the L1–L3 rational engines.
  • caltib minimax & pade-arctan: Computes rigorous Chebyshev minimax odd-polynomial approximations for strictly reproducible floating-point trigonometric evaluation in the L4/L5 engines.
  • caltib float-params: Generates full-precision hex-float representations of orbital parameters to guarantee bit-for-bit reproducibility across hardware architectures.

3. The Diagnostics Suite

Once an engine is designed, the diagnostic suite visually and mathematically proves its stability across centuries. These tools were used to generate the charts seen on the Traditions and Reforms pages.

  • caltib diag analysis: Fits quadratic curves to syzygy offsets over millennia to locate the engine's "Drift Vertex" (the exact historical year its parameters were perfect) and measures its implied secular acceleration.
  • caltib diag anomaly: Plots the forward and inverse kinematic anomalies, proving that the engine's continuous orbital math successfully absorbs the Moon's orbital perturbations (Evection, Variation, etc.).
  • caltib diag equinox: Evaluates an engine's sidereal/tropical drift by plotting its true solar longitude precisely at the true Vernal Equinox over a span of 1,500 years.
  • caltib diag drift-quad: A deep-dive tool that generates scatter plots and rolling standard deviation (\(\pm 1\sigma\)) spread bands to visualize the exact moment an engine's phase drifts into chaos.

CLI & Tools Reference

Below is the automatically generated technical reference for the command-line interface and the underlying design algorithms.

Command Line Interface

caltib.cli

cmd_astro_args 
cmd_astro_args(argv: list[str]) -> int
cmd_day 
cmd_day(argv: list[str]) -> int
cmd_lunar 
cmd_lunar(argv: list[str]) -> int
cmd_solar 
cmd_solar(argv: list[str]) -> int
main 
main(argv: list[str] | None = None) -> int

Calendar Design & Parameter Optimization

caltib.design.rational_params

ParameterDefinition
name instance-attribute 
name = name
scale instance-attribute 
scale = scale
unit instance-attribute 
unit = unit
value instance-attribute 
value = value
build_parameters 
build_parameters(k: int) -> Tuple[List[ParameterDefinition], List[ParameterDefinition], List[ParameterDefinition]]

Evaluates and builds the main and appendix parameters.

get_convergents 
get_convergents(x: float, max_den: int = 100000) -> List[Tuple[int, int]]

Generates the continued fraction convergents (p, q) for a real number x. Stops when the denominator exceeds max_den or the remainder is indistinguishable from 0. Cleanly handles negative values by running the algorithm on the absolute value.

main 
main(argv: Optional[List[str]] = None) -> int
print_param_list 
print_param_list(params: List[ParameterDefinition], max_den: int)

Helper to cleanly format and print a block of parameters.

caltib.design.float_params

FloatParam
category instance-attribute 
category = category
hex_str instance-attribute 
hex_str = hex()
name instance-attribute 
name = name
unit instance-attribute 
unit = unit
value instance-attribute 
value = value
build_float_parameters 
build_float_parameters(jd_tt: float) -> List[FloatParam]

Evaluates and builds the list of floating-point parameters for the given epoch.

main 
main(argv: Optional[List[str]] = None) -> int

caltib.design.sine_tables

evaluate_relative_error 
evaluate_relative_error(table: List[int], amplitude: int) -> float

Evaluates the maximum relative error of the linearly interpolated integer table compared to the exact continuous sine function over the quarter period.

generate_sine_table 
generate_sine_table(nodes: int, amplitude: int) -> List[int]

Generates an integer table for a quarter-period of the sine function.

main 
main(argv: Optional[List[str]] = None) -> int

caltib.design.minimax_polys

main 
main(argv: Optional[List[str]] = None) -> int
optimize_minimax_odd 
optimize_minimax_odd(func: Callable, interval: Tuple[float, float], degree: int, num_points: int = 10000) -> Tuple[List[float], List[int], float]

Finds the minimax polynomial approximation using ONLY odd powers. Returns (coefficients, powers, max_error).

caltib.design.pade_arctan

main 
main(argv: Optional[List[str]] = None) -> int
optimize_minimax_pade_arctan 
optimize_minimax_pade_arctan(interval: Tuple[float, float], deg_num: int, deg_den: int, num_points: int = 5000) -> Tuple[List[float], List[int], List[float], List[int], float]

Finds the minimax rational approximation P(x)/Q(x) for arctan(x). P(x) has odd powers (x, x^3...). Q(x) has even powers (1, x^2...) with Q_0 = 1.0.

The Diagnostics Suite

caltib.diagnostics.analysis

analyze_one 
analyze_one(np, evaluator, engine_name: str, jd_start: float, jd_end: float, time_mode: str, sigma_window_years: float, filter_hours: float, apply_delta_t: bool) -> Dict[str, object]
drift_h_per_century 
drift_h_per_century(A: float, B: float, year: float) -> float

If offset(y) = A y^2 + B y + C (hours), then d/dy = 2A y + B (hours/year). Return hours/century.

find_exact_syzygy 
find_exact_syzygy(x: int, jd_guess: float, evaluator) -> float

Finds the exact JD(TT) where elongation matches the absolute tithi x. Uses a highly efficient Secant root-finder seeded by the engine's true_date.

main 
main(argv: Optional[List[str]] = None) -> int
parabola_vertex 
parabola_vertex(A: float, B: float, C: float) -> Tuple[float, float]
rolling_std 
rolling_std(y, window_pts: int)

Centered rolling std (ddof=0). Returns array with NaNs at ends.

caltib.diagnostics.drift_quad

binned_variance_fit 
binned_variance_fit(x, y, bin_years: float, min_count: int = 20)

Bin data in x (year coordinate) into bins of width bin_years. For each bin, compute variance of y. Fit quadratic to variance vs bin-center.

find_exact_syzygy 
find_exact_syzygy(x: int, jd_guess: float, evaluator) -> float

Finds the exact JD(TT) where elongation matches the absolute tithi x. Uses a highly efficient Secant root-finder seeded by the engine's true_date.

main 
main(argv: Optional[List[str]] = None) -> int
rolling_mean_std 
rolling_mean_std(x, y, window_pts: int)

Rolling mean/std on y, assuming x is sorted, using a fixed window in points. Returns (mean, std) arrays with NaN at ends (centered window).

vertex_of_parabola 
vertex_of_parabola(c2: float, c1: float, c0: float)

caltib.diagnostics.anomaly

SeriesData dataclass
anomaly_deg instance-attribute 
anomaly_deg: 'np.ndarray'
label instance-attribute 
label: str
times instance-attribute 
times: 'np.ndarray'
de422_anomaly_series 
de422_anomaly_series(np, jd_start: float, jd_end: float, step_days: float) -> SeriesData

Sample DE422 elongation (degrees), unwrap, detrend -> anomaly.

detrended_anomaly 
detrended_anomaly(np, times: 'np.ndarray', angles_deg: 'np.ndarray') -> 'np.ndarray'

Given monotone (or unwrapped) angles_deg vs times, subtract best linear fit and mean.

jd_to_datetime 
jd_to_datetime(jd: float) -> datetime.datetime

Rough conversion from JD to Gregorian datetime for plotting.

main 
main(argv: Optional[List[str]] = None) -> int
need_matplotlib 
need_matplotlib()
need_numpy 
need_numpy()
parse_engine_list 
parse_engine_list(s: str) -> List[str]
reference_anomaly_series 
reference_anomaly_series(np, jd_start: float, jd_end: float, step_days: float) -> SeriesData

Sample analytical reference ephemeris true elongation (degrees), unwrap, detrend -> anomaly. Replaces DE422 for self-contained execution without heavy ephemeris files.

tib_anomaly_series 
tib_anomaly_series(np, engine: str, jd_start: float, jd_end: float, use_month: bool = False, label: str = '') -> Optional[SeriesData]

Universal anomaly sampler. Evaluates the absolute tithi index (x) using the standardized Day Engine pure astronomical boundaries.

caltib.diagnostics.equinox

build_global_grid 
build_global_grid(np, engine: str, jd_min: float, jd_max: float)

Builds a robust, continuous interpolation grid of (jd, sun_deg_unwrapped) using the absolute continuous tithi (x) architecture.

equinox_longitudes 
equinox_longitudes(np, engine: str, years: 'np.ndarray', evaluator)
find_true_vernal_equinox 
find_true_vernal_equinox(year: int, evaluator) -> float

Finds the exact JD(TT) where true/apparent solar longitude is exactly 0 degrees. Uses a highly efficient Secant root-finder seeded by the mean equinox.

main 
main(argv: Optional[List[str]] = None) -> int
mean_vernal_equinox_jd 
mean_vernal_equinox_jd(year: int) -> float

Meeus mean vernal equinox (JDE, TT) used as a baseline guess.

normalize_pm180 
normalize_pm180(deg: float) -> float
rolling_mean 
rolling_mean(np, y, win: int)

Centered rolling mean with NaN ends. win must be odd.

caltib.diagnostics.offsets

circular_mean_mod24 
circular_mean_mod24(hours_mod24: List[float]) -> float
find_exact_syzygy 
find_exact_syzygy(x: int, jd_guess: float, evaluator) -> float

Finds the exact JD(TT) where elongation matches the absolute tithi x. Uses a highly efficient Secant root-finder seeded by the engine's time.

main 
main(argv: Optional[List[str]] = None) -> int
need_matplotlib 
need_matplotlib()
need_numpy 
need_numpy()