The PTransf16 class

Class representing partial transformations.

SIMD accelerated class PTransf16 representing partial transformations on up to 16 points. Partial means it might not be defined everywhere. Undefined images are encoded as 255.

This class belongs to the hpcombi subpackage of libsemigroups_pybind11.

The functionality described on this page is only available if LIBSEMIGROUPS_HPCOMBI_ENABLED is True.

PTransf16 inherits from Vect16.

Contents

`PTransf16`	Class representing partial transformations.
`PTransf16.copy`(…)	Copy a `PTransf16`.
`PTransf16.domain_bitset`(…)	Returns a bit mask (as an `int`) for the domain of self (or its complement).
`PTransf16.domain_mask`(…)	Returns a mask for the domain.
`PTransf16.fix_points_bitset`(…)	Returns a bit mask (as an `int`) for the fixed, or non-fixed, points of self.
`PTransf16.fix_points_mask`(…)	Returns a mask for the fixed points of a partial transformation.
`PTransf16.image_bitset`(…)	Returns a bit mask (as an `int`) for the image of self (or its complement).
`PTransf16.image_mask`(…)	Returns a mask for the image.
`PTransf16.image_mask_ref`(…)	Returns a mask for the image.
`PTransf16.largest_fix_point`(…)	Returns the largest fix point.
`PTransf16.largest_moved_point`(…)	Returns the largest moved point.
`PTransf16.left_one`(…)	Returns the left one of a partial transformation.
`PTransf16.nb_fix_points`(…)	Returns the number of fixed points.
`PTransf16.one`(…)	Returns the identity partial transformation.
`PTransf16.rank`(…)	Returns the size of the image set of a partial transformation.
`PTransf16.rank_cmpestrm`(…)	Returns the size of the image set of a partial transformation.
`PTransf16.rank_ref`(…)	Returns the size of the image set of a partial transformation.
`PTransf16.right_one`(…)	Returns the right one of a partial transformation.
`PTransf16.smallest_fix_point`(…)	Returns the smallest fix point.
`PTransf16.smallest_moved_point`(…)	Returns the smallest moved point.
`PTransf16.validate`(…)	Check whether or not a `PTransf16` is well-defined.

Full API

class hpcombi.PTransf16

__init__(*args, **kwargs)

Overloaded function.

__init__(self: PTransf16) → None

Default constructor.

Constructs a PTransf16 object with its entries uninitialized. This means there is no guarantee about the values in the constructed object.

__init__(self: PTransf16, img: list[int]) → None

Construct a PTransf16 from a list of images.

This function constructs a PTransf16 from the list img of its entries. If the length of img is less than 16, then the constructed PTransf16 is fixed points at the end.

Parameters:

img (list[int]) – The list of images.

Raises:

LibsemigroupsError – if any value in img exceeds 16 and is not equal to 255.
LibsemigroupsError – if the length of img exceeds 16.
TypeError – if any value in img is larger than 255.

>>> from libsemigroups_pybind11.hpcombi import PTransf16
>>> PTransf16([1, 255, 1, 10])
PTransf16([ 1,255, 1,10, 4, 5, 6, 7, 8, 9,10,11,12,13,14,15])

__init__(self: PTransf16, dom: list[int], im: list[int]) → None

Construct from domain and image.

Constructs a partial transformation of degree n such that (dom[i])f = im[i] for all i and which is undefined (255 represents undefined in this context) on every other value in the range \([0, n)\).

Parameters:

dom (list[int]) – the domain.
im (list[int]) – the image.

Raises:

LibsemigroupsError – dom and im do not have the same size.
LibsemigroupsError – any value in dom or im is greater than 15.
LibsemigroupsError – there are repeated entries in dom.

>>> from libsemigroups_pybind11.hpcombi import PTransf16
>>> PTransf16([1, 2], [3, 4])
PTransf16([255, 3, 4,255,255,255,255,255,255,255,255,255,255,255,255,255])

