Documentation_

Welcome to the interactive Sumvela Engine documentation. Explore functions below, read their use-cases, and test them live.

Advanced Concepts

Global Implicit Binding

Advanced Concepts
variable_name

Explanation

Any undefined variable used in the global scope is automatically treated as an Input. You do not need to explicitly declare `name: Input("name")` unless you want to alias it.

EXAMPLEImplicit vs Explicit

Comparison of explicit declaration vs implicit binding

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

Relative Indexing

Advanced Concepts
Variable[-n]

Explanation

Access the value of a variable from a previous iteration (or relative position) using bracket syntax. Equivalent to using OFFSET but more concise.

EXAMPLEPrevious Period Reference

Calculate growth based on the previous value

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

Dynamic Indexing

Advanced Concepts
Array[index_expression]

Explanation

Access array elements using a dynamic index expression. Extremely useful when you need to look up values based on calculation results or the current iteration index.

EXAMPLECopying Arrays

Use the current index to map values from one array to another

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

Implicit Properties

Advanced Concepts
item.property

Explanation

Access properties of objects within a generic LAMBDA parameter or implicitly bound variable without needing specific Param declarations.

EXAMPLEScan with Implicit Property

Accessing properties on the item directly

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLEImplicit Context in MAP

Arrays in the expression implicitly align with the loop

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

Aggregation

SUM

Aggregation
SUM(...values)

Explanation

Calculates the sum of all numeric values. Automatically flattens arrays and handles multiple arguments.

EXAMPLETotal Revenue

Calculate total revenue from multiple product lines

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLEAnnual Expenses

Sum all monthly operating expenses for the year

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

AVERAGE

Aggregation
AVERAGE(...values)

Explanation

Calculates the arithmetic mean of all numeric values.

EXAMPLEAverage Deal Size

Calculate average contract value across all deals

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLEMonthly Average Revenue

Find the average monthly recurring revenue (MRR)

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

MIN

Aggregation
MIN(...values)

Explanation

Returns the smallest value from the provided arguments.

EXAMPLEMinimum Cash Balance

Find the lowest cash balance point in projections

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

MAX

Aggregation
MAX(...values)

Explanation

Returns the largest value from the provided arguments.

EXAMPLEPeak Revenue Quarter

Identify the highest quarterly revenue

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

COUNT

Aggregation
COUNT(array)

Explanation

Returns the number of elements in an array. Input must be an array.

EXAMPLENumber of Active Contracts

Count total contracts for capacity planning

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

Array Operations

MAP

Array Operations
MAP(array, expression) or MAP(array, LAMBDA(params..., expression))

Explanation

Input must be an array. Transforms an array by applying a calculation to each element. Supports both scalar and object arrays with LAMBDAs for explicit parameter naming. Can be used inline within other expressions.

EXAMPLEScalar Array with LAMBDA

Apply calculation to simple numeric arrays

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLEObject Array with Multi-Parameter LAMBDA

Calculate revenue from product data with multiple properties

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLEInline Nested MAP

Use MAP within other expressions without assignment

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLEComplex Financial Model

Multi-period revenue projections with growth rates

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

SEQUENCE

Array Operations
SEQUENCE(rows, [start], [step])

Explanation

Generates a list of sequential numbers. Useful for creating time series or index arrays.

EXAMPLEBasic Sequence

Generate numbers 1 to 5

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLECustom Range

Generate years

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

SCAN

Array Operations
SCAN(array, initial, LAMBDA(accumulator, item, expression))

Explanation

Input must be an array. Scans an array and returns an array of accumulated results. The accumulator carries over logic from one iteration to the next.

EXAMPLECumulative Cash Flow

Calculate running total of monthly cash flows

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLECompound Growth Projection

Project revenue with year-over-year growth

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLEObject Array with Implicit Logic

Accumulate values using properties directly from the array objects

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

LAMBDA

Array Operations
LAMBDA(param1, [param2, ...], expression)

Explanation

Defines an anonymous function with named parameters for use in MAP and SCAN. Parameter names automatically bind to object properties in object arrays, or represent the scalar value in scalar arrays.

EXAMPLEScalar Array LAMBDA

Single parameter binds to the array element value

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLEObject Array LAMBDA

Multiple parameters bind to object properties by name

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLEComplex Logic

Use full expressions within LAMBDA

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLESCAN with Accumulator

Two parameters: accumulator and current item

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLEExtract Attribute (Column)

Extract a specific column from a table input by ignoring the row parameter and accessing the column name directly.

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

OFFSET

Array Operations
OFFSET(array, steps, default)

Explanation

Input must be an array. Access array elements relative to the current iteration index. Used within MAP/SCAN to reference previous or future values. Negative steps look backward, positive look forward.

EXAMPLERevenue Growth Rate

Calculate month-over-month revenue growth

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLEInventory Replenishment

Calculate inventory to order based on previous consumption

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

Context Functions

INDEX

Context Functions
INDEX() or INDEX(array, position)

Explanation

Returns the current iteration index (0-based) when used without arguments in a MAP/SCAN. With arguments, retrieves the value at the specified position (1-based, like Excel). Note: Bracket notation array[index] uses 0-based indexing.

