1 of 100

Documentation

Introduction

Do you want to avoid unnecessary reading? Take a moment to decide which statement describes your curiosity best:

What makes you curious?...

"I'm just interested to know who might use Ampersand and for which purposes." Click here to learn why you might want Ampersand.
"I am a student wanting to use Ampersand in class." This tutorial was made just for you. Students who like something different will love it.
"I am a computer professional in need of a good method for designing an information system." Computer professionals who like fast results will be thrilled, provided they make the effort of learning.
"I am a scientific researcher and I want to learn more about the research behind Ampersand." Scientists who like formal methods will appreciate this particular use of relation algebra.
"I am a software engineer and I want to change Ampersand to suit my needs." You'll be delighted to see that your back-end software is as adaptable as your front-end software, and everything is generated towards proven technology for the sake of maintainable results.
"I work in an industry, an enterprise, or a government institute and I hope Ampersand is the silver bullet that kills all vampires and solves my problems." Alas, there's no such thing as a free lunch. Ampersand is not interesting for you. (Ampersand promises correct data and fast development to those who don't believe in fairy tales and do want to make the effort.)

One bite at a time

Rarely does one need to learn everything there is to know about Ampersand. Take one bite at a time, no more than you can chew, and use it in practice immediately. Learn as you go...

Disclaimer

Ampersand is a project with no funds. The people who are supporting Ampersand are volunteers with little spare time. This explains why there are omissions in this text. So please condone any shortcomings. We are looking for skilled volunteers to help this project forward, by the way.

Licence

Unless otherwise specified, everything in this repository is covered by the following licence:

Ampersand Documentation by the the Ampersand team is licensed under a Creative Commons Attribution 4.0 International Licence.

Based on a work at https://github.com/AmpersandTarski/documentation

Why Ampersand?

The purpose of Ampersand is to help business engineers deliver . Correct means that the system complies demonstrably to the rules of the business. How cool is that!

Some examples of information systems built in Ampersand

Medications, a demonstrator built by TNO in Ampersand to showcase attestation on the internet. This example is undocumented.
, a site to disclose standards for electronic messaging in the sector of flexible labour. This example is undocumented.
, a tool for students to learn how to work with Ampersand. This project is documented in .

Benefits

Make a conceptual analysis of your business problems to create a shared understanding. Then use the resulting data model to kick-start your application(s).
Use Ampersand as a platform for reactive programming, to deliver you from workflows and workflow models.
Be baffled by the precision with which you can formalize legal rules, and enjoy the benefits of compliance-by-design.
Experiment with rules to and cut back on red tape.
Make enterprise software adaptable by using Ampersand's software generator and reducing your programming effort to a minimum. Even complex changes, such as changes in your conceptual model (viz. data model) are brought into production quickly.
Support your own business, rather than someone else's view on your business. Designing with lets your business associates convince themselves that the system supports exactly the right rules.
Decrease maintenance cost and increase understanding, by describing goals instead of steps. Ampersand is a language, which yields simplicity without sacrificing precision.
Develop more efficiently by preventing errors instead of correcting them. Enjoy the benefits of strong and static typing. Several scientific studies show significant effects of strong and static typing on the total cost of ownership of your design. Besides, it enables Ampersand to generate efficient code.
Gain mathematical certainty of compliance. Ampersand uses relation algebra to align the IT system to the business, by exploiting its natural language interpretation alongside its technical interpretation as working software. Your claim that business stakeholders understand (solely in natural language) what the computer does (in software) can't be made more convincingly.
True low-code platforms, such as Ampersand, give you full functionality with little code. Do the and experience a full non-trivial example of an information system specified in 61 lines of code only.
Reduce risk by developing in small increments. Add constraints, user interfaces, relations, and other design elements one at a time. Generate a prototype at any intermediate stage, to try out your system long before it is finished.
Reduce risk by dividing the work into small subsystems. To isolate subsystems is easy, due to . Ampersand lets you combine subsystems into larger systems, automating the burden of combining them. Reuse design patterns to assemble systems, rather than re-invent from scratch.
Deploy quickly by building, configuring, and taking it to production automatically.

Why rule-based?

To design and build a good information system is a difficult task. Ampersand makes this easier by automating tedious coding tasks and preventing scores of errors you might make. Use it to create a wonderful festival organisation platform, your very own web shop for pedigree poodles, or the trip organiser for hiking expeditions in the Andes. It's all up to you.

Not many people can design and build good information systems. It is a difficult task. Ampersand makes your life easier by automating tedious coding tasks and preventing scores of errors you might make. Use it to create this wonderful festival organization platform, your very own webshop for pedigree poodles, or the trip organizer for hiking expeditions in the Andes. It's all up to you.

A characteristic of Ampersand is its focus on business rules. Business rules embody the agreements of people who pursue a common goal. Naturally, such rules are to be respected by every information system that supports their business. The value of Ampersand is this: once you have a precise set of rules, you have your information system. The coding of software is automated by Ampersand. So if a rule changes, you have altered it in your code in a breeze. That is why Ampersand focuses on rules.

How does it work?

Ampersand is a way of designing information systems for enterprises, supported by a method, a tool, and a course. These are the things you do (click on the hyperlinks to watch video clips):

Define a domain language (in Ampersand) to consolidate agreement of terms among stakeholders, using it solely for technical purposes.
Use the documented ontology that Ampersand generates to validate the agreed rules.

Foundations

Licenses

The Business Rules Manifesto and Ampersand

Ampersand lets you use business rules as intended in the (by the Business Rules Group, 2003). This chapter quotes each article from the manifesto verbatim. Besides, it describes how Ampersand implements it,

Tutorial

Ampersand is meant to develop information systems.
This tutorial will get you going with Ampersand. Consult your tutor with questions.
You have a tool to experiment with, supplemented by this video (in Dutch) to make your start even easier.

This tutorial is meant for Business- or IT professionals who want to learn about information systems development. Knowledge about Ampersand is not presumed. The text offers pointers for you to find out many things on your own. This tutorial is intended for individual study, but you can always ask your tutor if things are unclear. The required theory is also available in Learning Unit 3 of the coursebook of the course IM0403, Rule-Based Design, taught at the Open University of the Netherlands.

Overview

You will start by looking at an information system called "Enrollment" and learn the basics of its specification. By looking at a small information system you can discuss the purpose of the course with your tutor and peers.
Then you will be introduced to the web-based version of Ampersand, RAP4, in which you can specify an information system and create a working web-based prototype. With this tool, you can make information systems of your own, enabling you to complete the course.
Next, we will have a look at the conceptual model behind the Enrollment system. You will learn to interpret a rule based on the given concepts and relations. You will see some basics of relational algebra.
You will learn how to analyse a "spreadsheet information system" and turn it into a well defined information system. This technique allows you to help organizations with organizing and structuring data.
You will learn how to add rules to your data. This will allow you to add meaning to your information system, because you can assure your user community that these rules will remain satisfied.

What have you learned so far?

Ampersand is meant to develop information systems.
This tutorial will get you going with Ampersand. Consult your tutor with questions.
You have a tool to experiment with.

Example system: Enrollment

In this section, you will learn the basic structure of information systems according to Ampersand. By studying a simple system, you will learn how Ampersand represents such systems.

We will study an information system called "Enrollment". The purpose of that system is to enroll students for modules. Students can enroll (or be enrolled) for any module that is part of the course they take.

Try it out on an Ampersand implementation. Copy this example code, make a new script on an Ampersand system, compile it, and generate a prototype implementation from it. Run the prototype and then click on the icon "Overview" in the top-left of the screen. The application will start. Browse through the data and change things. Find out which courses, students, and modules there are and try to see what happens if you add or remove information from the system. You can use this assignment as a guide:

Assignment

