kodkod.engine.bool
Class BooleanMatrix

java.lang.Object
  extended by kodkod.engine.bool.BooleanMatrix
All Implemented Interfaces:
java.lang.Cloneable, java.lang.Iterable<IndexedEntry<BooleanValue>>

public final class BooleanMatrix
extends java.lang.Object
implements java.lang.Iterable<IndexedEntry<BooleanValue>>, java.lang.Cloneable

An n-dimensional matrix of boolean values. Boolean matrices are indexed using flat integer indeces. For example, let m be a the 2 x 3 matrix of boolean variables identifed by labels [0 4 1; 5 10 2]. Then, m[0] = 0, m[3] = 5, m[5] = 2, etc.

All values stored in the same matrix must be created by the same circuit factory. All methods that accept another BooleanMatrix as an input will throw an IllegalArgumentException if the values in the input matrix do not belong to the same factory as the values in the receiver matrix.

Some instances can store only constant values, or can only store values at particular indices (see BooleanFactory.matrix(Dimensions, IntSet, IntSet)). If this is the case, an attempt to call set(int, BooleanValue) with invalid parameters will cause an IllegalArgumentException or an IndexOutOfBoundsException.

Author:
Emina Torlak
specfield:
dimensions: Dimensions
factory: BooleanFactory
elements: [0..dimensions.capacity) -> one factory.components

Method Summary
 BooleanMatrix and(BooleanMatrix other)
          Returns a new matrix such that an entry in the returned matrix represents a conjunction of the corresponding entries in this and other matrix.
 Int cardinality()
          Returns an Int that represents the cardinality (number of non-FALSE entries) of this matrix using this.factory.intEncoding.
 BooleanMatrix choice(BooleanValue condition, BooleanMatrix other)
          Returns a boolean matrix m such that m = this if the given condition evaluates to TRUE and m = other otherwise.
 BooleanMatrix clone()
          Returns a copy of this boolean matrix.
 BooleanMatrix closure()
          Returns the transitive closure of this matrix.
 BooleanMatrix cross(BooleanMatrix other)
          Returns the cross product of this and other matrix, using conjunction instead of multiplication.
 IntSet denseIndices()
          Returns the set of all indices in this matrix that contain non-FALSE values.
 int density()
          Returns the number of non-FALSE entries in this matrix.
 BooleanMatrix difference(BooleanMatrix other)
          Returns a matrix representing the asymmetric difference between the entries in this and the given matrix.
 Dimensions dimensions()
          Returns the dimensions of this matrix.
 BooleanMatrix dot(BooleanMatrix other)
          Returns the dot product of this and other matrix, using conjunction instead of multiplication and disjunction instead of addition.
 BooleanValue eq(BooleanMatrix other)
          Returns a formula stating that the entries in this matrix are equivalent to the entries in the given matrix; i.e.
 BooleanFactory factory()
          Returns the factory used to construct all the non-constant entries in this matrix.
 BooleanValue get(int index)
          Returns the element at the specified index.
 java.util.Iterator<IndexedEntry<BooleanValue>> iterator()
          Returns an IndexedEntry-based view of the non-FALSE entries in this matrix.
 BooleanValue lone()
          Returns a BooleanValue that constrains at most one value in this.elements to be true.
 BooleanValue none()
          Returns a BooleanValue that constraints all values in this.elements to be false.
 BooleanMatrix not()
          Returns a new matrix each of whose entries is a negation of the corresponding entry in this matrix.
 BooleanValue one()
          Returns a BooleanValue that constraints exactly one value in this.elements to be true.
 BooleanMatrix or(BooleanMatrix other)
          Returns a new matrix such that an entry in the returned matrix represents a combination of the corresponding entries in this and other matrix.
 BooleanMatrix override(BooleanMatrix other)
          Overrides the values in this matrix with those in other.
 BooleanMatrix project(Int[] columns)
          Returns a matrix m such that the relational value of m is equal to the relational value of this projected on the specified columns.
 void set(int index, BooleanValue value)
          Sets the specified index to the given value.
 BooleanValue some()
          Returns a BooleanValue that constrains at least one value in this.elements to be true.
 BooleanValue subset(BooleanMatrix other)
          Returns a formula stating that the entries in this matrix are a subset of the entries in the given matrix; i.e.
 java.lang.String toString()
           
 BooleanMatrix transpose()
          Returns the transpose of this matrix.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

dimensions

public final Dimensions dimensions()
Returns the dimensions of this matrix.

Returns:
this.dimensions

factory

public final BooleanFactory factory()
Returns the factory used to construct all the non-constant entries in this matrix.

Returns:
this.factory

density

public final int density()
Returns the number of non-FALSE entries in this matrix.

Returns:
#this.elements.(BooleanValue - FALSE)

iterator

