What is Summit Event Language (SEL)?
Summit Event Language (SEL) is terminology that enables you to write calculations in Summit. Like spreadsheet formulas, SEL is a declarative language, which means you will use these expressions to declare the behavior of an event. When declaring an event's behavior, think of it at two points in time:
How should the event behave the first time it runs?
How should it behave the next time it runs (if applicable)?
Simple formulas may cause an event to behave the same way over and over, for example:
=2+2. An event with this formula will always evaluate to
4. If the event points to any other events, this value will be passed to those events (like cell references!).
Events often begin with an equals sign
= because the event simply needs to set a value and pass it along.
However, events can also operate on values they receive from other events. So if you point Event A at Event B, you could write an expression on Event B like:
/ 4 This will divide whatever Event B receives from Event A by 4. When A sends 4 to B, B will divide it by 4, and store 1 as its own internal state. This state can then be passed along to another event.
We have a choice, then, when we create a model using SEL, as to whether we want to split a complex formula apart into its separate pieces to take advantage of labeling and a visual structure on the canvas, or if we want to collapse the formula into a single statement like:
=(2+2) / 4 Either way, you will get
1, but which path is "more correct" is up to you, and whether it's more clear to be able to label the
/ 4 with its own title and whether you'd like to re-use the
/ 4. So you could also have an Event C that points to Event B and divides the output of C by four.
How do I apply formulas to my events?
Each event box includes a field to enter an expression, the same as a typical spreadsheet. Once an event is selected and highlighted, SEL expressions can also be entered into the formula bar at the top of the screen or on the input field for the selected event.
What values can be inputs for SEL expressions?
Numbers & Operators
SEL expressions can contain integers, decimals, positive or negative. And though many have resisted it throughout history -- we're also okay with zero.
Numbers in SEL should not contain commas, but you may use underscores
_ to separate place values. In practice, we encourage you to write
Because it's more natural, Summit also supports numerical abbreviations:
M -> thousand
m -> million
b -> billion
t -> trillion
1.2mm is shorthand for
You can also use decimals with these abbreviations, so
Note: Formatting Output Values
Do not put currency symbols directly into your SEL expressions. To format an event as currency, use the
$ option in the output table at the bottom of the screen. Highlight an event or row to display those formatting options in the output table to toggle the output format as
SEL expressions can be written using any standard arithmetic operators such as addition
+ , subtraction
/, and exponents
**, but SEL truly excels when handling advanced mathematical and time-native expressions through our library of unique SEL functions. For an overview of available SEL functions, click here. To learn how to run calculations directly on your results in the output table using Metrics, click here.
SEL has built-in symbols for declaring estimates and incorporating uncertainty. Any number in a SEL expression can be preceded by a tilde
~ to reflect the uncertainty of the value by +/- 10%.
=2 + ~5 means two plus five, plus or minus 10%, so the output of this formula will be somewhere between 6.5 (at a minimum) and 7.5 (maximum).
You may also deepen this uncertainty by adding
?'s. For example,
=2 + ~5? means two plus five, plus or minus 25%. Each
? represents an additional 25% variation. For example,
=~100???? translates into a random number somewhere between zero (100% less than 100) and two hundred (100% more than 100).
Note: If you use
?, you must still begin the expression with
SEL is a declarative language that primarily deals with numbers, but you can also put words on board by either (1) editing the event title or (2) adding comments directly in the formula field. These comments will not impact results in the output table, but may be helpful for adding context to certain expressions.
=2+2 # Hello, World and
# Hello, World are both valid in SEL.
Lists are useful when you want to feed a specific series of numbers to a model. A good example is the number of sales prospects entering a funnel for an e-commerce business with strong seasonality or the volume of customers arriving at a restaurant each day of the week. Any time you want to send specific values out of an event, you should reach for a list.
To represent an event as a list of values,
[1,2,3,4] is a valid SEL expression and so
[1, 2, 3, 4] (Note: The # of spaces are ignored). When an event is expressed as a list, each value is stored as the internal state for each subsequent period when the event is triggered (e.g. monthly, quarterly, etc).
For the SEL expression above, the first period it runs, the internal value is seen as [
1,2,3,4] and the value used for the first period will be
1. For the second period, the internal state of the event will be a shorter list, i.e.
[2,3,4] and the value used for the second period will be
2, followed by
(Note: Lists triggered to start by another event follow the preceding event's defined calendar start date and recurring event pattern. A list could also be triggered to start by its own calendar date and recurring pattern, but a list should not be defined with both; otherwise, the simulation will fail. Make sure a list-containing event connected by a route does not also include its own start date or recurring pattern.)
The final element in the list (e.g.
4) will be used in all subsequent periods until the simulation terminates. So in the example above, if you ran a 5-month simulation and the above event recurred monthly, the number
4 would be returned by the event for the fifth month and the following months.
Alternatively, if you want the event to return zero for months after the fourth period, you would simply declare the list with a final
Sometimes it's helpful to repeat a list from the beginning, rather than repeating the final element. A Repeating List is useful for situations where the same pattern needs to be repeated over some time interval. One list element could represent each month of a calendar year, for example.
To do so, append an
* to the end of the list like this:
This will generate an infinitely repeating sequence of the list values: 1, 2, 3, 4, 1, 2, 3, 4, ...
🔔 Note: Repeating lists cannot be used inside function calls or to define growth rates.
When constructing your logic in Summit, oftentimes users want values to change over time based on a static growth rate. For example, observe the
@ 8% in the following formula:
=Source(100 @ 8%) This means the number
100 will be compounded at an
8% rate in each period the event is triggered until the simulation terminates.
Things that compound grow extremely fast and can expand to extremely large quantities. In reality, in most systems, growth rates tend to be dynamic and slow down over time. If you wish to express growth rates as variable before flattening out in SEL, you can do so using a List. For example,
=Source(100 @ [1, 5, 8, 6, 5]%)
As stated above, the event will re-use the final element of the list (
5%) and continue to grow at the static rate beginning in the fifth period until the simulation terminates.
With growth rates expressed as lists, we can slow -- or accelerate -- the growth of an event's return values. You can also use negative numbers to shrink a value over time.
For example, you could write a formula like
=Pool(100 @ -5%) to represent a shrinking pool of customers, money, or any value!
You can also express growth rates as constants. For example,
=Source(100 @ 10)
[100, 110, 120, 130 ...]
And you can even mix n' match constants and percentages, such as
=Source(100 @ [10, 20, 30, 10%]) to return
[100, 110, 130, 160, 176.6 ...]!
If you want the growth rates to accelerate or decelerate over time, you can add a Change Rate to the function using the same
@ operator as growth rates. Just add it to the function following the growth rate. There are few different ways this could be applied to a Generator function like a Source, for example:
=Source(100 @ 10% @ -10%)will return
[100, 110, 119.9, 129.61, ...]
As a list:
=Source(100 @ 10% @ [5,10]%)will return
[100, 105, 115.5, 127.05, ...]
As a constant:
=Source(100 @ 10 @ 10)will return
[100, 110, 130, 160, ...]
As variable constants:
=Source(100 @ 10 @ [1,2,3]) # -> [100, 110, 121, 133, ...]
Minimum and Maximum Growth Rates
Sometimes you may want to accelerate or decelerate your growth rate to a minimum or maximum rate, then hold that rate constant. You can achieve this effect in SEL using the spread operator
=Source(50 @ 100...5% @ -10%) means the output will start at 50 and the growth rate will decrease from 100% to 5% by 10% for each occurrence until it reaches 5% where it will remain.
This also works for linear (non-compounding) rates, like so:
=Source(100 @ 100...30 @ -10) means the output will start at 100, then add 100, then 90, then 80, then ... 40, then 30. Then 30 repeating.
Adding units to event formulas helps clarify your assumptions and logic to ourselves and other readers. For example, the event title may be "New Customers", but is this 100 users or 100 accounts? You can declare the units of a constant using an expression wrapped in
>, like this:
Unit types can be placed after any constants, inside or outside of lists and functions:
Unit types should not be used to label growth rates.
You can also add a forward slash before a unit type to describe the constant as a rate. For example:
/year expression is more than a label. It allows you to express constants in units (such as annual salary) that are familiar to you and your reader, while setting the event to repeat on a different frequency. If the above event were set to repeat monthly, it would automatically convert
$100,000 per year to its monthly equivalent of
$8,333.33 as the value flowing through the event.
Acceptable time periods to follow a forward slash include:
quarter, and yes,
Units for Growth Rates
You can also use Unit Rates to define growth across a specific time interval. There are two approaches available: (1) The rate can be expressed as an APR (annual percentage rate) where the rate per period is set according to the event's recurring pattern. This is a common approach for modeling debt.
For example, you could represent a credit card with a $4,000 balance and 19% APR as:
=Pool(4k @ 19<%/year>)
If you set this pool to recur yearly, the pool's value will be $4,760 after 1 year. However, if set to recur monthly, the 19% will be automatically converted to a monthly rate of
1.583...% (19 divided by 12) and compound monthly, resulting in a total of $4,830 after 1 year.
(2) Alternatively, you can express growth as an Annual Percentage Yield (APY) by adding
y after the
%. This is more common for modeling investment returns.
For example, an investment account with a $10,000 initial balance and 10% APY can be expressed as:
=Pool(10k @ 10<%y/year>)
This tells Summit to treat the 10% as a yield rate. With a yield rate, you are indicating that $10k should grow by $1k over the course of a year. If you simply divide 10% by 12 (as in the APR example), the resulting value after 1 year will be higher than $11k since the results are compounded. By using
%y, the interpreter will instead convert the 10% to a rate that, when compounded according to the event's recurring pattern (e.g. monthly, quarterly), the result will still be exactly $11k after 12 months (
/year portion of the formula above can be set to any of the acceptable values for a Unit Rate.
Keep reading: Functions in SEL