Who are the three students and what are the courses they take?
Is there a module HRM?
- Add, in the tab Course, the module HRM to the Management course. The system sees that the subject is unknown, and provides a green plus-sign to add it.
- Each change will be saved automatically.
- Note that this change is also visible in the tab Modules.
Now enroll student John for the module Business Rules. You can do this either in the tab Students or the tab Modules. We will later see why this is the case.
Now enroll student Peter for the module Business Rules.
- This will trigger a message because this student does not take the course Business IT.
- Click on the message to see details.
- Look-up in the code below where this message is defined. It is the line that starts with RULE. You don't have to understand the syntax at this point.
- Click cancel.
Use the trash can icon to remove the course Business IT fromSusan in the tab Students.
- This also will trigger an error message because each student can only enroll for a module in courses he has registered in. Get rid of the message by going to the "List all interfaces" in the menu bar and navigate back to the overview.
- Look up in the code the definition of the RELATION takes. The keyword [TOT] is responsible for this message.
Note the four icons on the top-right of the screen and click on the second icon (nine dots).
- Click on 'Reinstall database'
- The Installer screen comes up. Click on the big red button and wait for it to turn green.
- Click on 'overview' and the initial data is back.
- Have a look at the code below, to find where the initial data is defined.
Have a look at the code-part at the end called INTERFACE and compare it with the screen. Note which parts you recognize. The syntax of the code is discussed in the documentation.

This information system was built by the following code:

What have you learned?

After finishing your assignment, you have learned:

to recognize details in the source code of your information system and relate them to the information system "Enrollment" that you have been playing with;
that a rule of the business, such as "A student can only enroll for a module that is in the course the student takes" can be formalized in Ampersand.
that such a business rule can be used to constrain data in a database.

Want to learn more?

Conceptual Model: Enrollment

In the code you can find the MEANING of each relation in natural language. In the model, each relation represents a set of pairs. The relation takes is filled with (Student, Course) -pairs that each specify a specific course that that specific student is taking. The same student can appear in more pairs and the same course can appear in more pairs. But each combination is unique, a specific pair (x,y) can only appear in the set once.

You have seen the web application Enrollment in action. You have seen the code that defines the system in such a way that Ampersand can generate the web application. Now we will have a look at the conceptual model that is defined in that code. In this tutorial we will only describe the example to make you more familiar with the terminology. Just try to recognize what is described in the code and in the working system.

We have three ingredients:

CONCEPT
RELATION
RULE

Before we discuss these three main ingredients, we will discuss the other keywords you see in the code.

INTERFACE is not crucial for the conceptual model, but still crucial for the web application. It uses the conceptual model to define the tabs and fields displayed. We will come back to this later.
The text after MEANING and PURPOSE is printed in the documentation that RAP4 can generate.
MESSAGE and VIOLATION are used to display messages on screen to the user about rule violations.
POPULATION provides the web application with actual data to test the rules with. Adding data to the system can also be done with an excel sheet. The data specifies elements that populate the concepts and whether or not these elements are connected to each other in a specific relation.

The core of the model

The goal of the model is to define rules that will govern the behavior of the system. Rules are about relations and relations link elements of one concept with elements of another concept. So we need all three ingredients (concept, relation and rule) to define the model. Deciding about these ingredients, their name and their attributes is exactly the modeling that you will learn in this course.

A conceptual model of Enrollment can be represented with a diagram:

In the code you can find the MEANING of each relation in natural English. In the model, each relation represents a set of pairs. The relation takes is filled with (Student, Course) -pairs that each specify a specific course that that specific student is taking. The same student can appear in more pairs and the same course can appear in more pairs. But each combination is unique, a specific pair (x,y) can only appear in the set once.

In the code you see the keyword [TOT] in the definition of the relation takes. It is called a multiplicity. The multiplicity 'total' means that each student must take at least one course.

Assignment

Question 1: given the initial dataset in the source-code of Enrollment, what pairs are in the relation isPartOf?

Question 2: given the initial dataset in the source-code of Enrollment, which students are enrolled for which modules?

Check your answer in the web application Enrollment.

The rule

So let’s finally go to the one rule that governs this information system: isEnrolledFor |- takes ; isPartOf~

The rule consists of two parts with |- as separator. On each side of the separator you find a relation. On the left-hand side we have the relation isEnrolledFor and on the right-hand side you see a relation that is not explicitly defined in the model. This relation is constructed with two relations that are in the model: takes and isPartOf~ (pronounced as “isPartOf-flip”, indicating the relation in opposite direction). This constructed relation consists of (Student, Module)-pairs with a specific student that is taking a course that contains (among others) this specific module. Try to trace this last description in the model and note that although the result is a pair of two elements, there are actually three concepts involved. Let’s call this new relation canEnrollFor.

Now we can pronounce the rule in more or less natural language: "isEnrolledFor implies canEnrollFor". If the first is true than the second must also be true.

Everytime the user of the system tries to enroll a student for a module, the rule checks whether this student can be enrolled for this module based on the course the student is taking. If this enrollement is not allowed, the rule produces a violation message. In fact, with each ‘save’ in the database, all information in the database is checked against this rule.

Assignment

Try to reason about the answers to the following questions based on the conceptual model and the rule. After that, try it out in the system.

Question 1: Suppose the user adds to the database that student Peter is enrolled for the module IT-Governance. Will this cause a violation message?

Question 2: Next, what will happen when the module IT-Governance is no longer a part of the course Business IT. Why?

Question 3: Think of an entry you can do in the system to generate a violation message and try it out in the system.

Question 4: John is a hard working student and he wants to take a second course, Management. Will the system allow this? Why?

Question 5: The multiplicity [TOT] seem to work as a rule. What is the difference between a multiplicity, like TOT, and a rule, like isEnrolledFor |- takes ; isPartOf~?

What have you learned?

an information system may be seen as a system of relations and rules that governs data, supplemented by user interfaces that give access to that data.
a rule engine executes the rules on all data regularly

What's next?

Your tool: RAP4

This section introduces the tool you will use during the course: RAP4. This tool stores Ampersand-scripts in which you can specify, analyze and build information systems. It runs on the internet, so all you need is a browser. Click here if you are a student of the Open University or here if you are not to start using it.

RAP4 is under development. New releases can be done daily. If you find problems with the software, please notify your tutor. If the software is to blame, we will ask you to make an issue in RAP's issue registration system. This way you can help improve Ampersand's tooling, for which the Ampersand team is very grateful.

During the remainder of this course, you will compile and run your own scripts in this way, so it pays to familiarize yourself with RAP4.

RAP4 keeps your work together under a student number. So click on the button 'login' on the left top of the screen.

Register with your own student number and e-mail. Create a password. Your student number is your account, but you can fill in a name. This name should not exist yet, so a green plus sign will appear. Click on it and your name is added to the database.

Notes:

About the user interface: Each time you change fields (e.g. using Tab), the form is updated. But you will not see what is the next active field. You may have to click again to ensure that your cursor is in the right field.
This application has no connection with the OU database, so be careful to fill in the right number on this and future occasions.
This login-screen is also the screen to logout later.
When RAP4 is updated, probably your account will be reset. You need to register again. We will inform you in the unlikely event that this happens during a course.

Use the system

After logging in, you will see your login name or student number in the RAP4 window.

In the menu bar you will find:

A horn symbol. Just ignore that for now, because it contains debug settings.
a 3x3 grid, which contains some Ampersand extensions.
a plus (+) symbol. That is important, because it lets you create a new Ampersand script.
a person-like symbol. It lets you switch on/off some role dependent functionalities. If you have more than one role, just try it out and watch functionalities appear and disappear from the menu bar. As a student you typically have just one role (User) so this button is not very relevant for you.

Notes:

After a period of not using RAP4, you will be logged out automatically. In the current system, you may get errors or weird behaviour. Please navigate back to the login screen to check whether you are still logged in.

Want to learn more?

how can I make and run my first Ampersand script.
How can I describe functionality in a conceptual model?
How can I upload bulk data from spreadsheets into my application?

What have you learned?

where to find the Repository for Ampersand Projects (RAP4)
to register yourself in RAP4

Disclaimer

RAP4 is under development. You can expect to find teething problems (kinderziektes) in the software. Please notify us by making an issue in our issue registration system. This way you can help improve Ampersand's tooling, for which the Ampersand-team is very grateful.

Making your first Ampersand script

Open your editor, copy a correct script into it, and have some fun...

When you click on the blue plus-sign on the top-right side in the menu bar in your screen, you can make a new script. Clicking this opens an editor screen in which you can type your very first Ampersand script.

Assignment