EXAMPLEGet Specific Year (1-Based)

Retrieve Year 5 revenue using Excel-style 1-based indexing

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLELast Element Using COUNT

Get the last element using 1-based COUNT

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLETime-Based Escalation (0-Based INDEX())

Apply annual price increases using INDEX() without arguments (0-based)

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

CURRENT

Context Functions
CURRENT()

Explanation

Returns the current item being processed in a MAP/SCAN iteration. Access object properties using Param declarations or LAMBDA parameters.

EXAMPLEVariance Analysis

Calculate variance between actual and budget

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

Data Binding

INPUT

Data Binding
Input([key]) or name: Input

Explanation

Binds a variable to external input data. key is optional; if omitted, the variable name is used as the key. Supports scalars, arrays, and objects.

EXAMPLEFinancial Statement Inputs

Import key financial metrics from external systems

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLECustomer Cohort Data

Analyze customer lifetime value by cohort

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

CONST

Data Binding
Const(value) or name: Const(value)

Explanation

Defines a constant value (number or string). Used for fixed assumptions and parameters.

EXAMPLEFinancial Assumptions

Define standard rates and multipliers

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

PARAM

Data Binding
name: Param

Explanation

Declares a parameter that will be bound from the context during MAP iteration. Used to access properties of objects in arrays (Legacy). Prefer using LAMBDA parameters.

EXAMPLEInvoice Line Items

Calculate invoice totals from line items

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

OBJECT

Data Binding
OBJECT("key1", value1, "key2", value2, ...)

Explanation

Creates an object/dictionary from key-value pairs. Useful for building structured context data.

EXAMPLEFinancial Metrics Object

Build a metrics object for analysis

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

Date Functions

DATE

Date Functions
DATE(year, month, day)

Explanation

Creates a valid date object from year, month, and day numbers.

EXAMPLECreate Date

Construct a specific date

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EOMONTH

Date Functions
EOMONTH(start_date, months)

Explanation

Returns the last day of the month, a specified number of months before or after start_date.

EXAMPLENext Month End

Get end of next month

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EDATE

Date Functions
EDATE(start_date, months)

Explanation

Returns a date that is the indicated number of months before or after the start date.

EXAMPLE3 Month Anniversary

Add 3 months

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

YEARFRAC

Date Functions
YEARFRAC(start_date, end_date)

Explanation

Calculates the fraction of the year represented by the number of whole days between two dates. Uses US (NASD) 30/360 basis.

EXAMPLEInterest Calculation

Year fraction for annual interest accrual

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

DAYS

Date Functions
DAYS(end_date, start_date)

Explanation

Returns the number of days between two dates.

EXAMPLEDuration

Days between dates

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

TODAY

Date Functions
TODAY()

Explanation

Returns the current date (system time).

EXAMPLECurrent Date

Get today's date

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

NOW

Date Functions
NOW()

Explanation

Returns the current date and time.

EXAMPLETimestamp

Get current timestamp

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

Financial Functions

PMT

Financial Functions
PMT(rate, nper, pv, [fv], [type])

Explanation

Calculates the periodic payment for a loan based on constant payments and a constant interest rate.

EXAMPLEMortgage Payment

Monthly payment for $400k loan at 8% for 30 years

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

NPER

Financial Functions
NPER(rate, pmt, pv, [fv], [type])

Explanation

Calculates the number of periods for an investment based on periodic, constant payments and a constant interest rate.

EXAMPLEPayoff Time

Months to pay off loan with extra payments

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

IPMT

Financial Functions
IPMT(rate, per, nper, pv, [fv], [type])

Explanation

Returns the interest payment for a given period for an investment based on periodic, constant payments and a constant interest rate.

EXAMPLEInterest Portion

Interest paid in the first month

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

PPMT

Financial Functions
PPMT(rate, per, nper, pv, [fv], [type])

Explanation

Returns the payment on the principal for a given period.

EXAMPLEPrincipal Portion

Principal paid in the first month

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

CUMIPMT

Financial Functions
CUMIPMT(rate, nper, pv, start_period, end_period, type)

Explanation

Returns the cumulative interest paid between two periods.

EXAMPLEFirst Year Interest

Total interest paid in first 12 months

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

CUMPRINC

Financial Functions
CUMPRINC(rate, nper, pv, start_period, end_period, type)

Explanation

Returns the cumulative principal paid between two periods.

EXAMPLEFirst Year Principal

Total principal paid in first 12 months

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

FV

Financial Functions
FV(rate, nper, pmt, [pv], [type])

Explanation

Calculates the future value of an investment based on a constant interest rate.

EXAMPLESavings Growth

Future value of monthly savings

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

PV

Financial Functions
PV(rate, nper, pmt, [fv], [type])

Explanation

Calculates the present value of a loan or an investment, based on a constant interest rate.

EXAMPLELoan Amount

How much can I borrow?

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

Logical

IF

Logical
IF(condition, true_value, false_value)

Explanation

