Documentation

How the engine works

The system is a deterministic computation pipeline. It takes four inputs — date of birth, time of birth, birth place, gender — and one target date, and produces a ranked list of attire ensembles with a decomposable score for each. Identical inputs produce byte-identical outputs for a given engine version. There is no randomness, no machine learning, and no manual curation in the scoring path. This page documents each stage of the pipeline: the method used, the reason the stage exists, its accuracy where measurable, and the source of every rule.

Processing pipeline

1. 1

   Time normalisation

   Method. The local birth time is converted to UTC using the IANA timezone database entry for the birth city, including historical offset and daylight-saving rules. The UTC instant is then expressed as a Julian Day number, the continuous time axis used in astronomical computation.

   Rationale. All planetary positions, the ascendant, and the dasha timeline are functions of this single instant. Timezone errors propagate to every downstream result, so the conversion uses the standard database rather than fixed offsets.

   Source. IANA timezone database; Julian Day convention.

2. 2

   Ephemeris computation

   Method. Planetary longitudes are computed, not read from tables. The Moon uses a truncated ELP-2000/82 series (32 principal terms plus planetary perturbations), the Sun the standard VSOP87-derived solar theory, and the five classical planets Kepler-orbit solutions from the JPL approximate elements, valid 1800–2050. Rahu is the mean lunar node; Ketu is its antipode.

   Rationale. Computing positions from published series makes every figure reproducible by third parties using the same formulas. No proprietary or opaque data source is involved.

   Accuracy. Moon ±0.003°, Sun ±0.01°, planets within a few arc-minutes over 1800–2050. The smallest unit consumed by the system is the nakshatra pada at 3°20′ (200′); the worst-case planetary error is roughly two orders of magnitude smaller. The mean node is the convention used by most published panchangams; the true node can differ by up to ±1.7°.

   Source. Meeus, Astronomical Algorithms, 2nd ed. — ch. 47 (lunar series), ch. 25 (solar theory), ch. 12 (sidereal time); Standish (JPL), Approximate Positions of the Planets.

3. 3

   Chart computation

   Method. Tropical longitudes are converted to sidereal using the Lahiri (Chitrapaksha) ayanamsa: 23.85236° at J2000.0, advancing at the general precession rate of 50.2719″ per Julian year. From the sidereal positions the engine derives the lagna (from local sidereal time and the birth coordinates), Moon sign, nakshatra, and pada. If the ascendant falls within 2.5° of a sign boundary, the output carries a low-confidence flag, because a birth-time error of roughly ten minutes can change the lagna.

   Rationale. Lahiri is the ayanamsa standard of Indian calendrics and the reference used by most published panchangams, which keeps the engine's output comparable to printed sources. The confidence flag exists because the natal pillar (40% of every score) depends on the lagna; the output records this uncertainty instead of suppressing it.

   Source. Lahiri ayanamsa — Government of India Calendar Reform Committee standard; ascendant formula from Meeus ch. 12.

4. 4

   Functional classification of the grahas

   Method. Each of the seven classical planets is classified as functional benefic, malefic, neutral, or yogakaraka for the user's lagna, according to the house-lordship rules of Brihat Parashara Hora Shastra. The classification differs by ascendant: Saturn is the yogakaraka for Tula lagna and a malefic for Karka lagna; Jupiter is a benefic for Karka and a malefic for Tula. Dignity is then applied from the birth chart: exaltation adds +0.20, own sign +0.15, debilitation −0.20 on the engine's −1…+1 affinity scale. Rahu and Ketu receive a fixed negative base and are never prescribed.

   Rationale. Fixed sign-to-colour mappings ("Libra wears blue") have no basis in the Parashara system, where a planet's auspiciousness is a function of the houses it rules from the ascendant. Lagna-dependent classification is the documented classical method and is the reason two charts a day apart can receive opposite recommendations.

   Source. Brihat Parashara Hora Shastra, lagna-wise auspiciousness chapters; standard exaltation/debilitation tables (Sun exalted in Mesha, Moon in Vrishabha, Mars in Makara, Mercury in Kanya, Jupiter in Karka, Venus in Meena, Saturn in Tula).