Next, click on the blue Compile button. When RAP4 is finished compiling your script, the compiler message should read "The script of Enrollment contains no type errors" and two blue buttons should be visible below that. Please make it a habit to read the Compiler message carefully each time you compile a script

Generate a Prototype: Click the blu button "Prototype" and when RAP3 has finished loading you will see a new link "Launch Prototype". Click the link.
Now you see the information system you have just compiled from the code. You are already familiar with the look and feel. Click the Overview button in the top-left of the screen and have a look around.
Try to generate documentation: Click on the button Diagnosis. When RAP4 is done, a link will be added below the button. Click on the button Func. spec + pictures and again a link will be added. These two functions create pdf-files with information about the code that has been compiled. During the course you can have a better look there.

During the remainder of this course you will compile and run your own scripts in this way, so it pays to familiarize yourself with it.

You are now going to change some code and view the results in RAP4. Navigate back to your script editor (wherever you are, you can always go back to it via "MyScripts" in the menu bar).

If you want to save the original script, go to MyScripts, create a new script and copy the same code in there.
Let's add the possibility to register teachers in this system:
- Define a new concept with the keyword CONCEPT: CONCEPT Teacherwith a short description. Note that concept names start with an Uppercase and that all quotes need to be double quotes.
- Define the relation between Module and Teacher with the keyword RELATION: RELATION providedBy[Module*Teacher] MEANING "A module is provided by a teacher" Note that relation names start with lowercase.
- You can define an initial set of teachers and relate them to a module following the examples already available in the script. But you can also add the data later using the prototype. (Adding initial data in the script is a lot of work. There is another method, using spreadsheets. This is another topic in this tutorial.)
- Add a service for the teachers in the third tab, the one for Modules. Below the codelines for "Modules" and above the line for "Course": , "Teacher" : providedBy CRUD
- Save, compile, create protype, launch prototype, reinstall database and see the result in the third tab called "Modules". Note that you need to reinstall the database because the old database is still there, but the database structure has changed in the application.
- Note that we have not defined any rules about teachers, so anything you fill in, is OK for this system.
Try to understand what you see in the script by making other changes, compile and inspect the changes; learn by doing. Try for instance to create a new course with modules and teachers. Demonstrate your changes to your peers and discuss the results.

What have you learned?

After finishing your assignment, you have learned:

how to use RAP4 to write, save and compile code.
the first basic keywords of Ampersand script and their effect on the prototype.

Want to learn more?

Reactive programming

Ampersand adheres to the reactive programming paradigm. This chapter tells the story...

The easiest way to think about Ampersand is to envisage an information system as a set of structured data that changes over time (just like a database), together with a set of constraints (the rules) on that data that must remain satisfied throughout their lifetime.

Abstract? Here is a simple example:

Think of your example system as an empty set of data with just one rule: "Every parcel must have an owner."
Suppose that there is an event that inserts into the data set: "Parcel with property identifier 074.0-0000-0084.0 is 0.54 acres large."
The system will now signal that property 074.0-0000-0084.0 doesn't have an owner.
Either you (as a user) or a computer (as automaton) can satisfy the rule by inserting into the data that the owner of property 074.0-0000-0084.0 is Grafton Town of Highway Department, 30 Providence Rd, Grafton, MA 01519-1186. Hence the rule is satisfied.
bla bla

The language Ampersand

This chapter describes the full language Ampersand. Please use it as a reference rather than an introductory course.

Watch this clip to learn how we use the words atom, concept, and relation. Below is a list of other words with a specific meaning in Ampersand.

Syntactic definitions are given where the underlying notions (e.g. rule, relation, pattern, etc.) are discussed. The metasyntax is singled out on a separate page. Because terms are defined in relation algebra, their semantics are explained in various ways to suit the background of each individual reader. Terms are the only algebraically defined things.

This section is organized by discussing each notion in isolation. Hyperlinks are added in the text to let the reader navigate on her own. The text is suitable for reference purposes, so there is no preferred order in reading.

How to read syntax statements

Sometimes, in describing the syntax, EBNF-like notation is used, with the following meaning:

To keep this chapter as readable as possible, we have chosen to omit some details that are irrelevant for practically all Ampersand modelers. In the very rare case that these technicalities are of interest, the reader could have a look in the sourcecode of the parser, where all EBNF statements are fully detailed in comments.

Truth

An information system should represent the truth. So, as a designer you must know a thing or two about truth.

Let us introduce some language to talk about truth. Consider a fact "Joe Smith lives in New York." from an Ampersand perspective. In Ampersand, we can analyse this as follows:

Let Person and City be concepts****
Let "Joe Smith" be an atom of the concept Person and "New York" an atom of the concept City.
Let us use the relation livesIn[Person*City] to contain our fact.
livesIn is the relation name and [Person*City] is the signature of this relation.
Person is the source of this relation and City is the target.
If the pair ("Joe Smith","New York") is an element of this relation, Ampersand considers the statement "Joe Smith" livesIn "New York" to be true. So all pairs in a relation represent facts, i.e. true statements.

Language that makes sense to the business

Ampersand takes a pragmatic stance on truth: You model only things that make sense to the business. This video clip illustrates the distinction between sensible and senseless statements. A sensible statement (we say: "It makes sense.") is a statement that can be true or false. Sentences that are not sensible (we can say: it is non-sense) are to be avoided. The Ampersand type system helps you to make sensible statements only.

Truth in context

Truth always has context. If we say "Jack was married to Jackie", this statement is true in a context where "Jack" refers to the 35th president of the United States, John F. Kennedy. However, this statement is not true in a context where there is no Jack. And in a context where marriage doesn't exist, this statement makes no sense.

Atoms

Purpose

To represent a real-world thing in an information system context, you use atoms.

Description

An atom refers to an individual object in the real world, such as the student called "Caroline". But what if there are three different Carolines? What does it mean to say: "Caroline has passed the exam for Spanish Medieval Literature."? This sentence might be true for one Caroline, but false for the others. Clearly, to avoid ambiguous sentences, an atom must identify exactly one real-world object, no more, no less. Or rather, it suffices that the atom identifies one object within the context in which we are working: if the context is a group with only one Caroline, there will be no ambiguity. Similarly, ABBA is unique among all pop groups in the world; there ought to be only one building permit with number 5678; etcetera.

Examples

"Caroline", 5, 1917-11-07 48, 10.34, 2., .001, -125, +5.33333, 2.5E2, 5E-3

Syntax and meaning

The syntax of atoms is largely taken from ISO8601 and corresponds to the syntax of SQL and Excel. (Acknowledgement: the following text was adapted from Wikipedia)

Date and time values are ordered from the largest to smallest unit of time: year, month (or week), day, hour, minute, second, and fraction of second. The lexicographical order of the representation thus corresponds to chronological order, except for date representations involving negative years. This allows dates to be naturally sorting|sorted by, for example, file systems.
Each date and time value has a fixed number of digits that must be padded with leading zeros.
Representations can be done in one of two formats - a basic format with a minimal number of separators or an extended format with separators added to enhance human readability. The separator used between date values (year, month, week, and day) is the hyphen, while the colon is used as the separator between time values (hours, minutes, and seconds).
For reduced accuracy, any number of values may be dropped from any of the date and time representations, but in the order from the least to the most significant. For example, "2004-05" is a valid ISO 8601 date, which indicates May (the fifth month) 2004. This format will never represent the 5th day of an unspecified month in 2004, nor will it represent a time-span extending from 2004 into 2005.
If necessary for a particular application, the standard supports the addition of a decimal fraction to the smallest time value in the representation.

Atomic types

Atoms are represented in an SQL database. For this purpose, every atom has a type (sometimes called the technical type). The representation in SQL is given in the following table.

The last column, eq, tells whether Ampersand implements equality on these types. If equality is not defined, the operators \/, /\, -, \, /, ;, and <> cannot be used.

The distinction between closed and open types is relevant in the following situations:

The complement of a relation, -r[A*B], is defined only if both A and B are closed.
The full relation, V[A*B] is defined only if both A and B are closed.
A service INTERFACE X : e requires that the target of e is closed.

Violations are currently signaled at runtime, but future versions of Ampersand will signal these violations at compile time.

