Base object types and functions¶

The following classes are at the base of many RepLAB objects/operations.

Str: Inherited by all RepLAB objects, the base class replab.Str is in charge of pretty printing. This is important for several reasons: Matlab has some support to pretty print objects, support which is missing in Octave. For standard objects (matrices, vectors), there are discrepancies between the output of Matlab and Octave. Finally the standard display of matrices and vectors can be a bit bulky.

We define three styles of printing for objects, which are covered by the three functions below.
headerStr: a header style that prints only the size and the type of the object,
shortStr: a short style that fits on a single display line
longStr: a long style that uses multiple lines, which can be obtained using replab.longStr.
Obj: This class is at the base of most RepLAB objects with notable exceptions (cyclotomic and H, which are value classes). The Obj base class provides helper methods to check the laws obeyed by the object in question (Obj.laws and Obj.check), methods to cache computed properties, and finally a default implementation of object comparison using ==.
Laws: Most algebraic structures in RepLAB obey algebraic laws; for example the binary operation of a Monoid is associative; and the identity element leaves other monoid elements invariant and so on. RepLAB uses randomized tests to check those axioms in all implementations, in the spirit of QuickCheck and ScalaCheck. The infrastructure is provided by the base class Laws, which is returned by the replab.Obj.laws method.
Domain: describes a set of elements that can be compared for equality, and randomly sampled from. The capability of sampling random elements from a domain is heavily used in law checks.

Note that some objects implement standard Matlab equality semantics (a.k.a. x == y); for example cyclotomic matrices can be tested for equality, and finite groups of the same type as well. Other objects such as generic compact groups, representations, will be compared using “is this the same object in memory”.

Str¶

class replab.Str¶

Bases: handle

Base class that provides sane pretty printing for all RepLAB objects

All classes in RepLAB inherit the Str base class, which provides explicit longStr and shortStr methods. Those methods take a dimension limit for width (and possibly height). In contrast, the functions replab.shortStr and replab.longStr use default values that are deduced from the terminal size.

This base class overloads ‘disp’

It also provides methods additionalFields and hiddenFields to guide long form object pretty printing.

Compare the two outputs:

Example

>>> P = replab.S(3)
  P =
      Symmetric group acting on 3 elements
                  identity: [1, 2, 3]
      generator(1 or 'x1'): [2, 3, 1]
      generator(2 or 'x2'): [2, 1, 3]
          recognize.source: Dihedral group of order 6 < a, x | a^3 = x^2 = x a x^-1 a = 1 >
>>> replab.longStr(P, 50, 50)
  {'Symmetric group acting on 3 elements'
   '            identity: [1, 2, 3]'
   'generator(1 or ''x1''): [2, 3, 1]'
   'generator(2 or ''x2''): [2, 1, 3]'
   '    recognize.source: Dihedral group of order 6'}
>>> replab.shortStr(P)
  'Symmetric group acting on 3 elements'

Class members list

Prettyprinting

additionalFields – Returns the name/value pairs corresponding to additional fields to be printed
disp – Standard MATLAB/Octave display method
headerStr – Tiny single line description of the current object type
hiddenFields – Returns the names of the fields that are not printed as a row vector
longStr – Multi-line description of the current object
shortStr – Single line text description of the current object

Own members

additionalFields(self)¶

Returns the name/value pairs corresponding to additional fields to be printed

Classes that override this method should call the superclass method.

Returns

names (cell{1,*} of charstring) – Additional names to display
values (cell{1,*} of charstring) – Additional values to display

disp(self)¶: Standard MATLAB/Octave display method

headerStr(self)¶: Tiny single line description of the current object type

See also

replab.headerStr

hiddenFields(self)¶

Returns the names of the fields that are not printed as a row vector

Classes that override this method should call the superclass method.

Returns: Field names to hide
Return type: cell{1,*} of charstring

longStr(self, maxRows, maxColumns)¶

Multi-line description of the current object

The default implementation of ‘longStr’ is to print a short description of the object on the first line, followed by public properties.

headerStr¶

replab.headerStr(obj)¶

Returns a tiny one-line description of the object type without inspecting its contents

Parameters: obj – Object to pretty print
Returns: String representation
Return type: charstring

longStr¶

replab.longStr(obj, maxRows, maxColumns)¶

Returns a multiline description of the given object, that fits within the given width/height limit

Returns a nRows x 1 cell array of strings lines; the output may be cut arbitrarily at columns after maxColumns, and for rows after maxRows. It is up to calling code to shape such overflowing output before finally printing it.

Parameters

obj – Object to pretty print
maxRows (integer or []) – Maximum row size Optional parameter with default value given in replab.globals.strMaxRows
maxColumns (integer or []) – Maximum column size Optional parameter with default value given in replab.globals.strMaxColumns

shortStr¶

replab.shortStr(obj, maxColumns)¶

Returns a one-line description of the given object, that fits within the given width maxColumns

Parameters

obj – Object to pretty print
maxColumns (integer or [], optional) – Maximum column size; if the output does not fit, it may be returned cut at an arbitrary place, provided that place is after the last column that fits. Optional parameter with default value given in replab.globals.strMaxColumns

Returns

String representation

Return type

charstring

Obj¶

class replab.Obj¶

Bases: replab.Str

Base class that provides sane pretty printing and instance equality tests

Class members list

Properties

Prettyprinting

additionalFields – Returns the name/value pairs corresponding to additional fields to be printed
disp – Standard MATLAB/Octave display method
headerStr – Tiny single line description of the current object type
hiddenFields – Returns the names of the fields that are not printed as a row vector
longStr – Multi-line description of the current object
shortStr – Single line text description of the current object

Property cache

cache – Sets the value of the designated property in the cache
cached – Returns the cached property if it exists, computing it if necessary
cachedOrDefault – Returns the cached property if it exists, or the provided default value if it is unknown yet
cachedOrEmpty – Returns the cached property if it exists, or [] if it is unknown yet
inCache – Returns whether the value of the given property has already been computed

Laws

check – Checks the consistency of this object
checkAndContinue – Checks the consistency of this object
laws – Returns the laws that this object obeys

Unique ID

eq – Equality test
id – Returns the unique ID of this object (deprecated)
isequal – Equality test
ne – Non-equality test

Inherited elements

additionalFields(self)¶: Documentation in replab.Str.additionalFields()

disp(self)¶: Documentation in replab.Str.disp()

headerStr(self)¶: Documentation in replab.Str.headerStr()

hiddenFields(self)¶: Documentation in replab.Str.hiddenFields()

longStr(self, maxRows, maxColumns)¶: Documentation in replab.Str.longStr()

shortStr(self, maxColumns)¶: Documentation in replab.Str.shortStr()

Own members

cache_¶

Contains the computed properties of this object

Type: struct

id_¶

Unique object ID

Type: integer

cache(self, name, value, handleExisting)¶

Sets the value of the designated property in the cache

If the property value is already in the cache, the behavior depends on the argument handleExisting:

overwrite: The existing value is overwritten
ignore: The existing value is left unchanged
isequal: The existing value and the given value are compared for equality using isequal
=: The existing value and the given value are compared for equality using ==
error: Raises an error

Note that function handles cannot be stored in the cache (if that is necessary, they can be wrapped in a scalar cell array); function handles are used to provide lazy evaluation of properties, and will be called once when the property is requested.

Parameters

name (charstring) – Name of the property
value – Value of the property, or a function handle able to compute the value
handleExisting ({'overwrite', 'ignore', 'isequal', '=='}, optional) – What to do if the value is already known, default 'ignore'

cached(self, name, fun)¶

Returns the cached property if it exists, computing it if necessary

If the property is not known, it will call the given function handle and cache the result.

Parameters

name (charstring) – Name of the property
fun (function_handle) – Function that computes the property

Returns

The property value

cachedOrDefault(self, name, defaultValue)¶

Returns the cached property if it exists, or the provided default value if it is unknown yet

See cached and cachedOrEmpty.

Parameters

name (charstring) – Name of the property
defaultValue – Value returned in case the property is unknown

Returns: The property value if known, otherwise defaultValue

cachedOrEmpty(self, name)¶

Returns the cached property if it exists, or [] if it is unknown yet

See cached and cachedOrDefault.

Parameters: name (charstring) – Name of the property
Returns: The property value if known, otherwise []

check(self)¶

Checks the consistency of this object

The default implementation checks the declared laws.

This method is useful in conjonction with dbstop if error.

Raises: An error if any law fails. –

checkAndContinue(self)¶

Checks the consistency of this object

The default implementation checks the declared laws.

This method is useful to see how many laws fail, as it catches errors and continues. For use with a debugger, check is better.

eq(self, rhs)¶

Equality test

Do not overload this, instead, overload isequal.

Parameters

self (object) – first object
rhs (object) – second object to compare to

Returns

true iff self == rhs

Return type

logical

id(self)¶: Returns the unique ID of this object (deprecated)

inCache(self, name)¶

Returns whether the value of the given property has already been computed

Parameters: name (charstring) – Name of the property
Returns: Whether the property value is in the cache
Return type: logical

isequal(lhs, rhs)¶

Equality test

Parameters

self (object) – first object
rhs (object) – second object to compare to

Returns

true iff both objects are the same

Return type

logical

laws(self)¶

Returns the laws that this object obeys

Returns: The Laws instance that is relevant for this object.
Return type: replab.Laws

ne(self, rhs)¶

Non-equality test

Do not overload this, instead, overload isequal.

Parameters

self (object) – first object
rhs (object) – second object to compare to

Returns

true iff self ~= rhs

Return type

logical

Domain¶

class replab.Domain¶

Bases: replab.Obj

Describes a set of elements with a common structure

At the base of the hierarchy, Domain describes a set of elements that can be tested for equality (eqv) and from which random samples can be taken (sample). Such sets are potentially infinite.

As Domain is an abstract base class, it contains abstract methods.

To quickly create an instance of Domain, the method lambda can be used, passing the method implementations as function handles.

Class members list

Properties

Prettyprinting

additionalFields – Returns the name/value pairs corresponding to additional fields to be printed
disp – Standard MATLAB/Octave display method
headerStr – Tiny single line description of the current object type
hiddenFields – Returns the names of the fields that are not printed as a row vector
longStr – Multi-line description of the current object
shortStr – Single line text description of the current object

Property cache

cache – Sets the value of the designated property in the cache
cached – Returns the cached property if it exists, computing it if necessary
cachedOrDefault – Returns the cached property if it exists, or the provided default value if it is unknown yet
cachedOrEmpty – Returns the cached property if it exists, or [] if it is unknown yet
inCache – Returns whether the value of the given property has already been computed

Laws

check – Checks the consistency of this object
checkAndContinue – Checks the consistency of this object
laws – Returns the laws that this object obeys

Unique ID

eq – Equality test
id – Returns the unique ID of this object (deprecated)
isequal – Equality test
ne – Non-equality test

Test helpers

assertEqv – Compares two elements for equality
assertNotEqv – Compares two elements for inequality

Sampling and equality test

eqv – Tests domain elements for equality/equivalence
sample – Samples an element from this set

Domain construction

lambda – Constructs a domain from function handles

Inherited elements

additionalFields(self)¶: Documentation in replab.Str.additionalFields()

cache(self, name, value, handleExisting)¶: Documentation in replab.Obj.cache()

cached(self, name, fun)¶: Documentation in replab.Obj.cached()

cachedOrDefault(self, name, defaultValue)¶: Documentation in replab.Obj.cachedOrDefault()

cachedOrEmpty(self, name)¶: Documentation in replab.Obj.cachedOrEmpty()

check(self)¶: Documentation in replab.Obj.check()

checkAndContinue(self)¶: Documentation in replab.Obj.checkAndContinue()

disp(self)¶: Documentation in replab.Str.disp()

eq(self, rhs)¶: Documentation in replab.Obj.eq()

headerStr(self)¶: Documentation in replab.Str.headerStr()

hiddenFields(self)¶: Documentation in replab.Str.hiddenFields()

id(self)¶: Documentation in replab.Obj.id()

inCache(self, name)¶: Documentation in replab.Obj.inCache()

isequal(lhs, rhs)¶: Documentation in replab.Obj.isequal()

laws(self)¶: Documentation in replab.Obj.laws()

longStr(self, maxRows, maxColumns)¶: Documentation in replab.Str.longStr()

ne(self, rhs)¶: Documentation in replab.Obj.ne()

shortStr(self, maxColumns)¶: Documentation in replab.Str.shortStr()

Own members

assertEqv(self, x, y, context)¶

Compares two elements for equality

Asserts that x and y are not equivalent

Parameters

x (domain element) – first element
y (domain element) – second element to compare
context (charstring, optional) – context

assertNotEqv(self, x, y, context)¶

Compares two elements for inequality

Asserts that x and y are equivalent

Parameters

x (domain element) – first element
y (domain element) – second element to compare
context (charstring) – context

eqv(self, t, u)¶

Tests domain elements for equality/equivalence

Parameters

t (domain element) – First element to test
u (domain element) – Second element to test

Returns

True when t and u are equivalent, and false otherwise

Return type

logical

static lambda(header, eqvFun, sampleFun)¶

Constructs a domain from function handles

Parameters

header (char) – Header display string
eqvFun (function_handle) – Handle implementing the eqv method
sampleFun (function_handle) – Handle implementing the sample method

Returns

The constructed domain

Return type

replab.Domain

sample(self)¶

Samples an element from this set

In general, this method does not make guarantees about genericity.

For CompactGroup however, this method must sample uniformly from the Haar measure.

Returns: Random set element
Return type: set element

Laws¶

class replab.Laws¶

Bases: replab.Str

Describes the laws that an algebraic structure should obey

Those laws are tested using random instances of the elements in the laws by the testing framework.

Laws are discovered by the getTestCases method, by enumerating the methods of this class.

Methods that start with a law_ prefix describe a single law. Then the method name has the following structure: law_{method name}_{types}. The part {method name} is the law name and corresponds to any valid identifier (thus the characters A-Z, a-z, 0-9 and _ are allowed). It will be interpreted as the law name, replacing underscore characters by spaces. The {types} part contains zero or more type identifiers: a type identifier is a letter (A-Z, a-z) followed by zero of more digits (0-9). This part does not contain any underscore. The number of type identifiers must correspond to the number of arguments of the method (excluding self). Each type identifier must correspond to a property field of this class of type replab.Domain, and those samplable sets will be used to sample the random instances passed to the law check method. Note that a law that does not require any arguments corresponds to a method name ending with an underscore.
Methods that start with a laws_ prefix must return another Laws instance (see also replab.laws.Collection). It enables delegation of checks when a tested object has subparts. For example, a FiniteGroup has a elementsSequence method of type Sequence, that is conveniently checked by replab.laws.SequenceLaws, see replab.laws.FiniteGroupLaws).

Example

>>> % We build a group from scratch, using function handles,
>>> % and verify that it obeys the group laws.
>>> n = 10;
>>> eqvFun = @(x, y) isequal(x, y);
>>> sampleFun = @() randperm(n);
>>> composeFun = @(x, y) x(y);
>>> identity = 1:n;
>>> inverseFun = @(x) arrayfun(@(i) find(x == i), 1:10);
>>> S10 = replab.Group.lambda('Permutations of 1..10', eqvFun, sampleFun, composeFun, identity, inverseFun);
>>> S10laws = S10.laws;
>>> S10laws.checkSilent
    1

Class members list

Properties

skipSlow – Whether to skip slow tests

Prettyprinting

additionalFields – Returns the name/value pairs corresponding to additional fields to be printed
disp – Standard MATLAB/Octave display method
headerStr – Tiny single line description of the current object type
hiddenFields – Returns the names of the fields that are not printed as a row vector
longStr – Multi-line description of the current object
shortStr – Single line text description of the current object

General

addTestCases – Adds law checks as test cases to the given test suite
assert – Assert function with a verbose error message
assertApproxEqual –
check – Runs the randomized tests without using MOxUnit
checkAndContinue – Runs the randomized tests without using MOxUnit
checkSilent – Runs the randomized tests without using MOxUnit, and returns whether all tests passed
empty – Returns an empty set of laws
getTestCases – Enumerates the laws present in this instance by looking for methods with the correct prefix
inexistent –
nRuns – Sets/gets the default number of runs
skip –
skippingSlow – Sets the skipSlow property to true and returns the Laws instance
thisIsSlow – Throws a replab:skip if skipSlow is true

Inherited elements

additionalFields(self)¶: Documentation in replab.Str.additionalFields()

assertApproxEqual()¶: No documentation

disp(self)¶: Documentation in replab.Str.disp()

headerStr(self)¶: Documentation in replab.Str.headerStr()

hiddenFields(self)¶: Documentation in replab.Str.hiddenFields()

inexistent()¶: No documentation

longStr(self, maxRows, maxColumns)¶: Documentation in replab.Str.longStr()

shortStr(self, maxColumns)¶: Documentation in replab.Str.shortStr()

skip()¶: No documentation

Own members

skipSlow¶

Whether to skip slow tests

Type: logical

addTestCases(self, testSuite, testName)¶

Adds law checks as test cases to the given test suite

Parameters

testSuite (MOxUnitTestSuite) – Adds the test cases of these laws to this
testName (charstring, optional) – name of the test

assert(self, predicate, context)¶: Assert function with a verbose error message

check(self)¶

Runs the randomized tests without using MOxUnit

This method is useful from the REPL command line.

This method stops at the first error.

checkAndContinue(self)¶

Runs the randomized tests without using MOxUnit

This method is useful from the REPL command line.

This method catches errors, displays them but does not throw.

checkSilent(self)¶

Runs the randomized tests without using MOxUnit, and returns whether all tests passed

Example

>>> S3 = replab.S(3);
>>> S3laws = S3.laws;
>>> S3laws.checkSilent
    1

Returns: True if all tests successful
Return type: logical

static empty()¶

Returns an empty set of laws

Returns: Empty set of laws
Return type: Laws

getTestCases(self)¶

Enumerates the laws present in this instance by looking for methods with the correct prefix

We look for the law_ and laws_ prefixes, see the Laws class description.

static nRuns(newValue)¶

Sets/gets the default number of runs

Parameters: newValue (integer, optional) – Sets the number of runs; if omitted returns the current number of runs
Returns: number of runs
Return type: integer

skippingSlow(self)¶: Sets the skipSlow property to true and returns the Laws instance

thisIsSlow(self)¶: Throws a replab:skip if skipSlow is true