4 releases (breaking)

0.4.0 Aug 12, 2024
0.3.0 May 14, 2024
0.2.0 Apr 11, 2024
0.1.0 Jan 19, 2024

#2055 in Parser implementations

MPL-2.0 license

63KB
1.5K SLoC

FlatZinc Serde

flatzinc-serde is a Rust library that provides serialization and deserialization support for the FlatZinc JSON format using the serde library. FlatZinc (JSON) is a representation used to represent decision and optimization problems to solvers of these types of problems. This format is used by the MiniZinc constraint modelling language.

Getting Started

Install the library using cargo:

cargo install flatzinc-serde

Read the documentation for more information about how to use the library.

License

This project is licensed under the MPL-2.0 License. See the LICENSE file for details.


lib.rs:

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. Although the serde specification in this crate could be used with a range of data formats, MiniZinc currently only outputs this formulation using the JSON data format. We suggest using serde_json with the specification in this crate to parse the FlatZinc JSON files produced by the MiniZinc compiler.

Getting Started

Install flatzinc-serde and serde_json for your package:

cargo add flatzinc-serde serde_json

Once these dependencies have been installed to your crate, you could 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 ...

If, however, you want to serialize a FlatZinc format you could follow the following fragment:

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.

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).

Dependencies

~0.8–1.4MB
~31K SLoC