5. 5

   Dasha and gochara

   Method. Two time-dependent layers are computed for the target date. (a) The Vimshottari dasha: the 120-year period system seeded by the Moon's position within its birth nakshatra, yielding the current mahadasha and antardasha lords. (b) Gochara: each planet's current house counted from the natal Moon sign, scored from the classical transit tables. Named configurations are detected explicitly: Sade Sati (Saturn in the 12th, 1st, or 2nd from the Moon), Ashtama Shani (8th), Ardhashtama (4th), and Guru Balam (Jupiter in 2, 5, 7, 9, or 11).

   Rationale. The natal chart is constant; these two layers are what make the output date-dependent. The dasha identifies the period lord whose themes are weighted; the gochara tables grade each planet's current station. Both are computed from the same ephemeris as the birth chart.

   Source. Vimshottari dasha — BPHS; gochara-phala house tables — Brihat Samhita / muhurta literature.

6. 6

   Daily favorability f(g)

   Method. The preceding layers reduce to one signed value per planet per day, f(g) ∈ [−1, +1]: 55% from the static part (functional nature + natal dignity + dasha-lord adjustment) and 45% from the transit part (gochara house score + transit dignity + named configurations). Negative values propagate through every subsequent sum unclamped. The polarity convention is amplification: wearing a planet's colour or dravya strengthens that planet. Consequently items keyed to a planet with f(g) ≤ −0.25 are excluded from ranking and listed in the avoid output with the triggering rule named. During Sade Sati and Ashtama Shani this exclusion applies to Saturn regardless of his natal standing.

   Rationale. The amplification convention follows the classical gem-prescription doctrine: ratnas are prescribed for functional benefics only, because the stone strengthens its graha; the documented remedies for an afflicting planet are dana and japa, not wearing its substances. The engine applies one convention uniformly because the two traditional schools (amplify vs. pacify) produce opposite outputs, and an engine that mixes them is not reproducible.

   Source. Classical ratna-prescription doctrine; remedial (dana/japa) tradition for afflicting grahas.

7. 7

   Item vectors

   Method. The catalogue is 12 shirt colours, 6 trouser colours, and 7 attars. Each item is a weighted vector over the nine grahas and the five elements; weights sum to 1. The planetary assignments follow the varna statements of the classical texts (Sun copper-red, Moon white, Mars blood-red, Mercury grass-green, Jupiter yellow, Venus white/variegated, Saturn dark/indigo) and the dravya assignments of the Kannauj attar tradition (vetiver and oud to Saturn, rose and sandalwood to Venus–Moon, kesar to Jupiter–Sun, jasmine and lotus to the Moon). The trouser palette is restricted to six neutrals. All fabric is cotton; fabric selection is out of scope by design.

   Rationale. Vector representation allows resonance to be computed rather than asserted: a colour's value on a given day is the dot product of its vector with that day's f(g) values. The neutral trouser palette follows the traditional structure of Indian dress, in which the lower garment (veshti, antariya) is unbleached or white and colour is carried by the upper garment; in the Kalapurusha mapping the lower limbs belong to Saturn's signs, which places the lower garment in the earth/stability register.

   Source. Brihat Jataka ch. II (graha varnas); Kannauj attar dravya tradition; veshti/antariya dress convention; Kalapurusha anga assignments.

8. 8

   Ensemble enumeration and scoring

   Method. All combinations of shirt × trouser × attar are enumerated — 504 before exclusions. Two filters apply: a fixed two-pair aesthetic denylist, and the affliction rule from step 6. Each remaining ensemble is blended into a single vector at 50% shirt, 30% attar, 20% trouser, and scored against four pillars (table below). The four pillar values are rounded to one decimal and the total is the rounded sum, so the printed breakdown always sums to the printed score. Ties are broken lexicographically on the ensemble identifier.

   Rationale. Exhaustive enumeration with full output makes the ranking auditable: the engine returns every scored ensemble, not only the winner. The 50/30/20 blend implements the uttariya principle — the upper garment is the primary carrier — with fragrance weighted above the lower garment as the more proximate dravya.

   Source. Engine specification v1.0.0; all weights recorded in a single versioned constants file.

