> For the complete documentation index, see [llms.txt](https://documentation.soulver.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.soulver.app/whats-new-in-soulver-4.md).

# What's new in Soulver 4?

#### **1. New workflow for&#x20;**<mark style="color:red;">**trip planning**</mark> 🛫

* Plan multi-stage trips & projects in Soulver
  * Declare date lines as **"time points"** (for example the start & end dates of a planned vacation)
  * Write out the amount of time you'd like to spend in each destination on lines in between the time points
  * Soulver will calculate the **total length of your trip**, show the **dates spent in each place**, and **alert you** if you've **exceeded your time budget** for your trip

#### **2. New&#x20;**<mark style="color:red;">**tags**</mark>**&#x20;workflow** 🏷️

* Tag lines with hashtags (#work, #home, #tony, etc) and do statistical (total, average, etc) calculations on all lines that include the tag

#### **3. The&#x20;**<mark style="color:red;">**definition sheet**</mark> 📖

* Define new global variables & new units in a dedicated Soulver sheet
  * Define global variables derived from calculations
  * Define new generic unit types
  * Auto-pluralization of new units

#### **4.&#x20;**<mark style="color:red;">**Line highlighting**</mark>**&#x20;& divider lines** 🖌️

* Highlight lines with 8 fruity colors to make them stand out in your sheets
* Create divider lines (type --- on a blank line) to add extra structure to your sheet

#### **5. More&#x20;**<mark style="color:red;">**natural language**</mark> functions & units in more areas 🌎

**Money**

* Sales tax (calculate tax on an amount, or subtract tax from a final price)
* Income tax (approximate tax or after-tax income in a given country)
* Inflation calculations (past-to-present values, and vice versa)

**Change over time**

* Linear change (change by a fixed amount over time)
* Exponential growth & decay (change by a percentage over time)

**Geography**

* Distance between places
* Arc second/minute unit calculations
* GPS & DMS calculations

**File transfer & speed**

* File transfers (time to download/copy/upload a file)
* Audio speeds (time saved when playing a sped-up file)

**Physics & chemistry**

* Pressure, force & acceleration units
* Moles & molar units

**Electrical**

* Volts, amps, ohms, & many other electrical units

**Vehicles**

* Torque & angular frequency units
* Fuel efficiency & consumption units

**Music**

* MIDI, pitch & frequency conversions

**Pace**

* Pace calculations

**Woodworking**

* Rounding to fractions

**Percentage shorthands**

* Shorthand percentage functions

#### **6. New&#x20;**<mark style="color:red;">**calendar calculation**</mark>**&#x20;features** 📅

* New work hour calculations & improved work day calculations
* Calculations involving cultural events (Christmas, Ramadan, Chinese New Year, etc)
* Format dates using format patterns
* Extract date components from dates
* Elapsed percentages in day/month/year
* State/region public holidays supported in more countries (US, UK, Canada, Australia)
* Astrological calculations

#### **7. Redesigned&#x20;**<mark style="color:red;">**settings**</mark> 🎛️

* Redesigned Mac settings window inspired by the macOS system settings
* Many new settings to further customize Soulver's styling
  * Including answer column color tinting & right aligning answers
* New settings to further customize calculator behaviour

#### **8. Sheet&#x20;**<mark style="color:red;">**management**</mark>**&#x20;&&#x20;**<mark style="color:red;">**sync**</mark>**&#x20;improvements** 📍

* Pin sheets to the top of folders
* Archive sheets into a read-only folder once you're done editing them
* New "Git-like" push/pull sync architecture, built on top of iCloud Drive
* Sync control center to manually sync & pause syncing

#### **9.&#x20;**<mark style="color:red;">**HTML emailing**</mark> service 💌

* Free service that lets you send your Soulver sheets as beautifully styled HTML emails
  * Compatible with Gmail & Apple Mail
  * Sends via our server for your convenience

#### **10. New&#x20;**<mark style="color:red;">**cursor pad**</mark>**&#x20;on iPhone** ↕️

* New cursor pad accessible from a popup on the 9 key gives you:
  * 4 arrow keys
  * Line bumping (up & down)
  * Go to start/end of sheet
  * Go to start/end of line (popups on the left/right arrows)
  * Forward delete

#### **11. Redesigned&#x20;**<mark style="color:red;">**agent-friendly**</mark>**&#x20;CLI** 🤖

* Redesigned **command line interface** that can now edit Soulver sheets & sheetbook files
  * Designed with agents in mind for automations involving your Soulver documents
    * For example you might ask Codex or Claude to create a Soulver sheet for you that includes data it can input itself

## <mark style="color:purple;">Detailed Release Notes</mark>

## 1. New <mark style="color:blue;">trip planning</mark> workflows

To start with this feature, nominate the start and/or end date or time as a "time point" via the contextual menu on an answer. Here are some examples to illustrate how to use this feature.

### **Multi-destination trip planning with a known start and end date**

With the first and last lines designated as time points, Soulver can show you the dates you'll be in each city, and show you how many days you have left in your "time budget" for this trip:

<div data-full-width="false" data-with-frame="true"><figure><img src="/files/T7XHaoUNi9k2DJm428To" alt="Planning a holiday in Soulver 4" width="563"><figcaption></figcaption></figure></div>

If you overshoot your planned return date, Soulver will alert you by how much:

<div data-with-frame="true"><figure><img src="/files/EayFIap4XVzeQODbhEDQ" alt="" width="563"><figcaption></figcaption></figure></div>

### **Planning an early morning airport trip**

Start by specifying your departure time (in this example 11:45am) and making it a time point.

Then add the time you estimate you will need for each activity up to your departure.

Soulver helps you work out that you'll need to be up at 8:10am to make your flight.

<div data-with-frame="true"><figure><img src="/files/rHT7kfHaOf8Ntg7KWA3v" alt="" width="563"><figcaption></figcaption></figure></div>

### **Planning a workday**

Specify the start of your workday with a time point, then add the activities you expect to perform during the day.

Soulver helps you calculate when you'll likely be home.

<div data-with-frame="true"><figure><img src="/files/bGcpv6RIr11SHrnrH2RR" alt="" width="563"><figcaption></figcaption></figure></div>

## 2. New <mark style="color:blue;">tags</mark> workflow

Tags are a new feature that let you perform statistical operations on a particular set of lines in your sheet by tagging them with #hashtags

### Splitting expenses with friends

<div data-with-frame="true"><figure><img src="/files/EhDxUu87Yae4nxnLlyJy" alt="" width="563"><figcaption></figcaption></figure></div>

### Adding up different expense categories in a trip

<div data-with-frame="true"><figure><img src="/files/qiDJG1JHlLsuj5pUtqco" alt="" width="563"><figcaption></figcaption></figure></div>

## 3. The <mark style="color:blue;">definition sheet</mark>

The definition sheet is a dedicated Soulver sheet that lets you define global variables & custom units. Units & variables declared in the definition sheet are usable across all your sheets and Soulver files.

This approach unlocks additional capabilities that were not possible in Soulver 3.

### Declare global variables

Variables declared in the definition sheet (using "=" like regular variables) are available to all your sheets and files.

This means you can now also declare global variables whose values are based off other variables.

{% hint style="info" %}
Global variables defined in settings continue to be supported.

They take precedence over definition sheet defined variables.
{% endhint %}

### Declare custom equivalence units

Declare custom units with the form "1 watermelon = 20 lb".

The custom unit will be available across your sheets: `20 lb in watermelons` (= 1 watermelon).

**Automatic unit pluralisation**

Custom units automatically generate a plural form (in English). So for example, if you declare a custom unit name `watermelon`, `watermelons` will also be recognized in your calculations.

{% hint style="info" %}
Your existing custom units & custom places from Soulver 3 will be automatically migrated to the definition sheet when you run Soulver 4 for Mac for the first time.
{% endhint %}

### Declare new generic units

New unit types are useful cases where you want to define an abstract unit to be used in rate calculations.

To declare an entirely new unit type, use `new unit` as the value. For example:

`operation = new unit`

Then `3 operations / second * 5 minutes` (= 900 operations)

## 4. <mark style="color:blue;">Line highlighting</mark> & divider lines

### **Line highlights**

You can now apply highlights to different parts of your expression (labels, body and comments).

Choose from 1 of 8 attractive colors to make important lines stand out in your sheet:

<div data-with-frame="true"><figure><img src="/files/VBHoDLqliLFK2ADQXTYc" alt="Expression highlighting in Soulver 4" width="563"><figcaption></figcaption></figure></div>

### **Divider lines**

Divider lines are helpful to add extra structure to your sheet and separate different sections.

Create a divider line by typing 3 dashes (---) on a blank line:

<div data-with-frame="true"><figure><img src="/files/sSHEivUa8kwoRWfxStA6" alt="Divider lines in Soulver 4" width="563"><figcaption></figcaption></figure></div>

#### Using dividers to create scope

Divider lines are not just cosmetic: they can create "scopes" for variables, subtotals & tags.

After a divider line, all values are reset (variables & tags), and subtotals will not add up through a divider line boundary.

## 5. New natural language <mark style="color:blue;">functions & units</mark>

## <mark style="color:green;">Money</mark>

#### <mark style="color:green;">Sales tax</mark> calculations (GST, VAT, etc)

* Calculate the amount of tax paid in a given amount: "VAT in $499"
* Calculate the original (pre-tax) price: "$499 - VAT" (this is a different calculation from simply subtracting the percentage from the price)
* Customize sales tax name ("sales tax", "GST", "VAT", etc) & value (10%, 20%, etc) in the **Money** settings

<div data-with-frame="true"><figure><img src="/files/b26gzuy9DR5xaJKerenY" alt="" width="563"><figcaption></figcaption></figure></div>

#### <mark style="color:orange;">Income tax calculations</mark>

You can use Soulver 4 to work out the (approximate) tax you'll pay (or after tax income remaining) in a particular country:

* "income tax on $55k in Australia" (= $8,388.00)
* "income after tax on $95k in Canada" (= $81,099.98)
* "tax rate on $45,300 in USA" (= 7.30%)

Naturally these are just rough estimates — actual tax paid will often depend on the state and your individual circumstances. Still, it's sometimes helpful to get a ballpark figure (and Soulver’s raison d’être is back-of-the-envelope calculations after all).

#### <mark style="color:green;">Inflation calculations</mark>

Soulver now includes an inflation calculator (based on the average yearly CPI change data published by the U.S. Bureau of Labor Statistics).

You can convert between currency amounts in various years, accounting for inflation, and predict the future value of an amount.

**Calculate the current value of an equivalent amount from the past**

* "value of $4.2k from 2003" (= $6,795.58)
* "$1 in 1997 is worth what today" (= $1.85)
* "$10k from 1960 worth" (= $102.877k)

**Convert today's dollars to a previous year**

* "what was $500 worth in 1997" (= $269.56)
* "value of $1 in 1977" (= $0.20)

**Predicting the future value of an amount today**

* "value of $500 in 2028 assuming 5% inflation" (= $411.35)
* "what will $1M be worth in 2042 assuming 10% inflation" (= $217.629k)

### <mark style="color:purple;">Change over time</mark>

#### <mark style="color:orange;">Linear growth functions</mark>

Let's say that you currently have $**20,000** and you receive an allowance of **$2,000** every month. You're saving up for a **$40,000** car. How long will it take before you can afford to buy it?

* "time from $20k to $40k at $2k every month" (= 10 months)

You can also omit the starting amount (it will be assumed to be 0):

* "time to $500 at $10 every 5 hours" (= 250 hours)

#### <mark style="color:red;">Exponential growth & decay functions</mark>

These functions are helpful for working with exponential growth (like user base growth, compounding interest, or virus spread).

**Growth of a quantity (by a percentage) over time**

* Let's say your company is experiencing **10%** monthly user growth, and you currently have **20k** users.
* You want to calculate how many users you'll have 6 months from now:
* "20k after 6 months at 10% per month" (= 35,431 users)

**Time required to grow/shrink to a certain quantity**

* Perhaps we want to calculate how long it will take to get to **100k** users at the present growth rate:
* "time from 20k to 100k at 10% growth per month" (= 16.88 months)

**Calculating exponential growth rate**

* Imagine that in the course of a week, cases of a particularly catchy virus in a community increased from **10k** to **15k**.
* We want to calculate the daily growth rate of the virus:
* "growth per day from 10k to 15k over 1 week" (= 6%)

### <mark style="color:green;">Geography</mark>

#### **Distance between places**

Calculate the distance between locations:

* "distance between Sydney and London" (= 16,989.1 km)
* "distance from NYC to Toronto" (= 556.34 km)
* "distance berlin paris" (= 880.63 km)

{% hint style="info" %}
The distance is calculated by tracing a line between the two points that follows the curvature of the Earth, and measuring the length of the resulting arc.
{% endhint %}

**Get an approximate GPS location for a given city or airport**

* "location of Paris" (= 48.85341°, 2.3488°)
* "longitude of SFO" (= -122.375°)
* "latitude of Sydney" (= -33.86785°)

#### **DMS (degrees, minutes, seconds)**

Soulver 4 supports calculations involving DMS values, including converting between degrees & DMS, and converting between DMS & GPS coordinates.

**Converting between DMS & decimal degrees**

* "156.742° as DMS" (= 156° 44′ 31.2″)
* 90° 50′ 30″ to degrees = 90.8416666667°

**Adding & subtracting DMS values**

* "32 degrees 14 minutes 52 seconds + 18 degrees 11 minutes 33 seconds" (= 50° 26′ 25″)
* 74 ° 25' 20" - 24 ° 1' 10" (= 50° 24′ 10″)

**Converting between DMS & GPS**

* "56°13′48″N, 043°47′12″E" (= 56.23° N, 43.78° E)
  * This conversion is automatic
* "latitude of Tokyo as DMS" (= 35° 41′ 22.2″)

### <mark style="color:blue;">File transfer & speed</mark>

**Time to complete file transfer (download/upload/transfer/send)**

Calculate the time it will take to transfer (download, upload or copy) a file at a particular speed:

* "time to upload 3GB @ 10 MB/s"
* "time to transfer 1.7GB at 600 KB/s"
* "time to download 25 MB at 5 KB/s" (*remember 56k modems?*)

**Speeding up the time of an audio or video file**

* "1 hour 30 minutes at 1.5x" (= 1 hour)

**Time saved when consuming a sped up file**

* "time saved 5 min at 1.5x" (= 1 min 40 s)

### <mark style="color:orange;">Physics & chemistry</mark>

**Pressure**

* Pascals, hectopascals (hPa), kilopascals (kPa), megapascals (MPa), gigapascals (GPa)
* Bars, millibars (mbar)
* Pounds force per square inch (psi)
* Kilopounds force per square inch (ksi)
* Atmospheres (atm)

**Chemistry**

* Moles, millimoles, micromoles, nanomoles
* Molarity & molar calculations
  * "55 mol/L in molars" (= 55 ᴍ)
  * "2 mol/L × 0.1 L × 58 g/mol" (= 11.6 g)

**Acceleration**

* m/s^2, ft/s^2
  * multiply by weight for force
  * 3 kg \* 10 m/s² (= 30 N)
  * 150 lb \* 8 ft/s^2 (= 1,200 pdl)

**Force**

* newtons, kilonewtons, micronewtons, etc
* poundals, pounds of force, ounces of force

### <mark style="color:blue;">Electrical calculations</mark>

The following units have been added (with support for corresponding micro, milli, regular, kilo and mega sized units):

* Electrical resistance: ohms
* Electrical potential: volts
* Electrical current: amps
* Charge: coulombs
* Inductance: henrys
* Capacitance: farads
* Conductance: siemens
* Flux: webers
* Flux density: teslas

### <mark style="color:purple;">Vehicle calculations</mark>

**Angular velocity units**

* revolutions per second (rps),
* revolutions per minute (rpm)
* radians per second (rad/s)

Convert angular velocity to frequency

* "60 RPM in Hz" (= 1 Hz)

Tire speed calculations

* "speed of 12" tire at 522 rpm" (= 18.64 mph)

**Torque units**

* Newton meters, pound feet, pound inches, ounce inches

Calculate torque at a particular wattage & angular velocity

* "500 Watts at 1500 rpm" (= 3.1830988618 N⋅m)

**Fuel consumption units**

* Liters per kilometer, liters per 100 kilometers

**Fuel efficiency units**

* Miles per gallon, grams per liter, kilometers per liter

### <mark style="color:green;">Music</mark>

Convert between pitches, sound wave frequencies, and MIDI numbers

Examples:

* "440 hz as pitch" (= A4)
* G4 to hz (= 392 Hz)
* C2 to midi (= 36)

### <mark style="color:blue;">Pace</mark>

Calculate pace from distance and time

* "5 km in 25 min" (= 05:00/km)
* "10 mi in 55 min" (= 05:30/mi)

### <mark style="color:red;">Woodworking</mark>

Round a number to the nearest fraction

* "0.534 to nearest 16th" (= 9/16)
* "3.192 to nearest 32nd" (= 3 6/32)

### <mark style="color:orange;">Percentage shorthands</mark>

#### **Percentage ratios**

Given one number and its percentage of a whole, determine the percentage of another number:

* "20% is 500, what is 750" (= 30%)

You can also calculate another percentage of the whole:

* "if 20 is 30%, what is 60%" (= 40)

#### **Is what % of a set**

This function allows you to get the percentage of one number from a set of other numbers (inclusively).

* "3 is what % **with** 5, 7 and 9" (= 12.5%)
  * *(equivalent to "3 is what % of 3 + 5 + 7 + 9")*

#### **Is what % growth after change**

If you know the final amount, and a change amount, by what % has the original amount changed?

* "15 is what % after 3" (= 25%)
  * *(equivalent to (15-3) to 15 as %)*

#### **X on Y (as %)**

Useful for getting the percentage increase when one number is added to another

* "3k on 50k" (= 6% increase)
  * *(equivalent to 53k is what % on 50k)*

#### **X off Y (as %)**

* 50 off 150 (= 33.33%)
  * *(equivalent to 100 is what % off 150)*

#### **X of Y (as %)**

* 15 of 200 (= 7.5%)
  * *(equivalent to 15 is what % of 200)*

## 6. <mark style="color:blue;">Calendar calculation</mark> improvements

### Work hour calculations

* Do calculations like "work hours between March 12 and March 25", "work hours in June", "work hours left in 2026"
* Default is 8 hours/work day, and can be customized in the **Dates & Times** settings
* Convert time into work days: "55h in work days" (= 6.875 work days)

### Date calculations relative to cultural & religious events

* Do date calculations with widely observed annual cultural events, such as Christmas, Easter, Thanksgiving, Halloween, Ramadan, & Chinese New Year, and more
* For example, "days until Christmas", or "Chinese New Year 2029".
* This is especially helpful for events like Easter & Ramadan that change their date each year

### Format dates using format patterns

* For example, "March 12, 2023 as EEEE, MMM d, yyyy" (= Sunday, Mar 12, 2023)
* Or "March 12, 2023 as MM/dd/yy" (= 03/12/23)
* The pattern language is defined by the [Unicode Technical Standard #35](https://unicode.org/reports/tr35/tr35-dates.html#Date_Format_Patterns)
* Here is a good [cheat sheet](https://toolboxpro.app/blog/unicode-cheatsheet) (by the late Alex Hay)

### Percentage elapsed in calendar unit

These functions help quickly get the amount of time passed in a day, week, month, or year as a percentage of the whole (i.e., what % of the year has elapsed):

* "day percentage", "week %", "month percent", "year percentage"

### Astrological

#### Lunar day

* Get the current lunar day using "lunar day" or "moon day"

#### Daylight hours

Get the amount of daylight today in a given location:

* "daylight hours in Melbourne"

### State/region level public holiday support

* Public holidays for your state or region are now included in working day calculations
* You may also select a different state in your country in the `Dates & Times` settings

### Extract date components from a date

* Day of year
  * Get the current day of year number, from 1 to 365 (or 366), using "day of year" or "day number"
  * Also works for a particular date: "day number on march 15, 2024" (= 75)
* Day of month
  * Get the current day of month number, from 1 to 30 (or 28 & 31), using "day of month"
  * Also works for a particular date: "day of month on march 15, 2024" (= 15)
* Week of month
  * Get the current week of month number, from 1 to 5, using "week of month"
  * Also works for a particular date: "week of month on march 15, 2024" (= 2)

## 7. <mark style="color:blue;">Settings</mark> improvements

### Redesigned Settings window on macOS

This release has a redesigned settings window. It has been modelled on the macOS system settings for a familiar look and each pane has been carefully redesigned for usability and clarity.

### New dates & times settings pane

* Customize how date intervals (like March 12 - April 25) are formatted
  * Days, weeks & days, months & days
* Specify the number of hours in a work day
  * Helpful for doing workday calculations
* Specify the interpretation of ambiguous clock times (without am/pm markers)
  * For example, should "11:00 to 3:00" be 4 hours (assume 3am) or 16 hours (assume 3pm)?
* Customize the default unit for trip planning totals (days or nights)

### New styling settings

* Customize line spacing (compact, regular, large)
* Choose the size of the line numbers (small, medium, large)
* Set a tint for the answer column
  * Tint can be the accent color or a custom color
  * Can also select "none" to use the same color as the text area (white or black depending on the appearance)
* Select text alignment (left or right) for the answer column text
* Set separate custom syntax colors for light & dark mode
* Toggle automatic bold for labels & headings

### New unit settings

* Toggle compound imperial unit formatting (5.5 feet as 5 feet 6 inches)
* Customize whether single units auto-convert (like 5km on its own would show 3.10 miles in the answer column)

## 8. <mark style="color:blue;">Sheet management</mark> improvements

### <mark style="color:blue;">Pin sheets to the top of a folder</mark>

* Similar to Apple Notes, you now can pin a sheet to keep it prominently displayed at the top of a folder

### <mark style="color:green;">Sheet archive</mark>

* Move a sheet to the new (read-only) archive to prevent any further edits.
* This safeguards sheets that you no longer want edited from changes

### <mark style="color:orange;">New sync architecture</mark>

* Soulver 4 has a new sync architecture designed from the ground up to be more flexible & dependable
  * Instead of directly editing a sheetbook file inside iCloud Drive, Soulver now "pushes" & "pulls" changes from iCloud Drive, to your local file stored on your Mac (stored in any folder you like)
  * This model gives Soulver more control over the syncing process
    * We can handle any conflicts ourselves, pause syncing temporarily, and merge data from multiple devices with no data loss.

## 9. <mark style="color:blue;">HTML emailing service</mark>

Every version of Soulver now has access to a dedicated Soulver sheet emailing service that transforms your Soulver sheets into beautifully styled HTML emails.

The styling is compatible with Apple Mail & Gmail, and emails are sent via our server for your convenience.

{% hint style="success" %}
No data is stored on the emailing server that provides this service. We never see the contents of your sheet emails, your address or the recipients.
{% endhint %}

## 10. <mark style="color:blue;">Cursor pad</mark> on iPhone

The iPhone version of Soulver features a new cursor pad. Hold down on the 9 key, swipe up over the arrow keys button, and then use the cursor pad to navigate your document using keys you are familiar with from your Mac sheet editing experience.

The cursor pad includes:

* 4 arrow keys
* Line bumping (up & down)
* Go to start/end of sheet
* Go to start/end of line (popups on the left/right arrows)
* Forward delete

<div data-with-frame="true"><figure><img src="/files/pvHxOPwkwFXlRfmTCMat" alt="The new cursor pad in Soulver 4 on iPhone" width="375"><figcaption></figcaption></figure></div>

## 11. <mark style="color:blue;">AI-friendly command line interface</mark>

We've completely redesigned Soulver's **command line interface** so it can now create/edit Soulver sheets & make changes to your default sheetbook too.

We designed this with agents firmly in mind, so you can now ask Codex or Claude to create a Soulver sheet for you that includes data it can input itself.

Documentation [here](https://github.com/soulverteam/Soulver-CLI).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://documentation.soulver.app/whats-new-in-soulver-4.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.