lib(flatzinc)



Overview


The core of this module is an interpreter for FlatZinc models, based
on 'Specification of FlatZinc 1.0' (May 2009).  It uses
lib(flatzinc_parser) to read a FlatZinc model one item at a time, and
immediately interprets it.  The mapping from FlatZinc built-in
operations to actual ECLiPSe solver operations is in separate modules
called fzn_ic, fzn_fd, fzn_eplex, etc.



Running FlatZinc Models


If you have a file containing a FlatZinc model, it can be loaded and
executed from ECLiPSE by calling

    ?- fzn_run("model.fzn", fzn_ic).

where model.fzn is the file name (the .fzn extension can be omitted)
and fzn_ic is the name of the chosen solver mapping.  It is also
possible to read a model from the standard input using fzn_run/1, or
from an arbitrary ECLiPSe input stream using fzn_run_stream/2.

If finer control is needed, the processing of a FlatZinc model can be
split up into initialization, loading and constraint-set-up, search,
and output.  The primitives that perform these steps are exported
and can be invoked separately, e.g.

my_fzn_run_stream(ModelStream, Options) :-

	% initialize the solver state
	fzn_init(Options, State),

	% load the model and set up the constraints
	fzn_load_stream(ModelStream, State),

	% perform the search
	fzn_search(State),

	% output solution, if found
	fzn_output(State).




Creating FlatZinc Models


Note that FlatZinc is not intended to be written by humans, but
created by translating models written in Zinc or MiniZinc.  A
translator for MiniZinc to FlatZinc called mzn2fzn is available at

http://www.g12.csse.unimelb.edu.au/minizinc


The use of an intermediate FlatZinc file can be avoided by
piping the result of the MiniZinc to FlatZinc converter directly
into the ECLiPSe-FlatZinc interpreter, e.g. via

% mzn2fzn --output-to-stdout model.mzn | eclipse -e "flatzinc:fzn_run(fzn_ic)"

The file lib/fzn_ic/globals.mzn contains specialised global constraint
definitinions for the use of fzn_ic.
For alternative ways to run MiniZinc models, see library(minizinc).



How to write a new solver mapping


The mapping from FlatZinc built-in operations to actual ECLiPSe solver
operations is defined in separate modules called fzn_ic, fzn_eplex, etc. 
To add a new mapping, create a new module file called fzn_xxx.ecl, and
place it in your library_path.
These modules should export predicates corresponding to the "built-in"
operations defined by FlatZinc, i.e.

int_lin_le/3, float_times/3,

etc.  See the FlatZinc specification for a complete list.

In addition to those, we require the following interface predicates:

For initialising variables:

bool_declare(-var),
int_declare(-var),
int_declare(-var, +list),
int_declare(-var, +min, +max),
float_declare(-var),
float_declare(-var, +min, +max),
set_declare(-var, +min, +max),
set_declare(-var, +list)


For initialising arrays:

bool_declare_array(-array),
int_declare_array(-array),
int_declare_array(-array, +list),
int_declare_array(-array, +min, +max),
float_declare_array(-array),
float_declare_array(-array, +min, +max),
set_declare_array(-array, +min, +max),
set_declare_array(-array, +list)


For invoking search:

satisfy(+annotations),
minimize(+objective, +annotations, -cost),
maximize(+objective, +annotations, -cost)


For converting constants in the Zinc model to the appropriate solver
type in ECLiPSe (e.g. floats to breals when using lib(ic)):

bool_fzn_to_solver(+atom, -bool),
bool_solver_to_fzn(+bool, -atom),
float_fzn_to_solver(+float, -real),
float_solver_to_fzn(+real, -float),
set_fzn_to_solver(+list, -set),
set_solver_to_fzn(+set, -list),
range_fzn_to_solver(+min, +max, -set).




TODO


interpret more variable annotations
constraint annotations (currently ignored)
stricter checking of the FlatZinc input?




