# Getting Started With TLA+

This post shows how to write your first simple TLA+ specification.

## What is a specification?

In software, the behaviour of a system is described as a sequence of states. Mathematically, each state is expressed as a function F(t), which represents the state of a system at time t. To completely specify a system, we write out each state to fully define the systems behaviour.

## A simple clock

This example comes from Chapter 2 of the book Specifying Systems by the creator of TLA+, Leslie Lamport. If you are unfamiliar with the math used here, refer to basic math for writing TLA+ article.

This example is a simple clock that shows only the hour of the day. How can we specify this behaviour using TLA+? More abstractly, what are the sequence of states that specify the behaviour of the clock? If the current hour is represented as the variable h, then the behaviour of the clock is to change this variable for each hour:

[h = 1] -> [h = 2] -> [h = 3] -> ...


To define this in TLA+ requires writing an initial predicate for the starting value of h, and a next-state relation describing how the hour changes at each step.

The initial starting point of the clock is somewhat irrelevant, and we can simply set it to any value between 1 and 12. The behaviour of the clock is to, at each step, increment its value by 1, except if the hour is 12, where we will reset the clock to 1 (assuming a 12 hour clock). To completely specify the clock, we would create a single formula combining the initial predicate with the next-state relation using a conjunction:

h ∈ {1, …, 12} ∧ [h = 1] -> [h = 2] -> [h = 3] -> …

Any system that we build that satisfies this formula satisfies our specification for the simple clock. This must be true for all starting steps, and for all possible points in time (all steps).

## A simple clock in TLA+

We can express this simple algorithm using TLA+. TLA+ divides partitions into modules; the simple clock can be contained in a single module. Modules are specified using a header, which is a sequence of four or more - characters and the MODULE keyword. The following section begins a TLA+ module:

---- MODULE Clock ----


Arithmetic operators like + are not defined in TLA+. This allows you to write your own + operator that adds matrices or complex numbers, for example. Thankfully, TLA+ provides a standard library that implements some common arithmetic. We can add those libraries to our module using the EXTENDS keyword.

---- MODULE Clock ----
EXTENDS Naturals


Variables in TLA+ need to be defined before use via the VARIABLE keyword. The following section defines a variable h to represent the hour value of the clock:

---- MODULE Clock ----
EXTENDS Naturals

VARIABLE h


Now, to define our initial condition of the clock we need a function. Functions are defined using the == operator, which means is defined to be:

---- MODULE Clock ----
EXTENDS Naturals

VARIABLE h

HCinit == h \in (1 .. 12)


The ∈ operator is written as \in in TLA+, and the .. operator defining a sequence of integers is part of the Naturals library. The next-state relation is similarly written as previously defined:

---- MODULE Clock ----
EXTENDS Naturals

VARIABLE h

HCinit == h \in (1 .. 12)
HCnext == h’ = IF h /= 12 THEN h + 1 ELSE 1


The /= operator means not equal. IF, THEN, ELSE constructs take their usual definitions in programming. h’ represents the new value of h, i.e., the new state of the variable after the function completes.

Lastly, we express the clock itself as the conjunction of the initial state and the next state, for all values of h:

---- MODULE Clock ----
EXTENDS Naturals

VARIABLE h

HCinit == h \in (1 .. 12)
HCnext == h’ = IF h /= 12 THEN h + 1 ELSE 1

HC == HCinit /\ [][HCnext]_h


The only tricky part here is the [][HCnext]_h syntax, which says “this formula is true for all values of h”. To be more precise, the [] operator is the temporal logic operator, which asserts that the formula following the operator is always logically true. The _h allows the formula to make no changes to a state variable, allowing state transitions from [h == 1] -> [h == 1], for example. Or, put another way [][HCnext]_h == [](HCNext \/ (hr’ = hr)).

Finally, we can add a THEOREM to our module. Theorem’s are formulas that follow logically from the definitions in the module, any included library modules, and the rules of TLA+ (set theory and logic).

---- MODULE Clock ----
EXTENDS Naturals

VARIABLE h

HCinit == h \in (1 .. 12)
HCnext == h' = IF h /= 12 THEN h + 1 ELSE 1

HC == HCinit /\ [][HCnext]_h

THEOREM HC => []HCinit


The complete specification of the clock is the formula definition of HC, HCinit, HCnext, the operators .. and + from the Naturals module.

## Checking our model with TLC and the TLA+ Toolbox

TLA+ comes with a set of tools for writing and verifying models. To start, download the latest TLA+ Toolbox release for your system from Github. Unzip the folder and you can run the precompiled Java application to start the toolbox. You should be presented with the following welcome screen:

From here, create a new specification from the file menu. In the following example, I create a new root module and specification called SimpleClock.

Clicking Finish will open up a blank module for you. You can copy in the specification above. The Toolbox is built on top of Eclipse and provides syntax parsing that marks the location of any parsing errors in your code. When you save your file, the box labelled ‘Parsed’ should remain green, showing that there are no syntax errors.

Now, we can create a model that verifies our specification does what it says it does. Models are created through the File -> TLC Model Checker window.

The model checker, TLC, is a program for finding errors in your specification. The model checker is run on a model of your specification, which tells the model checker what it should do. When creating a model you create a behaviour specification, which specifies the set of allowed behaviours of the system being specified. We also include explicitly what the model checker should check, and any initial values to substitute for parameters.

TLC works with formulas expressed as F == Init /\ [][Next]_var, which is an initial state combined with a next-state relation. The next-state relation can be built up from other formulas, but the entire specification should be reduced to such a formula for checking via TLC. Together, the initial state and the next-state are called the behaviour spec. TLC will check this behaviour spec.