and 1 contributors

# NAME

Algorithm::CP::IZ - Perl interface for iZ-C library

# SYNOPSIS

``````  use Algorithm::CP::IZ;

my \$iz = Algorithm::CP::IZ->new();

my \$v1 = \$iz->create_int(1, 9);
my \$v2 = \$iz->create_int(1, 9);
my \$rc = \$iz->search([\$v1, \$v2]);

if (\$rc) {
print "ok\n";
print "v1 = ", \$v1->value, "\n";
print "v2 = ", \$v2->value, "\n";
}
else {
print "fail\n";
}``````

# DESCRIPTION

Algorithm::CP::IZ is a simple interface of iZ-C constraint programming library.

Functions declared in iz.h are mapped to:

methods of Algorithm::CP::IZ

initialize, variable constructor, most of constraints and search related functions

methods of Algorithm::CP::IZ::Int

accessors of variable attributes and some constraints

Please refer to iZ-C reference manual to see specific meaning of methods.

## SIMPLE CASE

In most simple case, this library will be used like following steps:

``````  # initialize
use Algorithm::CP::IZ;
my \$iz = Algorithm::CP::IZ->new();

# construct variables
my \$v1 = \$iz->create_int(1, 9);
my \$v2 = \$iz->create_int(1, 9);

# add constraints ("v1 + v2 = 12" in this case)

# search solution
my \$rc = \$iz->search([\$v1, \$v2]);

# you may get "v1 = 3, v2 = 9"
print "v1 = \$v1, v2 = \$v2\n";``````

# CONSTRUCTOR

new

Initialize iZ-C library (cs_init is called). For limitation of iZ-C, living instance of Algorithm::CP::IZ must be only one per process.

# METHODS

create_int(INT)

Create Algorithm::CP::IZ::Int instance. Its domain contains INT.

create_int(VALUES [, NAME])

Create Algorithm::CP::IZ::Int instance. Its domain contains values specified by VALUES(arrayref).

create_int(MIN, MAX, [, NAME])

Create Algorithm::CP::IZ::Int instance. Its domain is {MIN..MAX}.

search(VARIABLES [, PARAMS])

Try to instantiate all VARIABLES(arrayref).

PARAMS will be hashref containning following keys.

FindFreeVar

FindFreeVar specifies variable selection strategy. Choose constants from Algorithm::CP::IZ::FindFreeVar or specify your own function as coderef here.

Most simple function will be following. (select from first)

``````    sub simple_find_free_var{
my \$array = shift; # VARIABLES is in parameter
my \$n = scalar @\$array;

for my \$i (0..\$n-1) {
return \$i if (\$array->[\$i]->is_free);
}

return -1; # no free variable
};``````
Criteria

Criteria specifies value selection strategy. Specify your own function as coderef here.

``````    sub sample_criteria {
# position in VARIABLES, and candidate value
my (\$index, \$val) = @_;

# first value used in search is
# minimum value returned by criteria.
return \$val;
};``````
MaxFail

Upper limit of fail count while searching solutions.

Returns 1 (success) or 0 (fail).

find_all(VARIABLES, CALLBACK [, PARAMS])

Find all solutions. CALLBACK(coderef) is called for each solution. (First parameter of CALLBACK is VARIABLE)

``````    # this callback collects all solutions in @r
my @r;
sub callback {
my \$var_array = shift;
push(@r, [map { \$_->value } @\$var_array]);
};``````

PARAMS will be hashref containning following keys.

FindFreeVar

Same as search method.

Returns 1 (success) or 0 (fail).

get_nb_fails

Returns fail count while search solution.

get_nb_choice_points

Returns choice count while search solution.

save_context

Save current status of variables and constraints.

``````  my \$v1 = \$iz->create_int(1, 9);
\$iz->save_context;    # current status is saved.
\$v1->Le(5);           # \$v1 is {1..5}
\$iz->restore_context; # \$v1 is restored to {1..9}``````

Returns integer which will be used for restore_context_until.

restore_context

Restore status of variables and constraints to last point which 'save_context' is called.

restore_context_until(LABEL)

Restore status of variables and constraints to point of label which 'save_context' returns.

restore_all

Restore status of variables and constraints to point of first 'save_context' call.

backtrack(VAR, INDEX, CALLBACK)

