Skip to content

Calculations

How it fits

A calculation describes what time is displayed for a zman. The critical component of a calculation is the (Lua) code which describes how to perform the calculation.

  1. Dependency. A dependency is the name of a calculation that must be evaluated prior. Calculations may use the results of other calculations, and dependencies are how we ensure that all the required calculations have been done. [see Dependencies]
  2. Name. The name is how calculations are refered to by zmanim, and they form the base of the variable name in the Lua code. [see Lua code - the gory details]

Calculations list

Add/Edit a calculation

  • To edit, tap an existing calculation.
  • To add, tap the + button in the upper right.
  1. Name. The name must be a valid Lua identifier. [see Lua code]
  2. Save. Tap to save changes to name or dependency.
  3. Code. Tap to open the code editor].
  4. Dependency. Any calculation other than the one being edited may be selected. Beware of creating dependency loops!

Calculation

Dependencies

Many zmanim are derived from the value of other zmanim. For example, candle lighting is expressed as a number of minutes before sunset. To calculate candle lighting time, one must first calculate sunset. Candle Lighting depends on sunset.

Chains

Dependencies can form chains. A chain is where calculation A depends on calculation B, which in turn depends on calculation C. A depends on B depends on C. Chains are always calculated from the end which does not have a dependency. In our example, C is calculated first, then B, then A.

Example

graph LR
    A[midday] -- depends on --> B[hour_standard]
    B -- depends on --> C[sunset]
    C -- depends on --> D[sunrise]

Calculating midday (the point in time when the sun appears directly overhead) requires knowing how many hours of daylight there are.
To calculate this, one needs to know when both sunrise and sunset are, or will be. By creating this dependency chain, it is guaranteed that hour_standard and sunrise will be available when midday is calculated.

Loops

A dependency loop is created when the "last" calculation in the chain depends on the "first". Quotes are used here because in a loop, there's no obvious first or last calculation.

Example

graph LR
    A[midday] -- depends on --> B[hour_standard]
    B -- depends on --> C[sunset]
    C -- depends on --> D[sunrise]
    D -- depends on --> A

Here, midday is depending on calculations that ultimately depend on sunrise, but sunrise itself depends on midday! Zmanim Advanced prevents you from saving a calculation that will form a dependency loop, but if this protection fails, you will be presented with details of the issue, and guidance on how to correct it.

Code editor

  1. Variable name. This is the text that is used in code. It is also the text used with dynamic titles. Variables defined here are local to the calculation. They are not visible to other calculations. [see Lua code]
  2. Save. Tap save after making changes. The button is not enabled when the code does not parse. [see Lua code]
  3. Calculation picker. Selecting a calculation from the list inserts the variable name which stores the calculated time. This is the mechanism by which one calculation can use the results of another.
  4. Variable value. The text entered here is the value that the variable has when evaluating the code.
  5. Code. This is where code is entered to perform the calculation. Zmanim Advanced offers syntax highlighting.
  6. Local variable picker. Selecting a variable from the list inserts its name into the code.

Code editor

Lua code

Units of time

A zman is calculated as a number of seconds since midnight.

Here is the code pictured above. Let's disect it. 

return zman_sunset + minutes * 60

  1. return is a keyword that instructs Lua to return the value of the rest of the line, which is called an expression.
  2. zman_sunset is the variable name in which the value of the sunset calculation is stored. Dependencies ensure this variable will have the expected value when this calculation is evaluated. [see Dependencies]
  3. +. This is the familiar addition operation from grade-school math class.
  4. minutes is the local variable that is a placeholder for the number of minutes after sunset by which night has concidered to have fallen (צאת הכוכבים).
  5. *. This is the multiplication operation.
  6. 60. minutes is multiplied by 60 because zmanim are calculated in units of seconds (and there are 60 seconds in one minute 😶).

Notes

  1. Lua follows standard operator precedence for mathematical operations, so minutes * 60 is calculated first.

  2. Code may span multiple lines, but unless it forms a single expression, the return keyword must be used with the final line.

    multiple lines

    local seconds_after_sunset = minutes * 60
return zman_sunset + seconds_after_sunset

For a full treatment of the interplay between calculations and Lua, see Lua code - the gory details. Inside, you'll find detailed explanations of the Lua features used in default calculations that ship with Zmanim Advanced, a full list of the facilities offered by Zmanim Advanced for use in calculations, and more!