Miscellaneous

Every atom whose atomic type is marked "yes" in the column "eq" can be compared for equality. For all other atoms, equality is not defined.
The following Ampersand statement declares the atomic type of a concept:
```
REPRESENT <Concepts> TYPE <Atomic type>
```
e.g.
```
REPRESENT LegalEntity TYPE ALPHANUMERIC
```
If Person and Company are both LegalEntity, then both of them will be implicitly declared as ALPHANUMERIC too.

The CONCEPT statement

Purpose:

A concept statement defines a concept in natural language. A concept is a name for similar things. For example: Peter, John, and Barack are things you might want to call Person, whereas 45-NP-88 and KD-686-D could be instances of the concept LicensePlate.

Syntax:

Semantics

This statement means that there exists a concept called <upper case identifier> in the current context.

<upper case identifier> specifies the name of the concept. It starts with an upper case character and may subsequently have any combination of upper case (ABCDEFGHIJKLMNOPQRSTUVWXYZ), lower case (abcdefghijklmnopqrstuvwxyz), digits (0123456789) and underscore (_).
<String> defines the concept. Please describe in natural language the conditions that make an atom belong to this concept. Your definition is used by the documentation generator, which expects it to be a grammatically correct and complete sentence.

Examples

Miscellaneous

The name of a concept starts with an uppercase character.
A concept should be used for immutable concepts. E.g. use a concept Person to express that a person will always be a person and will not change in, let us say, a table. However, don't use Employee, because termination of an employee's contract causes a person to be an employee no longer. So employees are not immutable. To be an employee is a dynamic property, so model it as a relation.
The description will be printed in the functional specification, so please check that your definition is a complete sentence.
Concepts need not be defined. If you use a concept without a definition, Ampersand makes it for you.

Markup

For the purpose of documentation, you may state the language in which the meaning is written. You may also state in which markup you have written your meaning. Examples:

If you specify the language, Ampersand can restrict the documentation for the language you choose. Currently, you can only choose DUTCH or ENGLISH. The default language is English

By specifying a markup language, Ampersand interprets the text as specified. If you do not specify the markup language, your text is interpreted as restructured text. The available markup languages are LATEX, MARKDOWN, HTML, and REST. The default markup language is REStructured Text (REST).

The RELATION statement

Purpose

A relation statement says that a relation exists. It introduces (defines, declares) the relation in the context that uses the relation statement.

A population statement specifies which pairs (of atoms) are in a relation.

Description

A relation is a set that contains pairs of atoms. Over time, pairs can be inserted into or deleted from a relation, for example by a user typing data into an Ampersand application. So the content of a relation is changing over time.

When discussing relations, an arbitrary relation is referred to as , , or . To say that a pair belongs to a relation , we write or alternatively .

Examples

In this example:

contract is the name of the relation,
Order is the source concept of the relation,
ContractID is the target concept of this relation, and
UNI and TOT are constraints of this relation.

Syntax and meaning

Each relation used in Ampersand has to be declared. This means that the developer tells the system that this particular relation exists. A relation declaration can have one of the following formats:

In the declaration RELATION owner[Person*Building], owner is the name and [Person*Building] is the type of the relation. Relation names start with a lower case character, to avoid confusion with concept names. The signature of this relation is owner[Person*Building]. The signature identifies the relation within its context. The left hand concept, Person, is called the source of the relation and the right concept, Building, is called the target.

All three formats define a relation by its name, its source concept and its target concept. By convention, the name of a relation is a single word that starts with a lower case letter. The source and target concepts start with an upper case letter. This convention avoids confusion between concepts and relations.

A relation statement means that there exists a relation in the current context with the specified name, source concept and target concept.

A relation statement may occur anywhere inside a context, both inside and outside a pattern.

The name, source concept and target concept together identify a relation uniquely within its context. As a consequence, the name of a relation does not have to be unique. E.g. name[Book*Name] can be specified in the same context as name[Person*Name]. Because they have different source concepts, these are different relations.

Properties

The <properties>-part is meant for writing multiplicity constraints in a comma separated list between square brackets '[' and ']'. E.g. [UNI,TOT] . The following properties can be specified on any relation r[A*B]

There are additional relations that can be specified on endo relations. An endo relation is a relation where the source and target concepts are equal. r[A*A].

Let's assume that we want to express that any person can live in one city only. So under this constraint "Joe Smith lives in New York" and "Joe Smith lives in Denver" cannot both be true at the same time.

In relation algebra, we say that the relation is univalent, which means that every atom in the source concept can only be paired with a single atom in the target concept. This is modeled as

PRAGMA

A pragma is optional and is characterized by the reserved word PRAGMA. The PRAGMA is followed by two or three strings. It is used to construct sentences in natural language, using pairs from the actual population of a relation. A pragma specifies how we speak (in natural language) about any pair in the relation. Ampersand also uses pragmas to generate examples in the functional specification. Example of a pragma with three strings:

To use this pragma on the pair (John,Amsterdam) results in the sentence "Student John flies the flag of Amsterdam in top.". The two atoms are fitted in between the three strings. A pragma with two strings is identical to a pragma in which the third string is empty.

(The PRAGMA keyword will become obsolete in a future version of Ampersand. It will be replaced by the VIEW-statement which offers more flexibility in composing sentences.)

Example:

The PRAGMA tells us that it makes sense to utter the phrase "Provider Mario's Pizza's has accepted order 12345."

MEANING

Miscellaneous

The MEANING statement

MEANING can be used with CONCEPT-statements, RELATION-statements, and RULE-statements, to define the meaning of your concepts, relations, and rules.

A meaning is optional and is characterized by the reserved word MEANING. It specifies the meaning of a concept, a relation, or a rule in natural language. The meaning is used to generate documentation and is printed in the functional specification. A <meaning> can be any text, starting with {+ and ending with +} e.g.

MEANING
{+ This is an example that is
   spread over multiple lines. 
+}

The optional <language> is specified as

IN ENGLISH or
IN DUTCH.

Example :

MEANING IN DUTCH {+ Dit is een voorbeeld in een (1) regel.+}

This is a way to override the default language (which is English).

Sometimes you need formatting in the meaning, such as dotted lists, italics, or mathematical symbols. For this purpose you have a choice in which syntax you specify the meaning. The optional <markup> is one of :

REST (Restructured text. This is the default)
HTML
LATEX
MARKDOWN

Example :

MEANING LATEX {+This is a {\em mathematical} formula $\frac{3}{x+7}$.+}

Ampersand uses Pandoc to offer a choice for your markup. See pandoc.org for details.

The PURPOSE statement

Semantics

Most things in your model are in it for a reason. To document these, you should use the PURPOSE statement.

Syntax

PURPOSE <type of thing> <name> <language>? <markup>?

{+ <anything> +}

Where <type of thing> and <name> are the type and name of the thing that is refered to. This could be one of: CONCEPT, RELATION, RULE, IDENT, VIEW, PATTERN, INTERFACE, CONTEXT

The optional and can be used to override the settings for language and markup. If omitted, these are inherited from the pattern of context where the PURPOSE statement is specified in.

Examples:

PURPOSE CONCEPT Person {+The concept Person keeps all personal data together.+}

PURPOSE RELATION accountOwner
{+ The system shall register all accounts to an owner,
   so accounts with the same owner are linked in this way.
+}

When defining the purpose of a relation, make sure that Ampersand can identify the relation unambiguously. If you have multiple relations accountOwner, add the signature to disambiguate it. For instance:

PURPOSE RELATION accountOwner[Account*Owner]
{+ The system shall register all accounts to an owner,
   so accounts with the same owner are linked in this way.
+}

Markup

For the purpose of documentation, you may state the language in which you write a purpose. You may also state in which markup language you use. Examples:

PURPOSE CONCEPT Person IN ENGLISH {+ The concept PERSON keeps all personal data together, which we need to comply with the GDPR.  +}

If you specify the language, Ampersand can restrict the documentation for the language you choose. Currently, you can only choose DUTCH or ENGLISH. The default language is English.

PURPOSE RELATION accountOwner LATEX
{+ The system {\em shall} register all accounts to an owner, so accounts with the same owner are linked in this way.
+}