public final java.util.Iterator<IndexedEntry<BooleanValue>> iterator()
Returns an IndexedEntry-based view of the non-FALSE entries in this matrix. The returned iterator enumerates indexed entries that represent the non-FALSE entries in the matrix, in the ascending order of indeces. For example, suppose that the elements of this are 0->FALSE, 1->(a & b), 2->FALSE, 3->(c | d). Then, the Iterator will return two IndexedEntries, c1 then c2, such that c1.index=1 && c1.value = a & b and c2.index=3 && c.value = c | d. Calling Iterator.remove() on the returned iterator has the same effect as setting the entry obtained through the last call to Iterator.next() to FALSE.

Specified by:
iterator in interface java.lang.Iterable<IndexedEntry<BooleanValue>>
Returns:
an iterator over IndexedEntries representing the non-FALSE entries in this matrix.

denseIndices

public final IntSet denseIndices()
Returns the set of all indices in this matrix that contain non-FALSE values.

Returns:
the set of all indices in this matrix that contain non-FALSE values.

get

public final BooleanValue get(int index)
Returns the element at the specified index.

Returns:
this.elements[index]
Throws:
java.lang.IndexOutOfBoundsException - - index < 0 || index >= this.dimensions.capacity

not

public final BooleanMatrix not()
Returns a new matrix each of whose entries is a negation of the corresponding entry in this matrix.

Returns:
{ m: BooleanMatrix | m.dimensions=this.dimensions && m.factory = this.factory && all i: [0..m.dimensions.capacity) | m.elements[i] = !this.elements[i] }

and

public final BooleanMatrix and(BooleanMatrix other)
Returns a new matrix such that an entry in the returned matrix represents a conjunction of the corresponding entries in this and other matrix. The effect of this method is the same as calling this.compose(Operator.Binary.AND, other).

Returns:
{ m: BooleanMatrix | m.dimensions = this.dimensions && m.factory = this.factory && all i: [0..m.dimensions.capacity) | m.elements[i] = this.elements[i] AND other.elements[i] }
Throws:
java.lang.NullPointerException - - other = null
java.lang.IllegalArgumentException - - !other.dimensions.equals(this.dimensions) || this.factory != other.factory

or

public final BooleanMatrix or(BooleanMatrix other)
Returns a new matrix such that an entry in the returned matrix represents a combination of the corresponding entries in this and other matrix. The effect of this method is the same as calling this.compose(Operator.Binary.OR, other).

Returns:
{ m: BooleanMatrix | m.dimensions = this.dimensions && m.factory = this.factory && all i: [0..m.dimensions.capacity) | m.elements[i] = this.elements[i] OR other.elements[i] }
Throws:
java.lang.NullPointerException - - other = null
java.lang.IllegalArgumentException - - !other.dimensions.equals(this.dimensions) || this.factory != other.factory

cross

public final BooleanMatrix cross(BooleanMatrix other)
Returns the cross product of this and other matrix, using conjunction instead of multiplication.

Returns:
{ m: BooleanMatrix | m = this x other }
Throws:
java.lang.NullPointerException - - other = null
java.lang.IllegalArgumentException - - this.factory != other.factory

dot

public final BooleanMatrix dot(BooleanMatrix other)
Returns the dot product of this and other matrix, using conjunction instead of multiplication and disjunction instead of addition.

Returns:
{ m: BooleanMatrix | m = this*other }
Throws:
java.lang.NullPointerException - - other = null
java.lang.IllegalArgumentException - - this.factory != other.factory
java.lang.IllegalArgumentException - - dimensions incompatible for multiplication

subset

public final BooleanValue subset(BooleanMatrix other)
Returns a formula stating that the entries in this matrix are a subset of the entries in the given matrix; i.e. the value of every entry in this matrix implies the value of the corresponding entry in the given matrix.

Returns:
{ f: BooleanValue | f <=> (this.elements[0]=>other.elements[0]) AND ... AND (this.elements[this.dimensions.capacity-1]=>other.elements[this.dimensions.capacity-1]))
Throws:
java.lang.NullPointerException - - other = null
java.lang.IllegalArgumentException - - !other.dimensions.equals(this.dimensions) || this.factory != other.factory

eq

public final BooleanValue eq(BooleanMatrix other)
Returns a formula stating that the entries in this matrix are equivalent to the entries in the given matrix; i.e. the value of every entry in this matrix is true if and only if the value of the corresponding entry in the given matrix is true. The same formula can be obtained by calling factory.and(this.subset(other), other.subset(this)), but this method performs the operation more efficiently.

Returns:
{ f: BooleanValue | f <=> (this.elements[0]<=>other.elements[0]) AND ... AND (this.elements[this.dimensions.capacity-1]<=>other.elements[this.dimensions.capacity-1]))
Throws:
java.lang.NullPointerException - - other = null
java.lang.IllegalArgumentException - - !other.dimensions.equals(this.dimensions) || this.factory != other.factory

difference

