# ASP DSL Quickstart Guide
**Learn the ASP DSL in 5 minutes!**
## What is ASP DSL?
The ASP DSL is a language for expressing Answer Set Programming problems. It outputs **valid Clingo syntax** that you can run directly with the Clingo solver.
### Key Concept: It's Real ASP
Unlike other DSLs that translate to different languages, ASP DSL programs ARE valid Clingo code:
```asp
% This is both valid ASP DSL and valid Clingo syntax!
color(red; blue; green).
1 {assign(X, C) : color(C)} 1 :- vertex(X).
#show assign/2.
```
## Hello World: Graph Coloring
Let's color a simple triangle graph with 3 colors.
### Step 1: Define the Problem
```asp
% Vertices of the triangle
vertex(1). vertex(2). vertex(3).
% Edges forming a triangle
edge(1, 2). edge(2, 3). edge(3, 1).
% Available colors
color(red; blue; green).
```
### Step 2: Add Choice Rules
```asp
% Each vertex gets exactly one color
1 {assign(X, C) : color(C)} 1 :- vertex(X).
```
**Translation:** For each vertex X, choose exactly 1 color C from the available colors.
### Step 3: Add Constraints
```asp
% Adjacent vertices cannot have the same color
:- assign(X, C), assign(Y, C), edge(X, Y).
```
**Translation:** Eliminate any solution where vertices X and Y are connected by an edge and have the same color C.
### Step 4: Control Output
```asp
% Show only color assignments
#show assign/2.
```
### Complete Program
```asp
% Facts: graph structure
vertex(1). vertex(2). vertex(3).
edge(1, 2). edge(2, 3). edge(3, 1).
% Facts: available colors
color(red; blue; green).
% Choice rule: assign colors
1 {assign(X, C) : color(C)} 1 :- vertex(X).
% Constraint: no adjacent same colors
:- assign(X, C), assign(Y, C), edge(X, Y).
% Output control
#show assign/2.
```
### Running It
**With ASP DSL:**
```typescript
const result = await aspSystem.solve(program);
```
**With Clingo directly:**
```bash
echo "..." > triangle.lp
clingo triangle.lp
```
**Output:**
```
Answer: 1
assign(1,red) assign(2,blue) assign(3,green)
Answer: 2
assign(1,red) assign(2,green) assign(3,blue)
...
SATISFIABLE
Models: 6
```
## Core Syntax Elements
### 1. Facts
```asp
person(alice). % Simple fact
age(alice, 30). % Fact with multiple arguments
likes(alice, bob). % Binary relation
```
**Meaning:** These are always true.
### 2. Rules
```asp
friend(X, Y) :- knows(X, Y), trusts(X, Y).
```
**Meaning:** "X and Y are friends IF X knows Y AND X trusts Y"
**Structure:** `head :- body.`
### 3. Choice Rules
```asp
{selected(X) : item(X)}.
```
**Meaning:** "For each item X, choose whether to include selected(X) or not"
**With bounds:**
```asp
2 {team(P) : person(P)} 5.
```
**Meaning:** "Choose between 2 and 5 people for the team"
### 4. Constraints
```asp
:- person(X), age(X, A), A < 18, selected(X).
```
**Meaning:** "Eliminate solutions where a person under 18 is selected"
**Structure:** `:- conditions.`
### 5. Negation
**Default negation (not):**
```asp
fly(X) :- bird(X), not penguin(X).
```
**Meaning:** "X flies if X is a bird and we cannot prove X is a penguin"
**Classical negation (-):**
```asp
-broken(X) :- tested(X), working(X).
```
**Meaning:** "X is explicitly NOT broken"
### 6. Aggregates
```asp
% Count
large_class(C) :- #count{S : enrolled(S, C)} > 50.
% Sum
expensive :- #sum{P, I : item(I), price(I, P)} > 100.
% Min/Max
oldest(P) :- person(P), age(P, A),
#max{X : person(Q), age(Q, X)} = A.
```
### 7. Optimization
```asp
% Minimize number of colors used
#minimize {1, C : assign(X, C)}.
% Maximize profit
#maximize {P, X : selected(X), profit(X, P)}.
```
## Common Patterns
### Pattern 1: Generate-and-Test
```asp
% GENERATE: Create solution candidates
{in_solution(X) : candidate(X)}.
% TEST: Eliminate bad solutions
:- in_solution(X), in_solution(Y), conflicts(X, Y).
```
### Pattern 2: Exactly-One Selection
```asp
% Each person assigned to exactly one shift
1 {assign(P, S) : shift(S)} 1 :- person(P).
```
### Pattern 3: All Different
```asp
% All variables have different values (implicit from choice rule)
1 {value(V, X) : number(X)} 1 :- variable(V).
```
### Pattern 4: Reachability
```asp
% Define reachability from start node
reachable(X) :- start(X).
reachable(Y) :- reachable(X), edge(X, Y).
% Constraint: all nodes must be reachable
:- vertex(V), not reachable(V).
```
## Five Quick Examples
### Example 1: N-Queens (4x4)
```asp
% Board size
row(1..4). col(1..4).
% Place exactly one queen per row
1 {queen(R, C) : col(C)} 1 :- row(R).
% No two queens in same column
:- queen(R1, C), queen(R2, C), R1 != R2.
% No diagonal attacks
:- queen(R1, C1), queen(R2, C2), R1 != R2, |C1 - R1| = |C2 - R2|.
:- queen(R1, C1), queen(R2, C2), R1 != R2, C1 + R1 = C2 + R2.
#show queen/2.
```
### Example 2: Scheduling
```asp
% Employees and shifts
employee(alice; bob; carol).
shift(morning; afternoon; evening).
% Each employee works exactly one shift
1 {assign(E, S) : shift(S)} 1 :- employee(E).
% Each shift needs 1-2 employees
1 {assign(E, S) : employee(E)} 2 :- shift(S).
% Alice cannot work morning
:- assign(alice, morning).
#show assign/2.
```
### Example 3: Sudoku (Simplified 4x4)
```asp
% Grid 4x4, numbers 1-4
cell(1..4, 1..4). num(1..4).
% Each cell has exactly one number
1 {sudoku(R, C, N) : num(N)} 1 :- cell(R, C).
% Row constraint
:- sudoku(R, C1, N), sudoku(R, C2, N), C1 != C2.
% Column constraint
:- sudoku(R1, C, N), sudoku(R2, C, N), R1 != R2.
% Given clues
sudoku(1, 1, 3).
sudoku(2, 3, 1).
#show sudoku/3.
```
### Example 4: Knapsack
```asp
% Items with weights and values
item(a; b; c; d).
weight(a, 4). weight(b, 3). weight(c, 5). weight(d, 2).
value(a, 5). value(b, 4). value(c, 7). value(d, 3).
capacity(10).
% Select items
{selected(I) : item(I)}.
% Don't exceed capacity
:- #sum{W, I : selected(I), weight(I, W)} > C, capacity(C).
% Maximize value
#maximize {V, I : selected(I), value(I, V)}.
#show selected/1.
```
### Example 5: Hamiltonian Path
```asp
% Graph
vertex(1..5).
edge(1,2). edge(2,3). edge(3,4). edge(4,5). edge(5,1).
edge(X,Y) :- edge(Y,X). % Make undirected
start(1).
% Select path edges
{in_path(X, Y)} :- edge(X, Y).
% Each vertex (except start) has exactly one incoming edge
1 {in_path(Y, X) : edge(Y, X)} 1 :- vertex(X), not start(X).
% Each vertex has at most one outgoing edge
{in_path(X, Y) : edge(X, Y)} 1 :- vertex(X).
% Start has exactly one outgoing edge
1 {in_path(X, Y) : edge(X, Y)} 1 :- start(X).
% No incoming to start
:- in_path(Y, X), start(X).
% Reachability
reach(X) :- start(X).
reach(Y) :- reach(X), in_path(X, Y).
% All vertices must be reachable
:- vertex(V), not reach(V).
#show in_path/2.
```
## Using Natural Language
ASP DSL can understand natural language problem descriptions:
```typescript
// Input: Natural language
const input = "Color a cycle graph with 5 vertices using 3 colors";
// ASP DSL detects problem type and generates program
const result = await aspSystem.solve(input);
```
**Generated program:**
```asp
vertex(1..5).
edge(1,2). edge(2,3). edge(3,4). edge(4,5). edge(5,1).
color(1..3).
1 {assign(X, C) : color(C)} 1 :- vertex(X).
:- assign(X, C), assign(Y, C), edge(X, Y).
#show assign/2.
```
## Using Templates
Templates provide pre-built solutions for common problems:
```typescript
const result = await aspSystem.solveWithTemplate('graph_coloring', {
vertices: [1, 2, 3, 4, 5],
edges: [[1,2], [2,3], [3,4], [4,5], [5,1]],
numColors: 3
});
```
**Available Templates:**
- `graph_coloring` - Color graph nodes
- `hamiltonian_path` - Find Hamiltonian paths/cycles
- `scheduling` - Schedule tasks/people
- `n_queens` - Solve N-Queens puzzle
- `sudoku` - Solve Sudoku puzzles
- `knapsack` - Solve knapsack problems
- `configuration` - System configuration
## Default Logic Extension
ASP DSL supports default logic with special syntax:
```asp
% Default logic syntax
typically flies(X) if bird(X) unless penguin(X).
% Compiles to ASP:
flies(X) :- bird(X), not ab_flies(X).
ab_flies(X) :- penguin(X).
```
**More examples:**
```asp
typically available(X) if resource(X) unless reserved(X).
typically open(S) if store(S) unless holiday.
```
## Common Mistakes & Solutions
### Mistake 1: Unsafe Variables
❌ **Wrong:**
```asp
path(X, Y) :- edge(Y, Z).
```
**Error:** X doesn't appear in body!
✅ **Correct:**
```asp
path(Y, Z) :- edge(Y, Z).
```
### Mistake 2: Missing Periods
❌ **Wrong:**
```asp
vertex(1)
vertex(2)
```
✅ **Correct:**
```asp
vertex(1).
vertex(2).
```
### Mistake 3: Unbounded Domains
❌ **Slow:**
```asp
number(X) :- X = 1..1000000. % Huge grounding!
```
✅ **Better:**
```asp
number(1..100). % Reasonable size
```
### Mistake 4: Forgetting #show
Without `#show`, you get ALL atoms:
```asp
% Lots of output including auxiliary predicates
```
With `#show`:
```asp
#show assign/2. % Only show what matters
```
## Next Steps
1. **Try the examples** - Copy and run them
2. **Read the specification** - [ASP_DSL_SPECIFICATION.md](ASP_DSL_SPECIFICATION.md)
3. **Explore templates** - [ASP_DSL_TEMPLATES.md](ASP_DSL_TEMPLATES.md)
4. **Study more examples** - [ASP_DSL_EXAMPLES.md](ASP_DSL_EXAMPLES.md)
## Quick Reference Card
```asp
% Facts
atom.
predicate(arg1, arg2).
% Rules
head :- body_literal1, body_literal2.
% Choice rules
{atom1; atom2; atom3}.
L {atoms} U :- condition.
% Constraints
:- bad_condition.
% Negation
not atom % Default negation
-atom % Classical negation
% Aggregates
#count{Vars : condition}
#sum{Weight, Vars : condition}
% Optimization
#minimize {Weight, Terms : condition}.
#maximize {Weight, Terms : condition}.
% Output
#show predicate/arity.
```
---
**You're ready to start using ASP DSL! Try the examples and have fun!**