copy(self: PTransf16) → PTransf16

Copy a PTransf16.

Returns:: A copy of the argument.
Return type:: PTransf16

>>> from libsemigroups_pybind11.hpcombi import PTransf16
>>> x = PTransf16([1, 2, 3, 4, 255])
>>> x.copy() is not x
True
>>> x.copy() == x
True

domain_bitset(self: PTransf16, complement: bool = False) → int

Returns a bit mask (as an int) for the domain of self (or its complement).

This function returns a bitset mask for the domain of self or its complement depending on the value of complement. If complement is True, then the returned mask has 1 in bit i if and only if i is in the domain of self. If complement is False, then the returned mask has 0 in bit i if and only if i is in the domain of self.

Parameters:: complement (bool) – whether or not the complement is sought (defaults to False).
Returns:: The domain bitset or its complement.
Return type:: int

>>> from libsemigroups_pybind11.hpcombi import PTransf16
>>> x = PTransf16([1, 3, 1, 255, 10])
>>> x.domain_bitset()
65527
>>> bin(x.domain_bitset())
'0b1111111111110111'
>>> bin(x.domain_bitset(True))
'0b1000'
>>> bool(x.domain_bitset() & 1 << 1)
True
>>> bool(x.domain_bitset() & 1 << 3)
False

domain_mask(self: PTransf16, complement: bool = False) → Vect16

Returns a mask for the domain.

This function returns a mask for the domain of self or its complement depending on the value of complement. If complement is True, then the returned mask has 0 in position i for every i in the domain of self and 255 (undefined) otherwise. If complement is False, then the returned mask has 0 in position i for every i not in the domain of self and 255 otherwise.

Parameters:: complement (bool) – whether or not the complement is sought (defaults to False).
Returns:: The domain mask or its complement.
Return type:: Vect16

>>> from libsemigroups_pybind11.hpcombi import PTransf16
>>> PTransf16([1, 0, 1]).domain_mask(True)
Vect16([ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0])
>>> PTransf16([1, 0, 1]).domain_mask(False)
Vect16([255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255])

fix_points_bitset(self: PTransf16, complement: bool = False) → int

Returns a bit mask (as an int) for the fixed, or non-fixed, points of self.

This function returns a bitset mask for the fixed points of self or the non-fixed points of self depending on the value of complement. If complement is True, then the returned mask has 1 in bit i if and only if i is fixed by self. If complement is False, then the returned mask has 0 in bit i if and only if i is fixed by self.

Parameters:: complement (bool) – whether or not the complement is sought (defaults to False).
Returns:: The fixed points bitset or its complement.
Return type:: int

>>> from libsemigroups_pybind11.hpcombi import PTransf16
>>> x = PTransf16([1, 3, 2, 255, 10])
>>> x.fix_points_bitset()
65508
>>> x.fix_points_bitset(False)
65508
>>> x.fix_points_bitset(True)
27
>>> bin(x.fix_points_bitset())
'0b1111111111100100'
>>> bin(x.fix_points_bitset(True))
'0b11011'

fix_points_mask(self: PTransf16, complement: bool = False) → Vect16

Returns a mask for the fixed points of a partial transformation.

This function returns a mask for the fixed points of self or its complement depending on the value of complement. If complement is True, then the returned mask has 255 in position i for every fixed point i of self and 0 (undefined) otherwise. If complement is False, then 0 and 255 are switched in the output.

Parameters:: complement (bool) – whether or not the complement is sought (defaults to False).
Returns:: The fixed points mask or its complement.
Return type:: Vect16

>>> from libsemigroups_pybind11.hpcombi import Vect16
>>> x = PTransf16([1, 3, 1, 255, 10])
>>> x.fix_points_mask()
Vect16([ 0, 0, 0, 0, 0,255,255,255,255,255,255,255,255,255,255,255])
>>> x.fix_points_mask(True)
Vect16([255,255,255,255,255, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0])
>>> x.one().fix_points_mask()
Vect16([255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255])
>>> x.one().fix_points_mask(True)
Vect16([ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0])

image_bitset(self: PTransf16, complement: bool = False) → int

Returns a bit mask (as an int) for the image of self (or its complement).

This function returns a bitset mask for the image of self or its complement depending on the value of complement. If complement is True, then the returned mask has 1 in bit i if and only if i is in the image of self. If complement is False, then the returned mask has 0 in bit i if and only if i is in the image of self.

Parameters:: complement (bool) – whether or not the complement is sought (defaults to False).
Returns:: The image bitset or its complement.
Return type:: int

>>> from libsemigroups_pybind11.hpcombi import PTransf16
>>> x = PTransf16([1, 3, 1, 255, 10])
>>> x.image_bitset()
65514
>>> bin(x.image_bitset())
'0b1111111111101010'
>>> bin(x.image_bitset(True))
'0b10101'
>>> bool(x.image_bitset() & 1 << 1)
True
>>> bool(x.image_bitset() & 1 << 2)
False

image_mask(self: PTransf16, complement: bool = False) → Vect16

Returns a mask for the image.

This function returns a mask for the image of self or its complement depending on the value of complement. If complement is True, then the returned mask has 0 in position i for every i in the image of self and 255 (undefined) otherwise. If complement is False, then the returned mask has 0 in position i for every i not in the image of self and 255 otherwise.

Parameters:: complement (bool) – whether or not the complement is sought (defaults to False).
Returns:: The image mask or its complement.
Return type:: Vect16

>>> from libsemigroups_pybind11.hpcombi import PTransf16
>>> PTransf16([1, 0, 1]).image_mask(True)
Vect16([ 0, 0,255, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0])
>>> PTransf16([1, 0, 1]).image_mask(False)
Vect16([255,255, 0,255,255,255,255,255,255,255,255,255,255,255,255,255])

image_mask_ref(self: PTransf16, complement: bool = False) → Vect16

Returns a mask for the image.

This function returns a mask for the image of self or its complement depending on the value of complement. If complement is True, then the returned mask has 0 in position i for every i in the image of self and 255 (undefined) otherwise. If complement is False, then the returned mask has 0 in position i for every i not in the image of self and 255 otherwise.

This is the reference implementation, use image_mask for better performance.

Parameters:: complement (bool) – whether or not the complement is sought (defaults to False).
Returns:: The image mask or its complement.
Return type:: Vect16

>>> from libsemigroups_pybind11.hpcombi import PTransf16
>>> PTransf16([1, 0, 1]).image_mask_ref(True)
Vect16([ 0, 0,255, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0])
>>> PTransf16([1, 0, 1]).image_mask_ref(False)
Vect16([255,255, 0,255,255,255,255,255,255,255,255,255,255,255,255,255])

largest_fix_point(self: PTransf16) → int

Returns the largest fix point.

This function returns the largest integer i such that self[i] == i or 255 if self[i] != i for all i < 16.

Returns:: The largest fixed point.
Return type:: int

>>> from libsemigroups_pybind11.hpcombi import PTransf16
>>> PTransf16([1, 3, 2, 255, 10]).largest_fix_point()
15
>>> PTransf16.one().largest_fix_point()
15

largest_moved_point(self: PTransf16) → int

Returns the largest moved point.

This function returns the largest integer i such that self[i] != i or 255 if self[i] == i for all i < 16.

Returns:: The largest moved point.
Return type:: int

>>> from libsemigroups_pybind11.hpcombi import PTransf16
>>> PTransf16([1, 3, 2, 255, 10]).largest_moved_point()
4
>>> PTransf16.one().largest_moved_point()
255

left_one(self: PTransf16) → PTransf16

Returns the left one of a partial transformation.

This function returns a newly constructed PTransf16 with the same image as self and that acts as the identity on self by left multiplication.

Returns:: A left one of self.
Return type:: PTransf16

>>> from libsemigroups_pybind11.hpcombi import PTransf16
>>> x = PTransf16([1, 3, 1, 255, 10])
>>> x.domain_bitset() == x.left_one().domain_bitset()
True
>>> x.left_one() * x == x
True

nb_fix_points(self: PTransf16) → int

Returns the number of fixed points.

This function returns the number of integers i such that self[i] != i and i < 16.

Returns:: The number of fixed points.
Return type:: int

>>> from libsemigroups_pybind11.hpcombi import PTransf16
>>> PTransf16([1, 3, 2, 255, 10]).nb_fix_points()
12
>>> PTransf16.one().nb_fix_points()
16

static one() → PTransf16

Returns the identity partial transformation.

This function returns the identity PTransf16 which fixes every value in \([0, 16)\).

Returns:: The identity transformation.
Return type:: PTransf16

>>> from libsemigroups_pybind11.hpcombi import PTransf16
>>> x = PTransf16([1, 0, 1])
>>> x * x.one() == PTransf16.one() * x == x
True

rank(self: PTransf16) → int

Returns the size of the image set of a partial transformation.

This function returns the size of the image set of self.

Returns:: The size of the image set.
Return type:: int

>>> from libsemigroups_pybind11.hpcombi import Vect16
>>> x = PTransf16([1, 3, 1, 255, 10])
>>> x.rank()
13

rank_cmpestrm(self: PTransf16) → int

Returns the size of the image set of a partial transformation.

This function returns the size of the image set of self.

Returns:: The size of the image set.
Return type:: int

>>> from libsemigroups_pybind11.hpcombi import Vect16
>>> x = PTransf16([1, 3, 1, 255, 10])
>>> x.rank_cmpestrm()
13

rank_ref(self: PTransf16) → int

Returns the size of the image set of a partial transformation.

This function returns the size of the image set of self.

Returns:: The size of the image set.
Return type:: int

>>> from libsemigroups_pybind11.hpcombi import PTransf16
>>> x = PTransf16([1, 3, 1, 255, 10])
>>> x.rank_ref()
13

right_one(self: PTransf16) → PTransf16

Returns the right one of a partial transformation.

This function returns a newly constructed PTransf16 with the same image as self and that acts as the identity on self by right multiplication.

Returns:: A right one of self.
Return type:: PTransf16

>>> from libsemigroups_pybind11.hpcombi import PTransf16
>>> x = PTransf16([1, 3, 1, 255, 10])
>>> x.image_bitset() == x.right_one().image_bitset()
True
>>> x * x.right_one() == x
True

smallest_fix_point(self: PTransf16) → int

Returns the smallest fix point.

This function returns the smallest integer i such that self[i] == i or 255 if self[i] != i for all i < 16.

Returns:: The smallest fixed point.
Return type:: int

>>> from libsemigroups_pybind11.hpcombi import PTransf16
>>> PTransf16([1, 3, 2, 255, 10]).smallest_fix_point()
2

smallest_moved_point(self: PTransf16) → int

Returns the smallest moved point.

This function returns the smallest integer i such that self[i] != i or 255 if self[i] == i for all i < 16.

Returns:: The smallest moved point.
Return type:: int

>>> from libsemigroups_pybind11.hpcombi import PTransf16
>>> PTransf16([1, 3, 2, 255, 10]).smallest_moved_point()
0
>>> PTransf16.one().smallest_moved_point()
255

validate(self: PTransf16, bound: int = 16) → bool

Check whether or not a PTransf16 is well-defined.

This function returns True if self is a well-defined partial transformation (i.e. no image value is larger than 15) on the values 0 up to bound.

Parameters:: bound (int) – the bound (defaults to 16).
Returns:: Whether or not self is valid.
Return type:: bool

Note

It should not be possible to create an invalid PTransf16 in libsemigroups_pybind11, and this function is only included for completeness.

>>> from libsemigroups_pybind11.hpcombi import PTransf16
>>> PTransf16([1, 0, 1]).validate()
True