public final BooleanMatrix difference(BooleanMatrix other)
Returns a matrix representing the asymmetric difference between the entries in this and the given matrix. The same matrix can be obtained by calling this.and(other.not()), but this method performs the operation more efficiently (intermediate values are not explicity created).

Returns:
{ m: BooleanMatrix | m.dimensions = this.dimensions && m.factory = this.factory && all i: [0..m.dimensions.capacity) | m.elements[i] = this.elements[i] AND !other.elements[i] }
Throws:
java.lang.NullPointerException - - other = null
java.lang.IllegalArgumentException - - !other.dimensions.equals(this.dimensions) || this.factory != other.factory

closure

public final BooleanMatrix closure()
Returns the transitive closure of this matrix.

Returns:
{ m: BooleanMatrix | m = ^this }
Throws:
java.lang.UnsupportedOperationException - - #this.diensions != 2 || !this.dimensions.square()

transpose

public final BooleanMatrix transpose()
Returns the transpose of this matrix.

Returns:
{ m: BooleanMatrix | m = ~this }
Throws:
java.lang.UnsupportedOperationException - - #this.dimensions != 2

choice

public final BooleanMatrix choice(BooleanValue condition,
                                  BooleanMatrix other)
Returns a boolean matrix m such that m = this if the given condition evaluates to TRUE and m = other otherwise.

Returns:
{ m: BooleanMatrix | m.dimensions = this.dimensions && all i: [0..m.dimensions.capacity) | m.elements[i] = condition => this.elements[i], other.elements[i] }
Throws:
java.lang.NullPointerException - - other = null || condition = null
java.lang.IllegalArgumentException - - !other.dimensions.equals(this.dimensions) || this.factory != other.factory

project

public final BooleanMatrix project(Int[] columns)
Returns a matrix m such that the relational value of m is equal to the relational value of this projected on the specified columns.

Returns:
{ m: BooleanMatrix | [[m]] = project([[this]], columns) }
Throws:
IllegalArgumentExceptions - - columns.length < 1 || !this.dimensions.isSquare()
java.lang.NullPointerException - - columns = null
requires:
column[int] in this.dimensions.dimensions[int]
this.dimensions.isSquare()

override

public final BooleanMatrix override(BooleanMatrix other)
Overrides the values in this matrix with those in other. Specifically, for each index i of the returned matrix m, m.elements[i] is true iff other.elements[i] is true or this.elements[i] is true and all elements of other that are in the same row as i are false.

Returns:
{m: BooleanMatrix | m.dimensions = this.dimensions && all i: [0..m.capacity()) | m.elements[i] = other.elements[i] || this.elements[i] && !OR(other.elements[row(i)]) } where other.elements[row(i)] selects all elements of other that are in the same row as i.
Throws:
java.lang.NullPointerException - - other = null
java.lang.IllegalArgumentException - - other.dimensions != this.dimensions

cardinality

public final Int cardinality()
Returns an Int that represents the cardinality (number of non-FALSE entries) of this matrix using this.factory.intEncoding.

Returns:
{i: Int | [[i]] = sum({v: elements[int] | if [[v]] then 1 else 0}) }

some

public final BooleanValue some()
Returns a BooleanValue that constrains at least one value in this.elements to be true. The effect of this method is the same as calling this.orFold().

Returns:
{ f: BooleanValue | f <=> this.elements[0] || ... || this.elements[this.dimensions.capacity-1] }

lone

public final BooleanValue lone()
Returns a BooleanValue that constrains at most one value in this.elements to be true. The effect of this method is the same as calling this.factory.or(this.one(), this.none()).

Returns:
{ f: BooleanValue | f <=> this.one() || this.none() }

one

public final BooleanValue one()
Returns a BooleanValue that constraints exactly one value in this.elements to be true.

Returns:
{ f: BooleanValue | f <=> #this.elements[int] = 1 }

none

public final BooleanValue none()
Returns a BooleanValue that constraints all values in this.elements to be false. The effect of this method is the same as calling this.factory.not(this.orFold()).

Returns:
{ f: BooleanValue | f <=> !(this.elements[0] || ... || !this.elements[this.dimensions.capacity-1]) }

set

public final void set(int index,
                      BooleanValue value)
Sets the specified index to the given value.

Throws:
java.lang.NullPointerException - - value = null
java.lang.IllegalArgumentException - - the given is a formula, and this matrix accepts only constants
java.lang.IndexOutOfBoundsException - - the given index does not belong to the set of indices at which this matrix can store non-FALSE values.
effects:
this.elements'[index] = value
requires:
value in this.factory.components

clone

public BooleanMatrix clone()
Returns a copy of this boolean matrix.

Overrides:
clone in class java.lang.Object
Returns:
{m: BooleanMatrix - this | m.dimensions = this.dimensions && m.elements = copy of this.elements }

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object
See Also:
Object.toString()