By specifying a markup language, Ampersand interprets the text as specified. If you do not specify the markup language, your text is interpreted as REStructured Text (REST). The available markup languages are LATEX, MARKDOWN, HTML, and REST.

PURPOSE RULE "Check Digit Character"
IN ENGLISH MARKDOWN
{+ This rule enforces the use of a check digit character
   as described in [ISO 7064](en.wikipedia.org/wiki/ISO/IEC_7064).
   This is applicatble to IBAN bank account numbers.
+}

The CLASSIFY statement

Purpose

A classify statement is also called a specialization. It specifies that atoms of one concept are atoms of another concept as well. You can use it to buils classifications like Linnaeus did.

Syntax and meaning

CLASSIFY <upper case identifier> ISA <upper case identifier>

In a specialization, e.g. CLASSIFY Sedan ISA Car, we call the first concept (Sedan) the specific concept and the second (Car) the generic concept. The meaning of a specialization is that every atom from the specific concept is an atom from the generic concept as well. So every (atom that is a) Sedan is a Car as well.

So in general: CLASSIFY $A$ ISA $B$ means: $\forall a: a\in A\Rightarrow a\in B$ .

Examples

CLASSIFY Monkey ISA Mammal

CLASSIFY Sedan ISA Car

To save some writing, you may specify

CLASSIFY Monkey, Cow, Human ISA Mammal

This means exactly the same as

CLASSIFY Monkey ISA Mammal
CLASSIFY Cow ISA Mammal
CLASSIFY Human ISA Mammal

Best practice

A specialization is a static relationship. If you want to say that a student is a person, please consider whether you want this to be static. If a person can enroll to become a student, or graduate or drop out to become non-student again, the dynamics of that cannot be captured in a specialization. Use a relationship instead to model the state of being a student. E.g. RELATION student[Person*Enrollment]

By adding and removing pairs to that relation, it continuously reflects which persons are a student.

The RULE statement

Purpose

The purpose of a rule is to constrain data. Refer to the chapter about rules in the tutorial for examples and a practice-oriented explanation.

A rule statement defines something that should be true. It does not define the enforcement.

Syntax of rules

A <rule> has the following syntax:

RULE <label>? <term> <meaning>* <message>* <violation>?

Terms and operators are discussed in a separate section:

Syntax of labels

A <label> is optional. It can be a single word or a string (enclosed by double brackets) followed by a colon (:).

MEANING*

The meaning of a rule can be written in natural language in the Meaning part of the RULE statement. It is a good habit to specify the meaning! The meaning will be printed in the functional specification. The meaning is optional.

Syntax

MEANING {+<text>+}

The <text> part is where the the meaning is written down. It is enclosed by {+ and +} and may be spread across multiple lines. If you need specific markup, turn to this page for a full explanation.

MESSAGE*

Messages may be defined to give feedback whenever the rule is violated. The message is a string. When you run your prototype this is printed in a red box when the rule is violated. You will see the violations by clicking on that message.

MESSAGE String

VIOLATION

A violation message can be constructed so that it gives specific information about the violating atoms:

VIOLATION (Segment1,Segment2,... )

Every segment must be of one of the following forms:

TXT String
SRC Expression
TGT Expression

A rule is violated by a pair of atoms (source, target). The source atom is the root of the violation message. In the message, the target atoms are printed. With the Identity relation, the root atom itself can be printed. You can use an expression to print other atoms. Below two examples reporting a violation of the rule that each project must have a project leader. The first prints the project's ID, the second the project's name using the relation projectName:

VIOLATION ( TXT "Project ", SRC I, TXT " does not have a projectleader")

VIOLATION ( TXT "Project ", SRC projectName, TXT " does not have a projectleader")

ROLE MAINTAINS

By default, rules are invariant rules. By preceding the rule statement with a role specification for this rule, the rule becomes a process rule.

tbd

Terms

This page describes the notion of term. Its subpages provide several interpretations of terms, all of which are valid so you can use each interpretation at your own discretion.

Purpose

The purpose of a term is to compute pairs that constitute a relation. We use operators to assemble terms from smaller terms, to express in formal language precisely what is meant in the natural language of the business. The smallest term is a single relation.

We noticed that our readers have different backgrounds. They have different preferences about the way we explain the operators in Ampersand. Some prefer an explanation in logic, others in algebra, and still others in set theory. So we decided to explain the operators in many different ways simultaneously, hoping that one of them suits your preference.

Description

A term is a combination of operators and relations. Its meaning is a set of pairs, which is in fact a newly created relation. The word "expression" may be used as a synonym for "term" in the context of Ampersand.

Examples

owner

r;s~

I /\ goalkeeper;goalkeeper~

destination;"Algarve" |- spoken;"Portugese"

Syntax

Every term is built out of relations, which are combined by operators. An term has one of the following 8 syntactic structures

<Term> <BinaryOperator> <Term>
<UnaryOpPre> <Term>
<Term> <UnaryOpPost>
<RelationRef> <type>?
I <type>?
V <type>?
<atom>
( <Term> )

`Operators`

The operators come in families. We advise novices to study only the rule operators, boolean operators and relational operators. There is a wealth of things you can express with just these operators. The residual operators seem harder to learn and the Kleene operators are not fully implemented yet. You can click the hyperlink to navigate to the semantics of each family.

Brackets

Operators with different binding power may be used in the same term without brackets, because the binding power tells how it is interpreted. For example, $r\cap s;t$ means $r\cap(s;t)$ because $;$ has a higher binding power than $\cap$ .

Operators with the same binding power must be used unambiguously. For example: $r\cap(s-t)$ means something different than $(r\cap s)-t$ . In such cases Ampersand insists on the use of brackets, so readers without knowledge of the binding powers of the operators can read a term unambiguously.

Repeated uses of an associative operator does not require brackets. So $r\cap s \cap t$ is allowed because $\cap$ is associative.

Notation on the keyboard

When coding in Ampersand, these operators are typed with characters on the keyboard. The following table shows the operators in math and their equivalent in code:

Semantics

Semantics tell us about meaning. About how to interpret terms and their operators.

We present the semantics of terms in 5 different (but equivalent) ways: one explanation in terms of logic, one in set theory, one in terms of axioms (algebraically), one in natural language, and one visual explanation. These ways are equivalent, so you can interpret a term in any of the presented ways. Any way will do; take your pick!

(the pages without hyperlinks are yet to be made).

Semantics in logic

Relational operators

Purpose of relational operators

To say things such as "the name of the owner", we want to string together multiple relations (viz. name and owner). Relational operators allow us to make such statements.

Converse

A relation can be altered by swapping the elements of every pair in the relation. Mathematically, $(a, b)$ is a different from $(b,a)$ . This operation is called the converse operator. It produces a new relation from an existing one. It is denoted by writing \smallsmile\ (pronounced 'wok' or ’flip’) after the relation name. This is how converse is defined:

a(r\smallsmile)b\ \Leftrightarrow\ b\ r\ a

If $r$ has type $[A\times B]$ , then r\smallsmile\ has type $[B\times A]$ .

Composition

The composition operator is denoted by a semicolon $;$ between two terms. It is pronounced as 'composed with'. Let us take a look at $r$ composed with $s$ . Let $r_{[A\times B]}$ and $s_{[B\times C]}$ be two relations, with the target of r being the same as the source of s. Then the composition of $r$ and $s$ is defined by:

a(r;s)c\ \Leftrightarrow\ ∃ b∈B\ ∙\ a\ r\ b ∧ b\ s\ c

If $r$ has type $[A\times B]$ and $s$ has type $[B\times C]$ , then $r;s$ has type $[A\times C]$ .

How to type boolean operators in your script

This page shows how you can type boolean (and other) operators in your Ampersand script.

Other explanation

Would you like a different explanation of the relational operators? This page explains the relational operators in terms of set theory. This page explains them in natural language. Click here for some algebraic rules about relational operators.

Residual operators

are used when "" is involved.

right residual : . In other words: is in the right residual of and means that for every , pair is in relation implies that pair is in .
left residual : . In words: is in the left residual of and
means that for every pair is in relation implies that pair is in .
diamond: . In words: For every , both and are true or both are false.

