%unimsg 0 astronomy/solar-system/v1

-- The planets of the solar system: what they are, and where they will be.
--
-- The second half of that sentence is why this document exists. Positions are
-- not stored here and could not be: a position is a function of time, and
-- there are infinitely many times. What is stored is the orbit — six numbers
-- per body — together with the procedure that turns six numbers and an instant
-- into a place.
--
-- That is the oldest idea in this project and the first document to use it. A
-- document need not contain an answer if it contains the formula and the
-- arguments. The reader supplies a machine; the document supplies the rule.
-- Nothing here is executed by reading it, and nothing needs to be: the
-- procedure is inert data until something chooses to act on it.

solar-system @sol/v1 {
  title  "Orbital elements and physical properties of the eight planets"
  centre "the Sun"
  frame  "heliocentric, J2000 ecliptic"

  provenance {
    elements-from "JPL approximate orbital elements, epoch J2000"
    valid-over    "1800 to 2050"
    accuracy      "Approximate by construction: these are mean elements fitted
                   for a two-century window, not an ephemeris. Positions
                   computed from them are good to arcminutes for the inner
                   planets and worse for the outer ones."
    why-that-is-fine "The document is a demonstration that a formula can
                      travel with its arguments. An ephemeris would be a larger
                      table and the same idea."
    precision-note "Values are given to the precision the source publishes.
                    Trailing digits are not padded, because in this format a
                    trailing zero is a claim about significance."
  }

  -- ===================================================================
  -- THE ORBITS
  -- ===================================================================

  -- Six elements fix an orbit; the seventh column is the period, which is
  -- implied by the first but published alongside it and kept here so the
  -- document can check itself further down.
  elements [
    | body                a-au           e     incl-deg      node-deg      peri-long-deg     mean-long-deg   period-days
    | "Mercury"   0.38709927  0.20563593    7.004979   48.33076593   77.45779628  252.25032350      87.969
    | "Venus"     0.72333566  0.00677672    3.394676   76.67984255  131.60246718  181.97909950     224.701
    | "Earth"     1.00000261  0.01671123   -0.000015    0.00000000  102.93768193  100.46457166     365.256
    | "Mars"      1.52371034  0.09339410    1.849691   49.55953891  -23.94362959   -4.55343205     686.980
    | "Jupiter"   5.20288700  0.04838624    1.304397  100.47390909   14.72847983   34.39644051    4332.589
    | "Saturn"    9.53667594  0.05386179    2.485992  113.66242448   92.59887831   49.95424423   10759.220
    | "Uranus"   19.18916464  0.04725744    0.772638   74.01692503  170.95427630  313.23810451   30685.400
    | "Neptune"  30.06992276  0.00859048    1.770043  131.78422574   44.96476227  -55.12002969   60189.000
  ]

  units {
    a-au          "astronomical units"
    e             "dimensionless"
    incl-deg      "degrees from the ecliptic"
    node-deg      "degrees, longitude of the ascending node"
    peri-long-deg "degrees, longitude of perihelion"
    mean-long-deg "degrees, mean longitude at the epoch"
    period-days   "days"
  }

  -- ===================================================================
  -- THE BODIES
  -- ===================================================================

  physical [
    | body            mass-kg  radius-km  rotation-days  axial-tilt-deg
    | "Mercury"   3.3011e23     2439.7   58.64600     0.03
    | "Venus"     4.8675e24     6051.8 -243.02500   177.36
    | "Earth"     5.9724e24     6378.1    0.99727    23.44
    | "Mars"      6.4171e23     3396.2    1.02596    25.19
    | "Jupiter"   1.8982e27    71492.0    0.41354     3.13
    | "Saturn"    5.6834e26    60268.0    0.44401    26.73
    | "Uranus"     8.681e25    25559.0   -0.71833    97.77
    | "Neptune"   1.0241e26    24764.0    0.67125    28.32
  ]

  physical-units {
    mass-kg        "kilograms"
    radius-km      "equatorial radius, kilometres"
    rotation-days  "sidereal rotation period; negative is retrograde"
    axial-tilt-deg "degrees"
  }

  retrograde-note "Venus and Uranus carry negative rotation periods. The sign
                   is the datum, not a formatting accident — they turn the
                   other way."

  -- ===================================================================
  -- WHERE A PLANET IS
  -- ===================================================================

  -- The generator. Given a body's elements and an instant, these steps yield a
  -- heliocentric position. They are written as data: a reader that has sine,
  -- cosine and a loop can carry them out, and one that has not can still read
  -- and present them.
  --
  -- Nothing is resolved at read time. This block is a description of a
  -- computation, not a computation.

  position-of !formula/procedure {
    yields  "heliocentric ecliptic coordinates, in astronomical units"
    given   [ "a row of `elements`", "an instant, as days from J2000" ]
    needs   [ :sin, :cos, :sqrt, :atan2, :iteration ]

    steps [
      | n  name                 rule
      | 1  "mean anomaly"       "M = mean-long-deg + 360 x t / period-days - peri-long-deg, reduced to [-180, 180)"
      | 2  "eccentric anomaly"  "solve M = E - e x sin(E) for E"
      | 3  "in-plane position"  "x = a x (cos(E) - e);  y = a x sqrt(1 - e^2) x sin(E)"
      | 4  "to the ecliptic"    "rotate x and y by the argument of perihelion, then the inclination, then the node"
  ]

    solving-step-2 {
      method     :newton-raphson
      iteration  "E' = E - (E - e x sin(E) - M) / (1 - e x cos(E))"
      start-from "E = M"
      until      "the change is smaller than the precision wanted"
      why-iterate "Kepler's equation has no closed-form solution in elementary
                   functions. That is a property of the problem, and a document
                   that pretended otherwise would be encoding a wish."
      terminates "For e < 1 the iteration converges, and every orbit here has
                  e below 0.21. A reader should still bound it: a document is
                  not trusted to terminate, and this one is only asserting that
                  it does."
    }

    what-this-is-not "An ephemeris. Perturbations between planets are ignored,
                      so this is a two-body approximation per planet — good
                      enough to place a dot on a diagram, not to aim anything."
  }

  -- ===================================================================
  -- THE DOCUMENT CHECKING ITSELF
  -- ===================================================================

  -- Kepler's third law relates the two columns that were given independently,
  -- so the document carries a test of its own data rather than asking to be
  -- believed. A reader that can multiply can verify the table it was handed.
  self-check !formula/assertion {
    law       "Kepler's third: the square of the period is proportional to the
               cube of the semi-major axis"
    predicate "(period-days / 365.256) ^ 2 / a-au ^ 3 = 1, within 0.002"
    holds-for :every-row
    measured  "1.0000 for the four inner planets; 0.9987 to 1.0004 for the
               outer four, the drift being the mean elements rather than the
               physics"
    why-here "A table of numbers is an assertion. A table of numbers with a law
              they must satisfy is a checkable one, and this format is meant to
              carry the second kind."
  }

  -- ===================================================================
  -- WHAT A GENERIC STORE CAN AND CANNOT DO WITH THIS
  -- ===================================================================

  ordering-note {
    can "Order bodies by any single published quantity — mass, radius, period,
         distance — by giving a descriptor with a numeric ordering and a path
         to the column. The store needs no knowledge of astronomy to do it."

    cannot "Order bodies by computed position. The store's formula grammar has
            arithmetic and no trigonometry, and no iteration, so Kepler's
            equation is outside it — deliberately. A grammar that could express
            step 2 would be a programming language, and the store would be
            running it during a write."

    the-shape-of-that "The same boundary the presentation surface has: a reader
                       acts on what arrives at a level it can already act on.
                       Elements are such a level for ordering by mass, and are
                       not for ordering by position."
  }
}