Evaluates a condition and returns one of two values based on the result. Uses numeric comparison where 0 is false and any other value is true.

EXAMPLERevenue Milestone Bonus

Apply bonus if revenue target is exceeded

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLETiered Pricing

Apply different pricing based on volume

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLECredit Risk Assessment

Determine credit limit based on payment history

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

AND

Logical
AND(...conditions)

Explanation

Returns 1 (true) if all conditions are true, otherwise returns 0 (false).

EXAMPLEInvestment Approval Criteria

Check if all investment criteria are met

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

OR

Logical
OR(...conditions)

Explanation

Returns 1 (true) if any condition is true, otherwise returns 0 (false).

EXAMPLEAccount Review Flag

Flag accounts needing review based on multiple risk factors

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

NOT

Logical
NOT(condition)

Explanation

Returns the logical opposite: 1 (true) if condition is false, 0 (false) if condition is true.

EXAMPLENon-Performing Assets

Identify assets not meeting performance threshold

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

Comparison Operators

Logical
=, <>, <, <=, >, >=

Explanation

Comparison operators that return 1 (true) or 0 (false). Used in IF conditions and logical expressions.

EXAMPLEBasic Comparisons

All comparison operators

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLEIn IF Conditions

Use comparison operators to build conditional logic

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

Lookup & Reference

LOOKUP

Lookup & Reference
LOOKUP(lookup_value, lookup_array, result_array, [default]) OR LOOKUP(key, object, [default])

Explanation

Searches for a value. Can work in two modes: 1) XLOOKUP style searching arrays, or 2) Object property lookup where it finds a key in a dictionary object.

EXAMPLEFind Rate (Array Mode)

Look up tax rate by region

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLEObject Property

Get value from a specific property key in an object

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

IFERROR

Lookup & Reference
IFERROR(value, value_if_error)

Explanation

Returns value_if_error if the expression evaluates to an error; otherwise, returns the value of the expression.

EXAMPLESafe Division

Handle division by zero

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

Math Functions

POWER

Math Functions
POWER(number, power)

Explanation

Returns the result of a number raised to a power.

EXAMPLECompound Interest Factor

Calculate growth factor

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

ROUND

Math Functions
ROUND(number, digits)

Explanation

Rounds a number to a specified number of digits using MidpointRounding.AwayFromZero (standard financial rounding).

EXAMPLERound Currency

Round price to 2 decimal places

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

ROUNDUP

Math Functions
ROUNDUP(number, digits)

Explanation

Rounds a number away from zero to the specified number of digits. (e.g. -3.14 to 1 digit becomes -3.2).

EXAMPLECeiling for Pricing

Always round up to next cent

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

ABS

Math Functions
ABS(number)

Explanation

Returns the absolute value of a number.

EXAMPLEVariance Magnitude

Get absolute variance regardless of direction

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

Arithmetic Operators

Math Functions
+, -, *, /, ^

Explanation

Standard arithmetic operators for calculations. IMPORTANT: Use ^ for exponentiation, NOT **.

EXAMPLEBasic Arithmetic

Addition, subtraction, multiplication, division

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLEPower / Exponentiation

CRITICAL: Use ^ for power operations, NOT **

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLEMortgage Payment Calculation

Use ^ for loan amortization formulas

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

Patterns & Practices

Excel to CostVela

Patterns & Practices
Concept

Explanation

Guide for translating common Excel patterns to CostVela DSL. Move from cell-based logic to named, structural logic.

EXAMPLEVLOOKUP / XLOOKUP

Replace lookups with conditionals or logic. (For simple tiered logic)

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLESUMIF / SUMIFS

Filter data using MAP and logic before summing.

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLEAbsolute References ($A$1)

Use Constants or single variables.

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

Structuring Models

Patterns & Practices
Best Practice

Explanation

Tips for organizing your model for readability and maintainability.

EXAMPLERecommended Layout

Group Inputs, Constants, and Logic clearly.

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLENaming Conventions

Use clear, descriptive snake_case names.

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

DSL Best Practices

Patterns & Practices
Critical Rules

Explanation

Essential rules to follow when writing CostVela DSL models to avoid common errors.

EXAMPLENo Unused Variables

Every variable you define must be used somewhere in the model.

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLEUse ^ for Power, NOT **

The exponentiation operator is ^ (caret), not ** (double asterisk)

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLEDefine Before Use

Variables must be defined before they are referenced

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

Common Mistakes

Patterns & Practices
Anti-Patterns

Explanation

A list of common pitfalls and syntax errors to avoid.

EXAMPLEUsing != instead of <>

The not-equal operator is <> (SQL style). The C/JS style != is NOT supported.

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLEConst with Arrays

Const() only supports scalar values (numbers/strings). For arrays, use Input() and define the array in the inputs JSON.

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

Text Functions

CONCAT

Text Functions
CONCAT(text1, [text2], ...)

Explanation

Concatenates a list of text strings or numbers.

EXAMPLEJoin Strings

Join two words

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.

EXAMPLEJoin Number

Create a label

Model Logic (DSL)
Input Data (JSON)
Ready. Click execute to run the model against the provided input.