Set a callback function which will be called when context is restored to current status.

VAR is an instance of Algorithm::CP::IZ::Int.

INDEX is an integer value.

CALLBACK is a coderef which takes parameters like:

``````  sub callback {
# \$var = VAR, \$index = INDEX
my (\$var, \$index) = @_;
}``````
event_all_known(VARIABLES, CALLBACK, EXTRA)

Set a callback function which will be called when all variables in VARIABLES are instantiated.

VARIABLES is an arrayref contains Create Algorithm::CP::IZ::Int.

CALLBACK is a coderef and takes parameters and must return like:

``````  sub callback {
# \$variables and \$extra are same as parameter.
my (\$variables, \$extra) = @_;

# return 1(success) or 0(fail)
return 1;
}``````

EXTRA is a just a data passed to callbeck as parameter (it can be anything).

event_known(VARIABLES, CALLBACK, EXTRA)

Set a callback function which will be called when any variable in VARIABLES is instantiated.

VARIABLES is an arrayref contains Create Algorithm::CP::IZ::Int.

CALLBACK is a coderef and takes parameters and must return like:

``````  sub callback {
# \$val is instantited now.
# \$index is position in \$variables.
# \$variables and \$extra are same as parameter.
my (\$val, \$index, \$variables, \$extra) = @_;

# return 1(success) or 0(fail)
return 1;
}``````

EXTRA is a just a data passed to callbeck as parameter (it can be anything).

event_new_min(VARIABLES, CALLBACK, EXTRA)

Set a callback function which will be called when lower bound of any variable in VARIABLES is changed.

VARIABLES is an arrayref contains Create Algorithm::CP::IZ::Int.

CALLBACK is a coderef and takes parameters and must return like:

``````  sub callback {
# minimum value of \$var is changed from \$old_min.
# \$var is same as \$variables[\$index].
# \$variables and \$extra are same as parameter.
my (\$var, \$index, \$old_min, \$variables, \$extra) = @_;

# return 1(success) or 0(fail)
return 1;
}``````

EXTRA is a just a data passed to callbeck as parameter (it can be anything).

event_new_max(VARIABLES, CALLBACK, EXTRA)

Set a callback function which will be called when upper bound of any variable in VARIABLES is changed.

VARIABLES is an arrayref contains Create Algorithm::CP::IZ::Int.

CALLBACK is a coderef and takes parameters and must return like:

``````  sub callback {
# maximum value of \$var is changed from \$old_max.
# \$var is same as \$variables[\$index].
# \$variables and \$extra are same as parameter.
my (\$var, \$index, \$old_max, \$variables, \$extra) = @_;

# return 1(success) or 0(fail)
return 1;
}``````

EXTRA is a just a data passed to callbeck as parameter (it can be anything).

event_neq(VARIABLES, CALLBACK, EXTRA)

Set a callback function which will be called when value of any variable is removed in VARIABLES is changed.

VARIABLES is an arrayref contains Create Algorithm::CP::IZ::Int.

CALLBACK is a coderef and takes parameters and must return like:

``````  sub callback {
# \$val is removed from \$var.
# \$var is same as \$variables[\$index].
# \$variables and \$extra are same as parameter.
my (\$var, \$index, \$val, \$variables, \$extra) = @_;

# return 1(success) or 0(fail)
return 1;
}``````

EXTRA is a just a data passed to callbeck as parameter (it can be anything).

# METHODS (Constraints)

Add(VAR1, VAR2 [, VAR3....])

Create new Algorithm::CP::IZ::Int instance constrainted to be:

``  CREATED = VAR1 + VAR2 + ....``
Mul(VAR1, VAR2 [, VAR3....])

Create Algorithm::CP::IZ::Int instance constrainted to be:

``  CREATED = VAR1 * VAR2 * ....``
Sub(VAR1, VAR2)

Create Algorithm::CP::IZ::Int instance constrainted to be:

``  CREATED = VAR1 - VAR2``
Div(VAR1, VAR2)

Create Algorithm::CP::IZ::Int instance constrainted to be:

``  CREATED = VAR1 / VAR2``
ScalProd(VARIABLES, COEFFICIENTS)

Create Algorithm::CP::IZ::Int instance constrainted to be:

``  CREATED = COEFFICIENTS*VARIABLES + COEFFICIENTS*VARIABLES + ...``

