Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/V3RNE42/helios/llms.txt

Use this file to discover all available pages before exploring further.

In the Northern Hemisphere the sun traces its arc across the southern sky. Before solar noon it is climbing toward the south-east; after solar noon it is descending toward the south-west. That single geometric fact is the engine behind every recommendation Helios makes: combine the direction a vehicle is travelling with whether the current moment is before or after solar noon, and you can determine which window the sun will be shining through.

​
The four cases

Helios reduces every journey segment to one of four cases. The table below is reproduced directly from the project’s core algorithm specification:
LeftRightConditionDirection
SUNSHADEBefore solar noonNorth to South
SHADESUNBefore solar noonSouth to North
SHADESUNAfter solar noonNorth to South
SUNSHADEAfter solar noonSouth to North
Reading the table: a traveller going north to south before solar noon should sit on the left to be in the sun (or on the right to be in the shade). After solar noon the same north-to-south traveller should switch sides. Journeys going south to north are mirror images of their north-to-south equivalents.

​
Solar noon as the dividing line

Clock noon and solar noon are different things. Solar noon is the moment when the sun reaches its highest point in the sky at a given longitude — it can be more than 30 minutes away from 12:00 on the clock, depending on the time of year and where in a time zone you are. Helios never uses clock noon as the dividing line. Instead it calculates the true solar noon for each geographic position along the route. In index_def.js, solar noon is obtained from SunCalc.getTimes() for both the origin and the destination: 
// Solar noon at the origin
let times = getTimes(salida, latitudOrigen, longitudOrigen);
datos.start = {
    lat: coordenadas.latOrig,
    lon: coordenadas.lonOrig,
    sunset: tiempo1.sunset.end,
    sunrise: tiempo1.sunrise.start,
    solarnoon: times.solarNoon,   // ← true solar noon
};

// Solar noon at the destination
times = getTimes(llegada, latitudDestino, longitudDestino);
datos.end = {
    lat: coordenadas.latDest,
    lon: coordenadas.lonDest,
    sunset: tiempo2.sunset.end,
    sunrise: tiempo2.sunrise.start,
    solarnoon: times.solarNoon,   // ← true solar noon
};
Within a day-segment, the solar noon used for the AM/PM decision is the midpoint between that segment’s sunrise and sunset times — both of which are themselves computed at the interpolated position along the great-circle route, not at a fixed point.

​
Seat-change logic

The user interface exposes a cambio (“can you change seats?”) toggle. Its effect depends on whether the journey spans solar noon: When seat changes are enabled (cambio = true): Helios can recommend sitting on one side up to solar noon and then switching to the other side. If sunrise and solar noon are not at the same moment, the result text instructs the traveller to sit on side A from departure until solar noon, then move to side B for the remainder. When seat changes are disabled (cambio = false): Helios picks a single side for the entire segment. It does this by comparing how much time is spent before solar noon versus after: 
let morning = el["noon"].getTime() - el["sunrise"].getTime();
let afternoon = el["sunset"].getTime() - el["noon"].getTime();
leftSeat = getLeftSeat(morning >= afternoon, el.NaS);
If the morning portion (sunrise → noon) is longer than or equal to the afternoon portion (noon → sunset), the “before solar noon” row of the four-case table wins. Otherwise the “after solar noon” row wins.

​
The getLeftSeat function

Once the AM/PM status and the travel direction are known, a small pure function translates them into a concrete side: 
let getLeftSeat = (ams, NaS) => {
    let leftSeat = true;
    if (!ams) { leftSeat = !leftSeat; };
    if (!datos["sun"]) { leftSeat = !leftSeat; };
    if (!NaS) { leftSeat = !leftSeat; };
    return leftSeat;
};
  • ams — true if the current moment is before solar noon (Ante Meridiano Solar), false if after.
  • NaS — true if the vehicle is travelling North-to-South, false if South-to-North.
  • datos["sun"] — true if the user wants to maximise sun exposure, false if they want shade.
Each if (!…) flips the recommendation. Starting from “left = sun, north-to-south, before noon”, any deviation from that baseline inverts the answer once. If two conditions deviate, the inversions cancel out and the original answer is restored — which is exactly what the four-case table predicts.

​
Handling edge cases

Night-time travel: computeRouteSections in routeSolar.js detects whether the entire journey falls between sunset and the following sunrise. When night = true, renderResults renders a 🌙 message instead of a seat recommendation. Multi-day journeys: The outer loop in computeRouteSections runs until it has found all solar events between departure and arrival. The loop limit is set dynamically based on trip duration (limit = floor(total_time × 2 / ONE_DAY)), so a three-day trip gets a proportionally larger budget of iterations than a single-day trip. Each (sunrise, sunset) pair becomes one independent section, each rendered as a separate card in the results. Polar and high-latitude travel: At extreme latitudes, the sun may not rise or set on a given day. If getDayInfo cannot find a sunrise or sunset — because the sun is either always above or always below the horizon — the segment either has no daylight events to record (treated as all-night) or the times returned fall outside the journey window and are handled by sectionFormatter’s boundary logic.
Helios assumes a straight-line (great-circle) route between origin and destination. Real roads, rail tracks, and flight paths curve, detour, and change compass bearing continuously. The recommendation is therefore an approximation based on the overall direction of travel, not a turn-by-turn analysis.

Build docs developers (and LLMs) love

Get started for freeTalk to us