How to type boolean operators in your script

shows how you can type boolean (and other) operators in your Ampersand script.

Other explanation

Would you like a different explanation of the residual operators? explains them in natural language. for visualized examples about residual operators.

Boolean operators in natural language

Purpose of boolean operators

To say things such as pair ("peter","macbook") is either in relation ownsa or wantsa, requires us to use boolean operators , , and .

Meaning

Let us explain the meaning of relational operators , , and by means of examples.

Assume we have a relation, ownsa[Person*LaptopType], which contains the persons who own a particular type of laptop. A fact "peter" ownsa "macbook" means that Peter owns a MacBook.

Also assume another relation wantsa[Person*LaptopType], which contains the persons who want a particular type of laptop. A fact "peter" wantsa "macbook" means that Peter wants a MacBook.

Union

The sentence: "Peter owns a MacBook or Peter wants a MacBook." is represented as "peter" (ownsa wantsa) "macbook".

Intersection

The sentence: "Peter owns a MacBook and Peter wants a MacBook." is represented as "peter" (label colour) "macbook".

Difference

The sentence: "Peter owns a MacBook and Peter does not want a MacBook." is represented as "peter" (label colour) "macbook".

Natural language templates

Other explanation

Relational operators in natural language

Purpose of relational operators

To say things such as "the name of the owner", we want to string together multiple relations (viz. name and owner). Relational operators allow us to make such statements.

Meaning

The meaning of relational operators and is best explained by means of examples.

Assume we have a relation, label[Contract*Colour], which contains the colour of labels on contracts. A fact "1834" label "blue" means that contract 1834 has a blue label.

Also assume another relation stored[Contract*Location], which gives the location where a contract is stored. Fact "1834" store "cabinet 42" means that contract 1834 is stored in cabinet 42.

Converse

A relation can be altered by swapping the elements of every pair in the relation. Mathematically, is a different from . In natural language, however, the meaning does not change. So if"1834" label "blue" means that contract 1834 has a blue label, "blue" label~ "1834" also means that contract 1834 has a blue label.

The sentence: "All contracts with a blue label are stored in cabinet 42." is represented as "blue" (label\stored) "cabinet 42". Literally it says: For every contract, if it has a blue label, then it is stored in cabinet 42.

Composition

The sentence "A contract with a blue label is stored in cabinet 42." can be represented as "blue" (label~;stored) "cabinet 42". Literally it says: There is a contract that has a blue label and is stored in cabinet 42.

Natural language templates

The natural language translation for b r~ ais the same as language translation for a r b.

Other explanation

Semantics in sets

Prototype multi-stage build

Syntactical Conventions

To keep this chapter as readable as possible, we have chosen to omit some details that are irrelevant for practically all &-modelers. In the very rare case that these technicalities are of interest, the reader could have a look in , where all EBNF statements are in comments.

Purpose

This page is meant as a reference for syntactical details and conventions, reserved words, etc.

Learning the syntax

The most effective way to learn Ampersand's syntax is to copy from existing scripts. This is learning by examples. This reference chapter is suitable to check things, and less suitable for learning.

Symbols

Ampersand has reserved words, such as RELATION, CONTEXT, CONTAINS. All reserved words are written in capital letters. They are introduced on the fly. You will find an exhaustive list of reserved words at the end of this page.

Untyped atoms are written between double quotes, e.g. "Peter" or "KD-686-D". If you want to introduce a double quote inside an atom, escape it with a backslash, e.g. "the symbol \" is called double quote". Numeric atoms always start with a digit, e.g. 4711 or 75.88E3. The boolean atoms are TRUE and FALSE. Dates and timestamps follow the Excel-syntax, e.g. ??? The atom _SESSION indicates the current user session, and is an instance of concept SESSION. It is used in services.

Brackets must always match. For terms, we use round brackets ( and ). For populations and services we use square brackets [ and ].

Constructs that contain ampersand statements are contexts and patterns. They always come in pairs: PATTERN and ENDPATTERN, and CONTEXT and ENDCONTEXT.

White space characters (spaces, tabs, CRLF) are meaningless. You can use them freely to layout your script in a way that helps you to recognize its structure.

A comment on a single line starts with --. Everything after a -- symbol is ignored until the line ends. Multiline comments are wrapped between comment brackets {- and -}. Multiline comments may be nested.

Identifiers always start with a letter. Concepts start with a capital letter, as in Person, Case, A, and Order. Relation names start with a lower case letter, as in contains, attr, sessionLogin, or r.

terms

terms are combined with operators. Binary operators may require brackets to avoid ambiguity. To save writing unneccessary brackets, some precedence rules are in place.

Within an operator category, you must place brackets to disambiguate. E.g. r/\s\/t is not allowed. You have to write either (r/\s)\/t or r/\(s\/t). Across categories, you may omit brackets because a higher precedence binds stronger. So r;s\/t means (r;s)\/t. (Note that (r;s)\/t and r;(s\/t) have different meanings). Associative operators (\/, /\, ;) need not be disambiguated with brackets. So r\/s\/t and (r\/s)\/t and r\/(s\/t) all mean exactly the same.

List of reserved words

Keywords in Ampersand are always written in CAPITALS.

Keywords for the main structure of the code
- ENDCONTEXT
- ENGLISH
- DUTCH
- META
- THEMES
- ENDPATTERN
- PRAGMA
- UNI
- INJ
- SUR
- TOT
- SYM
- ASY
- TRN
- RFX
- IRF
- PROP
- CONTAINS
- RULE
- MESSAGE
- VIOLATION
- TXT
- SRC
- TGT
- I
- V
- ONE
- ROLE
- MAINTAINS
Keywords for documentation
- REF
- REST
- HTML
- LATEX
- MARKDOWN
- INTERFACE
- FOR
- LINKTO
- BOX
Keywords for identities
Keywords for views
- VIEW
- ENDVIEW
- DEFAULT
- TEMPLATE
- HTML
Keywords for generalisations:
- CLASSIFY
- ISA
- IS
Keywords for TType:
- REPRESENT
- TYPE
- ALPHANUMERIC
- BIGALPHANUMERIC
- HUGEALPHANUMERIC
- PASSWORD
- BINARY
- BIGBINARY
- HUGEBINARY
- DATE
- DATETIME
- BOOLEAN
- INTEGER
- FLOAT
- AUTOINCREMENT
Reserved words for values of atoms:
- TRUE
- FALSE --for booleans
- _SESSION
Reserved words for concepts
- ONE
- SESSION
Experimental keywords:
- SERVICE
- EDITS
Deprecated keywords:
- SPEC
- KEY
- PROCESS
- ENDPROCESS

The ExecEngine

This chapter is meant for Ampersand users that want to build prototypes that automatically fix violations for specific rules. The idea behind this is quite simple: all it takes is another way of specifying violation texts. In practice, however, it takes some effort to learn how to do this correctly. Therefore, we only encourage you to do this if you are sufficiently motivated to spend this effort, i.e. if you are convinced it is worth your while.

Before studying this chapter, make sure you know how to predict violations. You need to understand how Ampersand computes violations, given a certain population.

Automated rules

Did you ever wonder how you can make your computer prevent rules from being violated? For that purpose, you must specify what your prototype will do the moment it signals a violation. This chapter tells you how.

In essence, an Ampersand prototype is a database application that helps its users to keep rules satisfied. Keeping a rule satisfied happens in one of the following ways: 1. Your prototype imposes a rule. Violations are not tolerated. The prototype does not accept any change of data that violates the rule. As a result, the rule remains satisfied all the time. Such rules are called invariants. 2. Your prototype signals each violation to a designated role. The signal does not go away until the user has eliminated the violation. The rule is called process rule because it prompts users to do some work. Notice that a violation of a process rule may persist. That is because it is meant to be resolved by persons rather than a computer. 3. Your prototype restores a violation the moment it occurs. It does so by means of a built-in robot, which we call the ExecEngine. Such rules are called automated. 4. The rule cannot be violated because of the way Ampersand is built. These rules are called laws. No effort is needed to maintain them, because they are always true.

This chapter is about the third category: automated rules. The idea is to prevent violations by acting in time, to satisfy the violated rule. This is nice for your users, who have no concern with those violations.

