Introduction

A block-editor web app for essence built using blockly

• Live Site
• Repo

Please note that the aim of this documentation is to provide understanding of each blocks’ functionality. For knowledge on the conjure language, please see Conjure’s documentation here

Program

This section contains blocks that define the domains of parameters and decision variables. These blocks are vital in structuring constraint programs.

Find Statement Assignment

This block is used to declare decision variables. It must be nested in a find block.

For example, it can be used like this:

Which would produce the following Essence Output:

find  x : int (  0 .. 10  ) 

Find/Given Statement List

Stores a list of decision variables.

For example, it can be used like this:

Which would produce the following Essence Output:

find  x : int (  0 .. 10  ) 

Constraint list

Used to define constraints.

For example, it can be used like this:

Which would produce the following Essence Output:

such that a != b

Letting Statement

Used to define a variables’ domain. This must be nested in a ‘letting’ block.

For example, it can be used like this:

Which would produce the following Essence output:

letting x be domain int ( 0 .. 5  )

Domain Expression

Defines the domain.

The domains we currently support are:

• boolean
• integer

For example, it can be used like this:

Which would produce the following Essence Output:

domain int ( 0 .. 5  )

For more information about domains in essence, see this.

Letting Statement List

Assigns a variable to some domain.

For example, it can be used like this:

Which would produce the following Essence Output:

letting x be domain int ( 0 .. 5  )

Given List

Used to declare a parameter and its domain.

For example, it can be used like this:

Which would produce the following Essence Output:

given x : int ( 0 .. 5  )  ,

Dominance Relation

Identifies when one solution is guaranteed to be at least as good as another.

Example

Say we have 2 assignments, A and B. If A is always at least as good as B, then A dominates B and B can be ignored.

Rules

Dominance relations must have the following properties:

• Transitive: If A dominates B, and B dominates C, then A dominates C.
• Irreflexive: Nothing can dominate itself.

Domain

This section contains blocks that are used to create domains.

Currently, we support integer and boolean domains.

Boolean domain

This domain has two values: false and true. The boolean domain is ordered with false preceding true.

Integer Domain

Defines the values an integer variable can take.

The Integer Domain can either define a single integer or a list of sequential integers with a given lower and upper bound. The bounds can be omitted to create an open range, but note that using open ranges inside an integer domain declaration creates an infinite domain. Values in an integer domain should be in the range -262+1 to 262-1 as values outside this range may trigger errors in Savile Row or Minion, and lead to Conjure unexpectedly but silently deducing unsatisfiability. Intermediate values in an integer expression must also be inside this range.

For example, it can be used like this:

Which would produce the following Essence Output:

int ( 0 .. 100  )

Expression

This section contains information about blocks that can be used to create boolean and arithmetic expressions.

Bracket Expression

Used to group a collection of subexpressions.

Not Expression

This is a logical operation applied to a boolean expressions. Using this block inverts the truth value. (i.e. a true statement becomes false, and vice versa).

For example, if we wanted to create the statement:

not (x and y)

We could use the following blocks:

Which would produce the following Essence Output:

! ( x /\ y  )

Absolute Value

When x is an integer, |x| denotes the absolute value of x. The relationship

(2*toInt(x >= 0) - 1)*x = |x|

holds for all integers x such that |x| <= 2**62-2. Integers outside this range may be flagged as an error by Savile Row and/or Minion.

Exponent

Defines the exponent of an integer.

For example, 2^5 is defined in Conjure Blocks as follows:

Where the top value is the base, and the bottom is the exponent.

This would produce the following Essence Output:

2 ** 5 

Negative Expression

Converts an integer to be negative.

And Expression

A logical operator which abides by the following truth table:

Let x and y be some boolean variables.

For example, it can be used like this:

The statement x and y would be represented in Conjure Blocks as follows:

and would produce the following Essence Output:

x /\ y

Or Expression

A logical operator which abides by the following truth table:

Let x and y be some boolean variables.

For example, it can be used like this:

The statement x or y would be represented in Conjure Blocks as follows:

and would produce the following Essence Output:

x \/ y

Implication

A logical expression. where the following truth table holds.

Let x and y be some boolean variables.

For example, it can be used like this:

The statement x implies y would be represented in Conjure Blocks as follows:

and would produce the following Essence Output:

x /\ y

Quantifier Expression

Iterates over the given domains to find an instance whose conditions are met.

Multiple functions are available for this block:

• and
• or
• min
• max
• sum
• allDiff

For example, it can be used like this:

Which would produce the following Essence Output:

and  ([ x >= y, y <= x ])

Expression List

Stores a list of expressions.

From Solution

Uses the solution that was previously found for a variable.

True

Represents the boolean ‘true’ state.

False

Represents the boolean ‘false’ state.

Comparison

Used to compare two expressions. Returns a binary result.

For example, it can be used like this:

The statement x is not equal to y would be represented in Conjure Blocks as follows:

and would produce the following Essence Output:

x !=  y 

See here for information about the comparison operators conjure uses.

Comparison Operators

Selects the operator for a boolean comparison.

There are 6 comparison operators: =, !=, <=, >=, <, and >.

The equality operators = and != can be applied to compare two expressions, both taking values in the same domain and are supported for all types. The inline binary comparison operators <, <=, >, and <= can be used to compare expressions taking values in an ordered domain. The expressions must both be integer, both Boolean.

For example, it can be used like this:

The statement x is not equal to y would be represented in Conjure Blocks as follows:

and would produce the following Essence Output:

x !=  y 

See here for further information surrounding comparison operators.

Additive Operators

Selects the operator for a sum expression.

There are 2 additive operators: +, and -.

For example, it can be used like this:

and would produce the following Essence Output:

5 + 10

See here for further information surrounding arithmetic operators.

Sum Expression

Used to create + or - arithmetic expression.

For example, it can be used like this:

and would produce the following Essence Output:

5 + 10

See here for further information surrounding arithmetic operators.

Product Expressions

Used to create *, / or % arithmetic expression.

For example, it can be used like this:

and would produce the following Essence Output:

4 / 12

See here for further information surrounding arithmetic operators.

Multiplicative Operators

Selects the operator for a multiplicative expression.

There are 3 multiplicative operators: *, /, and %.

For example, it can be used like this:

and would produce the following Essence Output:

4 / 12

See here for further information surrounding arithmetic operators.

Range

This section contains information about blocks that help define integer ranges.

Integer Range

Used to define a group of integers.

For example, to declare a decision variable x that can take values between 1 and 10, you can do the following:

Which would produce the following Essence Output:

find  x : int (  0 .. 10  ) 

Note

Notice in the blocks example above, we define the range to be 0 to 10.

Say that you want a range A to B where A and B are some integers. Your bounds must extend one step outside of that range. So the lower bound would be A - 1 and the upper bound would be B.

Range List

Defines a list of ranges.

Variables

This section contains information about variable blocks. Conjure blocks supports the creation of boolean and int domain variables. These variables are vital parts of constraint programming.

Variable List

Stores a collection of variables.

Misc

Blocks defined in this section can be found by pressing all on the Conjure Blocks UI. They do not exist in any specific section.

toInt Expression

Takes a boolean expression x and converts to an integer 0 or 1