Skip to content

Commit 698d408

Browse files
radevgitradevgit
committed
Update Zinc document
1 parent 7cf3a25 commit 698d408

File tree

1 file changed

+162
-0
lines changed

1 file changed

+162
-0
lines changed

‎docs/development/ZINC.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
## 2a. Survey of Existing Parsers and Design Notes
2+
3+
- **Rust ecosystem:** No mature Rust crates exist for FlatZinc or MiniZinc parsing as of 2025. Most solvers in other languages (C++, Python, Java) implement their own parser or use the official C++ library (libminizinc).
4+
- **Reference implementations:**
5+
- [MiniZinc/libminizinc](https://github.com/MiniZinc/libminizinc): Official C++ library with FlatZinc parser (useful for grammar/structure reference).
6+
- [Chuffed](https://github.com/chuffed/chuffed): C++ solver with FlatZinc parser.
7+
- [Google OR-Tools](https://github.com/google/or-tools): C++ FlatZinc parser.
8+
- **Design takeaways:**
9+
- FlatZinc is line-oriented and regular, making it feasible to hand-write a parser in Rust.
10+
- The official FlatZinc BNF grammar is a good starting point for tokenizer and parser design.
11+
- Most solvers use a simple recursive-descent parser or state machine for FlatZinc.
12+
- **No external dependencies:** All parsing and lexing will be implemented manually in Rust, using only the standard library.
13+
14+
---
15+
16+
## 2b. Crate Organization: Standalone vs Integrated Parser
17+
18+
**Option 1: Separate Crate**
19+
- Pros:
20+
- Parser can be reused in other projects or solvers.
21+
- Clear separation of concerns; easier to test and document parser independently.
22+
- Encourages clean API boundaries.
23+
- Cons:
24+
- Slightly more maintenance overhead (versioning, publishing, documentation).
25+
- May be overkill if parser is tightly coupled to Selen's internal model.
26+
27+
**Option 2: Integrated in Selen Crate**
28+
- Pros:
29+
- Simpler project structure; no need for cross-crate dependencies.
30+
- Easier access to Selen's internal types and APIs.
31+
- Faster iteration for project-specific needs.
32+
- Cons:
33+
- Harder to reuse parser in other projects.
34+
- Parser code may become entangled with solver logic.
35+
36+
**Recommendation:**
37+
- If you anticipate reusing the FlatZinc parser in other Rust projects or want to encourage community adoption, a separate crate is preferable.
38+
- If the parser will be tightly integrated with Selen's internal model and not reused elsewhere, keep it as a module within this crate for simplicity.
39+
# MiniZinc Import: Detailed Implementation Plan
40+
41+
## 1. Scope and Requirements
42+
43+
- **Goal:** Enable parsing and importing of MiniZinc (.mzn) model files (and optionally .dzn data files) into the Selen CSP solver, mapping them to internal model structures.
44+
- **Directory:** Implementation is scoped to `docs/development/` (for planning/design) and the relevant Rust source directory for code.
45+
- **Constraints:** No external dependencies (no crates for parsing, lexing, or MiniZinc).
46+
47+
---
48+
49+
50+
## 2. MiniZinc and FlatZinc Standards and References
51+
52+
- **MiniZinc Language Reference (2.8.4):**
53+
- [MiniZinc 2.8.4 Language Reference](https://www.minizinc.org/doc-2.8.4/en/index.html)
54+
- [MiniZinc Grammar (BNF)](https://github.com/MiniZinc/libminizinc/blob/master/doc/grammar/minizinc.bnf)
55+
- **FlatZinc Specification (2.8.4):**
56+
- [FlatZinc 2.8.4 Specification](https://www.minizinc.org/doc-2.8.4/en/fzn-spec.html)
57+
- **File Types:**
58+
- `.mzn` — Model files (constraints, variables, parameters)
59+
- `.dzn` — Data files (parameter assignments)
60+
- **Key Language Features:**
61+
- Variable declarations (int, bool, set, array)
62+
- Constraints (global, arithmetic, logical)
63+
- Parameters and data separation
64+
- Solve annotations (satisfy, minimize, maximize)
65+
- Comments (`% ...`)
66+
- **Subset Recommendation:**
67+
- Start with a subset: integer/boolean variables, basic constraints, arrays, and parameter assignment.
68+
69+
---
70+
71+
## 3. Implementation Complexity
72+
73+
- **Parsing:**
74+
- Must hand-write a recursive-descent parser or a simple tokenizer and parser for the MiniZinc subset.
75+
- Handle comments, whitespace, identifiers, literals, arrays, and basic expressions.
76+
- **Mapping:**
77+
- Map MiniZinc constructs to Selen’s internal model (variables, constraints, objectives).
78+
- **Error Handling:**
79+
- Provide clear error messages for unsupported or malformed input.
80+
- **Extensibility:**
81+
- Design parser to allow future support for more MiniZinc features.
82+
83+
**Estimated Complexity:**
84+
- **Minimal Subset:** Moderate (basic parser, mapping, error handling)
85+
- **Full MiniZinc:** High (complex grammar, global constraints, advanced types)
86+
87+
---
88+
89+
## 4. Implementation Plan
90+
91+
### Step 1: Research and Design
92+
93+
- Review MiniZinc language reference and grammar.
94+
- Identify the minimal viable subset to support (variables, constraints, arrays, basic arithmetic).
95+
- Document mapping from MiniZinc constructs to Selen’s API.
96+
97+
### Step 2: Write a MiniZinc Tokenizer
98+
99+
- Implement a tokenizer for MiniZinc syntax:
100+
- Recognize keywords, identifiers, numbers, symbols, comments, and whitespace.
101+
- Output a stream of tokens for the parser.
102+
103+
### Step 3: Implement a Recursive-Descent Parser
104+
105+
- Parse MiniZinc model files into an AST (abstract syntax tree).
106+
- Support:
107+
- Variable declarations (int, bool, array)
108+
- Parameter assignments
109+
- Constraint statements
110+
- Solve annotations (optional, for future)
111+
- Ignore unsupported features with clear errors.
112+
113+
### Step 4: Map AST to Selen Model
114+
115+
- Translate parsed MiniZinc AST into Selen’s internal model:
116+
- Create variables, post constraints, set objectives.
117+
- Handle arrays and parameter substitution.
118+
119+
### Step 5: Integrate and Test
120+
121+
- Add import API (e.g., `Model::import_minizinc(path: &str) -> Result<Model, Error>`).
122+
- Write unit tests with sample MiniZinc files.
123+
- Document supported features and limitations.
124+
125+
---
126+
127+
128+
## 5. References and Resources
129+
130+
- [MiniZinc 2.8.4 Language Reference](https://www.minizinc.org/doc-2.8.4/en/index.html)
131+
- [MiniZinc BNF Grammar](https://github.com/MiniZinc/libminizinc/blob/master/doc/grammar/minizinc.bnf)
132+
- [FlatZinc 2.8.4 Specification](https://www.minizinc.org/doc-2.8.4/en/fzn-spec.html)
133+
- [MiniZinc Example Models](https://www.minizinc.org/examples.html)
134+
- [MiniZinc Standard Library](https://www.minizinc.org/doc-2.8.4/en/lib-globals.html)
135+
136+
---
137+
138+
## 6. No-Dependency Considerations
139+
140+
- All parsing and lexing must be implemented manually in Rust.
141+
- Avoid using crates like `nom`, `pest`, or `lalrpop`.
142+
- Use Rust’s standard library only.
143+
144+
---
145+
146+
## 7. Example: Minimal Supported MiniZinc
147+
148+
```minizinc
149+
int: n;
150+
array[1..n] of var 1..n: x;
151+
constraint all_different(x);
152+
solve satisfy;
153+
```
154+
155+
---
156+
157+
## 8. Future Extensions
158+
159+
- Support for `.dzn` data files.
160+
- More global constraints.
161+
- Objective functions (minimize/maximize).
162+
- Full MiniZinc grammar coverage.

0 commit comments

Comments
 (0)