This chapter introduces automated rules by example. We will first create a rule, which a user must keep satisfied. We will then automate that process by adding instructions for the ExecEngine.

Learn by experimenting

Most of the examples are taken from the demo script Project Administration Example. You can compile and run this script, and reproduce several of the examples that follow.

Example (`InsPair` and `DelPair`)

Consider the following example:

RELATION pl[Project*Person]      MEANING "A project can have project leaders."
RELATION member[Project*Person]  MEANING "A person can do actual work within a project."
RELATION coworker[Person*Person] MEANING "Two people are co-workers in a project."

The following rule defines coworkers. Two different persons are coworker if they work in the same project. As a person can be either a project leader or a member, we get this rule:

RULE coworker = (pl\/member)~;(pl\/member)-I

This rule basically says that coworker is shorthand for the much more complicated term (pl\/member)~;(pl\/member)-I. Quite useful indeed. Now suppose this rule is satisfied in the system. Then some manager assigns a new person, Harry, to the project Zeus-III. To administer that fact in the system, he adds a pair ("Zeus-III", "Harry") to the relation member. Now there is a problem. The prototype will not accept this input, because our rule is violated. For all present workers in the project now have Harry as a new coworker. That should be administered in the relation coworker in order to satisfy the rule.

One way to do that is to allow the manager to edit the relation coworker. This is not very convenient for that manager. He will be irritated, as he is forced to enter a number of pairs into the relation coworker that is equal to the number of persons in the project plus the number of projectleaders of that project. This rule is typically a candidate for automation.

We have to consider that whenever a person is added to the project, that person must be added to coworker as well. But when a person is discharged from the project, that person must be removed from coworker. We can split the rule in two, knowing that r=s is always equivalent to both r|-s and s|-r.

ROLE "ExecEngine" MAINTAINS r1
RULE r1:  (pl\/member)~;(pl\/member)-I |- coworker
VIOLATION (TXT "InsPair;coworker;Person;", SRC I, TXT ";Person;", TGT I)

ROLE "ExecEngine" MAINTAINS r2
RULE r2:  coworker |- (pl\/member)~;(pl\/member)-I
VIOLATION (TXT "DelPair;coworker;Person;", SRC I, TXT ";Person;", TGT I)

Let us discuss both rules, starting with the first one. The ROLE statement assigns rule r1 to the ExecEngine. The instruction for the ExecEngine is given in the VIOLATION string. It will be executed for each violation of rule r1.

Elaborating on this example, just which violations will the ExecEngine resolve? Suppose the project has Alfred and Bob on the team before Harry is assigned. This means that the relation coworker contains ("Alfred", "Bob") and ("Bob", "Alfred") for starters. When the pair ("Zeus-III", "Harry") is added to the relation member, we get the following violations: ("Alfred", "Harry"), ("Harry", "Alfred"), ("Bob", "Harry"), and ("Harry", "Bob"). So, the following instructions will be given to the ExecEngine:

"InsPair;coworker;Person;Alfred;Person;Harry"
"InsPair;coworker;Person;Harry;Person;Alfred"
"InsPair;coworker;Person;Bob;Person;Harry"
"InsPair;coworker;Person;Harry;Person;Bob"

Note that the violations of rule r1 are precisely the pairs the ExecEngine must add to coworker to satisfy rule r1. The function InsPair is a predefined ExecEngine function, that adds to the population of a relation. The corresponding function DelPair removes pairs from the population of a relation. In the example, it is used to remove people from coworker that no longer share a project.

Notes:

The examples use SRC I or TGT I to produce atoms that are to be inserted or deleted. However, I may be any term whose source concept is the same as that of the preceeding SRC or TGT.
The SRC <term> and TGT <term> is a set of pairs (a,b), where a is the source atom or target atom of the violation and b is a set of atoms that is the result of <term>. In the examples given, this set of atoms has cardinality 1 (which is most often the case). However, if it is empty, that is considered regular behaviour, and this will hence not result in an error. Also, if it has a cardinality > 1, then InsPair will insert them all whereas DelPair will produce an error.

Example (`InsAtom`) and (`{EX}`)

Consider the following example:

RELATION pl[Project*Person]                     MEANING "A project can have project leaders."
RELATION project[Assignment*Project] [UNI,TOT]  MEANING "Every Assignment must apply to one project"
RELATION assignee[Assignment*Person] [UNI,TOT]  MEANING "Every Assignment must apply to one person"

The following rule states that for every project leader, an assignment must exist that applies to one person and one project, basically assigning that person to be a project leader for the Project.

RULE "Require Assignment" : pl |- project~;assignee

This calls for two different things: first, the automated creation of an atom in the concept Assignment, and second the consecutive population of relations project and assignee using this newly created atom.

This is specified as follows:

ROLE "ExecEngine" MAINTAINS "Create Assignment"
RULE "Create Assignment" : pl |- project~;assignee
VIOLATION (TXT "{EX} InsAtom;Assignment"
          ,TXT "{EX} InsPair;project;Assignment;_NEW;Project;", SRC I
          ,TXT "{EX} InsPair;assignee;Assignment;_NEW;Person;", TGT I
          )

First, note that we have three consecutive statements: an InsAtom command followed by two InsPairs. Using the phrase {EX} in front of each statement allows the interpreter of the violation texts to recognize each individual command and its arguments. In order to ensure that you do not forget about this, you may want to consider habituating yourself to always use {EX} before any function.

The first statement assigns the rule Create Assignment to the ExecEngine. The prototype will send all violations of this rule to the ExecEngine. The rule says that for every project with a project leader, there must be an assignment. Without that assignment, the rule is violated. The VIOLATION statement specifies that a new Assignment must be made for each violation. For that purpose, we use the predefined function InsAtom. This function takes a single argument, being the concept within which an atom has to be generated (Assignment in the example).

The second statement calls the InsPair function in order to populate the relation project, in the manner we described above. Note that at the position where we want to specify the newly created Assignment atom, we use the phrase _NEW. The third statement calls the InsPair function in a similar fashion, and thus populates the relation assignee.

Note that

in an InsPair (or DelPair), the source-atom or the target-atom (or both) can be the keyword _NEW.
the keyword _NEW refers to the last atom that was created by the (last) InsAtom statement that was executed in the violation.
when using _NEW, the corresponding concept (obviously) MUST be the same as the concept as specified in the InsAtom statement.

Here is how it works. Suppose the pair ("Zeus-III", "Rhea") is added to the relation pl, meaning that Rhea is being made a project leader of project Zeus-III. This produces a violation ("Zeus-III", "Rhea") of the rule Create Assignment. The associated VIOLATION statement produces the text

 {EX} InsAtom;Assignment{EX} InsPair;project;Assignment;_New;Project;Zeus-III{EX} InsPair;assignee;Assignment;_NEW;Person;Rhea

which is passed to the ExecEngine, which splits the text in three statements

 InsAtom;Assignment
 InsPair;project;Assignment;_New;Project;Zeus-III
 InsPair;assignee;Assignment;_NEW;Person;Rhea

