# Archer Modeling Language

Archer modeling language is a domain-specific language designed to model configuration models based on variables and constraints. It provides a powerful way to specify relationships between variables (features) and express conditional logic using a simple syntax that is easy to read and understand. The language is designed to be flexible and extensible, allowing users to define custom functions and integrate them into their models.

With Archer modeling language, users can create complex configuration models that accurately represent real-world systems. The language supports a wide range of constraints, including equality, inequality, logical operators, and more. It also allows users to define decision variables and objective functions, enabling them to optimize their models and find the best solution for a given set of inputs.

Whether you're a domain expert or a software developer, Archer modeling language provides a powerful tool for modeling configuration models in your area of expertise. With its intuitive syntax and flexible design, Archer modeling language makes it easy to create and analyze complex systems, enabling you to make better decisions and achieve better outcomes.

## Defining models

To define a model in Archer modeling language, use the following syntax: `model ModelName { }`

. Replace `ModelName`

with the name of your model. Inside the curly braces, you can define all of the model's variables and constraints. To specify relationships between variables, use the following syntax: `VariableA - RelationshipType -> VariableB`

. Replace `VariableA`

and `VariableB`

with the names of the variables you want to relate, and `RelationshipType`

with the type of relationship you want to specify.

For example, suppose you want to model a smartphone with a certain amount of storage and memory, and optional GPS functionality. You can define a model named `Phone`

using the following code:

`model Phone {`

Phone - mandatory -> Storage

Phone - mandatory -> Memory

Phone - optional -> GPS

Phone - mandatory -> Screen

Screen - alternative -> HD

Screen - alternative -> OLED

constraint Storage >= 16

constraint Memory >= 2

}

In this example, we've defined five variables, `Storage`

, `Memory`

, `GPS`

, `Screen`

, `HD`

, and `OLED`

, and related them to the `Phone`

model using the appropriate relationship types. The `GPS`

variable is optional, while the others are mandatory. The `Screen`

variable is related to two alternative variables, `HD`

and `OLED`

, using the `- alternative ->`

relationship type. We've also defined two constraints using the constraint keyword. The first constraint specifies that the `Storage`

variable must be greater than or equal to 16, while the second constraint specifies that the Memory variable must be greater than or equal to 2. This model defines a smartphone with a minimum of 16 GB of storage and 2 GB of memory, and provides optional GPS functionality and two alternative screen options, `HD`

and `OLED`

.

### Defining relationships

Relationships are used to define how different variables in a model relate to each other. The relationship statement syntax uses the form

`ID1 - REL_TYPE -> ID2`

where `ID1`

and `ID2`

are the IDs of the variables being related, and `REL_TYPE`

is the type of relationship being defined. There are 2 categories of relationships: structural and logical. Structural relationships are used to define the structure of a model, while logical relationships are used to define the logic of a model.

#### Structural relationships

Type | Description |
---|---|

mandatory | This relationship type indicates that a variable is required in a model. If a variable is mandatory, it must be present if its parent is present. |

optional | This relationship type indicates that a variable is not required, but may be included if desired. |

alternative | This relationship type indicates that a variable can be substituted by another variable. If one alternative variable is chosen, the others become invalid. |

or | This relationship type indicates that at least one of a set of variables must be included in a model. |

#### Logical relationships

Type | Description |
---|---|

excludes | This relationship type indicates that two variables cannot be included in a model at the same time. |

requires | This relationship type indicates that one variable requires another variable to be included in a model. |

filters | This relationship type indicates that one variable is used to filter or limit the options available for another variable. |

suggests | This relationship type indicates that one variable suggests another variable as a potential addition to a model. |

removes | This relationship type indicates that one variable removes another variable as a potential addition to a model. |

### Defining variable value bounds

Archer modeling language supports variable value bounds, which allow you to specify the minimum and maximum values that a variable can take. To specify a variable's bound you can use the following syntax: `lower_bound ID1 = <EXPR>`

. Replace `ID1`

with the ID of the variable you want to set the lower bound for, and `<EXPR>`