9. 9

   Panchanga at sunrise

   Method. Sunrise at the user's current location is computed with the NOAA solar position algorithm, and the panchanga is evaluated at that instant: vara (weekday lord), tithi (from solar–lunar elongation in 12° steps), the Moon's nakshatra, and nitya-yoga (from the sum of solar and lunar longitudes). Tarabala is the nine-fold count from the janma nakshatra to the day's nakshatra. Chandrashtama — the Moon transiting the 8th sign from the natal Moon — multiplies the panchanga pillar by 0.4.

   Rationale. The Hindu civil day begins at sunrise, and published panchangams state tithi and nakshatra as of sunrise; evaluating at the same instant keeps the engine's panchanga directly comparable to printed sources. Tarabala and Chandrashtama are standard muhurta-grade day filters.

   Accuracy. NOAA sunrise: approximately ±1 minute at Indian latitudes.

   Source. NOAA solar calculator algorithm; panchanga definitions from standard calendric practice; Tarabala cycle from the muhurta literature.

10. 10

    Seasonal and constitutional layer

    Method. The ritu (classical season) is derived from the Sun's sidereal longitude in 60° segments. Each ritu has a documented aggravated dosha (Varsha and Grishma → Vata, Sharad → Pitta, Vasanta/Hemanta/Shishira → Kapha), further weighted by the day's adverse transits through standard graha–dosha correlations. Each ensemble's five-element blend is scored for its capacity to pacify the aggravated dosha, plus a harmony term with the element of the natal Moon sign.

    Rationale. Ritucharya — adjusting regimen by season — is a documented layer of the classical Ayurveda corpus, and the graha–dosha correlations (Saturn–Vata, Sun/Mars–Pitta, Jupiter–Kapha, etc.) are the standard correspondence used in medical astrology. This pillar is what gives the wellness component daily and seasonal variation.

    Source. Ritucharya chapters of the Ayurveda corpus (Charaka/Ashtanga Hridaya tradition); Siddha aimpootham correspondences; standard graha–dosha correlations.

11. 11

    Output and presentation policy

    Method. The engine returns the complete ranked list with per-pillar breakdowns, the nine f(g) values with their triggering rules, an avoid list with reasons, and the day's context (panchanga, dasha, gochara, ritu). A separate presentation layer applies the product policy: a 70-point threshold, at most three Alignment Sets per 90-day window selected by cumulative quality, exact wear dates per set, and a fixed no-alignment message when nothing qualifies. The engine itself never filters; thresholds and capsules exist only in the presentation layer.

    Rationale. Separating computation from policy keeps the scoring auditable and lets presentation rules change without touching the mathematics. Zero qualifying days is a valid output state and is reported as such.

    Source. Engine output specification; capsule policy: threshold 70, maximum 3 sets / 90 days.

Scoring model

Maximum score 100. The pillar weights are fixed and recorded in the versioned constants file.

Score bands: 90–100 exceptional · 80–89 strong · 70–79 moderate · below 70 no recommendation. The bands are informational; the engine reports all scores and the presentation layer applies the threshold.

Classification of claims

The system's components rest on three distinct kinds of ground. They are not the same, and the documentation does not present them as the same.

Evidence on the output channel

The engine controls two variables: the colour register of what is worn and the fragrance applied. Both act on the wearer through channels documented in peer-reviewed research. The studies below establish the channel — that attire and scent measurably affect the person wearing them. They do not test astrological selection, and are not cited as if they did. The selection logic is the classical doctrine of the previous section; the mechanism of action is the wearer's own perception and physiology.

Invariants enforced in code

The following properties are not policies or intentions; they are enforced by the implementation and checked by the automated test suite.