and subsequently executes them. Executing the InsAtom statement creates a new atom in concept Assignment (let's say it is Assignment_3495812395. The keywords _NEW in the InsPair statements are then replaced by Assignment_3495812395, so that ("Assignment_3495812395", "Zeus-III") is inserted into relation project[Assignment*Project], and ("Assignment_3495812395", "Rhea") is inserted into relation assignee[Assignment*Person].

Example (`DelAtom`)

In our example, whenever a project participant is discharged from his task, the corresponding Assignment needs to be deleted. We can do this by means of an automated rule:

ROLE "ExecEngine" MAINTAINS "Delete Assignment"
RULE "Delete Assignment" :  project~;assignee |- pl\/member
VIOLATION ( TXT "DelAtom;Assignment;", SRC I)

The function 'DelAtom' is predefined, and takes two arguments: 1. the concept from which an atom is to be deleted; 2. the actual atom to be deleted.

Note that when an atom is deleted, also every pair (in any relation) is deleted if either its source atom or target atom is the deleted atom.

Example (`_;`)

When you try to create or delete pairs with atoms that contain texts, you may find that some texts contain the semi-colon. When such a text is used in a violation statement, this will be interpreted as an argument separator, causing all sorts of unexpected results. This can be prevented by using _; rather than ; as an argument separator. However, the ExecEngine must be made aware that this alternative argument separator is used. This is done by mentioning it immediately at the beginning of a function call, as in the below example:

VIOLATION (TXT "{EX}_;InsPair_;r1_;A_;", SRC I, TXT "_;B_;", TGT I)

Of course, if the SRC or TGT atom is a text that contains the characters _;, the problem still remains...

Example (`TransitiveClosure`)

Consider the r :: A * A [IRF,ASY]. In relation algebra, terms such as r+ or r* are allowed, designating the transitive closure of r. The + and * operators are currently not supported in Ampersand.

This section describes a workaround that allows you to use transitive closures.To do so, we simply define a relation rPlus :: A * A and/or rStar :: A * A, and define the following automated rules to populate these relations:

 ROLE ExecEngine MAINTAINS "Grow rPlus"
 RULE "Grow rPlus": r;rPlus \/ rPlus;r |- rPlus
 VIOLATION (TXT "{EX} InsPair;rPlus;A;", SRC I, TXT ";A;", TGT I)

 ROLE ExecEngine MAINTAINS "Shrink rPlus"
 RULE "Shrink rPlus": rPlus |- r;rPlus \/ rPlus;r
 VIOLATION (TXT "{EX} DelPair;rPlus;A;", SRC I, TXT ";A;", TGT I)

 ROLE ExecEngine MAINTAINS "Grow rStar"
 RULE "Grow rStar": r \/ r;rStar \/ rStar;r |- rStar
 VIOLATION (TXT "{EX} InsPair;rStar;A;", SRC I, TXT ";A;", TGT I)

 ROLE ExecEngine MAINTAINS "Shrink rStar"
 RULE "Shrink rStar": rStar |- r \/ r;rStar \/ rStar;r
 VIOLATION (TXT "{EX} DelPair;rStar;A;", SRC I, TXT ";A;", TGT I)

While this works (certainly in theory), a practical issue is that it quickly becomes very timeconsuming as the population of r grows, up to an unacceptable level. Also, Ampersand prototypes have a time limit (30 or 60 seconds) for an ExecEngine run. In order to make transitive closures a bit more practicable (but certainly not workable for 'real' software), we can use the predefined ExecEngine function TransitiveClosure, as follows:

 rCopy :: A * A
 MEANING "a copy of the relation `r`, needed to detect deletions in `r`"

 rPlus :: A * A 
 ROLE ExecEngine MAINTAINS "Warshall on r"
 RULE "Warshall on r": rCopy = r
 VIOLATION (TXT "{EX} TransitiveClosure;r;A;rCopy;rPlus")

What this does is the following. Any time that r is being (de)populated, the rule Warshall on r is violated. This calls the (predefined) function TransitiveClosure with its four arguments, the result of which is that 1. the relation rPlus is computed as the (smallest) transitive closure of r (using the Warshall algorithm); 2. the relation rCopy is made to have the same population as r, thereby resolving all violations of the rule.

Note that if you want to use (the equivalent of) r* somewhere in an term, the most practical way is to use the term (I \/ rPlus) at that spot.

HELP! I got errors!

As an Ampersand user, you are used to getting error messages from the compiler. Yet, errors in rules for the Exec-engine are not signalled by the compiler. Instead, you get run-time error message that some inexperienced users find hard to work with, as it requires some knowledge of the backgrounds.

Here are some tips. 1. Most (all?) predefined functions check for a valid number of arguments. If the error message relates to the number of arguments, 1. you have missed out on a ;. The function NewStruct is well-known to produce this error, because of the wealth of arguments allowed. Learning and maintaining a strict discipline regarding how you write such (e.g. NewStruct) statements is a big help in preventing this error from occurring. 2. you may have to many ;s. Of course, you may just mistakenly having written too many ;s. Another, less known cause is where a violation occurs on an atom that happens to be a text containing one or more ; characters. This will cause the ExecEngine to interpret the text as multiple arguments, which (usually) results in an illegal number of arguments error. The cure is to use the _; separator rather than the ; separator (see the appropriate section above). 2. Most (all?) predefined functions that have arguments to specify a relation definition, will check (at run-time) whether or not this relation is actually defined (at define-time). Misspellings in relation or concept names (e.g. capitalizations) often cause this error. 3. You should specify a relation just with its name, e.g. project (not: project[Assignment*Project]). The reason for this is that it (currently) is the ExecEngine itself that parses the violation string (rather than the Ampersand compiler). This very simple parser does not handle [Assignment*Project]-like constructs. 4. For the same reason (simple ExecEngine parser), there is no type checking for the ExecEngine functions. This means that you must check yourself whether or not the type of atom(s) you want to insert or delete match with the source or target atom of the relation you try to (de)populate. 5. Look at the log window to get more information on what is actually happening when the ExecEngine executes. You can turn it on by clicking on the left-most icon of the icon-list that is at the right hand side in the menu bar. There, you turn on the 'Show log window'. In the log window, you can select what you do and do not see. Options you may want to select include 'ExecEngine', 'RuleEngine' and 'Database'. 6. If everything else fails, read the error messages and log lines slowly and carefully, as they (sometimes unexpectedly) do provide information that may actually help you to resolve the issue at hand.

For the time that researchers are working on this problem, you will have to live with all this. It makes programming of automated rules initially error-prone and time consuming, but when you get the hang of it, it gets better. Still, the best piece of advice we can currently give here is:

Keep automated rules simple.
Test thoroughly.

Ways to run the ExecEngine (one or more times)

The ExecEngine currently is a simple one. Whenever it executes, it evaluates the automated rules one after another. Whenever an automated rule produces violations, the associated violation text is executed for every such violation.

While rules are most often evaluated in the order in which they are defined, you really should not make any assumptions about the evaluation order (nor about the order in which violations of a rule are processed). Hence, it may happen that the violations are processed 'out of order', resulting in violations of automated rules that could 'easily' have been fixed.

To overcome this issue, the ExecEngine (by default) simply runs itself again, until all automated rules have no violations any more, or until the maximum amount of such reruns has been reached - this limit is set to guarantee that execution terminates. The default number of maximum reruns is 10 (decimal). You can modify this setting in LocalSettings.php, , by (including and/or) modifying the following texts:

 Config::set('maxRunCount', 'execEngine', 10);

For research or debugging purposes, it may sometimes be neccesary to have further control over the manner in which the ExecEngine does. There are three possibilities for running the ExecEngine:

Automatically. This is the default behaviour. Turning the autoRerun feature off means that the ExecEngine will always run only once when called. You can specify this in the file LocalSettings.php, by replacing the text true by false in the line that contains the text:
Config::set('autoRerun', 'execEngine', true);
Manually. This is when you, as a user, clik on the refresh/reset options icon in a prototype, and the select Run execution engine. Note that if you also use logins, you must have been assigned a role that allows you to do this, or you won't see this option.
By using the ExecEngine function RerunExecEngine, which takes one argument (an explanatory text, that is used for logging - see the example below). Whenever the ExecEngine calls this function, a flag is set requesting a rerun. When, at the end of an ExecEngine run, this flag is set, the ExecEngine will run itself again.

Here is an example of how RerunExecEngine can be used to create a transitive closure:

 r :: A * A [ASY]
 rStar :: A * A -- This will contain a transitive closure

 ROLE ExecEngine MAINTAINS "InsPair on rStar"
 RULE "InsPair on rStar": r \/ r;rStar \/ rStar;r |- rStar
 VIOLATION (TXT "{EX} InsPair;rStar;A;", SRC I, TXT ";A;", TGT I
           ,TXT "{EX} RerunExecEngine;InsPair on rStar"
           )
 ROLE ExecEngine MAINTAINS "DelPair on rStar"
 RULE "DelPair on rStar": rStar |- r \/ r;rStar \/ rStar;r
 VIOLATION (TXT "{EX} DelPair;rStar;A;", SRC I, TXT ";A;", TGT I
           ,TXT "{EX} RerunExecEngine;DelPair on rStar"
           )