with the expression that defines the lower bound.

The expression can include constants, variables, and arithmetic operations. For example,

`lower_bound ID1 = 1 + 3 * ID2.Value`

sets the lower bound of variable ID1 to 1 plus three times the value of variable ID2.

Similarly, you can define the upper bound of variable `ID1`

you can use:

`lower_bound ID1 = ID2.Value * 3`

### Defining variable conditions

Archer modeling language supports variable conditions, which allow you to specify the conditions under which a variable can be included in a model. To specify a variable's condition you can use the following syntax: `condition ID1 = <EXPR>`

. Replace `ID1`

with the ID of the variable you want to set the condition for, and `<EXPR>`

with the expression that defines the condition.

The expression can include constants, variables, and arithmetic operations. For example,

`condition ID1 = ID2.Value > 3`

will only allow variable `ID1`

to be included in a model if the value of variable `ID2`

is greater than 3. If the condition is not met, the variable will be removed from the model.

### Defining constraints

Archer modeling language supports constraints, which allow you to specify the conditions that must be met by a model. To specify a constraint you can use the following syntax: `constraint <EXPR>`

. Replace `<EXPR>`

with the expression that defines the constraint.

The expression can include constants, variables, and arithmetic operations. For example,

`constraint A.Value + B.Value > C.Value`

will ensure that the sum of the values of variables `A`

and `B`

is greater than the value of variable `C`

.

## Expressions

Archer modeling language supports a wide range of expressions, including arithmetic, logical, and comparison operations. Expressions can be used to define variable bounds, variable conditions, and constraints.

### Arithmetic expressions

Archer modeling language supports arithmetic expressions, which allow you to perform arithmetic operations on variables and constants. The following table lists the supported arithmetic operations:

Operation | Description |
---|---|

`+` | Addition |

`-` | Subtraction |

`*` | Multiplication |

`/` | Division |

### Comparison expressions

Archer modeling language supports comparison expressions, which allow you to perform comparison operations on variables and constants. The following table lists the supported comparison operations:

Operation | Description |
---|---|

`==` | `=` | Equal to |

`<` | Less than |

`<=` | Less than or equal to |

`>` | Greater than |

`>=` | Greater than or equal to |

### Logical expressions

Archer modeling language supports logical expressions, which allow you to perform logical operations on variables and constants. The following table lists the supported logical operations:

Operation | Description |
---|---|

`&&` | `and` | Logical AND |

|| | `or` | Logical OR |

### Function expressions

Archer modeling language supports function expressions, which allow you to perform operations on variables and constants. The following table lists the supported functions:

Function | Description |
---|---|

`pow` | Returns the value of the first argument raised to the power of the second argument. |

`sqrt` | Returns the square root of the value of the argument. |

`floor` | Returns the largest integer less than or equal to the value of the argument. |

`abs` | Returns the absolute value of the value of the argument. |

`min` | Returns the minimum value of the arguments. |

`max` | Returns the maximum value of the arguments. |

`sum` | Returns the sum of the arguments. |

`iff` | `if` | `ite` | Returns the second argument if the first argument is true, otherwise returns the third argument. |

`distinct` | `alldiff` | Returns true if all arguments are distinct, otherwise returns false. |

## Integrating with Python

Archer allows direct integration with any Python script. For more information see Python Integration with Archer.

## Common Mistakes

**Incorrect relationship syntax**: Relationships between variables are defined using arrows (`->`

). Make sure the arrow points from the parent variable to the child variable, like`ParentVariable - relationship -> ChildVariable`

.**Ignoring value bounds**: When defining variables that have a certain range or limit, don't forget to define the lower and upper bounds. These bounds can prevent models from having impractical or impossible configurations.**Misusing logical relationships**: Be careful when using logical relationships like`excludes`

,`requires`

, etc. Using them incorrectly can lead to constraints that are contradictory or don't make sense in the context of the model.

Remember, practicing and reviewing your models can help avoid these common mistakes. Always double-check your models for these errors before finalizing them.