[ Reference Manual | Alphabetic Index ]

# library(flatzinc)

Interpreter for FlatZinc [more]

## Predicates

> fzn_error(?, ?)
>   No description available
> fzn_init(++SolverOrOptions, -FznState)
>   Initialize a FlatZinc solver
> fzn_last(+FznState)
>   Increments solutions count, and succeeds if last one reached
> fzn_load_stream(+ModelStream, -FznState)
>   Load a FlatZinc model and set up its constraints
> fzn_obj_lookup(+FznState, -Obj)
>   Find ECLiPSe term representing the Mini/FlatZinc model's objective
> fzn_output(+FznState)
>   Perform a FlatZinc model's output actions
> fzn_run(+SolverOrOptions)
>   Run a FlatZinc model from standard input
> fzn_run(+File, ++SolverOrOptions)
>   Run a FlatZinc model from a given file
> fzn_run_stream(+Stream, ++SolverOrOptions)
>   Run a FlatZinc model from a given open input stream
> fzn_search(+FznState)
>   Run the search part of a FlatZinc model
> fzn_unsat(?)
>   No description available
> fzn_var_lookup(+FznState, +Id, -Value)
>   Find ECLiPSe term corresponding to Mini/FlatZinc identifier
> fzn_write(?, ?)
>   No description available
> fzn_write(?, ?, ?, ?)
>   No description available
> zn_options(?, ?)
>   No description available

## Structures

> struct zn_options(solver, fzn_tmp, output, optimize, parser, setup_prio, solutions, statistics, timeout, var_names, fzn_output, mzn_output)
>   Options for Mini/FlatZinc solving
> struct zn_var(id, ann, type, group, eclvar, num)
>   Descriptor for a Mini/FlatZinc variable

## Description

### 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?

## About

- Status: prototype
- Author: Joachim Schimpf, supported by Cisco Systems and NICTA Victoria
- Copyright © Cisco Systems Inc, licensed under CMPL
- Date: $Date: 2015/01/14 01:31:09 $

## See Also

library(minizinc), library(flatzinc_parser), library(fzn_ic), library(fzn_fd), library(fzn_eplex)

Generated from flatzinc.eci on 2020-02-26 22:26