VARIABLES is an arrayref contains Create Algorithm::CP::IZ::Int, and COEFFICIENTS is an arreyref contains integer values.

AllNeq(VARIABLES)

Constraint all variables in VARIABLES to be different each other.

VARIABLES is an arrayref contains Create Algorithm::CP::IZ::Int.

Returns 1 (success) or 0 (fail).

Sigma(VARIABLES)

Create Algorithm::CP::IZ::Int instance constrainted to be:

``  CREATED = VARIABLES + VARIABLES + ...``

VARIABLES is an arrayref contains Create Algorithm::CP::IZ::Int.

Abs(VAR)

Create Algorithm::CP::IZ::Int instance constrainted to be:

``  CREATED = abs(VAR)``
Min(VARIABLES)

Create Algorithm::CP::IZ::Int instance constrainted to be:

``  CREATED = minimum value of (VARIABLES, VARIABLES, ...)``

VARIABLES is an arrayref contains Create Algorithm::CP::IZ::Int.

Max(VARIABLES)

Create Algorithm::CP::IZ::Int instance constrainted to be:

``  CREATED = maximum value of (VARIABLES, VARIABLES, ...)``

VARIABLES is an arrayref contains Create Algorithm::CP::IZ::Int.

IfEq(VAR1, VAR2, VAL1, VAL2)

Constraint VAR1 and VAR2 to be:

``````  VAR1 is instantiated to VAL1 and VAR2 is instantiated to VAL2.
VAR2 is instantiated to VAL2 and VAR1 is instantiated to VAL1.``````

Returns 1 (success) or 0 (fail).

IfNeq(VAR1, VAR2, VAL1, VAL2)

Constraint VAR1 and VAR2 to be:

``  pair (VAR1, VAR2) != pair (VAL1, VAL2)``

Returns 1 (success) or 0 (fail).

OccurDomain(VAL, VARIABLES)

Create Algorithm::CP::IZ::Int instance represents count of VAL in VARIABLES.

VARIABLES is an arrayref contains Create Algorithm::CP::IZ::Int.

OccurConstraints(VAR, VAL, VARIABLES)

Constraint VAR to represent count of VAL in VARIABLES.

VARIABLES is an arrayref contains Create Algorithm::CP::IZ::Int.

Returns 1 (success) or 0 (fail).

Index(VARIABLES, VAL)

Create Algorithm::CP::IZ::Int instance represents position of VAL in VARIABLES.

``  VAL = VARIABLES[CREATED]``

VARIABLES is an arrayref contains Create Algorithm::CP::IZ::Int.

Element(VAR, VALUES)

Create Algorithm::CP::IZ::Int instance represents value at VAR in VARIABLES.

``  CREATED = VARIABLES[VAR]``

VARIABLES is an arrayref contains Create Algorithm::CP::IZ::Int.

ReifEq(VAR1, VAR2)

Create Algorithm::CP::IZ::Int instance represents VAR1 == VAR2. Created variable will be instantiated to 1 when VAR1 == VAR2 otherwise to 0.

ReifNeq(VAR1, VAR2)

Create Algorithm::CP::IZ::Int instance represents VAR1 != VAR2. Created variable will be instantiated to 1 when VAR1 != VAR2 otherwise to 0.

ReifLt(VAR1, VAR2)

Create Algorithm::CP::IZ::Int instance represents VAR1 < VAR2. Created variable will be instantiated to 1 when VAR1 < VAR2 otherwise to 0.

ReifLe(VAR1, VAR2)

Create Algorithm::CP::IZ::Int instance represents VAR1 <= VAR2. Created variable will be instantiated to 1 when VAR1 <= VAR2 otherwise to 0.

ReifGt(VAR1, VAR2)

Create Algorithm::CP::IZ::Int instance represents VAR1 > VAR2. Created variable will be instantiated to 1 when VAR1 > VAR2 otherwise to 0.

ReifGe(VAR1, VAR2)

Create Algorithm::CP::IZ::Int instance represents VAR1 >= VAR2. Created variable will be instantiated to 1 when VAR1 >= VAR2 otherwise to 0.

# AUTHOR

Toshimitsu FUJIWARA, <tttfjw at gmail.com>

Copyright (C) 2015 by Toshimitsu FUJIWARA

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at: