@typescriptify/sweph 1.0.0

package/src/SwissEph/UseCases/HouseSystems.md

@@ -0,0 +1,279 @@
+# House Systems
+
+In astrology, the **houses** are twelve divisions of the sky (or the ecliptic) as seen from a specific location on Earth at a specific time. While the zodiac signs divide the ecliptic based on the Sun's annual path, the houses divide it based on the Earth's daily rotation. Each house represents a domain of life experience (self, finances, communication, home, creativity, etc.).
+
+Because there are many different mathematical ways to divide the sky into twelve sections, there are many **house systems**. Each produces slightly (or sometimes dramatically) different house cusps. The choice of house system is one of the most debated topics in Western astrology. Vedic astrology predominantly uses Whole Sign houses.
+
+The Swiss Ephemeris supports over 20 house systems. Given a time and geographic location, it computes the twelve house cusp longitudes plus several important angles (Ascendant, MC, Vertex, etc.).
+
+---
+
+## Quick Example
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+
+// January 1, 2000 at noon UT, London
+const jd = SwissEph.julianDay(2000, 1, 1, 12);
+const geo = { longitude: -0.1276, latitude: 51.5074 };
+
+const houses = swe.houses(jd, geo, 'P'); // Placidus
+
+console.log(`Ascendant: ${houses.ascendant.toFixed(2)} deg`);
+console.log(`MC:        ${houses.mc.toFixed(2)} deg`);
+
+// House cusps are 1-indexed: cusps[1] through cusps[12]
+for (let i = 1; i <= 12; i++) {
+  console.log(`House ${String(i).padStart(2)} cusp: ${houses.cusps[i].toFixed(2)} deg`);
+}
+
+swe.close();
+```
+
+---
+
+## Detailed Examples
+
+### Comparing house systems
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 3, 20, 12); // Vernal equinox 2024
+const geo = { longitude: -73.9857, latitude: 40.7484 }; // New York
+
+const systems = [
+  { code: 'P', name: 'Placidus' },
+  { code: 'K', name: 'Koch' },
+  { code: 'E', name: 'Equal (from Asc)' },
+  { code: 'W', name: 'Whole Sign' },
+  { code: 'R', name: 'Regiomontanus' },
+  { code: 'C', name: 'Campanus' },
+  { code: 'O', name: 'Porphyry' },
+  { code: 'T', name: 'Topocentric (Polich/Page)' },
+];
+
+for (const sys of systems) {
+  const h = swe.houses(jd, geo, sys.code);
+  console.log(`\n--- ${sys.name} (${sys.code}) ---`);
+  console.log(`  Asc: ${h.ascendant.toFixed(2)}  MC: ${h.mc.toFixed(2)}`);
+  for (let i = 1; i <= 12; i++) {
+    process.stdout.write(`  H${i}: ${h.cusps[i].toFixed(1)}  `);
+    if (i % 4 === 0) process.stdout.write('\n');
+  }
+}
+
+swe.close();
+```
+
+### Whole Sign and Equal houses
+
+Whole Sign and Equal houses are the simplest systems. In Whole Sign, each house is exactly one zodiac sign (30 degrees). In Equal, each house is 30 degrees starting from the Ascendant.
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 1, 1, 0);
+const geo = { longitude: 80.27, latitude: 13.08 }; // Chennai, India
+
+// Whole Sign houses (popular in Vedic astrology)
+const ws = swe.houses(jd, geo, 'W');
+console.log('Whole Sign:');
+for (let i = 1; i <= 12; i++) {
+  // Each cusp is the start of a sign boundary
+  console.log(`  House ${i}: ${ws.cusps[i].toFixed(2)} deg`);
+}
+
+// Equal houses from Ascendant
+const eq = swe.houses(jd, geo, 'E');
+console.log('\nEqual from Ascendant:');
+for (let i = 1; i <= 12; i++) {
+  // Each cusp is exactly 30 degrees apart, starting from the Ascendant
+  console.log(`  House ${i}: ${eq.cusps[i].toFixed(2)} deg`);
+}
+
+swe.close();
+```
+
+### Accessing all the angle values
+
+Beyond the 12 house cusps, the `houses()` function returns several important astronomical/astrological points:
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 6, 21, 12);
+const geo = { longitude: -0.1276, latitude: 51.5074 }; // London
+
+const h = swe.houses(jd, geo, 'P');
+
+console.log(`Ascendant (ASC):           ${h.ascendant.toFixed(4)} deg`);
+console.log(`Midheaven (MC):            ${h.mc.toFixed(4)} deg`);
+console.log(`ARMC (sidereal time):      ${h.armc.toFixed(4)} deg`);
+console.log(`Vertex:                    ${h.vertex.toFixed(4)} deg`);
+console.log(`Equatorial Ascendant:      ${h.equatorialAscendant.toFixed(4)} deg`);
+console.log(`Co-Ascendant (Koch):       ${h.coAscendantKoch.toFixed(4)} deg`);
+console.log(`Co-Ascendant (Munkasey):   ${h.coAscendantMunkasey.toFixed(4)} deg`);
+console.log(`Polar Ascendant:           ${h.polarAscendant.toFixed(4)} deg`);
+
+swe.close();
+```
+
+### Computing houses from ARMC directly
+
+If you already know the ARMC (sidereal time in degrees), geographic latitude, and obliquity of the ecliptic, you can compute houses without a Julian Day:
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+
+// ARMC in degrees (sidereal time * 15)
+const armc = 279.50;   // example value
+const lat = 51.5074;   // London latitude
+const eps = 23.4393;   // mean obliquity of the ecliptic (approx)
+
+const h = swe.housesFromArmc(armc, lat, eps, 'P');
+console.log(`Ascendant: ${h.ascendant.toFixed(4)} deg`);
+console.log(`MC:        ${h.mc.toFixed(4)} deg`);
+
+swe.close();
+```
+
+### Getting the name of a house system
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+
+const codes = 'PKEWCRTADFGHIJLMNOQSUVXY'.split('');
+for (const code of codes) {
+  console.log(`${code} = ${swe.houseName(code)}`);
+}
+
+swe.close();
+```
+
+### Gauquelin sectors (36 sectors)
+
+The Gauquelin sector system uses 36 sectors instead of 12 houses. When you request system `'G'`, the `cusps` array contains 37 entries (cusps[1] through cusps[36]).
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 1, 1, 12);
+const geo = { longitude: 2.3522, latitude: 48.8566 }; // Paris
+
+const g = swe.houses(jd, geo, 'G');
+console.log('Gauquelin sectors (36):');
+for (let i = 1; i <= 36; i++) {
+  console.log(`  Sector ${String(i).padStart(2)}: ${g.cusps[i].toFixed(2)} deg`);
+}
+
+swe.close();
+```
+
+---
+
+## Deep Explanation
+
+### All supported house systems
+
+Each system is identified by a single-character code passed as the `system` parameter.
+
+| Code | Name                       | Description                                                                                                                                     |
+|------|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
+| `P`  | Placidus                   | The most popular system in modern Western astrology. Divides the diurnal and nocturnal semi-arcs of the ecliptic into three equal time intervals. Fails at high latitudes (>66.5 deg) where some points never rise or set. |
+| `K`  | Koch                       | Also called GOH (Geburtsort-Haeuser). Similar to Placidus in concept but uses a different mathematical approach. Also fails at high latitudes. |
+| `E`  | Equal (from Ascendant)     | Each house is exactly 30 degrees. House 1 starts at the Ascendant. Simple and unambiguous at all latitudes. The MC does not necessarily fall on the 10th cusp. |
+| `W`  | Whole Sign                 | Each house corresponds to an entire zodiac sign. House 1 is the sign containing the Ascendant (cusp = 0 deg of that sign). The oldest known house system, used in Hellenistic and Vedic astrology. |
+| `B`  | Alcabitius                 | Semi-arc system that divides the diurnal semi-arc of the Ascendant into three equal parts. Medieval European system. |
+| `C`  | Campanus                   | Divides the prime vertical (the great circle passing through the east point, zenith, west point, and nadir) into 12 equal arcs of 30 degrees, then projects them onto the ecliptic. |
+| `R`  | Regiomontanus              | Divides the celestial equator into 12 equal arcs of 30 degrees, then projects them onto the ecliptic via great circles through the north and south points of the horizon. Popular in horary astrology. |
+| `T`  | Polich/Page (Topocentric)  | Very similar to Placidus in practice but uses a different mathematical model. Claimed to be more accurate for topocentric purposes. Works at all latitudes. |
+| `A`  | Equal (from Ascendant)     | Same as `E`. Alternative code. |
+| `D`  | Equal (from MC)            | Each house is 30 degrees starting from the MC (Midheaven). The MC is exactly on the 10th cusp. |
+| `F`  | Carter poli-equatorial     | Carter's system projecting from the equator. |
+| `G`  | Gauquelin sectors          | 36 sectors (not 12 houses) used in the Gauquelin research on planetary positions in relation to the angles. |
+| `H`  | Horizon / Azimuthal        | Divides the horizon into 12 equal segments of 30 degrees, starting from the east point. |
+| `I`  | Sunshine (Treindl)         | Based on the proportion of daylight/nighttime hours. |
+| `J`  | Sunshine (alternative)     | Alternative version of the Sunshine system. |
+| `L`  | Pullen SD (sinusoidal delta) | Pullen's sinusoidal delta house system. |
+| `M`  | Morinus                    | Divides the equator into 12 equal arcs, then converts each cusp to ecliptic longitude. Does not use the horizon at all -- only depends on sidereal time. |
+| `N`  | Pullen SR (sinusoidal ratio) | Pullen's sinusoidal ratio house system. |
+| `O`  | Porphyry                   | Trisects the arcs between the four angles (ASC, IC, DSC, MC). One of the oldest quadrant-based systems. Simple and works at all latitudes. |
+| `Q`  | Pullen                     | Pullen's general house system. |
+| `S`  | Sripati                    | Used in Indian astrology. Similar to Porphyry but shifts each cusp by half a house: each house cusp is the midpoint of the corresponding Porphyry houses. |
+| `U`  | Krusinski                  | Krusinski-Pisa house system. Divides the vertical joining the Ascendant and Descendant. |
+| `V`  | Pisa                       | Variation of the Krusinski system. |
+| `X`  | Axial rotation             | Based on the Earth's axial rotation projected onto the ecliptic. |
+| `Y`  | APC houses                 | Astrological houses based on the Ascendant parallel circle. |
+
+### Cusps array indexing
+
+The `cusps` array is **1-indexed**: house cusp longitudes are in `cusps[1]` through `cusps[12]` (or `cusps[36]` for Gauquelin sectors). `cusps[0]` is unused (always 0).
+
+```typescript
+const h = swe.houses(jd, geo, 'P');
+// h.cusps[0]  -> 0 (unused)
+// h.cusps[1]  -> 1st house cusp (same as Ascendant for most systems)
+// h.cusps[2]  -> 2nd house cusp
+// ...
+// h.cusps[12] -> 12th house cusp
+```
+
+For most quadrant systems (Placidus, Koch, Regiomontanus, Campanus, Topocentric, Porphyry), `cusps[1]` equals the Ascendant and `cusps[10]` equals the MC. For Equal and Whole Sign, `cusps[10]` may differ from the MC.
+
+### The angle values explained
+
+| Field                  | Description                                                                                    |
+|------------------------|------------------------------------------------------------------------------------------------|
+| `ascendant`            | The ecliptic degree rising on the eastern horizon. The most important angle in a chart.        |
+| `mc`                   | Medium Coeli (Midheaven). The ecliptic degree at the upper meridian (highest point the ecliptic reaches). |
+| `armc`                 | ARMC = sidereal time expressed in degrees (sidereal time in hours * 15). Used internally for house position calculations. |
+| `vertex`               | The ecliptic degree on the prime vertical in the west. Used in synastry and as a "fated point." |
+| `equatorialAscendant`  | The Ascendant calculated on the celestial equator (sometimes called the "East Point").         |
+| `coAscendantKoch`      | Co-Ascendant as defined by Koch.                                                               |
+| `coAscendantMunkasey`  | Co-Ascendant as defined by Munkasey.                                                           |
+| `polarAscendant`       | The Ascendant of the polar opposite latitude (also called the "Anti-Vertex").                  |
+
+### High-latitude issues
+
+**Placidus and Koch** systems fail at latitudes beyond approximately 66.5 degrees (within the Arctic or Antarctic circles). At these latitudes, some ecliptic degrees never rise or set, making it impossible to compute the time-based house divisions these systems require. The engine will return results but they may be unreliable.
+
+Systems that work at **all latitudes** include:
+- Equal (`E`, `A`, `D`)
+- Whole Sign (`W`)
+- Porphyry (`O`)
+- Morinus (`M`)
+- Campanus (`C`)
+- Regiomontanus (`R`)
+- Topocentric/Polich-Page (`T`) -- designed to handle extreme latitudes
+- Axial rotation (`X`)
+- APC (`Y`)
+
+### Geographic position convention
+
+- **Longitude**: Positive = east, negative = west. For example, New York is about -74 degrees, Tokyo is about +139.7 degrees.
+- **Latitude**: Positive = north, negative = south. For example, Sydney is about -33.9 degrees.
+- **Altitude**: In meters above sea level. Optional (defaults to 0). Only affects topocentric corrections.
+
+### Choosing a house system
+
+There is no universally "correct" house system. The choice depends on your astrological tradition:
+
+- **Modern Western astrology**: Placidus (`P`) is by far the most popular, followed by Koch (`K`) and Equal (`E`).
+- **Traditional/Hellenistic astrology**: Whole Sign (`W`) is the historically oldest system and has seen a major revival.
+- **Horary astrology**: Regiomontanus (`R`) is traditional for horary work.
+- **Vedic/Indian astrology (Jyotish)**: Whole Sign (`W`) or Sripati (`S`).
+- **Uranian/Hamburg School**: Often uses Meridian or equal systems.
+- **Research (Gauquelin)**: The Gauquelin sector system (`G`) with 36 sectors.
+
+When in doubt, Placidus is the safe default for Western astrology, and Whole Sign for Vedic or Hellenistic work.

package/src/SwissEph/UseCases/LunarEclipse.md

@@ -0,0 +1,326 @@
+# Lunar Eclipses
+
+A **lunar eclipse** occurs when the Earth passes between the Sun and the Moon, casting Earth's shadow onto the Moon. Unlike solar eclipses, which are only visible from a narrow path on Earth, a lunar eclipse is visible from anywhere on the night side of the planet where the Moon is above the horizon. This makes lunar eclipses far more commonly observed than solar eclipses.
+
+Lunar eclipses can only happen during a Full Moon, when the Sun and Moon are on opposite sides of the Earth. But just as with solar eclipses, the Moon's orbit is tilted about 5 degrees from the ecliptic, so most Full Moons pass above or below Earth's shadow. An eclipse only occurs when the Full Moon is near one of its orbital nodes.
+
+During a total lunar eclipse, the Moon does not disappear entirely. Instead, it typically turns a deep red or copper color -- sometimes called a "Blood Moon." This happens because Earth's atmosphere bends (refracts) sunlight around the planet's edge, and the atmosphere filters out shorter blue wavelengths while allowing longer red wavelengths to reach the Moon.
+
+---
+
+## Quick Example
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+
+// Find the next lunar eclipse after January 1, 2025
+const jd = SwissEph.julianDay(2025, 1, 1, 0);
+const eclipse = swe.lunarEclipseGlobal(jd);
+
+const date = SwissEph.fromJulianDay(eclipse.maximum);
+console.log(`Next lunar eclipse: ${date.year}-${date.month}-${date.day}`);
+console.log(`Maximum at JD: ${eclipse.maximum.toFixed(6)}`);
+
+swe.close();
+```
+
+---
+
+## Detailed Examples
+
+### The 2025 March 14 total lunar eclipse
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_ECL_TOTAL } from '../../constants';
+
+const swe = new SwissEph();
+
+// Search for the next total lunar eclipse after 2025-01-01
+const jd = SwissEph.julianDay(2025, 1, 1, 0);
+const eclipse = swe.lunarEclipseGlobal(jd, SE_ECL_TOTAL);
+
+const fmt = (jd: number) => {
+  if (jd === 0) return '(n/a)';
+  const d = SwissEph.fromJulianDay(jd);
+  const h = Math.floor(d.hour);
+  const m = Math.floor((d.hour - h) * 60);
+  return `${d.year}-${String(d.month).padStart(2,'0')}-${String(d.day).padStart(2,'0')} ${h}:${String(m).padStart(2,'0')} UT`;
+};
+
+console.log(`Total lunar eclipse`);
+console.log(`  Maximum:          ${fmt(eclipse.maximum)}`);
+console.log(`  Penumbral begin:  ${fmt(eclipse.penumbralBegin)}`);
+console.log(`  Partial begin:    ${fmt(eclipse.partialBegin)}`);
+console.log(`  Total begin:      ${fmt(eclipse.totalBegin)}`);
+console.log(`  Total end:        ${fmt(eclipse.totalEnd)}`);
+console.log(`  Partial end:      ${fmt(eclipse.partialEnd)}`);
+console.log(`  Penumbral end:    ${fmt(eclipse.penumbralEnd)}`);
+// 2025-03-14, maximum around 06:58 UT
+
+swe.close();
+```
+
+### Eclipse attributes: magnitude and shadow sizes
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+
+const jd = SwissEph.julianDay(2025, 1, 1, 0);
+const eclipse = swe.lunarEclipseGlobal(jd);
+
+// Get detailed attributes at maximum
+const how = swe.lunarEclipseHow(eclipse.maximum);
+
+console.log(`Eclipse type flags: ${how.type}`);
+console.log(`Umbral magnitude:    ${how.umbraMagnitude.toFixed(4)}`);
+console.log(`Penumbral magnitude: ${how.penumbraMagnitude.toFixed(4)}`);
+console.log(`Moon diameter:       ${how.moonDiameter.toFixed(2)} arc-minutes`);
+console.log(`Umbra diameter:      ${how.umbraDiameter.toFixed(2)} arc-minutes`);
+console.log(`Penumbra diameter:   ${how.penumbraDiameter.toFixed(2)} arc-minutes`);
+console.log(`Sun dist from node:  ${how.sunDistanceFromNode.toFixed(2)} deg`);
+
+// For the 2025 Mar 14 eclipse, umbral magnitude is about 1.176
+// (greater than 1.0 = total eclipse; the Moon fits entirely inside the umbra)
+
+swe.close();
+```
+
+### Local visibility: is the eclipse visible from my city?
+
+Use `lunarEclipseLocal` to find when the Moon rises and sets during the eclipse at your location, which tells you how much of the eclipse you can observe.
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+
+const jd = SwissEph.julianDay(2025, 1, 1, 0);
+
+// Check visibility from different cities
+const cities = [
+  { name: 'New York',  geo: { longitude: -74.006, latitude: 40.713 } },
+  { name: 'London',    geo: { longitude: -0.128,  latitude: 51.507 } },
+  { name: 'Tokyo',     geo: { longitude: 139.692, latitude: 35.690 } },
+  { name: 'Sydney',    geo: { longitude: 151.209, latitude: -33.868 } },
+];
+
+const fmt = (jd: number) => {
+  if (jd === 0) return '(below horizon)';
+  const d = SwissEph.fromJulianDay(jd);
+  const h = Math.floor(d.hour);
+  const m = Math.floor((d.hour - h) * 60);
+  return `${h}:${String(m).padStart(2,'0')} UT`;
+};
+
+for (const city of cities) {
+  const local = swe.lunarEclipseLocal(jd, city.geo);
+  const date = SwissEph.fromJulianDay(local.maximum);
+  console.log(`\n${city.name} (${date.year}-${date.month}-${date.day}):`);
+  console.log(`  Maximum:         ${fmt(local.maximum)}`);
+  console.log(`  Moon rise:       ${fmt(local.moonRise)}`);
+  console.log(`  Moon set:        ${fmt(local.moonSet)}`);
+  console.log(`  Umbra magnitude: ${local.attributes.umbraMagnitude.toFixed(3)}`);
+
+  // Check if the full eclipse is visible
+  if (local.moonRise === 0 || local.moonRise < local.penumbralBegin) {
+    console.log(`  Full eclipse visible (Moon is up the entire time)`);
+  } else {
+    console.log(`  Partial visibility (Moon rises/sets during eclipse)`);
+  }
+}
+
+swe.close();
+```
+
+### Filtering by eclipse type
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_ECL_TOTAL, SE_ECL_PARTIAL, SE_ECL_PENUMBRAL } from '../../constants';
+
+const swe = new SwissEph();
+
+// Find the next penumbral lunar eclipse
+let jd = SwissEph.julianDay(2024, 1, 1, 0);
+const penumbral = swe.lunarEclipseGlobal(jd, SE_ECL_PENUMBRAL);
+const d1 = SwissEph.fromJulianDay(penumbral.maximum);
+console.log(`Next penumbral: ${d1.year}-${d1.month}-${d1.day}`);
+
+// Find the next partial lunar eclipse
+const partial = swe.lunarEclipseGlobal(jd, SE_ECL_PARTIAL);
+const d2 = SwissEph.fromJulianDay(partial.maximum);
+console.log(`Next partial:   ${d2.year}-${d2.month}-${d2.day}`);
+
+// Find the next total lunar eclipse
+const total = swe.lunarEclipseGlobal(jd, SE_ECL_TOTAL);
+const d3 = SwissEph.fromJulianDay(total.maximum);
+console.log(`Next total:     ${d3.year}-${d3.month}-${d3.day}`);
+
+swe.close();
+```
+
+### Listing all lunar eclipses over a period
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_ECL_TOTAL, SE_ECL_PARTIAL, SE_ECL_PENUMBRAL } from '../../constants';
+
+const swe = new SwissEph();
+
+let jd = SwissEph.julianDay(2024, 1, 1, 0);
+const endJd = SwissEph.julianDay(2028, 1, 1, 0);
+
+const typeName = (flags: number): string => {
+  if (flags & SE_ECL_TOTAL) return 'Total';
+  if (flags & SE_ECL_PARTIAL) return 'Partial';
+  if (flags & SE_ECL_PENUMBRAL) return 'Penumbral';
+  return 'Unknown';
+};
+
+console.log('Lunar eclipses 2024-2027:');
+while (jd < endJd) {
+  const ecl = swe.lunarEclipseGlobal(jd);
+  if (ecl.maximum > endJd) break;
+
+  const date = SwissEph.fromJulianDay(ecl.maximum);
+  const how = swe.lunarEclipseHow(ecl.maximum);
+
+  console.log(
+    `  ${date.year}-${String(date.month).padStart(2,'0')}-${String(date.day).padStart(2,'0')}` +
+    `  ${typeName(ecl.type).padEnd(10)}` +
+    `  umbra mag: ${how.umbraMagnitude.toFixed(3)}`
+  );
+
+  jd = ecl.maximum + 1;
+}
+
+swe.close();
+```
+
+### Searching backward in time
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+
+// Find the most recent lunar eclipse before 2025-01-01
+const jd = SwissEph.julianDay(2025, 1, 1, 0);
+const eclipse = swe.lunarEclipseGlobal(jd, 0, true); // backward = true
+
+const date = SwissEph.fromJulianDay(eclipse.maximum);
+console.log(`Most recent lunar eclipse: ${date.year}-${date.month}-${date.day}`);
+
+swe.close();
+```
+
+---
+
+## Deep Explanation
+
+### Eclipse types
+
+| Type | Constant | Description |
+|------|----------|-------------|
+| **Total** | `SE_ECL_TOTAL` (4) | The Moon passes completely into Earth's umbral shadow. The entire lunar disc turns dark/red. Umbral magnitude > 1.0. |
+| **Partial** | `SE_ECL_PARTIAL` (16) | Only part of the Moon enters the umbra. Part of the Moon remains bright. Umbral magnitude between 0.0 and 1.0. |
+| **Penumbral** | `SE_ECL_PENUMBRAL` (64) | The Moon passes only through Earth's penumbral shadow. The dimming is subtle and often hard to notice visually. Umbral magnitude < 0.0. |
+
+### Umbra and penumbra
+
+Earth casts two nested shadows into space:
+
+- **Umbra**: The dark inner cone of shadow where all direct sunlight is blocked. If you were standing on the Moon inside the umbra, you would see Earth completely blocking the Sun.
+- **Penumbra**: The lighter outer shadow where only part of the Sun is blocked. From inside the penumbra, you would see Earth covering part of the Sun but not all of it.
+
+The umbra is about 2.5 times the Moon's diameter at the Moon's distance, which is why total lunar eclipses are possible and can last over an hour.
+
+### Understanding magnitude
+
+For lunar eclipses, **magnitude** has a specific meaning:
+
+- **Umbral magnitude** (`umbraMagnitude`): How deeply the Moon penetrates into the umbra, measured as a fraction of the Moon's diameter. A value of 0.0 means the Moon just touches the umbral edge. A value of 1.0 means the Moon's edge just reaches the center of the umbra (the entire Moon is inside). Values greater than 1.0 mean the Moon is well inside the umbra (deeper totality). For the 2025 Mar 14 eclipse, the umbral magnitude is about 1.178.
+
+- **Penumbral magnitude** (`penumbraMagnitude`): Same concept but for the penumbra. Always larger than the umbral magnitude.
+
+A negative umbral magnitude means the Moon does not enter the umbra at all (purely penumbral eclipse).
+
+### The Danjon scale
+
+Astronomers use the **Danjon scale** (L value) to classify the visual appearance of a total lunar eclipse:
+
+| L | Description |
+|---|-------------|
+| 0 | Very dark eclipse; Moon almost invisible at mid-totality |
+| 1 | Dark eclipse; gray or brownish color; details hard to see |
+| 2 | Deep red or rust-colored; very dark central shadow with brighter edge |
+| 3 | Brick-red; umbral shadow usually has a bright or yellow rim |
+| 4 | Very bright copper-red or orange; umbral shadow has a bluish, very bright rim |
+
+The Danjon value cannot be predicted by ephemeris calculations alone -- it depends on atmospheric conditions, particularly volcanic aerosols. Major volcanic eruptions (like Pinatubo in 1991) can produce very dark eclipses (L=0) for several years afterward. The Swiss Ephemeris predicts *when* and *where* eclipses occur, but not their color.
+
+### Why the Moon turns red
+
+During totality, the only light reaching the Moon has been refracted (bent) through Earth's atmosphere. Earth's atmosphere acts like a lens that bends sunlight around the planet's edge and filters it:
+
+1. Short-wavelength light (blue, violet) is scattered away by the atmosphere (the same Rayleigh scattering that makes our sky blue).
+2. Long-wavelength light (red, orange) passes through more easily and is bent toward the Moon.
+
+The result is that the Moon is illuminated by the combined light of all the sunrises and sunsets happening around Earth's edge at that moment. If you were standing on the Moon during a total lunar eclipse, you would see Earth surrounded by a bright red ring.
+
+### Eclipse timeline (the `lunarEclipseGlobal` result)
+
+| Field | Description |
+|-------|-------------|
+| `penumbralBegin` | Moon enters the penumbra. Very subtle dimming begins. |
+| `partialBegin` | Moon enters the umbra. A dark "bite" appears on the Moon's edge. |
+| `totalBegin` | Moon is completely inside the umbra. Totality begins; Moon turns red. |
+| `maximum` | Mid-eclipse. The Moon is deepest inside the shadow. |
+| `totalEnd` | Moon begins to exit the umbra. Totality ends. |
+| `partialEnd` | Moon completely exits the umbra. Only penumbral shading remains. |
+| `penumbralEnd` | Moon exits the penumbra entirely. Eclipse is over. |
+
+For a partial eclipse, `totalBegin` and `totalEnd` are 0 (totality never occurs).
+For a penumbral eclipse, `partialBegin`, `partialEnd`, `totalBegin`, and `totalEnd` are all 0.
+
+### The `lunarEclipseHow` result
+
+| Field | Description |
+|-------|-------------|
+| `type` | Bitmask of eclipse type flags |
+| `umbraMagnitude` | Fraction of Moon's diameter inside the umbra (>1.0 = total) |
+| `penumbraMagnitude` | Fraction of Moon's diameter inside the penumbra |
+| `moonDiameter` | Apparent diameter of the Moon (arc minutes) |
+| `umbraDiameter` | Apparent diameter of Earth's umbral shadow at the Moon's distance (arc minutes) |
+| `penumbraDiameter` | Apparent diameter of Earth's penumbral shadow (arc minutes) |
+| `sunDistanceFromNode` | Sun's angular distance from the nearest lunar node (degrees) |
+
+### Differences from solar eclipses
+
+| Aspect | Solar Eclipse | Lunar Eclipse |
+|--------|--------------|---------------|
+| **When** | New Moon | Full Moon |
+| **What happens** | Moon blocks Sun | Earth's shadow covers Moon |
+| **Visibility** | Narrow path (100-200 km wide) | Entire night hemisphere |
+| **Duration of totality** | Up to ~7 minutes | Up to ~1 hour 47 minutes |
+| **Frequency** | 2-5 per year globally | 0-3 per year |
+| **Danger** | Never look at Sun without filter | Safe to watch with naked eye |
+| **Timing** | Different for every location | Same UT time for all observers |
+
+### Local visibility considerations
+
+Unlike solar eclipses, the timing of a lunar eclipse (in UT) is the same for everyone -- the Moon enters and exits Earth's shadow at the same absolute moment. The question is whether the Moon is above the horizon at your location during that time.
+
+The `lunarEclipseLocal` result includes `moonRise` and `moonSet` times, which tell you when the Moon is above the horizon at your location. If the Moon rises after penumbral begin or sets before penumbral end, you will miss part of the eclipse.
+
+### Tips
+
+- When searching for eclipses, advance `jd` by at least 1 day past the previous result to find the next one.
+- A `lunarEclipseHow` call without a `geo` parameter gives the eclipse attributes as seen from the geocenter (Earth's center). With a `geo` parameter, it accounts for the observer's location, which can slightly affect the apparent magnitude since the Moon's position in the umbra shifts slightly with parallax.
+- Penumbral eclipses are very subtle visually. Most observers cannot notice a penumbral eclipse unless the penumbral magnitude exceeds about 0.7.
+- The `sunDistanceFromNode` value indicates how close the geometry is to producing a central eclipse. Smaller values mean deeper eclipses.