Crate flatzinc_serde 

Serialization of the FlatZinc data format

FlatZinc is the language in which data and solver specific constraint models are produced by the MiniZinc compiler. This crate implements the FlatZinc serialization format as described in the Interfacing Solvers to FlatZinc section of the MiniZinc reference manual. It supports both the JSON-based FlatZinc representation, via serde, and the older textual .fzn format. For the JSON format, we suggest using serde_json with the specification in this crate to parse the FlatZinc JSON files produced by the MiniZinc compiler.

Feature Flags

• serde (default): enables JSON serialization and deserialization support via the serde crate.
• fzn: enables parsing of the original .fzn text format via winnow.

Getting Started

For the default JSON-based workflow, install flatzinc-serde and serde_json for your package:

cargo add flatzinc-serde serde_json

If you disable the default serde feature and only use the older textual .fzn support, serde_json is not required.

Once these dependencies have been installed to your crate, you can deserialize a FlatZinc JSON file as follows:

// let path = Path::new("/lorem/ipsum/model.fzn.json");
let rdr = BufReader::new(File::open(path).unwrap());
let fzn: FlatZinc = serde_json::from_reader(rdr).unwrap();
// ... process FlatZinc ...

When deserializing FlatZinc JSON, this crate rejects unknown fields on inner FlatZinc objects such as variables, arrays, constraints, solve items, and annotation-call objects. Unknown fields on the outer top-level wrapper object are ignored to preserve some forward compatibility for envelope metadata.

The older textual .fzn format is also supported when the fzn feature is enabled:

// let path = Path::new("/lorem/ipsum/model.fzn");
let rdr = BufReader::new(File::open(path).unwrap());
let fzn: FlatZinc = FlatZinc::from_fzn(rdr).unwrap();
// ... process FlatZinc ...

To serialize a FlatZinc JSON value, you can use the usual serde_json APIs:

let fzn = FlatZinc::<String>::default();
// ... create  solver constraint model ...
let json_str = serde_json::to_string(&fzn).unwrap();

Note that serde_json::to_writer, using a buffered file writer, would be preferred when writing larger FlatZinc files.

To serialize a FlatZinc value to the older textual .fzn format, use its Display implementation:

let fzn = FlatZinc::<String>::default();
let fzn_text = fzn.to_string();

Register your solver with MiniZinc

If your goal is to deserialize FlatZinc to implement a MiniZinc solver, then the next step is to register your solver executable with MiniZinc. This can be done by creating a MiniZinc Solver Configuration (.msc) file, and adding it to a folder on the MZN_SOLVER_PATH or a standardized path, like ~/.minizinc/solvers/. A basic solver configuration for a solver that accepts JSON input would look as follows:

{
  "name" : "My Solver",
  "version": "0.0.1",
  "id": "my.organisation.mysolver",
  "inputType": "JSON",
  "executable": "../../../bin/fzn-my-solver",
  "mznlib": "../mysolver"
  "stdFlags": [],
  "extraFlags": []
}

Once you have placed your configuration file on the correct path, then you solver will be listed by minizinc --solvers. Calling minizinc --solver mysolver model.mzn data.dzn, assuming a valid MiniZinc instance, will (after compilation) invoke the registered executable with a path of a FlatZinc JSON file, and potentially any registered standard and extra flags (e.g., ../../../bin/fzn-my-solver model.fzn.json).

Modules

helpers

Helper structures, methods, and functions to support the serialization and deserialization of FlatZinc data.

Structs

AnnotationCall

An object depicting an annotation in the form of a call

Array

A definition of a named array literal in FlatZinc

Constraint

An object depicting a constraint

FlatZinc

The structure depicting a FlatZinc instance

RangeList

A sorted collection of inclusive ranges that can be used to represent non-continuous sets of values.

SolveObjective

A specification of objective of a FlatZinc instance

Variable

The definition of a decision variable

Enums

Annotation

Additional information provided in a standardized format for declarations, constraints, or solve objectives

AnnotationArgument

The argument type associated with AnnotationCall

AnnotationLiteral

Literal values as arguments to AnnotationCall

Argument

The argument type associated with Constraint

FznParseError

Errors that can occur when parsing .fzn models.

LinkError

Error produced while linking an variable and array references of the model.

Literal

Literal values

Method

Goal of solving a FlatZinc instance.

NamedRef

Reference to a named top-level declaration (variable or array)

Type

Used to signal the type of (decision) Variable