diff --git a/docs/source-old/_static/custom.css b/docs/source-old/_static/custom.css new file mode 100644 index 000000000..c82ec54e3 --- /dev/null +++ b/docs/source-old/_static/custom.css @@ -0,0 +1,3 @@ +.wy-nav-content { + max-width: 1000px; +} diff --git a/docs/source-old/action.rst b/docs/source-old/action.rst new file mode 100644 index 000000000..af03bea82 --- /dev/null +++ b/docs/source-old/action.rst @@ -0,0 +1,57 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Actions +======= + +.. cpp:namespace:: libsemigroups + +This page contains an overview summary of the functionality in +``libsemigroups`` for finding actions of semigroups, or groups, on sets. The +notion of an "action" in the context of ``libsemigroups`` is analogous to the +notion of an orbit of a group. + +You are unlikely to want to use :cpp:class:`Action` directly, but rather via +the more convenient aliases :cpp:any:`RightAction` and :cpp:any:`LeftAction`. +To use :cpp:any:`RightAction` and :cpp:any:`LeftAction` with custom types, +actions, and so on, see :cpp:class:`ActionTraits`. +See also :cpp:any:`ImageLeftAction` and :cpp:any:`ImageRightAction`. + +.. code-block:: cpp + + using namespace libsemigroups; + RightAction, PPerm<16>, ImageRightAction, PPerm<16>>> o; + o.add_seed(PPerm<16>::identity(16)); + o.add_generator( + PPerm<16>({0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15}, + {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 0}, + 16)); + o.add_generator( + PPerm<16>({0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15}, + {1, 0, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15}, + 16)); + o.add_generator( + PPerm<16>({1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15}, + {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14}, + 16)); + o.add_generator( + PPerm<16>({0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14}, + {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15}, + 16)); + o.reserve(70000); + o.size(); // returns 65536 + + +The classes in ``libsemigroups`` for actions are: + +.. toctree:: + :maxdepth: 1 + + _generated/libsemigroups__action.rst + _generated/libsemigroups__actiontraits + api/left-action + api/right-action + _generated/libsemigroups__side.rst diff --git a/docs/source-old/adapters.rst b/docs/source-old/adapters.rst new file mode 100644 index 000000000..d18264e13 --- /dev/null +++ b/docs/source-old/adapters.rst @@ -0,0 +1,57 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _Adapters: + +Adapters +======== + +Declared in ``adapters.hpp``. + +This file contains class templates for adapting a user-defined type for use +with the algorithms in ``libsemigroups``. There are explicit implementations for +relevant element types from ``libsemigroups`` and ``HPCombi``, details of which +can be found elsewhere in this documentation. + +No default implementation +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following adapters have no default implementation for arbitrary types: + +.. toctree:: + :maxdepth: 1 + + _generated/libsemigroups__complexity.rst + _generated/libsemigroups__degree.rst + _generated/libsemigroups__imageleftaction.rst + _generated/libsemigroups__imagerightaction.rst + _generated/libsemigroups__increasedegree.rst + _generated/libsemigroups__inverse.rst + _generated/libsemigroups__lambda.rst + _generated/libsemigroups__lambdavalue.rst + _generated/libsemigroups__one.rst + _generated/libsemigroups__product.rst + _generated/libsemigroups__rho.rst + _generated/libsemigroups__rhovalue.rst + +Default implementation +~~~~~~~~~~~~~~~~~~~~~~ + +The following adapters do have a default implementation for arbitrary types: + +.. The following are not in the yml setup because JDM couldn't figure out how + to generate the rst page for EqualTo::operator(). + +.. toctree:: + :maxdepth: 1 + + api/equalto.rst + api/hash.rst + api/less.rst + api/ontuples.rst + api/onsets.rst + _generated/libsemigroups__rankstate.rst + api/swap.rst diff --git a/docs/source-old/api/bipart_validate.rst b/docs/source-old/api/bipart_validate.rst new file mode 100644 index 000000000..5ff0a859c --- /dev/null +++ b/docs/source-old/api/bipart_validate.rst @@ -0,0 +1,12 @@ +.. Copyright (c) 2019-21, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + + +Validating Bipartitions +======================= + +.. doxygenfunction:: libsemigroups::validate(Bipartition const&) + :project: libsemigroups diff --git a/docs/source-old/api/digraph-helper.rst b/docs/source-old/api/digraph-helper.rst new file mode 100644 index 000000000..8e1afad77 --- /dev/null +++ b/docs/source-old/api/digraph-helper.rst @@ -0,0 +1,64 @@ +.. Copyright (c) 2020-2022, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Helper functions for ActionDigraph +================================== + +Overview +-------- + +Defined in ``action-digraph-helper.hpp``. + +This page contains the documentation for helper function for the class +:cpp:type:`libsemigroups::ActionDigraph`. + +Full API +-------- + +.. doxygenfunction:: libsemigroups::operator<<(std::ostream&, ActionDigraph const&) + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::action_digraph_helper::follow_path + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::action_digraph_helper::follow_path_nc(ActionDigraph const&, node_type const, word_type const&) noexcept + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::action_digraph_helper::follow_path_nc(ActionDigraph const&, node_type const, S, S) noexcept + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::action_digraph_helper::last_node_on_path + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::action_digraph_helper::last_node_on_path_nc + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::action_digraph_helper::is_acyclic(ActionDigraph const&) + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::action_digraph_helper::is_acyclic(ActionDigraph const&, node_type) + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::action_digraph_helper::is_reachable + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::action_digraph_helper::topological_sort(ActionDigraph const&) + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::action_digraph_helper::topological_sort(ActionDigraph const&, node_type) + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::action_digraph_helper::add_cycle(ActionDigraph&, U, U) + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::action_digraph_helper::add_cycle(ActionDigraph&, size_t) + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::action_digraph_helper::make(size_t, std::initializer_list>) + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::action_digraph_helper::is_connected(ActionDigraph const&) + :project: libsemigroups diff --git a/docs/source-old/api/equalto.rst b/docs/source-old/api/equalto.rst new file mode 100644 index 000000000..9e49ec682 --- /dev/null +++ b/docs/source-old/api/equalto.rst @@ -0,0 +1,15 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +EqualTo +======= + +.. doxygenstruct:: libsemigroups::EqualTo + :project: libsemigroups + :members: diff --git a/docs/source-old/api/fpsemi-examples.rst b/docs/source-old/api/fpsemi-examples.rst new file mode 100644 index 000000000..a3dda2240 --- /dev/null +++ b/docs/source-old/api/fpsemi-examples.rst @@ -0,0 +1,205 @@ +.. Copyright (c) 2022, M. T. Whyte + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + + This file only exists because Breathe always displays all members when + documenting a namespace, and this is nicer for now. + +.. cpp:namespace:: libsemigroups + +Examples +-------- + +This page contains the documentation for various examples of presentations of +finitely presented semigroups and monoids. + +Presentations from the following sources are implemented: :cite:`Gay1999aa`; +:cite:`Godelle2009aa`; :cite:`East2022aa`; :cite:`Maltcev2007aa`; +:cite:`Arthur2000aa`; :cite:`Kudryavtseva2006aa`; :cite:`Burnside2012aa`; +:cite:`Ganyushkin2009aa`; :cite:`Cassaigne2001aa`; :cite:`Campbell1994aa`; +:cite:`Abram2022aa`; :cite:`Easdown2007aa`; :cite:`FitzGerald2003aa`; +:cite:`East2011aa`; :cite:`Ayik2000aa`; :cite:`Ruskuc1995aa`; +:cite:`Aizenstat1958aa`; :cite:`Coxeter1979aa`; :cite:`Knuth1970aa`; +:cite:`Lascoux1981aa`; :cite:`Moore1897aa`; :cite:`Aizenstat1962aa`; +:cite:`Fernandes2022aa`; :cite:`Fernandes2022ab`. + +.. cpp:type:: libsemigroups::fpsemigroup::author + + The values in this enum class are used to specify the authors of a + presentation. Where there are different presentations by different authors, + values of this type can be passed as an argument to disambiguate which + presentation is wanted. + +.. doxygenfunction:: libsemigroups::fpsemigroup::operator+(author, author) + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::operator<<(std::ostringstream&, author) + :project: libsemigroups + +Contents +~~~~~~~~ + +.. cpp:namespace:: libsemigroups::fpsemigroup + +.. list-table:: + :widths: 50 50 + :header-rows: 0 + + * - :cpp:any:`symmetric_group` + - A presentation for the symmetric group. + + * - :cpp:any:`alternating_group` + - A presentation for the alternating group. + + * - :cpp:any:`full_transformation_monoid` + - A presentation for the full transformation monoid. + + * - :cpp:any:`partial_transformation_monoid` + - A presentation for the partial transformation monoid. + + * - :cpp:any:`symmetric_inverse_monoid` + - A presentation for the symmetric inverse monoid. + + * - :cpp:any:`dual_symmetric_inverse_monoid` + - A presentation for the dual symmetric inverse monoid. + + * - :cpp:any:`uniform_block_bijection_monoid` + - A presentation for the uniform block bijection monoid. + + * - :cpp:any:`partition_monoid` + - A presentation for the partition monoid. + + * - :cpp:any:`brauer_monoid` + - A presentation for the Brauer monoid. + + * - :cpp:any:`rectangular_band` + - A presentation for a rectangular band. + + * - :cpp:any:`stellar_monoid` + - A presentation for the stellar monoid. + + * - :cpp:any:`chinese_monoid` + - A presentation for the Chinese monoid. + + * - :cpp:any:`monogenic_semigroup` + - A presentation for a monogenic semigroup. + + * - :cpp:any:`plactic_monoid` + - A presentation for the plactic monoid. + + * - :cpp:any:`stylic_monoid` + - A presentation for the stylic monoid. + + * - :cpp:any:`fibonacci_semigroup` + - A presentation for a Fibonacci semigroup. + + * - :cpp:any:`temperley_lieb_monoid` + - A presentation for the Temperley-Lieb monoid. + + * - :cpp:any:`singular_brauer_monoid` + - A presentation for the singular part of the Brauer monoid. + + * - :cpp:any:`orientation_preserving_monoid` + - A presentation for the monoid of orientation preserving + mappings. + + * - :cpp:any:`orientation_reversing_monoid` + - A presentation for the monoid of orientation reversing + mappings. + + * - :cpp:any:`order_preserving_monoid` + - A presentation for the monoid of order preserving + mappings. + + * - :cpp:any:`cyclic_inverse_monoid` + - A presentation for the cyclic inverse monoid. + + * - :cpp:any:`order_preserving_cyclic_inverse_monoid` + - A presentation for the order-preserving part of the cyclic inverse monoid. + + * - :cpp:any:`partial_isometries_cycle_graph_monoid` + - A presentation for the monoid of partial isometries of a cycle graph. + + * - :cpp:any:`not_symmetric_group` + - A non-presentation for the symmetric group. +.. cpp:namespace-pop:: + +Full API +~~~~~~~~ + +.. doxygenfunction:: libsemigroups::fpsemigroup::symmetric_group + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::alternating_group + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::full_transformation_monoid + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::partial_transformation_monoid + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::symmetric_inverse_monoid + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::dual_symmetric_inverse_monoid + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::uniform_block_bijection_monoid + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::partition_monoid + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::brauer_monoid + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::rectangular_band + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::stellar_monoid + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::chinese_monoid + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::monogenic_semigroup + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::plactic_monoid + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::stylic_monoid + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::fibonacci_semigroup + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::temperley_lieb_monoid + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::singular_brauer_monoid + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::orientation_preserving_monoid + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::orientation_reversing_monoid + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::order_preserving_monoid + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::cyclic_inverse_monoid + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::order_preserving_cyclic_inverse_monoid + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::partial_isometries_cycle_graph_monoid + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::fpsemigroup::not_symmetric_group + :project: libsemigroups diff --git a/docs/source-old/api/hash.rst b/docs/source-old/api/hash.rst new file mode 100644 index 000000000..194bef637 --- /dev/null +++ b/docs/source-old/api/hash.rst @@ -0,0 +1,15 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +Hash +==== + +.. doxygenstruct:: libsemigroups::Hash + :project: libsemigroups + :members: diff --git a/docs/source-old/api/hpcombi-complexity.rst b/docs/source-old/api/hpcombi-complexity.rst new file mode 100644 index 000000000..ba9e24371 --- /dev/null +++ b/docs/source-old/api/hpcombi-complexity.rst @@ -0,0 +1,15 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +Complexity +========== + +.. doxygenstruct:: libsemigroups::Complexity< TPTransf16Subclass, std::enable_if_t< std::is_base_of< HPCombi::PTransf16, TPTransf16Subclass >::value > > + :project: libsemigroups + :members: diff --git a/docs/source-old/api/hpcombi-degree.rst b/docs/source-old/api/hpcombi-degree.rst new file mode 100644 index 000000000..b3dd87ab2 --- /dev/null +++ b/docs/source-old/api/hpcombi-degree.rst @@ -0,0 +1,15 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +Degree +====== + +.. doxygenstruct:: libsemigroups::Degree< TPTransf16Subclass, std::enable_if_t< std::is_base_of< HPCombi::PTransf16, TPTransf16Subclass >::value > > + :project: libsemigroups + :members: diff --git a/docs/source-old/api/hpcombi-imageleftaction.rst b/docs/source-old/api/hpcombi-imageleftaction.rst new file mode 100644 index 000000000..6606a4576 --- /dev/null +++ b/docs/source-old/api/hpcombi-imageleftaction.rst @@ -0,0 +1,15 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +ImageLeftAction +================ + +.. doxygenstruct:: libsemigroups::ImageLeftAction< HPCombi::PPerm16, HPCombi::PPerm16 > + :project: libsemigroups + :members: diff --git a/docs/source-old/api/hpcombi-imagerightaction.rst b/docs/source-old/api/hpcombi-imagerightaction.rst new file mode 100644 index 000000000..5906a4bb9 --- /dev/null +++ b/docs/source-old/api/hpcombi-imagerightaction.rst @@ -0,0 +1,19 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +ImageRightAction +================ + +.. doxygenstruct:: libsemigroups::ImageRightAction< HPCombi::Perm16, TIntType, std::enable_if_t< std::is_integral< TIntType >::value > > + :project: libsemigroups + :members: + +.. doxygenstruct:: libsemigroups::ImageRightAction< HPCombi::PPerm16, HPCombi::PPerm16 > + :project: libsemigroups + :members: diff --git a/docs/source-old/api/hpcombi-inverse.rst b/docs/source-old/api/hpcombi-inverse.rst new file mode 100644 index 000000000..dc3da957f --- /dev/null +++ b/docs/source-old/api/hpcombi-inverse.rst @@ -0,0 +1,15 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +Inverse +======= + +.. doxygenstruct:: libsemigroups::Inverse< HPCombi::Perm16 > + :project: libsemigroups + :members: diff --git a/docs/source-old/api/hpcombi-one.rst b/docs/source-old/api/hpcombi-one.rst new file mode 100644 index 000000000..0409a67ff --- /dev/null +++ b/docs/source-old/api/hpcombi-one.rst @@ -0,0 +1,15 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +One +=== + +.. doxygenstruct:: libsemigroups::One< TPTransf16Subclass, std::enable_if_t< std::is_base_of< HPCombi::PTransf16, TPTransf16Subclass >::value > > + :project: libsemigroups + :members: diff --git a/docs/source-old/api/hpcombi-product.rst b/docs/source-old/api/hpcombi-product.rst new file mode 100644 index 000000000..f6da20553 --- /dev/null +++ b/docs/source-old/api/hpcombi-product.rst @@ -0,0 +1,15 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +Product +======= + +.. doxygenstruct:: libsemigroups::Product< TPTransf16Subclass, std::enable_if_t< std::is_base_of< HPCombi::PTransf16, TPTransf16Subclass >::value > > + :project: libsemigroups + :members: diff --git a/docs/source-old/api/hpcombi-swap.rst b/docs/source-old/api/hpcombi-swap.rst new file mode 100644 index 000000000..73bdf016e --- /dev/null +++ b/docs/source-old/api/hpcombi-swap.rst @@ -0,0 +1,15 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +Swap +==== + +.. doxygenstruct:: libsemigroups::Swap< TPTransf16Subclass, std::enable_if_t< std::is_base_of< HPCombi::PTransf16, TPTransf16Subclass >::value > > + :project: libsemigroups + :members: diff --git a/docs/source-old/api/left-action.rst b/docs/source-old/api/left-action.rst new file mode 100644 index 000000000..54e1f7977 --- /dev/null +++ b/docs/source-old/api/left-action.rst @@ -0,0 +1,11 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +LeftAction +========== + +.. doxygentypedef:: libsemigroups::LeftAction + :project: libsemigroups diff --git a/docs/source-old/api/less.rst b/docs/source-old/api/less.rst new file mode 100644 index 000000000..ad3046949 --- /dev/null +++ b/docs/source-old/api/less.rst @@ -0,0 +1,15 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +Less +==== + +.. doxygenstruct:: libsemigroups::Less + :project: libsemigroups + :members: diff --git a/docs/source-old/api/lexicographical_compare_pointers.rst b/docs/source-old/api/lexicographical_compare_pointers.rst new file mode 100644 index 000000000..9baff8176 --- /dev/null +++ b/docs/source-old/api/lexicographical_compare_pointers.rst @@ -0,0 +1,11 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +lexicographical_compare (pointers) +================================== + +.. doxygenfunction:: libsemigroups::lexicographical_compare(T *const, T *const) + :project: libsemigroups diff --git a/docs/source-old/api/lexicographical_compare_references.rst b/docs/source-old/api/lexicographical_compare_references.rst new file mode 100644 index 000000000..28a40bec0 --- /dev/null +++ b/docs/source-old/api/lexicographical_compare_references.rst @@ -0,0 +1,11 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +lexicographical_compare (references) +==================================== + +.. doxygenfunction:: libsemigroups::lexicographical_compare(T const&, T const&) + :project: libsemigroups diff --git a/docs/source-old/api/lexicographicalcompare_struct.rst b/docs/source-old/api/lexicographicalcompare_struct.rst new file mode 100644 index 000000000..8ca01d513 --- /dev/null +++ b/docs/source-old/api/lexicographicalcompare_struct.rst @@ -0,0 +1,12 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +LexicographicalCompare +====================== + +.. doxygenstruct:: libsemigroups::LexicographicalCompare + :project: libsemigroups + :members: diff --git a/docs/source-old/api/make-froidure-pin.rst b/docs/source-old/api/make-froidure-pin.rst new file mode 100644 index 000000000..b2d90776b --- /dev/null +++ b/docs/source-old/api/make-froidure-pin.rst @@ -0,0 +1,19 @@ +.. Copyright (c) 2022, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Making FroidurePin objects from other objects +============================================= + +Defined in ``make-froidure-pin.hpp``. + +This page describes the functionality for creating :cpp:any:`FroidurePin` +objects in ``libsemigroups`` from other types of objects. + +.. doxygenfunction:: libsemigroups::make(ActionDigraph const&, size_t, size_t) + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::make(ActionDigraph const&) + :project: libsemigroups diff --git a/docs/source-old/api/make-present.rst b/docs/source-old/api/make-present.rst new file mode 100644 index 000000000..e9a8249ee --- /dev/null +++ b/docs/source-old/api/make-present.rst @@ -0,0 +1,43 @@ +.. Copyright (c) 2022, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Making presentations from other objects +======================================= + +Defined in ``make-present.hpp``. + +This page describes the functionality for creating semigroup and +monoid presentations in ``libsemigroups`` from other types of objects. + +.. doxygenfunction:: make(FroidurePinBase&) + :project: libsemigroups + +.. doxygenfunction:: make(FroidurePinBase &, std::string const &) + :project: libsemigroups + +.. doxygenfunction:: make(Presentation const &, F&&) + :project: libsemigroups + +.. cpp:function:: template \ + S make(Presentation const & p) + + Make a presentation from a different type of presentation. + + Returns a presentation equivalent to the input presentation but of a + different type (for example, can be used to convert from ``std::string`` to + ``word_type``). + + :tparam S: + the type of the returned presentation, must be a type of + :cpp:any:`Presentation` + :tparam W: the type of the words in the input presentation + :param p: the input presentation + + :returns: A value of type ``S``. + :throws LibsemigroupsException: if ``p.validate()`` throws. + +.. doxygenfunction:: make(Presentation const &, std::string const &) + :project: libsemigroups diff --git a/docs/source-old/api/number_of_words.rst b/docs/source-old/api/number_of_words.rst new file mode 100644 index 000000000..b03a66999 --- /dev/null +++ b/docs/source-old/api/number_of_words.rst @@ -0,0 +1,14 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Number of words +=============== + +The function :cpp:any:`libsemigroups::number_of_words` can be used to compute +the number of words over an alphabet with a given number of letters. + +.. doxygenfunction:: libsemigroups::number_of_words(size_t n, size_t min, size_t max) + :project: libsemigroups diff --git a/docs/source-old/api/onsets.rst b/docs/source-old/api/onsets.rst new file mode 100644 index 000000000..2afff471a --- /dev/null +++ b/docs/source-old/api/onsets.rst @@ -0,0 +1,15 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +OnSets +====== + +.. doxygenstruct:: libsemigroups::OnSets + :project: libsemigroups + :members: diff --git a/docs/source-old/api/ontuples.rst b/docs/source-old/api/ontuples.rst new file mode 100644 index 000000000..1740fa7a7 --- /dev/null +++ b/docs/source-old/api/ontuples.rst @@ -0,0 +1,15 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +OnTuples +======== + +.. doxygenstruct:: libsemigroups::OnTuples + :project: libsemigroups + :members: diff --git a/docs/source-old/api/pbr_validate.rst b/docs/source-old/api/pbr_validate.rst new file mode 100644 index 000000000..c838b2800 --- /dev/null +++ b/docs/source-old/api/pbr_validate.rst @@ -0,0 +1,12 @@ +.. Copyright (c) 2019-21, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + + +Validating PBRs +=============== + +.. doxygenfunction:: libsemigroups::validate(PBR const& x) + :project: libsemigroups diff --git a/docs/source-old/api/perm_validate.rst b/docs/source-old/api/perm_validate.rst new file mode 100644 index 000000000..d8b62cf93 --- /dev/null +++ b/docs/source-old/api/perm_validate.rst @@ -0,0 +1,12 @@ +.. Copyright (c) 2019-21, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + + +Validating permutations +======================= + +.. doxygenfunction:: libsemigroups::validate(Perm const& x) + :project: libsemigroups diff --git a/docs/source-old/api/pperm_validate.rst b/docs/source-old/api/pperm_validate.rst new file mode 100644 index 000000000..6aa0c8f5d --- /dev/null +++ b/docs/source-old/api/pperm_validate.rst @@ -0,0 +1,12 @@ +.. Copyright (c) 2019-21, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + + +Validating partial perms +======================== + +.. doxygenfunction:: libsemigroups::validate(PPerm const& x) + :project: libsemigroups diff --git a/docs/source-old/api/present-helper.rst b/docs/source-old/api/present-helper.rst new file mode 100644 index 000000000..83a58e943 --- /dev/null +++ b/docs/source-old/api/present-helper.rst @@ -0,0 +1,159 @@ +.. Copyright (c) 2022, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + + This file only exists because Breathe always displays all members when + documenting a namespace, and this is nicer for now. + +.. cpp:namespace:: libsemigroups + +Presentation helpers +-------------------- + +Defined in ``present.hpp`` and ``knuth-bendix.hpp``. + +This page contains the documentation for various helper functions for +manipulating :cpp:type:`Presentation` objects. All such functions are contained in +the namespace ``presentation``. + +These functions are available in the ``present.hpp`` file except +:cpp:any:`redundant_rule` which is in ``knuth-bendix.hpp``. + +Contents +~~~~~~~~ + +.. cpp:namespace:: libsemigroups::presentation + +.. list-table:: + :widths: 50 50 + :header-rows: 0 + + * - :cpp:any:`word_type operator+(word_type const& u, word_type const& w)` + - Concatenate two words or strings. + + * - :cpp:any:`void operator+=(word_type& u, word_type const& w)` + - Concatenate a word/string with another word/string in-place. + + * - :cpp:any:`template \::value>> T pow(T const&, size_t)` + - Take a power of a word or string. + + * - :cpp:any:`template \::value>> void pow_inplace(T&, size_t)` + - Take a power of a word or string. + + * - :cpp:any:`template \::value>> T prod(T const&, size_t, size_t, int)` + - Take a product from a collection of letters. + + * - :cpp:any:`add_rule` + - Add a rule to the presentation. + + * - :cpp:any:`add_rule_and_check` + - Add a rule to the presentation and check. + + * - :cpp:any:`add_identity_rules` + - Add rules for an identity element. + + * - :cpp:any:`add_inverse_rules` + - Add rules for inverses. + + * - :cpp:any:`add_zero_rules` + - Add rules for a zero element. + + * - :cpp:any:`are_rules_sorted` + - Check if the rules :math:`u_1 = v_1, \ldots, u_n = v_n` satisfy + :math:`u_1v_1 < \cdots < u_nv_n` where :math:`<` is the shortlex order. + + * - :cpp:any:`change_alphabet` + - Change or re-order the alphabet. + + * - :cpp:any:`character` + - Return a ``char`` by index (ordered for readability). + + * - :cpp:any:`first_unused_letter` + - Returns the first letter **not** in the alphabet of a presentation. + + * - :cpp:any:`greedy_reduce_length` + - Greedily reduce the length of the presentation using + :cpp:any:`longest_common_subword`. + + * - :cpp:any:`is_strongly_compressible` + - Returns ``true`` if the 1-relation presentation can be strongly + compressed. + + * - :cpp:any:`length` + - Return the sum of the lengths of the rules. + + * - :cpp:any:`letter` + - Return a possible letter by index. + + * - :cpp:any:`longest_common_subword` + - Returns the longest common subword of the rules. + + * - :cpp:any:`longest_rule` + - Returns an iterator pointing at the left hand side of the first rule of + maximal length. + + * - :cpp:any:`longest_rule_length` + - Returns the maximum length of a rule. + + * - :cpp:any:`make_semigroup` + - Convert a monoid presentation to a semigroup presentation. + + * - :cpp:any:`normalize_alphabet` + - Modify the presentation so that the alphabet is :math:`\{0, \ldots, n - + 1\}` (or equivalent) and rewrites the rules. + + * - :cpp:any:`reduce_complements` + - If there are rules :math:`u = v` and :math:`v = w` where + :math:`|w| < |v| `, then replace :math:`u = v` by :math:`u = w`. + + * - :cpp:any:`reduce_to_2_generators` + - Reduce the number of generators in a \f$1\f$-relation presentation to `2`. + + * - :cpp:any:`redundant_rule` + - Return an iterator pointing at the left hand side of a redundant rule. + + * - :cpp:any:`remove_duplicate_rules` + - Remove duplicate rules. + + * - :cpp:any:`remove_redundant_generators` + - Remove any trivially redundant generators. + + * - :cpp:any:`remove_trivial_rules` + - Remove rules consisting of identical words. + + * - :cpp:any:`replace_subword` + - Replace non-overlapping instances of a subword. + + * - :cpp:any:`replace_word` + - Replace instances of a word occupying either side of a rule. + + * - :cpp:any:`reverse` + - Reverse every word in every rule. + + * - :cpp:any:`shortest_rule` + - Returns an iterator pointing at the left hand side of the first rule of + minimal length. + + * - :cpp:any:`shortest_rule_length` + - Returns the minimum length of a rule. + + * - :cpp:any:`sort_each_rule` + - Sort each rule :math:`u = v` so that the left hand side is shortlex greater + than the right hand side. + + * - :cpp:any:`sort_rules` + - Sort the rules :math:`u_1 = v_1, \ldots, u_n = v_n` so that + :math:`u_1v_1 < \cdots < u_nv_n`. + + * - :cpp:any:`strongly_compress` + - Strongly compress a 1-relation presentation. + +.. cpp:namespace-pop:: + +Full API +~~~~~~~~ + +.. doxygennamespace:: libsemigroups::presentation + :project: libsemigroups diff --git a/docs/source-old/api/recursive_path_compare_iterators.rst b/docs/source-old/api/recursive_path_compare_iterators.rst new file mode 100644 index 000000000..bac3c462a --- /dev/null +++ b/docs/source-old/api/recursive_path_compare_iterators.rst @@ -0,0 +1,11 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +recursive_path_compare (iterators) +================================== + +.. doxygenfunction:: libsemigroups::recursive_path_compare(T const&, T, S const&, S) noexcept + :project: libsemigroups diff --git a/docs/source-old/api/recursive_path_compare_pointers.rst b/docs/source-old/api/recursive_path_compare_pointers.rst new file mode 100644 index 000000000..4dfeeff8a --- /dev/null +++ b/docs/source-old/api/recursive_path_compare_pointers.rst @@ -0,0 +1,11 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +recursive_path_compare (pointers) +================================= + +.. doxygenfunction:: libsemigroups::recursive_path_compare(T *const, T *const) noexcept + :project: libsemigroups diff --git a/docs/source-old/api/recursive_path_compare_references.rst b/docs/source-old/api/recursive_path_compare_references.rst new file mode 100644 index 000000000..2601bc433 --- /dev/null +++ b/docs/source-old/api/recursive_path_compare_references.rst @@ -0,0 +1,11 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +recursive_path_compare (references) +=================================== + +.. doxygenfunction:: libsemigroups::recursive_path_compare(T const&, T const&) noexcept + :project: libsemigroups diff --git a/docs/source-old/api/recursivepathcompare_struct.rst b/docs/source-old/api/recursivepathcompare_struct.rst new file mode 100644 index 000000000..12d266014 --- /dev/null +++ b/docs/source-old/api/recursivepathcompare_struct.rst @@ -0,0 +1,12 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +RecursivePathCompare +==================== + +.. doxygenstruct:: libsemigroups::RecursivePathCompare + :project: libsemigroups + :members: diff --git a/docs/source-old/api/right-action.rst b/docs/source-old/api/right-action.rst new file mode 100644 index 000000000..1d9e8ce59 --- /dev/null +++ b/docs/source-old/api/right-action.rst @@ -0,0 +1,11 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +RightAction +=========== + +.. doxygentypedef:: libsemigroups::RightAction + :project: libsemigroups diff --git a/docs/source-old/api/schreiersims-helper.rst b/docs/source-old/api/schreiersims-helper.rst new file mode 100644 index 000000000..797f09a7d --- /dev/null +++ b/docs/source-old/api/schreiersims-helper.rst @@ -0,0 +1,22 @@ +.. Copyright (c) 2022, Reinis Cirpons + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Helper functions for SchreierSims +================================= + +Overview +-------- + +Defined in ``schreier-sims-helper.hpp``. + +This page contains the documentation for helper functions for the class +:cpp:type:`libsemigroups::SchreierSims`. + +Full API +-------- + +.. doxygenfunction:: libsemigroups::schreier_sims_helper::intersection + :project: libsemigroups diff --git a/docs/source-old/api/shortlex_compare_iterators.rst b/docs/source-old/api/shortlex_compare_iterators.rst new file mode 100644 index 000000000..9103decd6 --- /dev/null +++ b/docs/source-old/api/shortlex_compare_iterators.rst @@ -0,0 +1,11 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +shortlex_compare (iterators) +============================ + +.. doxygenfunction:: libsemigroups::shortlex_compare(T const&, T const&, S const&, S const&) + :project: libsemigroups diff --git a/docs/source-old/api/shortlex_compare_pointers.rst b/docs/source-old/api/shortlex_compare_pointers.rst new file mode 100644 index 000000000..a625e39af --- /dev/null +++ b/docs/source-old/api/shortlex_compare_pointers.rst @@ -0,0 +1,11 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +shortlex_compare (pointers) +=========================== + +.. doxygenfunction:: libsemigroups::shortlex_compare(T *const, T *const) + :project: libsemigroups diff --git a/docs/source-old/api/shortlex_compare_references.rst b/docs/source-old/api/shortlex_compare_references.rst new file mode 100644 index 000000000..4ed79b29d --- /dev/null +++ b/docs/source-old/api/shortlex_compare_references.rst @@ -0,0 +1,11 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +shortlex_compare (references) +============================= + +.. doxygenfunction:: libsemigroups::shortlex_compare(T const&, T const&) + :project: libsemigroups diff --git a/docs/source-old/api/shortlexcompare_struct.rst b/docs/source-old/api/shortlexcompare_struct.rst new file mode 100644 index 000000000..cc36c63ab --- /dev/null +++ b/docs/source-old/api/shortlexcompare_struct.rst @@ -0,0 +1,12 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +ShortLexCompare +=============== + +.. doxygenstruct:: libsemigroups::ShortLexCompare + :project: libsemigroups + :members: diff --git a/docs/source-old/api/silo.rst b/docs/source-old/api/silo.rst new file mode 100644 index 000000000..f43acc41a --- /dev/null +++ b/docs/source-old/api/silo.rst @@ -0,0 +1,18 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Strings in lexicographic order (silo) +===================================== + +The functions :cpp:any:`libsemigroups::cbegin_silo` and +:cpp:any:`libsemigroups::cend_silo` can be used to iterate through strings in +lexicographic order in some range. + +.. doxygenfunction:: libsemigroups::cbegin_silo + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::cend_silo + :project: libsemigroups diff --git a/docs/source-old/api/sislo.rst b/docs/source-old/api/sislo.rst new file mode 100644 index 000000000..49a0b9c49 --- /dev/null +++ b/docs/source-old/api/sislo.rst @@ -0,0 +1,18 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Strings in short-lex order (sislo) +================================== + +The functions :cpp:any:`libsemigroups::cbegin_sislo` and +:cpp:any:`libsemigroups::cend_sislo` can be used to iterate through strings in +short-lex order in some range. + +.. doxygenfunction:: libsemigroups::cbegin_sislo + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::cend_sislo + :project: libsemigroups diff --git a/docs/source-old/api/stephen-helpers.rst b/docs/source-old/api/stephen-helpers.rst new file mode 100644 index 000000000..83914f87d --- /dev/null +++ b/docs/source-old/api/stephen-helpers.rst @@ -0,0 +1,63 @@ +.. Copyright (c) 2022, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + + This file only exists because Breathe always displays all members when + documenting a namespace, and this is nicer for now. + +.. cpp:namespace:: libsemigroups + +Stephen helpers +--------------- + +Defined in ``stephen.hpp``. + +This page contains the documentation for various helper functions for +manipulating :cpp:type:`Stephen` objects. All such functions are contained in +the namespace ``stephen``. + +Contents +~~~~~~~~ + +.. cpp:namespace:: libsemigroups::stephen + +.. list-table:: + :widths: 50 50 + :header-rows: 0 + + * - :cpp:any:`const_iterator_words_accepted` + - The return type of :cpp:any:`cbegin_words_accepted` and + :cpp:any:`cend_words_accepted`. + * - :cpp:any:`const_iterator_left_factors` + - The return type of :cpp:any:`cbegin_left_factors` and + :cpp:any:`cend_left_factors`. + * - :cpp:any:`accepts` + - Check if a word is equivalent to :cpp:any:`Stephen::word`. + * - :cpp:any:`is_left_factor` + - Check if a word is a left factor of :cpp:any:`Stephen::word`. + * - :cpp:any:`cbegin_words_accepted` + - Returns an iterator pointing at the first word equivalent to + :cpp:any:`Stephen::word` in short-lex order. + * - :cpp:any:`cend_words_accepted` + - Returns an iterator pointing one past the last word equivalent to + :cpp:any:`Stephen::word`. + * - :cpp:any:`cbegin_left_factors` + - Returns an iterator pointing at the first word (in short-lex order) + that is a left factor of :cpp:any:`Stephen::word`. + * - :cpp:any:`cend_left_factors` + - Returns an iterator pointing one past the last word that is a left + factor of :cpp:any:`Stephen::word`. + * - :cpp:any:`number_of_words_accepted` + - Returns the number of words accepted with length in given range. + * - :cpp:any:`number_of_left_factors` + - Returns the number of left factors with length in given range. + +.. cpp:namespace-pop:: + +Full API +~~~~~~~~ + +.. doxygennamespace:: libsemigroups::stephen + :project: libsemigroups diff --git a/docs/source-old/api/swap.rst b/docs/source-old/api/swap.rst new file mode 100644 index 000000000..bdd3c4fc0 --- /dev/null +++ b/docs/source-old/api/swap.rst @@ -0,0 +1,15 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +Swap +==== + +.. doxygenstruct:: libsemigroups::Swap + :project: libsemigroups + :members: diff --git a/docs/source-old/api/transf_validate.rst b/docs/source-old/api/transf_validate.rst new file mode 100644 index 000000000..6b1480e00 --- /dev/null +++ b/docs/source-old/api/transf_validate.rst @@ -0,0 +1,12 @@ +.. Copyright (c) 2019-21, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + + +Validating transformations +========================== + +.. doxygenfunction:: libsemigroups::validate(Transf const& x) + :project: libsemigroups diff --git a/docs/source-old/api/ukkonen-helper.rst b/docs/source-old/api/ukkonen-helper.rst new file mode 100644 index 000000000..074537ca4 --- /dev/null +++ b/docs/source-old/api/ukkonen-helper.rst @@ -0,0 +1,87 @@ +.. Copyright (c) 2023, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + + This file only exists because Breathe always displays all members when + documenting a namespace, and this is nicer for now. + +.. cpp:namespace:: libsemigroups + +Ukkonen helper functions +------------------------ + +Defined in ``ukkonen.hpp``. + +This page contains the documentation for various helper functions for +manipulating :cpp:type:`Ukkonen` objects. All such functions are contained in +the namespace ``ukkonen``. + +Contents +~~~~~~~~ + +.. cpp:namespace:: libsemigroups::ukkonen + +.. list-table:: + :widths: 50 50 + :header-rows: 0 + + * - :cpp:any:`add_words_no_checks` + - Add all words in a ``std::vector`` to a :cpp:any:`Ukkonen` object. + * - :cpp:any:`add_words` + - Add all words in a range to a :cpp:any:`Ukkonen` object. + * - :cpp:any:`dfs` + - Perform a depth first search in a suffix tree. + * - :cpp:any:`dot` + - Returns a string containing a `GraphViz `_ + representation of a suffix tree. + * - :cpp:any:`is_piece_no_checks` + - Check if a word is a piece. + * - :cpp:any:`is_piece` + - Check if a word is a piece. + * - :cpp:any:`is_subword_no_checks` + - Check if a word is a subword of any word in a suffix tree. + * - :cpp:any:`is_subword` + - Check if a word is a subword of any word in a suffix tree. + * - :cpp:any:`is_suffix_no_checks` + - Check if a word is a suffix of any word in a suffix tree. + * - :cpp:any:`is_suffix` + - Check if a word is a suffix of any word in a suffix tree. + * - :cpp:any:`length_maximal_piece_prefix_no_checks` + - Find the length of the maximal piece prefix of a word. + * - :cpp:any:`length_maximal_piece_prefix` + - Find the length of the maximal piece prefix of a word. + * - :cpp:any:`length_maximal_piece_suffix_no_checks` + - Find the length of the maximal piece suffix of a word. + * - :cpp:any:`length_maximal_piece_suffix` + - Find the length of the maximal piece suffix of a word. + * - :cpp:any:`maximal_piece_prefix_no_checks` + - Find the maximal piece prefix of a word. + * - :cpp:any:`maximal_piece_prefix` + - Find the maximal piece prefix of a word. + * - :cpp:any:`maximal_piece_suffix_no_checks` + - Find the maximal piece suffix of a word. + * - :cpp:any:`maximal_piece_suffix` + - Find the maximal piece suffix of a word. + * - :cpp:any:`number_of_distinct_subwords` + - Returns the number of distinct subwords of the words in a suffix tree. + * - :cpp:any:`number_of_pieces_no_checks` + - Find the number of pieces in a decomposition of a word (if any). + * - :cpp:any:`number_of_pieces` + - Find the number of pieces in a decomposition of a word (if any). + * - :cpp:any:`pieces_no_checks` + - Find the pieces in a decomposition of a word (if any). + * - :cpp:any:`pieces` + - Find the pieces in a decomposition of a word (if any). + * - :cpp:any:`traverse` + - Traverse the suffix tree from the root. + +.. cpp:namespace-pop:: + +Full API +~~~~~~~~ + +.. doxygennamespace:: libsemigroups::ukkonen + :project: libsemigroups + :content-only: diff --git a/docs/source-old/api/wilo.rst b/docs/source-old/api/wilo.rst new file mode 100644 index 000000000..50adb743a --- /dev/null +++ b/docs/source-old/api/wilo.rst @@ -0,0 +1,24 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Words in lexicographic order (wilo) +=================================== + +The functions :cpp:any:`libsemigroups::cbegin_wilo` and +:cpp:any:`libsemigroups::cend_wilo` can be used to iterate through words in +lexicographic order in some range. + +.. doxygenfunction:: libsemigroups::cbegin_wilo(size_t, size_t, word_type&&, word_type&&) + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::cend_wilo(size_t, size_t, word_type&&, word_type&&) + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::cbegin_wilo(size_t, size_t, word_type const&, word_type const&) + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::cend_wilo(size_t, size_t, word_type const&, word_type const&) + :project: libsemigroups diff --git a/docs/source-old/api/wislo.rst b/docs/source-old/api/wislo.rst new file mode 100644 index 000000000..48a5ae205 --- /dev/null +++ b/docs/source-old/api/wislo.rst @@ -0,0 +1,24 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Words in short-lex order (wislo) +================================ + +The functions :cpp:any:`libsemigroups::cbegin_wislo` and +:cpp:any:`libsemigroups::cend_wislo` can be used to iterate through words in +short-lex order in some range. + +.. doxygenfunction:: libsemigroups::cbegin_wislo(size_t, word_type&&, word_type&&) + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::cend_wislo(size_t, word_type&&, word_type&&) + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::cbegin_wislo(size_t, word_type const&, word_type const&) + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::cend_wislo(size_t, word_type const&, word_type const&) + :project: libsemigroups diff --git a/docs/source-old/authors.rst b/docs/source-old/authors.rst new file mode 100644 index 000000000..505eeb281 --- /dev/null +++ b/docs/source-old/authors.rst @@ -0,0 +1,84 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _Authors: + +Authors +======= + +`James Mitchell`_ (jdm3@st-andrews.ac.uk) + +.. _James Mitchell: https://jdbm.me + +Contributors +------------ + +- `Reinis Cirpons`_ (rc234@st-andrews.ac.uk) contributed to + ``IsObviouslyInfinite``, to integrating ``eigen``, and contributed an + implementation of the Radoszewski-Rytter algorithm for testing equivalence of + words in free bands. +- Joseph Edwards (jde1@st-andrews.ac.uk) contributed the container + ``StaticTriVector2``. +- Luke Elliott (le27@st-andrews.ac.uk) contributed to the Schreier-Sims + implementation. +- Jan Engelhardt (jengelh@inai.de) contributed some bug fixes to the build + system, and a number of helpful issues. +- Ilya Finkelshteyn (ilyaf@appveyor.com) contributed to the continuous + integration on AppVeyor. +- Isuru Fernando (isuruf@gmail.com) contributed to the build system. +- `Florent Hivert`_ (Florent.Hivert@lri.fr) contributed many helpful ideas to + ``libsemigroups``, an allocator implementation (to be included in a future + version), and ``HPCombi``. +- Max Horn (max@quendi.de) contributed some fixes. +- `Jerry James`_ (loganjerry@gmail.com) contributed some bugfixes. +- `Julius Jonušas`_ contributed to the implementation of the Froidure-Pin + algorithm. +- `Alex Levine` contributed to the Schreier-Sims implementation. +- `Michael Orlitzky` (michael@orlitzky.com) contributed to the build system. +- `Dima Pasechnik`_ (dimpase@gmail.com) contributed to the build system. +- Chris Russell contributed some tests for finitely presented semigroups. +- `Finn Smith`_ (fls3@st-andrews.ac.uk) contributed the implementation of the + Konieczny and Lallement-McFadden algorithm, to the Todd-Coxeter + implementation, and to BMat8s. +- `Nicolas Thiéry`_ (nthiery@users.sf.net) contributed to the build system, + packaging ``libsemigroups`` via conda, the python bindings and many helpful + conversations and suggestions. +- `Maria Tsalakou`_ (mt200@st-andrews.ac.uk) contributed to the Knuth-Bendix + implementation, related algorithms for the class :cpp:any:`ActionDigraph`, + and to the implementation of the :cpp:any:`Kambites` class. +- Wilf Wilson (wilf@wilf-wilson.net) contributed some fixes. +- Murray Whyte (mw231@st-andrews.ac.uk) contributed to the documentation and + reported a number of bugs. +- `Michael Young`_ (mct25@st-andrews.ac.uk) contributed to the congruences code + in the v0.0.1 to v0.6.7. + +.. _Reinis Cirpons: https://reinisc.id.lv +.. _Florent Hivert: https://www.lri.fr/~hivert/ +.. _Jerry James: http://www.jamezone.org/ +.. _Julius Jonušas: http://julius.jonusas.work/ +.. _Dima Pasechnik: http://users.ox.ac.uk/~coml0531 +.. _Finn Smith: https://flsmith.github.io +.. _Nicolas Thiéry: http://nicolas.thiery.name/ +.. _Maria Tsalakou: https://mariatsalakou.github.io/ +.. _Michael Young: https://mtorpey.github.io/ + +Acknowledgements +---------------- + +We acknowledge financial support from the OpenDreamKit_ Horizon 2020 +European Research Infrastructures project (#676541) (primarily for the +python bindings). + +We thank the `Carnegie Trust for the Universities of Scotland`_ for funding +the PhD scholarship of `Julius Jonušas`_ when he worked on this project. + +We thank the `Engineering and Physical Sciences Research Council (EPSRC)`_ for +funding the PhD scholarships of `Michael Young`_ and `Finn Smith`_ when they +worked on this project (EP/M506631/1, EP/N509759/1). + +.. _OpenDreamKit: https://opendreamkit.org/ +.. _Carnegie Trust for the Universities of Scotland: https://www.carnegie-trust.org/ +.. _Engineering and Physical Sciences Research Council (EPSRC): https://epsrc.ukri.org/ diff --git a/docs/source-old/biblio.rst b/docs/source-old/biblio.rst new file mode 100644 index 000000000..82dab3ff2 --- /dev/null +++ b/docs/source-old/biblio.rst @@ -0,0 +1,11 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Bibliography +============ + +.. bibliography:: libsemigroups.bib + :all: diff --git a/docs/source-old/bipart.rst b/docs/source-old/bipart.rst new file mode 100644 index 000000000..6f47e019b --- /dev/null +++ b/docs/source-old/bipart.rst @@ -0,0 +1,18 @@ +.. Copyright (c) 2019-2021, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Bipartitions +============ + +This page contains an overview summary of the functionality in +``libsemigroups`` for :cpp:any:`Bipartitions`. + +.. toctree:: + :maxdepth: 3 + + _generated/libsemigroups__bipartition + _generated/libsemigroups__blocks + api/bipart_validate diff --git a/docs/source-old/changelog-v1.rst b/docs/source-old/changelog-v1.rst new file mode 100644 index 000000000..a3eec6e59 --- /dev/null +++ b/docs/source-old/changelog-v1.rst @@ -0,0 +1,253 @@ +Changelog - version 1 +===================== + +v1.3.7 (released 28/02/2021) +---------------------------- + +This is a minor release for with a bug in ``Konieczny`` fixed by +`Finn Smith`_, and a limit added to ``CongruenceByPairs`` to try to resolve +https://github.com/semigroups/Semigroups/issues/634 (again). + +v1.3.6 (released 04/02/2021) +---------------------------- + +This is a minor release for compatibility with the GAP package `Semigroups`_. + +v1.3.5 (released 28/01/2021) +---------------------------- + +This is a minor release fixing a bug in the ``ToddCoxeter`` class (the +``contains`` member function could return false negatives in some cases after +``shrink_to_fit`` was called). + +v1.3.4 (released 27/11/2020) +---------------------------- + +This is a minor release resolving the following issues: + +* the tests failed when the hardware concurrency was limited to 1 (reported by + `Bernhard M. Wiedemann`_) +* compilation failed when in debug mode +* there were some bugs in the string formatting in exceptions on 32-bit + systems +* the disjoint sets data structures were refactored completely, and their + performance improved. + +v1.3.3 (released 07/10/2020) +---------------------------- + +This is a minor release resolving an issue with `make install` including a copy +of `eigen3` when it should not have. Reported by Antonio Rojas. + +v1.3.2 (released 02/10/2020) +---------------------------- + +This is a minor release resolving some issues in the build system, and some +issues related to PBRs. + +The issues resolved are: + +* eigen support is enabled if the configure flag `--with-external-eigen` is + given; Resolved by `J. James`_. +* the order the compile flags related to HPCombi were appended was changed, so + that they do not override user-provided `CFLAGS`. Reported by Jan Engelhardt + and fixed by `J. D. Mitchell`_ +* the macro ``LIBSEMIGROUPS_FMT_ENABLED`` was incorrectly used in ``report.cpp`` + and some weirdness ensued when ``libsemigroups`` was system installed (via + ``make install``). Resolved by `J. D. Mitchell`_. +* the configuration options ``--disable-fmt`` and ``--enable-fmt`` did the same + thing. Resolved by `J. D. Mitchell`_. +* it was possible to create invalid ``PBR`` objects, which caused some + incorrect values to be returned by ``FroidurePin`` instances. The + ``to_string`` implementation for ``PBR``'s also didn't work properly in all + cases. Resolved by `Finn Smith`_. + +v1.3.1 (released 28/08/2020) +---------------------------- + +This is a tediously minor release to fix some issues in the last release. + +v1.3.0 (released 28/08/2020) +---------------------------- + +In this release some new features have been added and some issues have been +resolved. The new features in this version of ``libsemigroups`` were implemented +by `J. D. Mitchell`_, `Reinis Cirpons`_, and `Finn Smith`_. + +.. _J. D. Mitchell: https://jdbm.me +.. _Reinis Cirpons: https://reinisc.id.lv +.. _Finn Smith: https://flsmith.github.io + +The major new feature in this release is: + +* an implementation of the Konieczny-Lallement-McFadden Algorithm + :cite:`Konieczny1994aa`, :cite:`Lallement1990aa` for computing + finite semigroups (`Finn Smith`_ and `J. D. Mitchell`_). + +The major improvements in this release are: + +* an improvement to the `is_obviously_infinite` function for congruences, and + finitely presented semigroups and monoids. When ``libsemigroups`` is compiled + with ``eigen`` enabled (as it is by default), then an integer matrix can be + associated to a finite presentation, if this matrix does not have full rank, + then the associated finitely presented semigroup or monoid is + infinite. ``eigen`` is used to perform the computation of the rank of this + matrix if available (`Reinis Cirpons`_ and `J. D. Mitchell`_). + +* the time it takes to compile ``libsemigroups`` has be reduced. + +v1.2.1 (released 28/06/2020) +---------------------------- + +This is an exceedingly minor release removing some extraneous files from, and +adding one essential file to, the distro. + +v1.2.0 (released 28/06/2020) +---------------------------- + +In this release some new features have been added and some bugs have been +fixed. The new features in this version of ``libsemigroups`` were implemented +by `J. D. Mitchell`_ and `M. Tsalakou`_. + +.. _J. D. Mitchell: https://jdbm.me +.. _M. Tsalakou: https://mariatsalakou.github.io/ + +The major new features in this release are: + +* an implementation of Gilman's Algorithm :cite:`Gilman1979` to construct an + automaton that allows for counting, and iterating through, the normal forms + of strings in a ``KnuthBendix`` instance. This automaton is accessible via + the member function ``gilman_digraph``. Using this approach significantly + improves the performance of the ``size`` member function of ``KnuthBendix`` + and allows a ``KnuthBendix`` instance to know whether or not it is infinite. + +* improvements to the algorithm used by the ``number_of_paths`` member function + of the class template ``ActionDigraph``, and the ability to specify the + algorithm to be used. + +* the class template ``ActionDigraph`` gets new member functions: ``number_of_edges`` + for a node; ``number_of_paths`` with a single node as argument; + ``number_of_paths_algorithm`` which returns a value in an enum describing the + algorithm used by ``number_of_paths`` by default. + +* the functions ``topological_sort`` and ``add_cycle`` in the namespace + ``libsemigroups::action_digraph_helper`` + +* the function ``number_of_words`` for counting the number of words with length + in a given range over an alphabet of specified size. + +* the class template ``ActionDigraph`` gets new static member functions + ``random`` for outputting a random action digraph with a given number of + edges; and ``random_acyclic``. + +There were also several further minor improvements and bug fixes implemented in +this version, many of which arose while developing `libsemigroups_cppyy`_. +Thanks to Murray Whyte for pointing out several of these bugs. + +One major bug was also resolved: sometimes a ``KnuthBendix`` instance refusing +to run even though the rules it contained were not reduced (but were +confluent). + +v1.1.0 (released 28/05/2020) +---------------------------- + +This is a minor release which adds some new features and fixes some bugs. + +The more major new features in this release are: + +* iterators for words and strings with respect to lexicographic and short-lex + orders (``cbegin_wilo``, ``cbegin_wislo``, ``cbegin_silo``, ``cbegin_sislo``) +* the class template ``FroidurePin`` now has member functions for iterating + through its rules (``cbegin_rules``) +* the namespace ``action_digraph_helper`` is introduced. This namespace + contains the helper functions ``follow_path``, ``is_acyclic``, + ``is_reachable``, ``validate_node``, and ``validate_label`` for the class + template ``ActionDigraph``. +* the class template ``ActionDigraph`` has new member functions for iterating + through nodes in reverse (``crbegin_nodes``); for iterating through paths + (``cbegin_panilo``, ``cbegin_panislo``, ``cbegin_pilo``, ``cbegin_pislo``, + ``cbegin_pstilo``, and ``cbegin_pstislo``); and for counting the number of + paths starting at a source (and optionally ending at a target) node + (``number_of_paths``). + +The more major bugs fixed are: + +* the class ``FpSemigroup`` member functions ``number_of_rules``, ``run_until``, and + ``run_for`` now behave as expected +* a fix so that ``libsemigroups`` can be used with ``fmt`` version 6.2.0 was + made. +* a bug was resolved in ``FroidurePin::word_to_pos`` which resulted in + incorrect results for instances with duplicate generators. + +There were also several further minor improvements and bug fixes implemented in +this version, many of which arose while developing `libsemigroups_cppyy`_. +Thanks to Murray Whyte for pointing out several of these bugs. + +v1.0.9 (released 20/04/2020) +---------------------------- + +This is an exceedingly minor release removing some extraneous files from the +distro. + +v1.0.8 (released 20/04/2020) +---------------------------- + +This is another minor release fixing some minor issues, again mostly +highlighted from `libsemigroups_cppyy`_ + +v1.0.7 (released 17/03/2020) +---------------------------- + +This is a minor release fixing some minor issues, mostly highlighted from +`libsemigroups_cppyy`_ + +v1.0.6 (released 09/02/2020) +---------------------------- + +This is a minor release fixing some bugs. + +v1.0.5 (released 13/01/2020) +---------------------------- + +This is a minor release with some minor changes to the documentation and build +system. The non-trivial changes in this release were made by `Isuru Fernando`_ + +v1.0.4 (released 11/01/2020) +---------------------------- + +This is a minor release with several improvements to the build system. It is +now possible to build ``libsemigroups`` using an external installation of ``fmt`` +with the configure option ``--with-external-fmt``, and it should also be +possible to build ``libsemigroups`` on non-x86 architectures. + +v1.0.3 (released 07/12/2019) +---------------------------- + +This is a minor release that includes some fixes that caused tests to fail on +32-bit systems. The non-trivial changes in this release were made by +`J. James`_ + +v1.0.2 (released 30/11/2019) +---------------------------- + +This is a very minor release to fix a bad test that failed in the conda package +continuous integration. + +v1.0.1 (released 29/11/2019) +---------------------------- + +This is a minor release to resolve some issues with the conda package, and to +remove some compiler warnings. + +v1.0.0 (released 27/11/2019) +---------------------------- + +This is a major release that dramatically expands the scope of +``libsemigroups``. In v1.0.0, ``libsemigroups`` has been almost completely +rewritten, generalised, and some new features have been added. + +.. _J. James: http://www.jamezone.org/ +.. _Isuru Fernando: https://github.com/isuruf +.. _libsemigroups_cppyy: https://github.com/libsemigroups/libsemigroups_cppyy +.. _Bernhard M. Wiedemann: https://lizards.opensuse.org/author/bmwiedemann/ +.. _Semigroups: https://github.com/semigroups/Semigroups/ diff --git a/docs/source-old/changelog.rst b/docs/source-old/changelog.rst new file mode 100644 index 000000000..5240c4022 --- /dev/null +++ b/docs/source-old/changelog.rst @@ -0,0 +1,369 @@ +Changelog - version 2 +===================== + +v2.7.3 (released 19/01/2024) +---------------------------- + +* configure.ac: fix shell equality test by @orlitzky in + https://github.com/libsemigroups/libsemigroups/pull/490 +* Optimise Konieczny by @flsmith in + https://github.com/libsemigroups/libsemigroups/pull/491 + +This is a minor release where some minor issues have been resolved. + +v2.7.2 (released 20/10/2023) +---------------------------- + +This is a minor release where some minor issues have been resolved. + +v2.7.1 (released 29/03/2023) +---------------------------- + +In this release a couple of bugs in ``presentation::sort_rules`` are resolved: + +* present: fix sort_rules bug by @james-d-mitchell in + https://github.com/libsemigroups/libsemigroups/pull/478 + +v2.7.0 (released 22/03/2023) +---------------------------- + +This is a minor release with some new features and bug fixes: + +* Remove a pessimizing move by @jamesjer in + https://github.com/libsemigroups/libsemigroups/pull/467 +* More new features for presentations by @james-d-mitchell in + https://github.com/libsemigroups/libsemigroups/pull/473 +* Allow computation of strongly connected components of non-complete word + graphs by @james-d-mitchell in + https://github.com/libsemigroups/libsemigroups/pull/474 +* Ukkonen: expose suffix tree impl by @james-d-mitchell in + https://github.com/libsemigroups/libsemigroups/pull/476 + +v2.6.2 (released 27/02/2023) +---------------------------- + +This is a minor release adding the configuration options ``--enable-backward``, +and ``--disable-backward``, and some related changes to the build system. + +v2.6.1 (released 24/02/2023) +---------------------------- + +This is a minor release with some fixes and improvements to exception messages, +the documentation, and: + +* backward-cpp: add backward files by @james-d-mitchell in + https://github.com/libsemigroups/libsemigroups/pull/462 +* Remove auto return type from ``first_unused_letter`` by @james-d-mitchell in + https://github.com/libsemigroups/libsemigroups/pull/464 +* Properly initialise ``RepOrc`` by @james-d-mitchell in + https://github.com/libsemigroups/libsemigroups/pull/465 + +v2.6.0 (released 06/02/2023) +---------------------------- + +This is a minor release including some new features related to presentations +for semigroups and monoids. + +* Add a second symmetric group presentation due to Moore by @MTWhyte in + https://github.com/libsemigroups/libsemigroups/pull/431 +* Add three functions to ``presentation`` namespace by @james-d-mitchell in + https://github.com/libsemigroups/libsemigroups/pull/436 +* Add presentation for the monoid of partial isometries of a cycle graph by + @MTWhyte in https://github.com/libsemigroups/libsemigroups/pull/433 +* suffix-tree: fix longest common subword issue by @james-d-mitchell in + https://github.com/libsemigroups/libsemigroups/pull/451 +* word: implement user-defined literal ``_w`` for ``word_type`` by + @james-d-mitchell in https://github.com/libsemigroups/libsemigroups/pull/449 +* New helper functions for ``Presentation`` by @james-d-mitchell in + https://github.com/libsemigroups/libsemigroups/pull/453 +* Add ``congruence_kind`` argument check to ``ToddCoxeter`` function + ``to_gap_string`` by @MTWhyte in + https://github.com/libsemigroups/libsemigroups/pull/455 + +v2.5.1 (released 22/12/2022) +---------------------------- + +This is a minor release that resolves a number of minor issues. + +v2.5.0 (released 14/12/2022) +---------------------------- + +In this release a small number of issues are resolved, and one major new +feature is added. The features added in this release are: + +* Add ``order_preserving_monoid`` presentation by @MTWhyte in + https://github.com/libsemigroups/libsemigroups/pull/428 +* Add presentations for the cyclic inverse monoid, and its order-preserving + part by @MTWhyte in https://github.com/libsemigroups/libsemigroups/pull/426 +* Stephen's procedure for finitely presented semigroups by @james-d-mitchell in + https://github.com/libsemigroups/libsemigroups/pull/403 + +v2.4.1 (released 06/12/2022) +---------------------------- + +This is a minor release fixing some issues in the build system that should have +been included in the last release. + +* Change ``-march=avx`` -> ``-mavx`` by @james-d-mitchell in + https://github.com/libsemigroups/libsemigroups/pull/418 + +v2.4.0 (released 01/12/2022) +---------------------------- + +In this release a number of bugs and other minor issues were resolved. The new +features in this release are: + +New features: + +* Add ``replace_word`` presentation helper by @MTWhyte in + https://github.com/libsemigroups/libsemigroups/pull/388 +* A library of examples of finite presentations was added by @MTWhyte. + +Issues resolved: + +* Fix issue with ``replace_subword`` and the empty word by @MTWhyte in + https://github.com/libsemigroups/libsemigroups/pull/384 +* build: add missing eigen3 to pkg-config file by @jengelh in + https://github.com/libsemigroups/libsemigroups/pull/414 +* Fix ``Konieczny::add_generators`` by @flsmith in + https://github.com/libsemigroups/libsemigroups/pull/420 + +New Contributors: + +* @jengelh made their first contribution in + https://github.com/libsemigroups/libsemigroups/pull/414 + +v2.3.2 (released 28/10/2022) +---------------------------- + +In this release a number of bugs and other minor issues were resolved. + +* Fix inaccurate exception information for ``replace_subword`` by @MTWhyte in + https://github.com/libsemigroups/libsemigroups/pull/394 +* Fix broken link in ``CONTRIBUTING.rst`` by @MTWhyte in + https://github.com/libsemigroups/libsemigroups/pull/396 +* matrix: add case for some Apple clang weirdness by @james-d-mitchell in + https://github.com/libsemigroups/libsemigroups/pull/401 This might be a bug + in clang versions 13 and 14, which caused the ``identity`` static member + function of the ``StaticMatrix`` class template to not properly initialise the + matrix being constructed. +* string-view: fix bug in append method by @james-d-mitchell in + https://github.com/libsemigroups/libsemigroups/pull/399 + This bug sometimes caused the ``normal_form`` member function of the + ``Kambites`` class template to return incorrect results, or sometimes to + cause a crash. + +v2.3.1 (released 10/10/2022) +---------------------------- + +In this release a number of corner cases in the ``Sims1`` class are +fixed: + +* sometimes ``number_of_congruences`` erroneously returned ``0`` for the number + of congruences with 1 class; +* if an empty presentation (no generators or relations) was used to + initialise ``short_rules``, then the ``Sims1::for_each`` and + ``Sims1::find_if`` could crash; +* a more serious bug which could cause an invalid read beyond the end of a + container (caused by the erroneous assumption that the containers were always + of even length). Thanks to `J. James`_ for reporting this issue. + +v2.3.0 (released 28/09/2022) +---------------------------- + +In this release a number of minor issues a fixed, some improvements are made, +and the ``Sims1`` class has been redesigned and improved to implement a parallel +version of the low index congruences algorithm. + +v2.2.3 (released 22/09/2022) +---------------------------- + +This is a minor release fixing a number of minor issues, and including some +minor improvements. + +v2.2.2 (released 12/09/2022) +---------------------------- + +This is a minor release fixing a number of minor issues, and including some +minor improvements. + +v2.2.1 (released 12/08/2022) +---------------------------- + +This is a minor release fixing a data race (probably) caused by setting the +global locale, that sometimes caused a crash. + +v2.2.0 (released 01/07/2022) +---------------------------- + +This release adds two new features to libsemigroups: + +* Sims Low-Index Congruence Algorithm by @james-d-mitchell in + https://github.com/libsemigroups/libsemigroups/pull/349 +* Add permutation group intersections for SchreierSims by @reiniscirpons in + https://github.com/libsemigroups/libsemigroups/pull/351 + +v2.1.5 (released 21/04/2022) +---------------------------- + +This is a minor release with a few minor changes: + +* schreier-sims: fix issue #343 by @james-d-mitchell in https://github.com/libsemigroups/libsemigroups/pull/344 +* Replace -march=native by -march=avx by @fingolfin in https://github.com/libsemigroups/libsemigroups/pull/345 + +@fingolfin made their first contribution in https://github.com/libsemigroups/libsemigroups/pull/345 welcome @fingolfin! + +v2.1.4 (released 04/03/2022) +---------------------------- + +This is a minor release with a few minor changes: + +* it is now possible to create the ``quotient_froidure_pin`` of a congruence + with infinitely many classes; +* some exception messages were corrected for ``Bipartition`` objects; +* compilation of v2.1.0 to v2.1.3 did not work in cygwin for Windows; +* there was a file missing in the archive, which meant that it wasn't possible + to build the documentation. + +v2.1.3 (released 16/12/2021) +---------------------------- + +This is a minor release with some performance improvements in: +``ActionDigraph::number_of_paths`` (`eigen`_ is used in some circumstances when +available); the suffix tree implementation (used by ``Kambites``); and in +``KnuthBendix``. + +v2.1.2 (released 30/11/2021) +---------------------------- + +This is another very minor release resolving an issue in the last release +on 32-bit systems raised by Jan Engelhardt. + +v2.1.1 (released 28/11/2021) +---------------------------- + +This is a very minor release resolving an issue in the last release pointed out +by Jan Engelhardt. + +v2.1.0 (released 28/11/2021) +---------------------------- + +The following new features, improvements, and fixes are included in this +release: + +* new implementations of the linear time algorithm by Kambites for equality + checking and the algorithm by Mitchell and Tsalakou + for finding normal forms in small overlap monoids in the class ``Kambites`` + (@james-d-mitchell and @mariatsalakou + https://github.com/libsemigroups/libsemigroups/pull/278) +* a performance improvement in the implementation of Konieczny algorithm, for + determining the structure of a finite semigroup or monoid (@flsmith + https://github.com/libsemigroups/libsemigroups/pull/297 + https://github.com/libsemigroups/libsemigroups/pull/304) +* an implement of the linear time algorithm by Radoszewski and Rytter for + checking equality of words in free bands in the function + ``freeband_equal_to`` (@reiniscirpons + https://github.com/libsemigroups/libsemigroups/pull/298) +* a major revision, expansion of the settings, and improvement in the + performance of the implementation of the Todd-Coxeter algorithm in the + class ``ToddCoxeter`` (@james-d-mitchell + https://github.com/libsemigroups/libsemigroups/pull/313 + https://github.com/libsemigroups/libsemigroups/pull/318) +* some other minor issues in the class templates + ``FroidurePin`` and ``ActionDigraph`` were resolved + (@james-d-mitchell https://github.com/libsemigroups/libsemigroups/pull/299 + https://github.com/libsemigroups/libsemigroups/pull/300) + +**Full Changelog**: https://github.com/libsemigroups/libsemigroups/compare/v2.0.3...v2.1.0 + +v2.0.3 (released 11/11/2021) +---------------------------- + +This release contains a minor change to the ``FroidurePin`` class template that +resolves an issue with the `python binding `_ highlighted by `Maria Tsalakou`_ and Chinmaya Nagpal. + +v2.0.2 (released 20/09/2021) +---------------------------- + +This release includes some missing operators, adapters, and doc were added. + +v2.0.1 (released 28/08/2021) +---------------------------- + +This release includes some improvements and minor fixes including: + +- some remnants of C++11 in the code and docs were removed +- the class ``Runner`` was given proper copy and move constructors +- some performance improvements were made to ``Konieczny`` by `Finn Smith`_ +- some minor updates were made to ``FroidurePin`` and its documentation +- some missing adapters for ``KBE`` and ``TCE`` were implemented. + +v2.0.0 (released 26/05/2021) +---------------------------- + +This release includes a major rewrite of the functionality in ``libsemigroups`` +for matrices, transformations, and other elements of semigroups. +``libsemigroups`` has been updated to use C++14 (from C++11), and some +simplifications were made as a consequence. The documentation has been +improved, some deprecated functionality was remove, and other minor +improvements, and simplifications were made. The included version of `eigen`_ +was updated from version 3.3.7 to 3.3.9. + +.. _eigen: http://eigen.tuxfamily.org/ + +`J. James`_ contributed some improvements to the build system, and some +additional updates were made which arose from warnings issued by newer versions +of autotools. + +The following function was added: + +- ``Action::cache_scc_multipliers`` + +The following deprecated functionality was removed: + +- ``FroidurePin::FroidurePin(std::vector const*)`` +- ``FroidurePin::reset_next_relation`` +- ``FroidurePin::next_relation`` +- the ``Element`` class was removed +- the ``UFOld`` class was removed (replaced by ``Suf`` and ``Duf`` in v1.3.4) + +The following backwards incompatible changes have been made: + +- every function including ``_nr_`` has been renamed using ``_number_of_`` for + consistency +- ``const`` has been removed from all function parameters passed by value +- ``congruence_type`` was renamed ``congruence_kind`` for consistency +- ``CongruenceByPairsHelper`` was renamed ``CongruenceByPairs`` +- ``Congruence::policy`` was renamed ``Congruence::options`` +- ``FroidurePin::copy_closure`` returns by value instead of returning a pointer +- ``FroidurePin::copy_add_generators`` returns by value instead of returning a + pointer +- ``FroidurePin::letter_to_pos`` was renamed ``FroidurePin::current_position`` +- ``FroidurePin::length_const`` was renamed ``FroidurePin::length`` +- ``FroidurePin::length_non_const`` was renamed ``FroidurePin::current_length`` + (again for consistency) +- ``FroidurePin::word_to_pos`` was renamed ``FroidurePin::current_position`` +- ``KnuthBendix::policy`` was renamed ``KnuthBendix::options`` +- ``ToddCoxeter::policy`` was renamed ``ToddCoxeter::options`` + +The following files were renamed: + +- ``libsemigroups-config.hpp`` was renamed ``config.hpp`` +- ``libsemigroups-debug.hpp`` was renamed ``debug.hpp`` +- ``libsemigroups-exception.hpp`` was renamed ``exception.hpp`` + +Changelog - version 1 +===================== + +.. toctree:: + + changelog-v1 + +.. _J. James: http://www.jamezone.org/ +.. _Isuru Fernando: https://github.com/isuruf +.. _Bernhard M. Wiedemann: https://lizards.opensuse.org/author/bmwiedemann/ +.. _Semigroups: https://github.com/semigroups/Semigroups/ +.. _Finn Smith: https://flsmith.github.io +.. _Maria Tsalakou: https://mariatsalakou.github.io/ +.. _Reinis Cirpons: https://reinisc.id.lv +.. _Finn Smith: https://flsmith.github.io diff --git a/docs/source-old/conf.py b/docs/source-old/conf.py new file mode 100644 index 000000000..58e3d8fc1 --- /dev/null +++ b/docs/source-old/conf.py @@ -0,0 +1,55 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- + +import os +import subprocess +import sphinx_rtd_theme + +on_rtd = os.environ.get("READTHEDOCS", None) == "True" +if on_rtd: + subprocess.call( + "cd .. && mkdir -p build && doxygen && cd .. && etc/make-doc-yml.sh", + shell=True, + ) + +html_theme = "sphinx_rtd_theme" + +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +html_theme_options = { + # Toc options + "includehidden": False, +} + + +def setup(app): + app.add_css_file("custom.css") + + +extensions = [ + "breathe", + "sphinx.ext.mathjax", + "sphinx_copybutton", + "sphinxcontrib.bibtex", +] + +bibtex_bibfiles = ["libsemigroups.bib"] + +breathe_projects = {"libsemigroups": "../build/xml"} +breathe_projects_source = {} +templates_path = ["_templates"] +html_static_path = ["_static"] +source_suffix = ".rst" +master_doc = "index" +project = "libsemigroups" +copyright = "2019-23, J. D. Mitchell" +author = "J. D. Mitchell" +cpp_index_common_prefix = ["libsemigroups::"] + +html_logo = "" + +exclude_patterns = [] +highlight_language = "c++" +pygments_style = "sphinx" +todo_include_todos = False +htmlhelp_basename = "libsemigroups" diff --git a/docs/source-old/congruences.rst b/docs/source-old/congruences.rst new file mode 100644 index 000000000..e5a07d6b1 --- /dev/null +++ b/docs/source-old/congruences.rst @@ -0,0 +1,47 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Congruences +=========== + +.. cpp:namespace:: libsemigroups + +``libsemigroups`` implements several algorithms for computing a congruence of +a semigroup or monoid. The main algorithms implemented are Todd-Coxeter, +Knuth-Bendix, algorithms for C(4) small overlap monoids (by Kambites and +Tsalakou),and brute-force enumeration; see the links below for further details. +As a convenience, ``libsemigroups`` also has a class +:cpp:type:`libsemigroups::Congruence` that runs some predetermined variants of +Todd-Coxeter, Knuth-Bendix, the small overlap algorithms, and the brute-force +enumeration in parallel. This class is, at present, not very customisable, and +lacks some of the fine grained control offered by the classes implementing +individual algorithms, such as :cpp:type:`congruence::ToddCoxeter`, +:cpp:type:`congruence::KnuthBendix`, and :cpp:type:`congruence::Kambites`. + +All of the classes for congruences in ``libsemigroups`` can be used +"interactively", in the sense that they can be run for a particular amount of +time, or until some condition is met; for further details see, for example, +:cpp:func:`Runner::run_for` and +:cpp:func:`Runner::run_until`. + +The "handedness" of a congruence is determined by: + +.. doxygenenum:: libsemigroups::congruence_kind + :project: libsemigroups + +The classes in ``libsemigroups`` for congruences are: + +.. toctree:: + :maxdepth: 1 + + _generated/libsemigroups__congruenceinterface + _generated/libsemigroups__congruence + _generated/libsemigroups__congruencebypairs + _generated/libsemigroups__congruence__toddcoxeter + _generated/libsemigroups__congruence__knuthbendix + _generated/libsemigroups__congruence__kambites + _generated/libsemigroups__knuthbendixcongruencebypairs + sims1 diff --git a/docs/source-old/constants.rst b/docs/source-old/constants.rst new file mode 100644 index 000000000..15ab506da --- /dev/null +++ b/docs/source-old/constants.rst @@ -0,0 +1,54 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Constants +========= + +``libsemigroups`` contains certain constant values, which are described in this +section. The values below correspond to integer values (in some sense). All +of the constants in this section can be implicitly converted to any integral +type, and have a value specified by + +.. code-block:: cpp + + std::numeric_limits::max/min() + +minus a compile-time offset (where :code:`T` is a member function template, and +can hence be any integral type), and we overload :code:`operator==`, +:code:`operator!=`, :code:`operator<`, and :code:`operator>` the constants +defined below and for certain integral type. So, the constants can be used as +if it was an integral type (say, :code:`-1`, although the precise value is not +defined), for the purposes of storing it in a data member and for comparisons. +This allows us to avoid duplicating code for constants like +:cpp:any:`UNDEFINED`, and makes :cpp:any:`UNDEFINED` more straightforward to +use. + +This approach also has some drawbacks, if, for example, :cpp:any:`UNDEFINED` is +implicitly converted to two different integral types and then these are +compared, this will yield :code:`false`, and so :code:`==` of +:cpp:any:`UNDEFINED` and itself is not transitive, so beware. + +.. code-block:: cpp + + using namespace libsemigroups; + UNDEFINED != 0; // true + POSITIVE_INFINITY > 0; // true + POSITIVE_INFINITY > NEGATIVE_INFINITY; // true + +.. doxygenvariable:: libsemigroups::LIMIT_MAX + :project: libsemigroups + +.. doxygenvariable:: libsemigroups::UNDEFINED + :project: libsemigroups + +.. doxygenvariable:: libsemigroups::NEGATIVE_INFINITY + :project: libsemigroups + +.. doxygenvariable:: libsemigroups::POSITIVE_INFINITY + :project: libsemigroups + +.. doxygenvariable:: libsemigroups::FOREVER + :project: libsemigroups diff --git a/docs/source-old/digraphs.rst b/docs/source-old/digraphs.rst new file mode 100644 index 000000000..8d041d006 --- /dev/null +++ b/docs/source-old/digraphs.rst @@ -0,0 +1,26 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Digraphs +======== + +``libsemigroups`` has some limited functionality for digraphs and spanning +trees. + +The classes in ``libsemigroups`` for digraphs are: + +.. toctree:: + :maxdepth: 1 + + _generated/libsemigroups__actiondigraph + _generated/libsemigroups__forest + +There are also some helper functions available: + +.. toctree:: + :maxdepth: 1 + + api/digraph-helper diff --git a/docs/source-old/elements.rst b/docs/source-old/elements.rst new file mode 100644 index 000000000..7e7f4259c --- /dev/null +++ b/docs/source-old/elements.rst @@ -0,0 +1,56 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Elements +======== + +This page contains an overview summary of the functionality in +``libsemigroups`` for defining elements of semigroups. + +If ``libsemigroups`` is compiled with HPCombi_ support enabled (see +:ref:`Installation` for details), then the types defined in HPCombi_ (which use +the SSE and AVX instruction sets for very fast manipulation of these types) can +be used with the algorithms in ``libsemigroups``; for further details see the +HPCombi_ documentation. + +.. toctree:: + :maxdepth: 1 + + bipart + ptransf + transf + perm + pperm + pbr + +Adapters +~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + hpcombi-adapters + adapters + +Helpers +~~~~~~~ + +The following helpers: + +.. toctree:: + :maxdepth: 1 + + _generated/libsemigroups__leastperm + _generated/libsemigroups__leastpperm + _generated/libsemigroups__leasttransf + +can be used to get the smallest/fastest type representing a permutation, +partial permutation, or transformation, and can be used independently of +whether or not ``libsemigroups`` is compiled with HPCombi_ support enabled. + + + +.. _HPCombi: https://github.com/hivert/HPCombi diff --git a/docs/source-old/exception.rst b/docs/source-old/exception.rst new file mode 100644 index 000000000..850d03054 --- /dev/null +++ b/docs/source-old/exception.rst @@ -0,0 +1,12 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Exceptions +========== + +.. doxygenstruct:: libsemigroups::LibsemigroupsException + :project: libsemigroups + :members: diff --git a/docs/source-old/fpsemigroups.rst b/docs/source-old/fpsemigroups.rst new file mode 100644 index 000000000..fd47b2cc9 --- /dev/null +++ b/docs/source-old/fpsemigroups.rst @@ -0,0 +1,44 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Finitely presented semigroups +============================= + +``libsemigroups`` implements several algorithms for computing finitely +presented semigroups and monoids. The main algorithms implemented are +Todd-Coxeter, Knuth-Bendix, algorithms for C(4) small overlap monoids (by +Kambites and Tsalakou), and brute-force enumeration; see the links below for +further details. As a convenience, ``libsemigroups`` also has a class +:cpp:type:`libsemigroups::FpSemigroup` that runs some predetermined variants of +Todd-Coxeter, Knuth-Bendix, and the brute-force enumeration in parallel. This +class is, at present, not very customisable, and lacks some of the fine grained +control offered by the classes implementing individual algorithms, such as +:cpp:type:`libsemigroups::fpsemigroup::ToddCoxeter` and +:cpp:type:`libsemigroups::fpsemigroup::KnuthBendix`. + +All of the classes for finitely presented semigroups and monoids in +``libsemigroups`` can be used "interactively", in the sense that they can be +run for a particular amount of time, or until some condition is met; for +further details see, for example, +:cpp:func:`libsemigroups::Runner::run_for` and +:cpp:func:`libsemigroups::Runner::run_until`. + +The classes in ``libsemigroups`` for finitely presented semigroups +and monoids are: + +.. toctree:: + :maxdepth: 1 + + _generated/libsemigroups__fpsemigroupinterface + _generated/libsemigroups__congruencewrapper + _generated/libsemigroups__fpsemigroup + _generated/libsemigroups__fpsemigroupbypairs + _generated/libsemigroups__fpsemigroup__kambites + _generated/libsemigroups__fpsemigroup__knuthbendix + stephen + _generated/libsemigroups__fpsemigroup__toddcoxeter + present + api/fpsemi-examples diff --git a/docs/source-old/freeband.rst b/docs/source-old/freeband.rst new file mode 100644 index 000000000..5fd81101e --- /dev/null +++ b/docs/source-old/freeband.rst @@ -0,0 +1,30 @@ +.. Copyright (c) 2021, J. D. Mitchell + T. D. Conti-Leslie + M. T. Whyte + R. Cirpons + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Free Bands +=========== + +.. cpp:namespace:: libsemigroups + +``libsemigroups`` contains an implementation of the Radoszewski-Rytter +algorithm :cite:`Radoszewski2010aa` for testing equivalence of words in free +bands. + +The functions in ``libsemigroups`` for free bands are described on this page. + +.. cpp:namespace-pop:: + +.. doxygenfunction:: libsemigroups::freeband_equal_to(word_type const &, word_type const &) + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::freeband_equal_to(T, T) + :project: libsemigroups + +.. doxygenfunction:: libsemigroups::freeband_equal_to(T, T, T, T) + :project: libsemigroups diff --git a/docs/source-old/hpcombi-adapters.rst b/docs/source-old/hpcombi-adapters.rst new file mode 100644 index 000000000..9561cc4a9 --- /dev/null +++ b/docs/source-old/hpcombi-adapters.rst @@ -0,0 +1,29 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +HPCombi adapters +================ + +This page contains the documentation of the functionality in ``libsemigroups`` +that adapts the types in HPCombi_ for use with the algorithms in +``libsemigroups``. The functionality in this section is only available if +``libsemigroups`` is compiled with HPCombi_ support enabled; this is only +possible on certain computer architectures. See `the installation instructions +`_ and the HPCombi_ documentation for further details. + +.. _HPCombi: https://github.com/hivert/HPCombi + +.. toctree:: + :maxdepth: 1 + + api/hpcombi-complexity + api/hpcombi-degree + api/hpcombi-imageleftaction + api/hpcombi-imagerightaction + api/hpcombi-inverse + api/hpcombi-one + api/hpcombi-product + api/hpcombi-swap diff --git a/docs/source-old/index.rst b/docs/source-old/index.rst new file mode 100644 index 000000000..924f20fd7 --- /dev/null +++ b/docs/source-old/index.rst @@ -0,0 +1,124 @@ +libsemigroups - Version 2.7.1 +============================= + +C++ library for semigroups and monoids +-------------------------------------- + +What is ``libsemigroups``? ~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``libsemigroups`` is a C++14 library containing implementations of +several algorithms for computing finite, and finitely presented, +semigroups and monoids. Namely: + +- the ``Froidure-Pin algorithm``\ \_ for computing finite semigroups + :cite:``Froidure1997aa``; +- the ``Todd-Coxeter algorithm``\ \_ for finitely presented semigroups + and monoids; see also + ``this paper ``\ \_ + :cite:``Coleman2022aa``; +- the ``Knuth-Bendix algorithm``\ \_ for finitely presented semigroups + and monoids; +- the ``Schreier-Sims algorithm``\ \_ for permutation groups; +- a preliminary implementation of the ``Konieczny``\ \_ + :cite:``Konieczny1994aa`` and ``Lallement-McFadden``\ \_ + :cite:``Lallement1990aa`` algorithm for computing finite semigroups + which act on sets; +- an implementation of the ``Radoszewski-Rytter``\ \_ + :cite:``Radoszewski2010aa`` algorithm for testing equivalence of + words in free bands; +- an implementation of the algorithm for solving the word problem for + small overlap monoids, and for computing normal forms in such + monoids; see + ``Kambites ``\ **:cite:``Kambites2009aa``, + ``Kambites ``** + :cite:``Kambites2009ab``, and + ``Mitchell-Tsalakou ``\ \_\_ + :cite:``Mitchell2021aa``; +- a version of Sims low index subgroup algorithm for computing + one-sided congruences of a semigroup or monoid; +- a version of ``Stephen's procedure``\ \_ for finitely presented + semigroups and monoids (for a given word :math:``w`` this procedure + is for determining words equivalent to :math:``w`` or that are left + divisors of :math:``w``). + +.. \_Froidure-Pin algorithm: https://www.irif.fr/~jep/PDF/Rio.pdf .. +\_Todd-Coxeter algorithm: +https://en.wikipedia.org/wiki/Todd%E2%80%93Coxeter_algorithm .. +\_Knuth-Bendix algorithm: +https://en.wikipedia.org/wiki/Knuth%E2%80%93Bendix_completion_algorithm +.. \_Schreier-Sims algorithm: +https://en.wikipedia.org/wiki/Schreier%E2%80%93Sims_algorithm .. +\_Konieczny: https://link.springer.com/article/10.1007/BF02573672 .. +\_Lallement-McFadden: +https://www.sciencedirect.com/science/article/pii/S0747717108800570 .. +\_Radoszewski-Rytter: +https://link.springer.com/chapter/10.1007/978-3-642-11266-9_55 .. +\_Stephen’s procedure: https://rb.gy/brsuvc + +``libsemigroups`` is partly based on +``Algorithms for computing finite semigroups``\ *, +``Expository Slides``*, and ``Semigroupe 2.01``\ \_ by +``Jean-Eric Pin``\ \_. + +.. \_Algorithms for computing finite semigroups: +https://www.irif.fr/~jep/PDF/Rio.pdf .. \_Expository slides: +https://www.irif.fr/~jep/PDF/Exposes/StAndrews.pdf .. \_Semigroupe 2.01: +https://www.irif.fr/~jep/Logiciels/Semigroupe2.0/semigroupe2.html .. +\_Jean-Eric Pin: https://www.irif.fr/~jep/ + +``libsemigroups`` is used in the ``Semigroups package for GAP``\ *, and +it is possible to use ``libsemigroups`` directly in Python 3 via the +package ``libsemigroups_pybind11``*. The development version of +``libsemigroups`` is available on github\_, and some related projects +are here\_. + +.. \_github: https://github.com/libsemigroups/libsemigroups .. \_here: +https://github.com/libsemigroups .. \_libsemigroups_pybind11: +https://libsemigroups.github.io/libsemigroups_pybind11/ .. \_Semigroups +package for GAP: https://semigroups.github.io/Semigroups + +The main classes in ``libsemigroups`` are named after the algorithms +they implement; see, for example, +:cpp:any:``libsemigroups::FroidurePin``, +:cpp:any:``libsemigroups::Konieczny``, +:cpp:any:``libsemigroups::congruence::ToddCoxeter``, +:cpp:any:``libsemigroups::fpsemigroup::Kambites``, +:cpp:any:``libsemigroups::fpsemigroup::KnuthBendix``, +:cpp:any:``libsemigroups::SchreierSims``, +:cpp:any:``libsemigroups::Sims1``, or +:cpp:any:``libsemigroups::Stephen``. + +The implementations in :cpp:any:``libsemigroups::FroidurePin``, +:cpp:any:``libsemigroups::Konieczny``, and +:cpp:any:``libsemigroups::SchreierSims`` are generic and easily adapted +to user-defined types. + +``libsemigroups`` uses: ``HPCombi``\ \_ which uses the SSE and AVX +instruction sets for very fast manipulation of transformations, partial +permutations, permutations, and boolean matrices of small size; +``catch``\ \_ for tests; ``fmt``\ \_ for reporting; and ``eigen``\ \_ +for some linear algebra computations. + +.. \_HPCombi: https://github.com/hivert/HPCombi .. \_catch: +https://github.com/catchorg/Catch2 .. \_fmt: +https://github.com/fmtlib/fmt .. \_eigen: http://eigen.tuxfamily.org/ + +.. toctree:: :maxdepth: 1 :caption: Installation and changelog + +install changelog + +.. toctree:: :caption: API REFERENCE :maxdepth: 1 + +action congruences digraphs elements fpsemigroups freeband matrix/index +misc order semigroups words + +.. toctree:: :caption: Bibliography + +biblio + +.. toctree:: :caption: Further info :maxdepth: 1 + +semigroupe authors + +.. \_Semigroupe: +https://www.irif.fr/~jep/Logiciels/Semigroupe2.0/semigroupe2.html diff --git a/docs/source-old/install.rst b/docs/source-old/install.rst new file mode 100644 index 000000000..a313e7225 --- /dev/null +++ b/docs/source-old/install.rst @@ -0,0 +1,187 @@ +.. |libsemigroups-version| replace:: 2.7.3 + +.. _Installation: + +Installation +============ + +Installing with conda +--------------------- + +This installation method assumes that you have anaconda or miniconda installed. +See the `getting started`_ and `miniconda download page`_ on the conda_ +website. + +.. _getting started: http://bit.ly/33B0Vfs +.. _miniconda download page: https://conda.io/miniconda.html +.. _conda: https://conda.io/ + +Activate the `conda-forge `__ package +repository: + +:: + + conda config --add channels conda-forge + +Install ``libsemigroups``: + +:: + + conda install libsemigroups + +From the sources +---------------- + +Building ``libsemigroups`` from the source files requires a C++ compiler +supporting the C++17 standard, ``autoconf``, and ``automake``. +Building the documentation from source has some additional requirements that +are detailed `here `_. + +From the github repo +~~~~~~~~~~~~~~~~~~~~ + +To build ``libsemigroups`` from the github repository: + +:: + + git clone https://github.com/libsemigroups/libsemigroups + cd libsemigroups + ./autogen.sh && ./configure && make -j8 && sudo make install + +From a release archive +~~~~~~~~~~~~~~~~~~~~~~ + +To build ``libsemigroups`` from a release archive: + +.. parsed-literal:: + + curl -L -O https://github.com/libsemigroups/libsemigroups/releases/latest/download/libsemigroups-|libsemigroups-version|.tar.gz + tar -xf libsemigroups-|libsemigroups-version|.tar.gz + rm -f libsemigroups-|libsemigroups-version|.tar.gz + cd libsemigroups-|libsemigroups-version| + ./configure && make -j8 && sudo make install + +Docker +~~~~~~ + +If you have Docker_ installed, you can download an `x86 docker image`_ for +``libsemigroups`` as follows: + +.. parsed-literal:: + docker pull libsemigroups/libsemigroups-docker + +or an `arm docker image`_ as follows + +.. parsed-literal:: + docker pull libsemigroups/libsemigroups-docker-arm + +and run it by doing + +.. parsed-literal:: + docker run --rm -it libsemigroups/libsemigroups-docker + docker run --rm -it libsemigroups/libsemigroups-docker-arm + +If you want to use a specific version of ``libsemigroups``, then use: + +.. parsed-literal:: + docker pull libsemigroups/libsemigroups-docker:version-1.0.9 + docker run --rm -it libsemigroups/libsemigroups-docker:version-1.0.9 + +or, for the latest version, use: + +.. parsed-literal:: + docker pull libsemigroups/libsemigroups-docker:latest + docker run --rm -it libsemigroups/libsemigroups-docker:latest + +.. _Docker: https://www.docker.com +.. _x86 docker image: https://hub.docker.com/repository/docker/libsemigroups/libsemigroups-docker +.. _arm docker image: https://hub.docker.com/repository/docker/libsemigroups/libsemigroups-docker-arm + +Configuration options +--------------------- + +In addition to the usual ``autoconf`` configuration options, the following +configuration options are available for ``libsemigroups``: + +========================== ================================================== +Option +-------------------------- -------------------------------------------------- +--enable-code-coverage enable code coverage support (default=no) +--enable-compile-warnings enable compiler warnings (default=no) +--enable-debug enable debug mode (default=no) +--enable-eigen enable ``eigen`` (default=yes) +--enable-fmt enable fmt (default=no) +--enable-hpcombi enable ``HPCombi`` (default=yes) +--enable-stats enable statistics mode in :cpp:any:`ToddCoxeter` (default=yes) +--enable-verbose enable verbose mode (default=no) +--with-external-fmt do not use the included copy of fmt (default=no) +--with-external-eigen do not use the included copy of eigen (default=no) +--disable-popcnt do not use __builtin_popcountl (default=yes) +--disable-clzll do not use __builtin_ctzll (default=yes) +========================== ================================================== + +Debug mode and verbose mode significantly degrade the performance of +``libsemigroups``. Compiling with ``fmt`` enabled increases build times +significantly. Note that the flags ``--enable-fmt`` and ``--with-external-fmt`` +are independent of each other, and so both flags should be included to enable +``fmt`` and use an external ``fmt``. + +Make install +------------ + +By default, ``make install`` installs the library and its ``pkg-config`` +configuration into ``/usr/local``. One can also specify another install +location, say, ``/foo/bar``, by calling ``./configure`` with parameter +``--prefix``, e.g. \ ``./configure --prefix=/foo/bar``. This might be +useful if ``sudo`` is not available. + +If you have ``pkg-config`` installed, it may be called to get +``libsemigroups``\ ’s version, location, etc (see its docs for details; +this facility is used in GAP package Semigroups, which may be configured +to use the external ``libsemigroups``). For example, + +:: + + pkg-config --modversion libsemigroups + +will print the version of the installed ``libsemigroups``, provided it is +scanning configurations in the install location. For installation +location unknown to ``pkg-config``, one needs to add it to +``PKG_CONFIG_PATH`` (an environment variable). E.g. if it is +``/foo/bar`` as above then + +:: + + PKG_CONFIG_PATH=/foo/bar/lib/pkgconfig pkg-config --modversion libsemigroups + +will print the version of the installed ``libsemigroups``. (As usual, +``PKG_CONFIG_PATH`` may be exported, added to shell configuration, etc.) + +Building the documentation +-------------------------- + +The following are required to be able to build the documentation: + +1. ``python3`` +2. ``doxygen`` +3. the python packages: ``sphinx bs4 lxml breathe pyyaml sphinx_rtd_theme sphinx_copybutton sphinxcontrib-bibtex`` + +Assuming you already have ``python3`` install, on Mac OSX you can install all of +the above by doing: + +:: + + brew install doxygen sphinx + pip3 install -r docs/requirements.txt + +.. TODO add ubuntu instructions + +Then it ought to be possible to just run ``make doc`` in the ``libsemigroups`` +directory. + +Issues +------ + +If you find any problems with ``libsemigroups``, or have any suggestions for +features that you’d like to see, please use the `issue +tracker `__. diff --git a/docs/source-old/konieczny.rst b/docs/source-old/konieczny.rst new file mode 100644 index 000000000..dc7221fab --- /dev/null +++ b/docs/source-old/konieczny.rst @@ -0,0 +1,35 @@ +.. Copyright (c) 2020, F. L. Smith + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Konieczny +========= + +``libsemigroups`` contains a preliminary implementation of Konieczny's +generalisation of the Lallement-McFadden algorithm for computing the structure +of finite semigroups that act on sets; see the documentation below for further +details. It is preliminary in the sense that the interface exposed by the +relevant classes is minimal, and that certain optimisations remain to be +performed. + +The implementation of this algorithm is generic, and can be easily adapted +for user-defined types. In other words, it is possible to directly apply this +algorithm to any types that satisfy some minimal prerequisites, via traits +classes and/or the adapters described here. + +The implementation of the Konieczny and Lallement-McFadden algorithm can be +used "interactively", in the sense that they can be run for a particular amount +of time, or until some condition is met; for further details see, for example, +:cpp:any:`void libsemigroups::Runner::run_for(std::chrono::nanoseconds)` and +:cpp:func:`libsemigroups::Runner::run_until`. + +The classes implementing the Konieczny and Lallement-McFadden algorithm are: + +.. toctree:: + :maxdepth: 1 + + _generated/libsemigroups__konieczny + _generated/libsemigroups__koniecznytraits + _generated/libsemigroups__konieczny__dclass diff --git a/docs/source-old/matrix/adapters/complexity.rst b/docs/source-old/matrix/adapters/complexity.rst new file mode 100644 index 000000000..f6d799f77 --- /dev/null +++ b/docs/source-old/matrix/adapters/complexity.rst @@ -0,0 +1,33 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Complexity +========== + +.. cpp:namespace:: libsemigroups + +.. cpp:struct:: template \ + Complexity>> + + Defined in ``matrix.hpp``. + + Specialization of the adapter :cpp:any:`Complexity` for types ``T`` such + that the value of :cpp:any:`IsMatrix\` is ``true``. + + :tparam: T the type of matrices. + + .. cpp:function:: constexpr size_t operator()(T const& x) const noexcept + + Returns ``x.number_of_rows()`` cubed. + + :param x: a matrix of type ``T``. + + :returns: a value of type ``size_t``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant. diff --git a/docs/source-old/matrix/adapters/degree.rst b/docs/source-old/matrix/adapters/degree.rst new file mode 100644 index 000000000..1f6825fe1 --- /dev/null +++ b/docs/source-old/matrix/adapters/degree.rst @@ -0,0 +1,33 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Degree +====== + +.. cpp:namespace:: libsemigroups + +.. cpp:struct:: template \ + Degree>> + + Defined in ``matrix.hpp``. + + Specialization of the adapter :cpp:any:`Degree` for types ``T`` such + that the value of :cpp:any:`IsMatrix\` is ``true``. + + :tparam: T the type of matrices. + + .. cpp:function:: constexpr size_t operator()(T const& x) const noexcept + + Returns ``x.number_of_rows()``. + + :param x: a matrix of type ``T``. + + :returns: a value of type ``size_t``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant. diff --git a/docs/source-old/matrix/adapters/increasedegreeby.rst b/docs/source-old/matrix/adapters/increasedegreeby.rst new file mode 100644 index 000000000..a0dd1f11b --- /dev/null +++ b/docs/source-old/matrix/adapters/increasedegreeby.rst @@ -0,0 +1,40 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +IncreaseDegree +============== + +.. cpp:namespace:: libsemigroups + +.. cpp:struct:: template \ + IncreaseDegree>> + + Defined in ``matrix.hpp``. + + Specialization of the adapter :cpp:any:`IncreaseDegree` for types ``T`` such + that the value of :cpp:any:`IsMatrix\` is ``true``. + + :tparam T: the type of matrices. + + .. warning:: + It is not possible to increase the degree of any of the types for which + :cpp:any:`IsMatrix\` is ``true``, and as such the call operator of this + type does nothing. + + + .. cpp:function:: constexpr void operator()(T&, size_t) const noexcept + + Returns (None). + + :parameters: (None) + + :returns: Does not do anything, do not use. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant. + diff --git a/docs/source-old/matrix/adapters/one.rst b/docs/source-old/matrix/adapters/one.rst new file mode 100644 index 000000000..ef2f89d40 --- /dev/null +++ b/docs/source-old/matrix/adapters/one.rst @@ -0,0 +1,43 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +One +====== + +.. cpp:namespace:: libsemigroups + +.. cpp:struct:: template \ + One>> + + Defined in ``matrix.hpp``. + + Specialization of the adapter :cpp:any:`One` for types ``T`` such + that the value of :cpp:any:`IsMatrix\` is ``true``. + + :tparam: T the type of matrices. + + .. cpp:function:: inline T operator()(T const& x) const + + Returns the identity matrix. + + :param x: a matrix of type ``T``. + + :returns: a matrix of type ``T``. + + :exceptions: + This function guarantees not to throw a + :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(m ^ 2)` where :math:`m` is the number of rows of the matrix ``x``. + + .. warning:: + This function only works for square matrices. + + .. seealso:: + See :cpp:any:`static StaticMatrix StaticMatrix::identity()`, or + :cpp:any:`static DynamicMatrix DynamicMatrix::identity(size_t n)` for + further details. diff --git a/docs/source-old/matrix/adapters/product.rst b/docs/source-old/matrix/adapters/product.rst new file mode 100644 index 000000000..d9db761fd --- /dev/null +++ b/docs/source-old/matrix/adapters/product.rst @@ -0,0 +1,46 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Product +======= + +.. cpp:namespace:: libsemigroups + +.. cpp:struct:: template \ + Product>> + + Defined in ``matrix.hpp``. + + Specialization of the adapter :cpp:any:`Product` for types ``T`` such + that the value of :cpp:any:`IsMatrix\` is ``true``. + + :tparam: T the type of matrices. + + .. cpp:function:: inline void operator()(T& xy, T const& x, T const& y, size_t = 0) const + + Replaces the value of ``xy`` by the product of the matrices ``x`` and ``y``. + + :param xy: a reference to a matrix of type ``T``. + :param x: a const reference to a matrix of type ``T``. + :param y: a const reference to a matrix of type ``T``. + + :returns: (None) + + :exceptions: + This function guarantees not to throw a + :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(m ^ 2)` where :math:`m` is the number of rows of the matrix ``x``. + + .. warning:: + This function only works for square matrices. + + .. seealso:: + For further details see: :cpp:any:`void + StaticMatrix::product_inplace(StaticMatrix const& A, StaticMatrix + const& B)`, :cpp:any:`void DynamicMatrix::product_inplace(DynamicMatrix + const& A, DynamicMatrix const& B)`. diff --git a/docs/source-old/matrix/bmat/adapters/imageleftaction.rst b/docs/source-old/matrix/bmat/adapters/imageleftaction.rst new file mode 100644 index 000000000..311f06879 --- /dev/null +++ b/docs/source-old/matrix/bmat/adapters/imageleftaction.rst @@ -0,0 +1,86 @@ +.. Copyleft (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + + +ImageLeftAction +================ + +.. cpp:namespace:: libsemigroups + +.. cpp:struct:: template \ + ImageLeftAction + + This struct is a specialisation of :cpp:any:`ImageLeftAction` for boolean + matrices and containers of bitsets. + + :tparam Container: + a container type where :cpp:any:`IsBitSet\` + is ``true``. For example, ``Container`` might be + ``detail::StaticVector1, N>`` or ``std::vector>`` for + some value of ``N`` with :math:`0\leq N\leq 64`. + + :tparam Mat: + a type such that :cpp:any:`IsBMat` is ``true``. + + .. cpp:function:: void operator()(Container& res, \ + Container const& pt, \ + Mat const& x) const + + Given a row basis ``pt`` and a boolean matrix ``x``, this function + computes the row basis of the space obtained by left multiplication of + the rows in ``pt`` by the matrix ``x``, and modifies ``res`` to contain + the resulting row basis. This is equivalent to applying + :cpp:any:`ImageRightAction` to the transpose of ``x``. + + :param res: container to store the result. + + :param pt: the container on which to act. + + :param x: the matrix which is acting. + + :returns: (None). + + :complexity: + :math:`O(r ^ 2 c)` where :math:`r` is the number of rows in ``pt`` and + :math:`c` is the number of columns in ``x``. + +.. cpp:struct:: template \ + ImageLeftAction> + + This struct is a specialisation of :cpp:any:`ImageLeftAction` for boolean + matrices and bitsets. + + :tparam N: + a value that exceeds the number of rows in any instance of ``Mat`` passed + to the call operator. + + :tparam Mat: + a type such that :cpp:any:`IsBMat` is ``true``. + + .. cpp:type:: result_type = BitSet + + Alias for the type of the result of the call operator. + + .. cpp:function:: void operator()(result_type& res, \ + result_type const& pt, \ + Mat const& x) const + + Given a bitset ``pt`` (representing a row of a boolean matrix) and a + boolean matrix ``x``, this function computes the row obtained by left + multiplying ``pt`` by the matrix ``x``, and modifies ``res`` to contain + the resulting bitset. This is equivalent to applying + :cpp:any:`ImageRightAction` to the transpose of ``x``. + + :param res: bitset to contain the result. + + :param pt: the bitset on which to act. + + :param x: the matrix which is acting. + + :returns: (None). + + :complexity: + :math:`O(r ^ 2)` where :math:`r` is the number of columns in ``x``. diff --git a/docs/source-old/matrix/bmat/adapters/imagerightaction.rst b/docs/source-old/matrix/bmat/adapters/imagerightaction.rst new file mode 100644 index 000000000..630c7186b --- /dev/null +++ b/docs/source-old/matrix/bmat/adapters/imagerightaction.rst @@ -0,0 +1,84 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + + +ImageRightAction +================ + +.. cpp:namespace:: libsemigroups + +.. cpp:struct:: template \ + ImageRightAction + + This struct is a specialisation of :cpp:any:`ImageRightAction` for boolean + matrices and containers of bitsets. + + :tparam Container: + a container type where :cpp:any:`IsBitSet\` + is ``true``. For example, ``Container`` might be + ``detail::StaticVector1, N>`` or ``std::vector>`` for + some value of ``N`` with :math:`0\leq N\leq 64`. + + :tparam Mat: + a type such that :cpp:any:`IsBMat` is ``true``. + + .. cpp:function:: void operator()(Container& res, \ + Container const& pt, \ + Mat const& x) const + + Given a row basis ``pt`` and a boolean matrix ``x``, this function + computes the row basis of the space obtained by right multiplication of + the rows in ``pt`` by the matrix ``x``, and modifies ``res`` to contain + the resulting row basis. + + :param res: container to store the result. + + :param pt: the container on which to act. + + :param x: the matrix which is acting. + + :returns: (None). + + :complexity: + :math:`O(r ^ 2 c)` where :math:`r` is the number of rows in ``pt`` and + :math:`c` is the number of columns in ``x``. + +.. cpp:struct:: template \ + ImageRightAction> + + This struct is a specialisation of :cpp:any:`ImageRightAction` for boolean + matrices and bitsets. + + :tparam N: + a value that exceeds the number of rows in any instance of ``Mat`` passed + to the call operator. + + :tparam Mat: + a type such that :cpp:any:`IsBMat` is ``true``. + + .. cpp:type:: result_type = BitSet + + Alias for the type of the result of the call operator. + + .. cpp:function:: void operator()(result_type& res, \ + result_type const& pt, \ + Mat const& x) const + + Given a bitset ``pt`` (representing a row of a boolean matrix) and a + boolean matrix ``x``, this function computes the row obtained by right + multiplying ``pt`` by the matrix ``x``, and modifies ``res`` to contain + the resulting bitset. + + :param res: bitset to contain the result. + + :param pt: the bitset on which to act. + + :param x: the matrix which is acting. + + :returns: (None). + + :complexity: + :math:`O(r ^ 2)` where :math:`r` is the number of rows in ``x``. diff --git a/docs/source-old/matrix/bmat/adapters/lambda.rst b/docs/source-old/matrix/bmat/adapters/lambda.rst new file mode 100644 index 000000000..3fa7e7350 --- /dev/null +++ b/docs/source-old/matrix/bmat/adapters/lambda.rst @@ -0,0 +1,62 @@ +.. Copyleft (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Lambda +====== + +This page contains details of the specialisations of the `adapters` +:cpp:any:`Lambda` and :cpp:any:`LambdaValue` for boolean matrices. + +.. cpp:struct:: template \ + LambdaValue + + Specialization of the adapter ``LambdaValue`` for instances of ``BMat``. + Note that the type chosen here limits the :cpp:any:`Konieczny` algorithm to + boolean matrices of dimension at most 64 (or 32 on 32-bit systems). + + :tparam Mat: + a type such that :cpp:any:`IsBMat` is ``true``. + + .. cpp:var:: static constexpr size_t N = BitSet<1>::max_size() + + Variable representing the maximum capacity of the container for lambda + values. + + .. cpp:type:: type = detail::StaticVector1, N> + + For :cpp:any:`BMat\` objects, ``type`` is + :cpp:any:`StaticVector1\, N>`, where ``N`` is the maximum + width of BitSet on the system. This represents a row space basis of a + :cpp:any:`BMat\`. + + +.. cpp:struct:: template \ + Lambda + + :tparam Container: + a container type for holding the return value of the call operator, can be + one of + :cpp:any:`StaticVector1\, N>`; + :cpp:any:`std::vector\>`; + :cpp:any:`StaticVector1\, N>`; or + :cpp:any:`std::vector\>` + for some value of ``N``. + + :tparam Mat: + a type such that :cpp:any:`IsBMat` is ``true``. + + .. cpp:function:: void operator()(Container& res, Mat const& x) const + + Modifies ``res`` to contain the row space basis of ``x``. + + :param res: the container to hold the result + :param x: the matrix + + :returns: (None). + + :complexity: + :math:`O(r ^ 2 c)` where :math:`r` is the number of rows in ``x`` and + :math:`c` is the number of columns in ``x``. diff --git a/docs/source-old/matrix/bmat/adapters/rank.rst b/docs/source-old/matrix/bmat/adapters/rank.rst new file mode 100644 index 000000000..7057f3c27 --- /dev/null +++ b/docs/source-old/matrix/bmat/adapters/rank.rst @@ -0,0 +1,96 @@ +.. Copyleft (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Rank +==== + +This page contains details of the specialisations of the :ref:`adapters` +:cpp:any:`Rank` and :cpp:any:`RankState` for boolean matrices. + +.. cpp:class:: template \ + RankState + + This class is a specialization of the adapter :cpp:any:`RankState` for + instances of :cpp:any:`BMat`. The :cpp:any:`RankState` is used as part of + the computation of the rank of a boolean matrix in :cpp:any:`Rank` + which is used by :cpp:any:`Konieczny`. + + :tparam Mat: + a type such that :cpp:any:`IsBMat` is ``true``. + + .. cpp:type:: MaxBitSet = BitSet::max_size()> + + Type of the maximum possible size of :cpp:any:`BitSet`. + + .. cpp:type:: type = RightAction> + + The type of additional data used by :cpp:any:`Rank`: the right + action consisting of all possible rows of matrices belonging to the + underlying semigroup. + + .. cpp:function:: RankState() = default + + Default constructor. The other standard constructors (copy constructor, + move constructor, etc) are deleted. + + .. cpp:function:: template \ + RankState(T first, T last) + + Construct from const iterators to the generators of the semigroup. + + :tparam T: type of const iterators to the generators of the semigroup + + :param first: const iterator to the first generator + + :param last: const iterator pointing one passed the last generator + + :throws: + :cpp:any:`LibsemigroupsException` if the distance between + ``first`` and ``last`` is ``0``. + + .. cpp:function:: type const& get() const + + Returns the fully enumerated row orbit. + + :parameters: (None) + + :returns: + A const reference to the fully enumerated row orbit, a value of type + :cpp:any:`type`. + + :complexity: + :math:`O(mn)` where :math:`m` is the number of generators added at the + time of construction (i.e. ``std::distance(first, last)``) and :math:`n` + is the size of the fully enumerated row orbit. + + +.. cpp:struct:: template \ + Rank> + + Specialization of the adapter :cpp:any:`Rank` for instances of + :cpp:any:`BMat`. + + :tparam Mat: + a type such that :cpp:any:`IsBMat` is ``true``. + + .. cpp:function:: size_t operator()(RankState const& state, Mat const& x) const + + Returns the rank of ``x``. + + :param state: a const reference to the `RankState` + + :param x: the matrix + + :returns: + the rank of the parameter ``x``, which is a value of type ``size_t``. + + :complexity: + The first call has complexity at worst :math:`O(mn)` where :math:`m` is + the number of generators added at the time of construction (i.e. + ``std::distance(first, last)``) and :math:`n` is the size of the fully + enumerated row orbit, subsequent calls have constant complexity. diff --git a/docs/source-old/matrix/bmat/adapters/rho.rst b/docs/source-old/matrix/bmat/adapters/rho.rst new file mode 100644 index 000000000..7acca27f5 --- /dev/null +++ b/docs/source-old/matrix/bmat/adapters/rho.rst @@ -0,0 +1,62 @@ +.. Copyleft (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Rho +=== + +This page contains details of the specialisations of the `adapters` +:cpp:any:`Rho` and :cpp:any:`RhoValue` for boolean matrices. + +.. cpp:struct:: template \ + RhoValue + + Specialization of the adapter ``RhoValue`` for instances of ``BMat``. + Note that the type chosen here limits the :cpp:any:`Konieczny` algorithm to + boolean matrices of dimension at most 64 (or 32 on 32-bit systems). + + :tparam Mat: + a type such that :cpp:any:`IsBMat` is ``true``. + + .. cpp:var:: static constexpr size_t N = BitSet<1>::max_size() + + Variable representing the maximum capacity of the container for lambda + values. + + .. cpp:type:: type = detail::StaticVector1, N> + + For :cpp:any:`BMat\` objects, ``type`` is + :cpp:any:`StaticVector1\, N>`, where ``N`` is the maximum + width of BitSet on the system. This represents a row space basis of a + :cpp:any:`BMat\`. + + +.. cpp:struct:: template \ + Rho + + :tparam Container: + a container type for holding the return value of the call operator, can be + one of + :cpp:any:`StaticVector1\, N>`; + :cpp:any:`std::vector\>`; + :cpp:any:`StaticVector1\, N>`; or + :cpp:any:`std::vector\>` + for some value of ``N``. + + :tparam Mat: + a type such that :cpp:any:`IsBMat` is ``true``. + + .. cpp:function:: void operator()(Container& res, Mat const& x) const + + Modifies ``res`` to contain the row space basis of ``x``. + + :param res: the container to hold the result + :param x: the matrix + + :returns: (None). + + :complexity: + :math:`O(r ^ 2 c)` where :math:`r` is the number of rows in ``x`` and + :math:`c` is the number of columns in ``x``. diff --git a/docs/source-old/matrix/bmat/bmat.rst b/docs/source-old/matrix/bmat/bmat.rst new file mode 100644 index 000000000..a93f3ab10 --- /dev/null +++ b/docs/source-old/matrix/bmat/bmat.rst @@ -0,0 +1,99 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +BMat\ +======== + +This page describes the functionality for :math:`m \times n` boolean matrices +for arbitrary dimensions :math:`m` and :math:`n`. There are two types of such +boolean matrices those whose dimension is known at compile-time, and those +where it is not. Both types can be accessed via the alias template +:cpp:any:`BMat\`: if ``R`` or ``C`` has value ``0``, then the dimensions +can be set at run time, otherwise the dimensions are ``R`` and ``C``. The default +value of ``R`` is ``0`` and of ``C`` is ``R``. + +The alias :cpp:any:`BMat\` is either :cpp:any:`StaticMatrix` or +:cpp:any:`DynamicMatrix`, please refer to the documentation of these class +templates for more details. The only substantial difference in the interface +of :cpp:any:`StaticMatrix` and :cpp:any:`DynamicMatrix` is that the former can +be default constructed and the latter should be constructed using the +dimensions. + +**Example** + +.. code-block:: cpp + + BMat<3> m; // default construct an uninitialized 3 x 3 static matrix + BMat<> m(4, 4); // construct an uninitialized 4 x 4 dynamic matrix + + +.. cpp:struct:: BooleanPlus + + This is a stateless struct with a single call operator of signature: + ``bool operator()(bool const x, bool const y) const noexcept`` + which returns ``x || y``; representing addition in the boolean semiring. + +.. cpp:struct:: BooleanProd + + This is a stateless struct with a single call operator of signature: + ``bool operator()(bool const x, bool const y) const noexcept`` + which returns ``x && y``; representing multiplication in the boolean + semiring. + +.. cpp:struct:: BooleanZero + + This is a stateless struct with a single call operator of signature: ``bool + operator()() const noexcept`` which returns ``false``; representing the + additive identity of the boolean semiring. + + +.. cpp:struct:: BooleanOne + + This is a stateless struct with a single call operator of signature: ``bool + operator()() const noexcept`` which returns ``true``; representing the + multiplicative identity of the boolean semiring. + + +.. cpp:type:: DynamicBMat \ + = DynamicMatrix + + Alias for the type of dynamic boolean matrices where the dimensions of the + matrices can be defined at run time. + + +.. cpp:type:: template \ + StaticBMat = StaticMatrix + + Alias for the type of static boolean matrices where the dimensions of the + matrices are defined at compile time. + + +.. cpp:type:: template \ + BMat = std::conditional_t> + + Alias template for boolean matrices. + + :tparam R: + the number of rows of the matrices. A value of ``0`` (the default value) + indicates that the dimensions will be set at run time. + + :tparam C: + the number of columns of the matrices. A value of ``0`` + indicates that the dimensions will be set at run time (the default value + is ``R``). + + +.. cpp:var:: template \ + static constexpr bool IsBMat + + This variable has value ``true`` if the template parameter ``T`` is the same + as :cpp:any:`BMat\` for some values of ``R`` and ``C``. diff --git a/docs/source-old/matrix/bmat/bmat8-adapters.rst b/docs/source-old/matrix/bmat/bmat8-adapters.rst new file mode 100644 index 000000000..0b1da39c3 --- /dev/null +++ b/docs/source-old/matrix/bmat/bmat8-adapters.rst @@ -0,0 +1,22 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +BMat8 adapters +============== + +This section describes the specialisations of :ref:`Adapters` for the class +:cpp:any:`BMat8`: + +.. toctree:: + :maxdepth: 1 + + bmat8-complexity + bmat8-degree + bmat8-imageleftaction + bmat8-imagerightaction + bmat8-inverse + bmat8-one + bmat8-product diff --git a/docs/source-old/matrix/bmat/bmat8-complexity.rst b/docs/source-old/matrix/bmat/bmat8-complexity.rst new file mode 100644 index 000000000..343a83f2e --- /dev/null +++ b/docs/source-old/matrix/bmat/bmat8-complexity.rst @@ -0,0 +1,15 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +Complexity +========== + +.. doxygenstruct:: libsemigroups::Complexity< BMat8 > + :project: libsemigroups + :members: diff --git a/docs/source-old/matrix/bmat/bmat8-degree.rst b/docs/source-old/matrix/bmat/bmat8-degree.rst new file mode 100644 index 000000000..68ea5610c --- /dev/null +++ b/docs/source-old/matrix/bmat/bmat8-degree.rst @@ -0,0 +1,15 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +Degree +====== + +.. doxygenstruct:: libsemigroups::Degree< BMat8 > + :project: libsemigroups + :members: diff --git a/docs/source-old/matrix/bmat/bmat8-helpers.rst b/docs/source-old/matrix/bmat/bmat8-helpers.rst new file mode 100644 index 000000000..5a131841f --- /dev/null +++ b/docs/source-old/matrix/bmat/bmat8-helpers.rst @@ -0,0 +1,19 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + + This file only exists because Breathe always displays all members when + documenting a namespace, and this is nicer for now. + +BMat8 helpers +------------- + +Defined in ``bmat8.hpp``. + +This page contains the documentation for various helper functions for +:cpp:type:`libsemigroups::BMat8`, and :cpp:type:`HPCombi::BMat8`. + +.. doxygennamespace:: libsemigroups::bmat8_helpers + :project: libsemigroups diff --git a/docs/source-old/matrix/bmat/bmat8-imageleftaction.rst b/docs/source-old/matrix/bmat/bmat8-imageleftaction.rst new file mode 100644 index 000000000..2c41651f3 --- /dev/null +++ b/docs/source-old/matrix/bmat/bmat8-imageleftaction.rst @@ -0,0 +1,15 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +ImageLeftAction +=============== + +.. doxygenstruct:: libsemigroups::ImageLeftAction< BMat8, BMat8 > + :project: libsemigroups + :members: diff --git a/docs/source-old/matrix/bmat/bmat8-imagerightaction.rst b/docs/source-old/matrix/bmat/bmat8-imagerightaction.rst new file mode 100644 index 000000000..4f62e1513 --- /dev/null +++ b/docs/source-old/matrix/bmat/bmat8-imagerightaction.rst @@ -0,0 +1,15 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +ImageRightAction +================ + +.. doxygenstruct:: libsemigroups::ImageRightAction< BMat8, BMat8 > + :project: libsemigroups + :members: diff --git a/docs/source-old/matrix/bmat/bmat8-inverse.rst b/docs/source-old/matrix/bmat/bmat8-inverse.rst new file mode 100644 index 000000000..874d35c24 --- /dev/null +++ b/docs/source-old/matrix/bmat/bmat8-inverse.rst @@ -0,0 +1,15 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +Inverse +======= + +.. doxygenstruct:: libsemigroups::Inverse< BMat8 > + :project: libsemigroups + :members: diff --git a/docs/source-old/matrix/bmat/bmat8-one.rst b/docs/source-old/matrix/bmat/bmat8-one.rst new file mode 100644 index 000000000..c718dae36 --- /dev/null +++ b/docs/source-old/matrix/bmat/bmat8-one.rst @@ -0,0 +1,15 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +One +=== + +.. doxygenstruct:: libsemigroups::One< BMat8 > + :project: libsemigroups + :members: diff --git a/docs/source-old/matrix/bmat/bmat8-product.rst b/docs/source-old/matrix/bmat/bmat8-product.rst new file mode 100644 index 000000000..026767171 --- /dev/null +++ b/docs/source-old/matrix/bmat/bmat8-product.rst @@ -0,0 +1,15 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. This file only exists because JDM couldn't figure out how to get the + operator() to appear using the yml setup. + +Product +======= + +.. doxygenstruct:: libsemigroups::Product< BMat8 > + :project: libsemigroups + :members: diff --git a/docs/source-old/matrix/bmat/bmat8.rst b/docs/source-old/matrix/bmat/bmat8.rst new file mode 100644 index 000000000..1940bfd45 --- /dev/null +++ b/docs/source-old/matrix/bmat/bmat8.rst @@ -0,0 +1,21 @@ + +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +BMat8 +===== + +This page describes the class :cpp:any:`BMat8` that are an optimized +representation of boolean matrices of dimension at most :math:`8`. + +For boolean matrices of higher dimensions see :cpp:any:`BMat\<>`. + +.. toctree:: + :maxdepth: 1 + + ../../_generated/libsemigroups__bmat8 + bmat8-helpers + bmat8-adapters diff --git a/docs/source-old/matrix/bmat/index.rst b/docs/source-old/matrix/bmat/index.rst new file mode 100644 index 000000000..988af1144 --- /dev/null +++ b/docs/source-old/matrix/bmat/index.rst @@ -0,0 +1,42 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Boolean matrices +================ + +The following classes in ``libsemigroups`` represent boolean matrices: + +.. toctree:: + :maxdepth: 1 + + bmat8 + bmat + +Boolean matrix helpers +---------------------- + +The following helper struct can be used to determine the smallest type of +boolean matrix of specified dimension. + +.. toctree:: + :maxdepth: 1 + + ../../_generated/libsemigroups__fastestbmat + +Boolean matrix adapters +----------------------- + +The following adapters are implemented to so that :cpp:any:`BMat` can be +used with :cpp:any:`Konieczny`. + +.. toctree:: + :maxdepth: 1 + + adapters/imagerightaction + adapters/imageleftaction + adapters/lambda + adapters/rho + adapters/rank diff --git a/docs/source-old/matrix/dynamicmatrix-compile.rst b/docs/source-old/matrix/dynamicmatrix-compile.rst new file mode 100644 index 000000000..4e1a13cb3 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-compile.rst @@ -0,0 +1,193 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +DynamicMatrix (with compile time arithmetic) +============================================ + +.. highlight:: cpp + +Defined in ``matrix.hpp``. + +.. cpp:class:: template \ + DynamicMatrix final + :tparam-line-spec: + + This is a class for matrices where the arithmetic operations in the + underlying semiring are known at compile time, and the dimensions of the + matrix can be set at run time. + + :tparam PlusOp: + a stateless type with a call operator of signature :code:`scalar_type + operator()(scalar_type, scalar_type)` implementing the addition of the + semiring + + :tparam ProdOp: + a stateless type with a call operator of signature :code:`scalar_type + operator()(scalar_type, scalar_type)` implementing the multiplication of + the semiring + + :tparam ZeroOp: + a stateless type with a call operator of signature :code:`scalar_type + operator()()` returning the zero of the semiring (the additive identity + element) + + :tparam OneOp: + a stateless type with a call operator of signature :code:`scalar_type + operator()()` returning the one of the semiring (the multiplicative + identity element) + + :tparam Scalar: + the type of the entries in the matrices (the type of elements in the + underlying semiring) + + .. note:: + Certain member functions only work for square matrices and some only work + for rows. + +.. toctree:: + :hidden: + + dynamicmatrix-compile/begin + dynamicmatrix-compile/call_operator + dynamicmatrix-compile/comparison_ops + dynamicmatrix-compile/constructors + dynamicmatrix-compile/coords + dynamicmatrix-compile/end + dynamicmatrix-compile/number_of_rows + dynamicmatrix-compile/operator_plus + dynamicmatrix-compile/operator_plus_equals + dynamicmatrix-compile/operator_prod + dynamicmatrix-compile/operator_prod_equals + dynamicmatrix-compile/row + dynamicmatrix-compile/rows + dynamicmatrix-compile/staticmemfn + dynamicmatrix-compile/swap + dynamicmatrix-compile/transpose + dynamicmatrix-compile/types + +Member types +------------ + +.. list-table:: + :widths: 50 50 + :header-rows: 1 + + * - Member type + - Definition + * - :ref:`scalar_type` + - the type of scalars contained in the matrix (:code:`Scalar`) + * - :ref:`scalar_reference` + - the type of references to scalars contained in the matrix + * - :ref:`scalar_const_reference` + - the type of const references to scalars contained in the matrix + * - :ref:`Row` + - type of a row of the matrix + * - :ref:`RowView` + - type of a row view int the matrix + * - :ref:`Plus` + - the template parameter :cpp:any:`PlusOp` + * - :ref:`Prod` + - the template parameter :cpp:any:`ProdOp` + * - :ref:`Zero` + - the template parameter :cpp:any:`ZeroOp` + * - :ref:`One` + - the template parameter :cpp:any:`OneOp` + * - :ref:`semiring_type` + - ``void`` + + +Member functions +---------------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`(constructor)` + - constructs the matrix + * - :ref:`number_of_rows/number_of_cols` + - the number of rows/columns in the matrix + +Static member functions +----------------------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`make` + - constructs a matrix and checks that its entries are valid + * - :ref:`identity` + - constructs an identity matrix + +Iterators +--------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`begin/cbegin` + - returns an iterator to the beginning + * - :ref:`end/cend` + - returns an iterator to the end + * - :ref:`coords` + - returns the coordinates corresponding to an iterator + +Accessors +--------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`operator()` + - access specified element + * - :ref:`row` + - access specified row + * - :ref:`rows` + - add all rows to a container + +Arithmetic operators +-------------------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`operator+=` + - add a (matrix, scalar, or row view) to the matrix in place + * - :ref:`operator\*=` + - multiply the matrix by a matrix or scalar in place + * - :ref:`operator+` + - add a (matrix, scalar, or row view) to the matrix + * - :ref:`operator*` + - multiply the matrix by a matrix or scalar + +Comparison operators +-------------------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`operator==` + - compare matrices + * - :ref:`operator!=` + - compare matrices + * - :ref:`operator\<` + - compare matrices + * - :ref:`operator\>` + - compare matrices + +Modifiers +--------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`swap` + - swaps the contents + * - :ref:`transpose` + - transposes the matrix diff --git a/docs/source-old/matrix/dynamicmatrix-compile/begin.rst b/docs/source-old/matrix/dynamicmatrix-compile/begin.rst new file mode 100644 index 000000000..59a055780 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-compile/begin.rst @@ -0,0 +1,53 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + + +.. _dynamicmatrix_compile_begin: + +begin, cbegin +============= + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: iterator begin() + + Returns a (random access) iterator pointing at the first entry in the + matrix. + + :returns: + A value of type ``iterator``. + + :complexity: Constant + + :throws: + this function is ``noexcept`` and is guaranteed never to throw. + + :parameters: (None) + + .. warning:: + The order in which entries in the matrix are iterated over is not + specified. + + +.. cpp:function:: const_iterator cbegin() + + Returns a const (random access) iterator pointing at the first entry in the + matrix. + + :returns: + A value of type ``const_iterator``. + + :complexity: Constant + + :throws: + this function is ``noexcept`` and is guaranteed never to throw. + + :parameters: (None) + + .. warning:: + The order in which entries in the matrix are iterated over is not + specified. + diff --git a/docs/source-old/matrix/dynamicmatrix-compile/call_operator.rst b/docs/source-old/matrix/dynamicmatrix-compile/call_operator.rst new file mode 100644 index 000000000..838096f08 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-compile/call_operator.rst @@ -0,0 +1,50 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_compile_call_operator: + +operator() +========== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: scalar_reference operator()(size_t const r, size_t const c) + + Returns a reference to the specified entry of the matrix. + + :param r: the index of the row of the entry + :param c: the index of the column of the entry + + :returns: A value of type :cpp:any:`scalar_reference`. + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + Constant + + .. warning:: + No checks on the validity of the parameters ``r`` and ``c`` are + performed. + +.. cpp:function:: scalar_const_reference operator()(size_t const r, size_t const c) const + + Returns a const reference to the specified entry of the matrix. + + :param r: the index of the row of the entry + :param c: the index of the column of the entry + + :returns: A value of type :cpp:any:`scalar_const_reference`. + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + Constant + + .. warning:: + No checks on the validity of the parameters ``r`` and ``c`` are + performed. diff --git a/docs/source-old/matrix/dynamicmatrix-compile/comparison_ops.rst b/docs/source-old/matrix/dynamicmatrix-compile/comparison_ops.rst new file mode 100644 index 000000000..1486f385c --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-compile/comparison_ops.rst @@ -0,0 +1,114 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_compile_comparison_ops: + +DynamicMatrix comparison operators +================================== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. _dynamicmatrix_compile_operator_equals: + +.. cpp:function:: bool operator==(DynamicMatrix const& that) const + + Equality operator. + + :param that: matrix for comparison. + + :returns: + ``true`` if ``*this`` and ``that`` are equal and ``false`` if they are + not. + + :complexity: + At worst :math:`O(mn)` where :math:`m` is the number of rows and + :math:`n` is the number of columns of the matrix. + +.. cpp:function:: bool operator==(RowView const& that) const + + Equality operator. + + :param that: the row view for comparison. + + :returns: + ``true`` if ``*this`` and ``that`` are equal and ``false`` if they are + not. In particular, if ``*this`` has more than one row, then ``false`` + is returned. + + :complexity: + At worst :math:`O(n)` where :math:`n` is the number of columns of the + matrix. + +.. _dynamicmatrix_compile_operator_not_equals: + +.. cpp:function:: template \ + bool operator!=(T const& that) const + + Inequality operator. + + :tparam T: + either :cpp:any:`DynamicMatrix` or :cpp:any:`DynamicMatrix::RowView` + + :param that: the matrix or row view for comparison. + + :returns: + the negation of ``operator==(that)``. + + :complexity: + see :cpp:any:`DynamicMatrix::operator==` + +.. _dynamicmatrix_compile_operator_less: + +.. cpp:function:: bool operator<(DynamicMatrix const& that) const + + Less than operator. + + This operator defines a total order on the set of matrices of the same type, + the details of which is implementation specific. + + :param that: the matrix for comparison. + + :returns: + ``true`` if ``*this`` is less than ``that`` and ``false`` if it is not. + + :complexity: + At worst :math:`O(mn)` where :math:`m` is + :cpp:any:`DynamicMatrix::number_of_rows` + and :math:`n` is :cpp:any:`DynamicMatrix::number_of_cols` + +.. cpp:function:: bool operator<(RowView const& that) const + + Less than operator. + + :param that: the row view for comparison. + + :returns: + ``true`` if ``*this`` is less than ``that``, and ``false`` + otherwise. In particular, if ``*this`` has more than one row, then + ``false`` is returned. + + :complexity: + At worst :math:`O(n)` where :math:`n` is + :cpp:any:`DynamicMatrix::number_of_cols` + +.. _dynamicmatrix_compile_operator_more: + +.. cpp:function:: bool operator>(DynamicMatrix const& that) const + + Greater than operator. + + This operator defines a total order on the set of matrices of the same type, + the details of which is implementation specific. + + :param that: the matrix for comparison. + + :returns: + ``true`` if ``*this`` is less than ``that`` and ``false`` if it is not. + + :complexity: + At worst :math:`O(mn)` where :math:`m` is + :cpp:any:`DynamicMatrix::number_of_rows` + and :math:`m` is :cpp:any:`DynamicMatrix::number_of_cols` diff --git a/docs/source-old/matrix/dynamicmatrix-compile/constructors.rst b/docs/source-old/matrix/dynamicmatrix-compile/constructors.rst new file mode 100644 index 000000000..9828ac998 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-compile/constructors.rst @@ -0,0 +1,133 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_compile_constructors: + +DynamicMatrix +============= + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +This page contains information about the constructors for the +:cpp:any:`DynamicMatrix` class. + +Default constructors +-------------------- + +.. cpp:function:: DynamicMatrix() = default + + Default constructor. + +.. cpp:function:: DynamicMatrix(DynamicMatrix const&) = default + + Default copy constructor. + +.. cpp:function:: DynamicMatrix(DynamicMatrix&&) = default + + Default move constructor. + +.. cpp:function:: DynamicMatrix& \ + operator=(DynamicMatrix const&) = default + + Default copy assignment operator. + +.. cpp:function:: DynamicMatrix& \ + operator=(DynamicMatrix&&) = default + + Default move assignment operator. + + +Matrix constructors +------------------- + +.. cpp:function:: DynamicMatrix(size_t r, size_t c) + + Construct a matrix. + + :param r: the number of rows in the matrix being constructed + :param c: the number of columns in the matrix being constructed + + :exceptions: + This function guarantees not to throw a + :cpp:any:`LibsemigroupsException`. + + :complexity: Constant + + **Example** + + .. code-block:: cpp + + Mat m(2, 3); // construct a 2 x 3 matrix + + +.. cpp:function:: DynamicMatrix( \ + std::initializer_list> m) + + Construct a matrix. + + :param m: the values to be copied into the matrix. + + :exceptions: + this function guarantees not to throw a + :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(mn)` where :math:`m` is the number of rows and + :math:`n` is the number of columns in the matrix being constructed. + + **Example** + + .. code-block:: cpp + + Mat m({{1, 1}, {0, 0}}); + + +.. cpp:function:: DynamicMatrix( \ + std::vector> const& m) + + Construct a matrix. + + :param m: the values to be copied into the matrix. + + :exceptions: + this function guarantees not to throw a + :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(mn)` where :math:`m` is the number of rows and + :math:`n` is the number of columns in the matrix being constructed. + +Row constructors +---------------- + +.. cpp:function:: DynamicMatrix( \ + std::initializer_list c) + + Construct a row. + + :param c: the values to be copied into the row. + + :exceptions: + this function guarantees not to throw a + :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(n)` where :math:`n` is the size of the row being + constructed. + +.. cpp:function:: DynamicMatrix(RowView const& rv) + + Construct a row from a row view. + + :param rv: the row view. + + :exceptions: + this function guarantees not to throw a + :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(n)` where :math:`n` is the size of the row being + constructed. diff --git a/docs/source-old/matrix/dynamicmatrix-compile/coords.rst b/docs/source-old/matrix/dynamicmatrix-compile/coords.rst new file mode 100644 index 000000000..29facebc1 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-compile/coords.rst @@ -0,0 +1,27 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_compile_coords: + +coords +====== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: std::pair \ + coords(const_iterator it) const + + Returns a pair containing the row and columns corresponding to an iterator. + + :param it: the iterator + + :returns: + A value of type ``std::pair``. + + :complexity: Constant + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. diff --git a/docs/source-old/matrix/dynamicmatrix-compile/end.rst b/docs/source-old/matrix/dynamicmatrix-compile/end.rst new file mode 100644 index 000000000..5e1e4454a --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-compile/end.rst @@ -0,0 +1,52 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_compile_end: + +end, cend +========= + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: iterator end() + + Returns a (random access) iterator pointing one passed the last entry of the + matrix. + + :returns: + A value of type ``iterator``. + + :complexity: Constant + + :exceptions: + this function is ``noexcept`` and is guaranteed never to throw. + + :parameters: (None) + + .. warning:: + The order in which entries in the matrix are iterated over is not + specified. + + +.. cpp:function:: const_iterator cend() + + Returns a const (random access) iterator pointing one passed the last entry + of the matrix. + + :returns: + A value of type ``const_iterator``. + + :complexity: Constant + + :exceptions: + this function is ``noexcept`` and is guaranteed never to throw. + + :parameters: (None) + + .. warning:: + The order in which entries in the matrix are iterated over is not + specified. + diff --git a/docs/source-old/matrix/dynamicmatrix-compile/number_of_rows.rst b/docs/source-old/matrix/dynamicmatrix-compile/number_of_rows.rst new file mode 100644 index 000000000..5208dbd58 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-compile/number_of_rows.rst @@ -0,0 +1,42 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_compile_number_of_rows: + +number_of_rows, number_of_cols +============================== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: size_t number_of_rows() + + Returns the number of rows of the matrix. + + :returns: + A value of type ``size_t``. + + :complexity: Constant + + :exceptions: + this function is ``noexcept`` and is guaranteed never to throw. + + :parameters: (None) + + +.. cpp:function:: size_t number_of_cols() + + Returns the number of columns of the matrix. + + :returns: + A value of type ``size_t``. + + :complexity: Constant + + :exceptions: + this function is ``noexcept`` and is guaranteed never to throw. + + :parameters: (None) + diff --git a/docs/source-old/matrix/dynamicmatrix-compile/operator_plus.rst b/docs/source-old/matrix/dynamicmatrix-compile/operator_plus.rst new file mode 100644 index 000000000..351c4776e --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-compile/operator_plus.rst @@ -0,0 +1,33 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_compile_operator_plus: + +operator+ +========= + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: DynamicMatrix operator+(DynamicMatrix const& that) + + Returns the sum of ``*this`` and ``that``. + + :param that: the matrix to add to ``this``. + + :returns: + a value of type ``DynamicMatrix``. + + :throws: + if the implementation of the semiring plus throws, or ``std::bad_alloc`` + if memory cannot be allocated for the result. + + :complexity: + :math:`O(mn)` where :math:`m` is :cpp:any:`DynamicMatrix::number_of_rows` + and :math:`m` is :cpp:any:`DynamicMatrix::number_of_cols` + + .. warning:: + The matrices must be of the same dimensions, although this is not + verified by the implementation. diff --git a/docs/source-old/matrix/dynamicmatrix-compile/operator_plus_equals.rst b/docs/source-old/matrix/dynamicmatrix-compile/operator_plus_equals.rst new file mode 100644 index 000000000..dc847a67b --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-compile/operator_plus_equals.rst @@ -0,0 +1,70 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_compile_operator_plus_equals: + +operator+= +========== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: void operator+=(DynamicMatrix const& that) + + Redefines ``this`` to be the sum of ``*this`` and ``that``. + + :param that: the matrix to add to ``this``. + + :returns: (None) + + :throws: + if the implementation of the semiring plus throws. + + :complexity: + :math:`O(mn)` where :math:`m` is :cpp:any:`DynamicMatrix::number_of_rows` + and :math:`m` is :cpp:any:`DynamicMatrix::number_of_cols` + + .. warning:: + The matrices must be of the same dimensions, although this is not + verified by the implementation. + +.. cpp:function:: void operator+=(RowView const& that) + + Redefines ``this`` to be the sum of ``*this`` and ``that``. + + :param that: the matrix to add to ``this``. + + :returns: (None) + + :throws: + if the implementation of the semiring plus throws. + + :complexity: + :math:`O(mn)` where :math:`m` is :cpp:any:`DynamicMatrix::number_of_rows` + and :math:`m` is :cpp:any:`DynamicMatrix::number_of_cols` + + .. warning:: + This function only works if ``this`` has a single row, i.e. the template + parameter ``R`` is ``1``. + +.. cpp:function:: void operator+=(scalar const a) + + Adds a scalar to every entry of the matrix in-place. + + :param a: the scalar to add to ``this``. + + :returns: (None) + + :throws: + if the implementation of the semiring plus throws. + + :complexity: + :math:`O(mn)` where :math:`m` is :cpp:any:`DynamicMatrix::number_of_rows` + and :math:`m` is :cpp:any:`DynamicMatrix::number_of_cols` + + .. warning:: + This function only works if ``this`` has a single row, i.e. the template + parameter ``R`` is ``1``. + diff --git a/docs/source-old/matrix/dynamicmatrix-compile/operator_prod.rst b/docs/source-old/matrix/dynamicmatrix-compile/operator_prod.rst new file mode 100644 index 000000000..e7a0b39be --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-compile/operator_prod.rst @@ -0,0 +1,33 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_compile_operator_prod: + +operator* +========= + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: DynamicMatrix operator*(DynamicMatrix const& that) + + Returns the product of ``*this`` and ``that``. + + :param that: the matrix to multiply by ``this``. + + :returns: + a value of type ``DynamicMatrix``. + + :throws: + if the implementation of the semiring multiplication throws, or + ``std::bad_alloc`` if memory cannot be allocated for the result. + + :complexity: + :math:`O(mn)` where :math:`m` is :cpp:any:`DynamicMatrix::number_of_rows` + and :math:`m` is :cpp:any:`DynamicMatrix::number_of_cols` + + .. warning:: + The matrices must be of the same dimensions, although this is not + verified by the implementation. diff --git a/docs/source-old/matrix/dynamicmatrix-compile/operator_prod_equals.rst b/docs/source-old/matrix/dynamicmatrix-compile/operator_prod_equals.rst new file mode 100644 index 000000000..9e937a1b5 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-compile/operator_prod_equals.rst @@ -0,0 +1,53 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_compile_operator_prod_equals: + +operator*= +========== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: void operator*=(scalar_type const a) + + Multiplies every entry of the matrix by a scalar in-place. + + :param a: the scalar to multiply every entry of ``this``. + + :returns: (None) + + :throws: + if the implementation of the semiring multiplication throws. + + :complexity: + :math:`O(mn)` where :math:`m` is :cpp:any:`DynamicMatrix::number_of_rows` + and :math:`m` is :cpp:any:`DynamicMatrix::number_of_cols` + +.. cpp:function:: void product_inplace(DynamicMatrix const& A, DynamicMatrix const& B) + + Multiplies ``A`` and ``B`` and stores the result in ``this``. + + Redefines ``this`` to be the product of ``A`` and ``B``. This is in-place + multiplication to avoid allocation of memory for products which do not need + to be stored for future use. + + :param A: the first matrix to multiply + :param B: the second matrix to multiply + + :returns: (None) + + :throws: + Throws if the implementation of the semiring plus or product throws + or ``std::bad_alloc``. + + :complexity: + :math:`O(n ^ 3)` where :math:`n` is :cpp:any:`DynamicMatrix::number_of_rows` + or :cpp:any:`DynamicMatrix::number_of_cols` + + .. warning:: + + This function only applies to matrices with the same number of rows + and columns. diff --git a/docs/source-old/matrix/dynamicmatrix-compile/row.rst b/docs/source-old/matrix/dynamicmatrix-compile/row.rst new file mode 100644 index 000000000..2d8451759 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-compile/row.rst @@ -0,0 +1,25 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_compile_row: + +row +=== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: RowView row(size_t i) const + + Returns a row view into the specified row. + + :param i: the row + + :returns: A value of type :cpp:any:`RowView`. + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: Constant diff --git a/docs/source-old/matrix/dynamicmatrix-compile/rows.rst b/docs/source-old/matrix/dynamicmatrix-compile/rows.rst new file mode 100644 index 000000000..ebd939ea7 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-compile/rows.rst @@ -0,0 +1,26 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_compile_rows: + +rows +==== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: template void rows(T& x) const + + Add row views for every row in the matrix to the container ``T``. + + :param x: a container + + :returns: (None) + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(m)` where :math:`m` is the template parameter :code:`R` diff --git a/docs/source-old/matrix/dynamicmatrix-compile/staticmemfn.rst b/docs/source-old/matrix/dynamicmatrix-compile/staticmemfn.rst new file mode 100644 index 000000000..0f6d2fd10 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-compile/staticmemfn.rst @@ -0,0 +1,68 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +DynamicMatrix static member functions +===================================== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. _dynamicmatrix_compile_identity: +.. cpp:function:: static DynamicMatrix identity(size_t n) + + Construct the :math:`n \times n` identity matrix. + + :param n: the dimension + + :returns: The :math:`n \times n` identity matrix. + + :exceptions: + This function guarantees not to throw a + :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(n ^ 2)`. + +.. _dynamicmatrix_compile_make: +.. cpp:function:: static DynamicMatrix \ + make(std::initializer_list> il) + + Validates the arguments, constructs a matrix and validates it. + + :param il: the values to be copied into the matrix. + + :returns: the constructed matrix if valid. + + :throws: + :cpp:any:`LibsemigroupsException` if ``il`` does not represent a + matrix of the correct dimensions. + + :throws: + :cpp:any:`LibsemigroupsException` if the constructed matrix + contains values that do not belong to the underlying semiring. + + :complexity: + :math:`O(mn)` where :math:`m` is the number of rows and + :math:`n` is the number of columns of the matrix. + +.. cpp:function:: static DynamicMatrix make(std::initializer_list il) + + Constructs a row and validates it. + + :param il: the values to be copied into the row. + + :returns: the constructed row if valid. + + :throws: + :cpp:any:`LibsemigroupsException` if the constructed row contains + values that do not belong to the underlying semiring. + + :complexity: + :math:`O(n)` where :math:`n` is the number of columns of the matrix. + + .. warning:: + + This constructor only works for rows, i.e. when the template parameter + :code:`R` is :code:`1`. diff --git a/docs/source-old/matrix/dynamicmatrix-compile/swap.rst b/docs/source-old/matrix/dynamicmatrix-compile/swap.rst new file mode 100644 index 000000000..b1f327b32 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-compile/swap.rst @@ -0,0 +1,25 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_compile_swap: + +swap +==== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: void swap(DynamicMatrix& that) noexcept + + Swaps the contents of ``this`` with the contents of ``that``. + + :param that: the matrix to swap contents with + + :returns: (None) + + :complexity: Constant + + :exceptions: + this function is ``noexcept`` and is guaranteed never to throw. diff --git a/docs/source-old/matrix/dynamicmatrix-compile/transpose.rst b/docs/source-old/matrix/dynamicmatrix-compile/transpose.rst new file mode 100644 index 000000000..918a491d4 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-compile/transpose.rst @@ -0,0 +1,30 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_compile_transpose: + +transpose +========= + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: void transpose() noexcept + + Transposes the matrix in-place. + + :parameters: (None) + + :returns: (None) + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(n ^ 2)` where :math:`n` is the number of rows and + the number of columns in the matrix. + + .. warning:: + This only works for square matrices. diff --git a/docs/source-old/matrix/dynamicmatrix-compile/types.rst b/docs/source-old/matrix/dynamicmatrix-compile/types.rst new file mode 100644 index 000000000..4b35c13b1 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-compile/types.rst @@ -0,0 +1,67 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +DynamicMatrix member types +========================== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +This page contains information about the member types of the +:cpp:any:`DynamicMatrix` class. + +.. _dynamicmatrix_compile_scalar_type: +.. cpp:type:: scalar_type = Scalar + + The type of the entries in the matrix. + +.. _dynamicmatrix_compile_scalar_reference: +.. cpp:type:: scalar_reference = Scalar& + + The type of references to the entries in the matrix (might not be + :code:`Scalar&`). + +.. _dynamicmatrix_compile_scalar_const_reference: +.. cpp:type:: scalar_const_reference = Scalar const& + + The type of references to the entries in the matrix (might not be + :code:`Scalar const&`). + +.. _dynamicmatrix_compile_row_type: +.. cpp:type:: Row = DynamicMatrix + + The type of a row of a :cpp:any:`DynamicMatrix` . + +.. _dynamicmatrix_compile_rowview_type: +.. cpp:type:: RowView = DynamicRowView + + The type of a row view into a :cpp:any:`DynamicMatrix`. + +.. _dynamicmatrix_compile_plus: +.. cpp:type:: Plus = PlusOp + + The template parameter ``PlusOp``. + +.. _dynamicmatrix_compile_prod: +.. cpp:type:: Prod = ProdOp + + The template parameter ``ProdOp``. + +.. _dynamicmatrix_compile_zero: +.. cpp:type:: Zero = ZeroOp + + The template parameter ``ZeroOp``. + +.. _dynamicmatrix_compile_one: +.. cpp:type:: One = OneOp + + The template parameter ``OneOp``. + +.. _dynamicmatrix_compile_semiring_type: +.. cpp:type:: semiring_type = void + + The type of the semiring over which the matrix is defined is ``void`` + because there's no semiring object, the arithmetic is defined by the + template parameters. diff --git a/docs/source-old/matrix/dynamicmatrix-run.rst b/docs/source-old/matrix/dynamicmatrix-run.rst new file mode 100644 index 000000000..12cfa4216 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-run.rst @@ -0,0 +1,182 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +DynamicMatrix (with run time arithmetic) +======================================== + +.. highlight:: cpp + +Defined in ``matrix.hpp``. + +.. cpp:class:: template \ + DynamicMatrix final + + This is a class for matrices where both the arithmetic operations in the + underlying semiring and the dimensions of the matrix can be set at run time. + + :tparam Semiring: + the type of a semiring object which defines the semiring arithmetic (see + requirements below). + + :tparam Scalar: + the type of the entries in the matrices (the type of elements in the + underlying semiring) + + .. note:: + Certain member functions only work for square matrices and some only work + for rows. + + **Semiring requirements** + + The template parameter :cpp:any:`Semiring` must have the following member + functions: + + * ``scalar_type zero()`` that returns the multiplicative zero scalar in + the semiring + * ``scalar_type one()`` that returns the multiplicative identity scalar in + the semiring + * ``scalar_type plus(scalar_type x, scalar_type y)`` + that returns the sum in the semiring of the scalars ``x`` and ``y``. + * ``scalar_type prod(scalar_type x, scalar_type y)`` + that returns the product in the semiring of the scalars ``x`` and ``y``. + + See, for example, :cpp:any:`MaxPlusTruncSemiring`. + +.. toctree:: + :hidden: + + dynamicmatrix-run/begin + dynamicmatrix-run/call_operator + dynamicmatrix-run/comparison_ops + dynamicmatrix-run/constructors + dynamicmatrix-run/coords + dynamicmatrix-run/end + dynamicmatrix-run/number_of_rows + dynamicmatrix-run/operator_plus + dynamicmatrix-run/operator_plus_equals + dynamicmatrix-run/operator_prod + dynamicmatrix-run/operator_prod_equals + dynamicmatrix-run/row + dynamicmatrix-run/rows + dynamicmatrix-run/semiring + dynamicmatrix-run/staticmemfn + dynamicmatrix-run/swap + dynamicmatrix-run/transpose + dynamicmatrix-run/types + +Member types +------------ + +.. list-table:: + :widths: 50 50 + :header-rows: 1 + + * - Member type + - Definition + * - :ref:`scalar_type` + - the type of scalars contained in the matrix (:code:`Scalar`) + * - :ref:`scalar_reference` + - the type of references to scalars contained in the matrix + * - :ref:`scalar_const_reference` + - the type of const references to scalars contained in the matrix + * - :ref:`Row` + - type of a row of the matrix + * - :ref:`RowView` + - type of a row view int the matrix + * - :ref:`semiring_type` + - the template parameter ``Semiring``. + +Member functions +---------------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`(constructor)` + - constructs the matrix + * - :ref:`number_of_rows/number_of_cols` + - the number of rows/columns in the matrix + * - :ref:`semiring` + - returns a pointer to the semiring defining the arithmetic + +Static member functions +----------------------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`make` + - constructs a matrix and checks that its entries are valid + * - :ref:`identity` + - constructs an identity matrix + +Iterators +--------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`begin/cbegin` + - returns an iterator to the beginning + * - :ref:`end/cend` + - returns an iterator to the end + * - :ref:`coords` + - returns the coordinates corresponding to an iterator + +Accessors +--------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`operator()` + - access specified element + * - :ref:`row` + - access specified row + * - :ref:`rows` + - add all rows to a container + +Arithmetic operators +-------------------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`operator+=` + - add a (matrix, scalar, or row view) to the matrix in place + * - :ref:`operator\*=` + - multiply the matrix by a matrix or scalar in place + * - :ref:`operator+` + - add a (matrix, scalar, or row view) to the matrix + * - :ref:`operator*` + - multiply the matrix by a matrix or scalar + +Comparison operators +-------------------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`operator==` + - compare matrices + * - :ref:`operator!=` + - compare matrices + * - :ref:`operator\<` + - compare matrices + * - :ref:`operator\>` + - compare matrices + +Modifiers +--------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`swap` + - swaps the contents + * - :ref:`transpose` + - transposes the matrix diff --git a/docs/source-old/matrix/dynamicmatrix-run/begin.rst b/docs/source-old/matrix/dynamicmatrix-run/begin.rst new file mode 100644 index 000000000..a101f91a9 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-run/begin.rst @@ -0,0 +1,52 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_run_begin: + +begin, cbegin +============= + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: iterator begin() + + Returns a (random access) iterator pointing at the first entry in the + matrix. + + :returns: + A value of type ``iterator``. + + :complexity: Constant + + :throws: + this function is ``noexcept`` and is guaranteed never to throw. + + :parameters: (None) + + .. warning:: + The order in which entries in the matrix are iterated over is not + specified. + + +.. cpp:function:: const_iterator cbegin() + + Returns a const (random access) iterator pointing at the first entry in the + matrix. + + :returns: + A value of type ``const_iterator``. + + :complexity: Constant + + :throws: + this function is ``noexcept`` and is guaranteed never to throw. + + :parameters: (None) + + .. warning:: + The order in which entries in the matrix are iterated over is not + specified. + diff --git a/docs/source-old/matrix/dynamicmatrix-run/call_operator.rst b/docs/source-old/matrix/dynamicmatrix-run/call_operator.rst new file mode 100644 index 000000000..8edf52f66 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-run/call_operator.rst @@ -0,0 +1,50 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_run_call_operator: + +operator() +========== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: scalar_reference operator()(size_t const r, size_t const c) + + Returns a reference to the specified entry of the matrix. + + :param r: the index of the row of the entry + :param c: the index of the column of the entry + + :returns: A value of type :cpp:any:`scalar_reference`. + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + Constant + + .. warning:: + No checks on the validity of the parameters ``r`` and ``c`` are + performed. + +.. cpp:function:: scalar_const_reference operator()(size_t const r, size_t const c) const + + Returns a const reference to the specified entry of the matrix. + + :param r: the index of the row of the entry + :param c: the index of the column of the entry + + :returns: A value of type :cpp:any:`scalar_const_reference`. + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + Constant + + .. warning:: + No checks on the validity of the parameters ``r`` and ``c`` are + performed. diff --git a/docs/source-old/matrix/dynamicmatrix-run/comparison_ops.rst b/docs/source-old/matrix/dynamicmatrix-run/comparison_ops.rst new file mode 100644 index 000000000..93d0ffdf9 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-run/comparison_ops.rst @@ -0,0 +1,114 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_run_comparison_ops: + +DynamicMatrix comparison operators +================================== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. _dynamicmatrix_run_operator_equals: + +.. cpp:function:: bool operator==(DynamicMatrix const& that) const + + Equality operator. + + :param that: matrix for comparison. + + :returns: + ``true`` if ``*this`` and ``that`` are equal and ``false`` if they are + not. + + :complexity: + At worst :math:`O(mn)` where :math:`m` is the number of rows and + :math:`n` is the number of columns of the matrix. + +.. cpp:function:: bool operator==(RowView const& that) const + + Equality operator. + + :param that: the row view for comparison. + + :returns: + ``true`` if ``*this`` and ``that`` are equal and ``false`` if they are + not. In particular, if ``*this`` has more than one row, then ``false`` + is returned. + + :complexity: + At worst :math:`O(n)` where :math:`n` is the number of columns of the + matrix. + +.. _dynamicmatrix_run_operator_not_equals: + +.. cpp:function:: template \ + bool operator!=(T const& that) const + + Inequality operator. + + :tparam T: + either :cpp:any:`DynamicMatrix` or :cpp:any:`RowView` + + :param that: the matrix or row view for comparison. + + :returns: + the negation of ``operator==(that)``. + + :complexity: + see :cpp:any:`operator==` + +.. _dynamicmatrix_run_operator_less: + +.. cpp:function:: bool operator<(DynamicMatrix const& that) const + + Less than operator. + + This operator defines a total order on the set of matrices of the same type, + the details of which is implementation specific. + + :param that: the matrix for comparison. + + :returns: + ``true`` if ``*this`` is less than ``that`` and ``false`` if it is not. + + :complexity: + At worst :math:`O(mn)` where :math:`m` is + :cpp:any:`number_of_rows` + and :math:`n` is :cpp:any:`number_of_cols` + +.. cpp:function:: bool operator<(RowView const& that) const + + Less than operator. + + :param that: the row view for comparison. + + :returns: + ``true`` if ``*this`` is less than ``that``, and ``false`` + otherwise. In particular, if ``*this`` has more than one row, then + ``false`` is returned. + + :complexity: + At worst :math:`O(n)` where :math:`n` is + :cpp:any:`number_of_cols` + +.. _dynamicmatrix_run_operator_more: + +.. cpp:function:: bool operator>(DynamicMatrix const& that) const + + Greater than operator. + + This operator defines a total order on the set of matrices of the same type, + the details of which is implementation specific. + + :param that: the matrix for comparison. + + :returns: + ``true`` if ``*this`` is less than ``that`` and ``false`` if it is not. + + :complexity: + At worst :math:`O(mn)` where :math:`m` is + :cpp:any:`number_of_rows` + and :math:`m` is :cpp:any:`number_of_cols` diff --git a/docs/source-old/matrix/dynamicmatrix-run/constructors.rst b/docs/source-old/matrix/dynamicmatrix-run/constructors.rst new file mode 100644 index 000000000..3a575ab80 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-run/constructors.rst @@ -0,0 +1,128 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_run_constructors: + +DynamicMatrix +============= + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +This page contains information about the constructors for the +:cpp:any:`DynamicMatrix` class. + +Default constructors +-------------------- + +.. cpp:function:: DynamicMatrix() = delete + + The default constructor for this variant of ``DynamicMatrix`` is deleted + because a valid pointer to a semiring object is required to define the + arithmetic at runtime. + +.. cpp:function:: DynamicMatrix(DynamicMatrix const&) = default + + Default copy constructor. + +.. cpp:function:: DynamicMatrix(DynamicMatrix&&) = default + + Default move constructor. + +.. cpp:function:: DynamicMatrix& \ + operator=(DynamicMatrix const&) = default + + Default copy assignment operator. + +.. cpp:function:: DynamicMatrix& \ + operator=(DynamicMatrix&&) = default + + Default move assignment operator. + +Matrix constructors +------------------- + +.. cpp:function:: DynamicMatrix( \ + Semiring const* semiring, size_t r, size_t c) + + Construct a matrix over the semiring ``semiring``. + + :param semiring: a pointer to const semiring object + :param r: the number of rows in the matrix being constructed + :param c: the number of columns in the matrix being constructed + + :exceptions: + This function guarantees not to throw a + :cpp:any:`LibsemigroupsException`. + + :complexity: Constant + +.. cpp:function:: DynamicMatrix( \ + Semiring const* semiring, \ + std::initializer_list> m) + + Construct a matrix over the semiring ``semiring``. + + :param semiring: a pointer to const semiring object + :param m: the values to be copied into the matrix. + + :exceptions: + This function guarantees not to throw a + :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(mn)` where :math:`m` is the template parameter :code:`R` and + :math:`n` is the template parameter :code:`C`. + +.. cpp:function:: DynamicMatrix( \ + Semiring const* semiring, \ + std::vector> const& m) + + Construct a matrix over the semiring ``semiring``. + + :param semiring: a pointer to const semiring object + :param m: the values to be copied into the matrix. + + :exceptions: + This function guarantees not to throw a + :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(mn)` where :math:`m` is the template parameter :code:`R` and + :math:`n` is the template parameter :code:`C`. + +Row constructors +---------------- + +.. cpp:function:: DynamicMatrix( \ + Semiring const* semiring, \ + std::initializer_list c) + + Construct a row over the semiring ``semiring``. + + :param semiring: a pointer to const semiring object + :param c: the values to be copied into the row. + + :exceptions: + This function guarantees not to throw a + :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(n)` where :math:`n` is the size of the row being + constructed. + +.. cpp:function:: DynamicMatrix(RowView const& rv) + + Construct a row from a row view. + + :param rv: the row view. + + :exceptions: + This function guarantees not to throw a + :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(n)` where :math:`n` is the size of the row being + constructed. diff --git a/docs/source-old/matrix/dynamicmatrix-run/coords.rst b/docs/source-old/matrix/dynamicmatrix-run/coords.rst new file mode 100644 index 000000000..fb52ae018 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-run/coords.rst @@ -0,0 +1,27 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_run_coords: + +coords +====== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: std::pair \ + coords(const_iterator it) const + + Returns a pair containing the row and columns corresponding to an iterator. + + :param it: the iterator + + :returns: + A value of type ``std::pair``. + + :complexity: Constant + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. diff --git a/docs/source-old/matrix/dynamicmatrix-run/end.rst b/docs/source-old/matrix/dynamicmatrix-run/end.rst new file mode 100644 index 000000000..edd804832 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-run/end.rst @@ -0,0 +1,52 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_run_end: + +end, cend +========= + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: iterator end() + + Returns a (random access) iterator pointing one passed the last entry of the + matrix. + + :returns: + A value of type ``iterator``. + + :complexity: Constant + + :exceptions: + this function is ``noexcept`` and is guaranteed never to throw. + + :parameters: (None) + + .. warning:: + The order in which entries in the matrix are iterated over is not + specified. + + +.. cpp:function:: const_iterator cend() + + Returns a const (random access) iterator pointing one passed the last entry + of the matrix. + + :returns: + A value of type ``const_iterator``. + + :complexity: Constant + + :exceptions: + this function is ``noexcept`` and is guaranteed never to throw. + + :parameters: (None) + + .. warning:: + The order in which entries in the matrix are iterated over is not + specified. + diff --git a/docs/source-old/matrix/dynamicmatrix-run/number_of_rows.rst b/docs/source-old/matrix/dynamicmatrix-run/number_of_rows.rst new file mode 100644 index 000000000..4e82e6bb0 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-run/number_of_rows.rst @@ -0,0 +1,42 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_run_number_of_rows: + +number_of_rows, number_of_cols +============================== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: size_t number_of_rows() + + Returns the number of rows of the matrix. + + :returns: + A value of type ``size_t``. + + :complexity: Constant + + :exceptions: + this function is ``noexcept`` and is guaranteed never to throw. + + :parameters: (None) + + +.. cpp:function:: size_t number_of_cols() + + Returns the number of columns of the matrix. + + :returns: + A value of type ``size_t``. + + :complexity: Constant + + :exceptions: + this function is ``noexcept`` and is guaranteed never to throw. + + :parameters: (None) + diff --git a/docs/source-old/matrix/dynamicmatrix-run/operator_plus.rst b/docs/source-old/matrix/dynamicmatrix-run/operator_plus.rst new file mode 100644 index 000000000..5a004ed75 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-run/operator_plus.rst @@ -0,0 +1,33 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_run_operator_plus: + +operator+ +========= + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: DynamicMatrix operator+(DynamicMatrix const& that) + + Returns the sum of ``*this`` and ``that``. + + :param that: the matrix to add to ``this``. + + :returns: + a value of type :cpp:any:`DynamicMatrix`. + + :throws: + if the implementation of the semiring plus throws, or ``std::bad_alloc`` + if memory cannot be allocated for the result. + + :complexity: + :math:`O(mn)` where :math:`m` is :cpp:any:`number_of_rows` + and :math:`m` is :cpp:any:`number_of_cols` + + .. warning:: + The matrices must be of the same dimensions, although this is not + verified by the implementation. diff --git a/docs/source-old/matrix/dynamicmatrix-run/operator_plus_equals.rst b/docs/source-old/matrix/dynamicmatrix-run/operator_plus_equals.rst new file mode 100644 index 000000000..dcc6fbb36 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-run/operator_plus_equals.rst @@ -0,0 +1,70 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_run_operator_plus_equals: + +operator+= +========== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: void operator+=(DynamicMatrix const& that) + + Redefines ``this`` to be the sum of ``*this`` and ``that``. + + :param that: the matrix to add to ``this``. + + :returns: (None) + + :throws: + if the implementation of the semiring plus throws. + + :complexity: + :math:`O(mn)` where :math:`m` is :cpp:any:`number_of_rows` + and :math:`m` is :cpp:any:`number_of_cols` + + .. warning:: + The matrices must be of the same dimensions, although this is not + verified by the implementation. + +.. cpp:function:: void operator+=(RowView const& that) + + Redefines ``this`` to be the sum of ``*this`` and ``that``. + + :param that: the matrix to add to ``this``. + + :returns: (None) + + :throws: + if the implementation of the semiring plus throws. + + :complexity: + :math:`O(mn)` where :math:`m` is :cpp:any:`number_of_rows` + and :math:`m` is :cpp:any:`number_of_cols` + + .. warning:: + This function only works if ``this`` has a single row, i.e. the template + parameter ``R`` is ``1``. + +.. cpp:function:: void operator+=(scalar const a) + + Adds a scalar to every entry of the matrix in-place. + + :param a: the scalar to add to ``this``. + + :returns: (None) + + :throws: + if the implementation of the semiring plus throws. + + :complexity: + :math:`O(mn)` where :math:`m` is :cpp:any:`number_of_rows` + and :math:`m` is :cpp:any:`number_of_cols` + + .. warning:: + This function only works if ``this`` has a single row, i.e. the template + parameter ``R`` is ``1``. + diff --git a/docs/source-old/matrix/dynamicmatrix-run/operator_prod.rst b/docs/source-old/matrix/dynamicmatrix-run/operator_prod.rst new file mode 100644 index 000000000..de567691f --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-run/operator_prod.rst @@ -0,0 +1,33 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_run_operator_prod: + +operator* +========= + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: DynamicMatrix operator*(DynamicMatrix const& that) + + Returns the product of ``*this`` and ``that``. + + :param that: the matrix to multiply by ``this``. + + :returns: + a value of type ``DynamicMatrix``. + + :throws: + if the implementation of the semiring multiplication throws, or + ``std::bad_alloc`` if memory cannot be allocated for the result. + + :complexity: + :math:`O(mn)` where :math:`m` is :cpp:any:`DynamicMatrix::number_of_rows` + and :math:`m` is :cpp:any:`DynamicMatrix::number_of_cols` + + .. warning:: + The matrices must be of the same dimensions, although this is not + verified by the implementation. diff --git a/docs/source-old/matrix/dynamicmatrix-run/operator_prod_equals.rst b/docs/source-old/matrix/dynamicmatrix-run/operator_prod_equals.rst new file mode 100644 index 000000000..b3e932ab6 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-run/operator_prod_equals.rst @@ -0,0 +1,53 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_run_operator_prod_equals: + +operator*= +========== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: void operator*=(scalar_type const a) + + Multiplies every entry of the matrix by a scalar in-place. + + :param a: the scalar to multiply every entry of ``this``. + + :returns: (None) + + :throws: + if the implementation of the semiring multiplication throws. + + :complexity: + :math:`O(mn)` where :math:`m` is :cpp:any:`DynamicMatrix::number_of_rows` + and :math:`m` is :cpp:any:`DynamicMatrix::number_of_cols` + +.. cpp:function:: void product_inplace(DynamicMatrix const& A, DynamicMatrix const& B) + + Multiplies ``A`` and ``B`` and stores the result in ``this``. + + Redefines ``this`` to be the product of ``A`` and ``B``. This is in-place + multiplication to avoid allocation of memory for products which do not need + to be stored for future use. + + :param A: the first matrix to multiply + :param B: the second matrix to multiply + + :returns: (None) + + :throws: + Throws if the implementation of the semiring plus or product throws + or ``std::bad_alloc``. + + :complexity: + :math:`O(n ^ 3)` where :math:`n` is :cpp:any:`DynamicMatrix::number_of_rows` + or :cpp:any:`DynamicMatrix::number_of_cols` + + .. warning:: + + This function only applies to matrices with the same number of rows + and columns. diff --git a/docs/source-old/matrix/dynamicmatrix-run/row.rst b/docs/source-old/matrix/dynamicmatrix-run/row.rst new file mode 100644 index 000000000..38fe75464 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-run/row.rst @@ -0,0 +1,25 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_run_row: + +row +=== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: RowView row(size_t i) const + + Returns a row view into the specified row. + + :param i: the row + + :returns: A value of type :cpp:any:`RowView`. + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: Constant diff --git a/docs/source-old/matrix/dynamicmatrix-run/rows.rst b/docs/source-old/matrix/dynamicmatrix-run/rows.rst new file mode 100644 index 000000000..d5b5c87a8 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-run/rows.rst @@ -0,0 +1,26 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_run_rows: + +rows +==== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: template void rows(T& x) const + + Add row views for every row in the matrix to the container ``T``. + + :param x: a container + + :returns: (None) + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(m)` where :math:`m` is the number of rows in the matrix ``x``. diff --git a/docs/source-old/matrix/dynamicmatrix-run/semiring.rst b/docs/source-old/matrix/dynamicmatrix-run/semiring.rst new file mode 100644 index 000000000..cc5e2aa4e --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-run/semiring.rst @@ -0,0 +1,25 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_run_semiring: + +semiring +======== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: Semiring const* semiring() const noexcept + + Returns a const pointer to the underlying semiring (if any). + + :parameters: (None) + + :returns: A value of type ``Semiring const*``. + + :exceptions: + This function is ``noexcept`` and guarantees not to throw. + + :complexity: Constant diff --git a/docs/source-old/matrix/dynamicmatrix-run/staticmemfn.rst b/docs/source-old/matrix/dynamicmatrix-run/staticmemfn.rst new file mode 100644 index 000000000..f79963d05 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-run/staticmemfn.rst @@ -0,0 +1,69 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +DynamicMatrix static member functions +===================================== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. _dynamicmatrix_run_identity: +.. cpp:function:: static DynamicMatrix identity(size_t n) + + Construct the :math:`n \times n` identity matrix. + + :param n: the dimension + + :returns: The :math:`n \times n` identity matrix. + + :exceptions: + This function guarantees not to throw a + :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(n ^ 2)`. + +.. _dynamicmatrix_run_make: +.. cpp:function:: static DynamicMatrix \ + make( \ + Semiring const* semiring, \ + std::initializer_list> il) + + Validates the arguments, constructs a matrix and validates it. + + :param semiring: a pointer to const semiring object + :param il: the values to be copied into the matrix. + + :returns: the constructed matrix if valid. + + :throws: + :cpp:any:`LibsemigroupsException` if ``il`` does not represent a + matrix of the correct dimensions. + + :throws: + :cpp:any:`LibsemigroupsException` if the constructed matrix + contains values that do not belong to the underlying semiring. + + :complexity: + :math:`O(mn)` where :math:`m` is the number of rows and + :math:`n` is the number of columns of the matrix. + +.. cpp:function:: static DynamicMatrix make( \ + Semiring const* semiring, \ + std::initializer_list il) + + Constructs a row and validates it. + + :param semiring: a pointer to const semiring object + :param il: the values to be copied into the row. + + :returns: the constructed row if valid. + + :throws: + :cpp:any:`LibsemigroupsException` if the constructed row contains + values that do not belong to the underlying semiring. + + :complexity: + :math:`O(n)` where :math:`n` is the number of columns of the matrix. diff --git a/docs/source-old/matrix/dynamicmatrix-run/swap.rst b/docs/source-old/matrix/dynamicmatrix-run/swap.rst new file mode 100644 index 000000000..22d6c116c --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-run/swap.rst @@ -0,0 +1,25 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_run_swap: + +swap +==== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: void swap(DynamicMatrix& that) noexcept + + Swaps the contents of ``this`` with the contents of ``that``. + + :param that: the matrix to swap contents with + + :returns: (None) + + :complexity: Constant + + :exceptions: + this function is ``noexcept`` and is guaranteed never to throw. diff --git a/docs/source-old/matrix/dynamicmatrix-run/transpose.rst b/docs/source-old/matrix/dynamicmatrix-run/transpose.rst new file mode 100644 index 000000000..19f8d0585 --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-run/transpose.rst @@ -0,0 +1,30 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicmatrix_run_transpose: + +transpose +========= + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +.. cpp:function:: void transpose() noexcept + + Transposes the matrix in-place. + + :parameters: (None) + + :returns: (None) + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(n ^ 2)` where :math:`n` is the number of rows and + the number of columns in the matrix. + + .. warning:: + This only works for square matrices. diff --git a/docs/source-old/matrix/dynamicmatrix-run/types.rst b/docs/source-old/matrix/dynamicmatrix-run/types.rst new file mode 100644 index 000000000..257a7895b --- /dev/null +++ b/docs/source-old/matrix/dynamicmatrix-run/types.rst @@ -0,0 +1,46 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +DynamicMatrix member types +========================== + +.. cpp:namespace:: libsemigroups::DynamicMatrix + +This page contains information about the member types of the +:cpp:any:`DynamicMatrix` class. + +.. _dynamicmatrix_run_scalar_type: +.. cpp:type:: scalar_type = Scalar + + The type of the entries in the matrix. + +.. _dynamicmatrix_run_scalar_reference: +.. cpp:type:: scalar_reference = Scalar& + + The type of references to the entries in the matrix (might not be + :code:`Scalar&`). + +.. _dynamicmatrix_run_scalar_const_reference: +.. cpp:type:: scalar_const_reference = Scalar const& + + The type of references to the entries in the matrix (might not be + :code:`Scalar const&`). + +.. _dynamicmatrix_run_row_type: +.. cpp:type:: Row = DynamicMatrix + + The type of a row of a :cpp:any:`DynamicMatrix`. + +.. _dynamicmatrix_run_rowview_type: +.. cpp:type:: RowView = DynamicRowView + + The type of a row view into a :cpp:any:`DynamicMatrix`. + +.. _dynamicmatrix_run_semiring_type: +.. cpp:type:: semiring_type = Semiring + + The type of the semiring over which the matrix is defined, coincides with + the template parameter ``Semiring``. diff --git a/docs/source-old/matrix/dynamicrowview.rst b/docs/source-old/matrix/dynamicrowview.rst new file mode 100644 index 000000000..a2c451b66 --- /dev/null +++ b/docs/source-old/matrix/dynamicrowview.rst @@ -0,0 +1,198 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +DynamicRowView +============== + +.. highlight:: cpp + +Defined in ``matrix.hpp``. + +This is a class for views into a row of a matrix over a semirings. An +instance of this class provides access to the elements in a row of a +matrix and is cheap to create and copy. Addition, scalar multiplication, +and other usual vector operations are defined for row views. + +There are two types of :cpp:any:`DynamicMatrix` and two types of +:cpp:any:`DynamicRowView` also: + +1. those where the arithmetic is defined at compile time; +2. those where the arithmetic is defined at run time. + +From the perspective of using these DynamicRowViews there is no +difference in the interface; the distinction is only important if you +want to extend the functionality of ``libsemigroups`` to further +semirings. + +.. warning:: + + If the underlying matrix is destroyed, then any row views for that matrix + are invalidated. + +.. cpp:class:: template \ + DynamicRowView final + :tparam-line-spec: + + This class is the type of row views into a :cpp:any:`DynamicMatrix` with the + same template parameters; see the documentation for :cpp:any:`DynamicMatrix` + for further details. + + .. warning:: + If the underlying matrix is destroyed, then any row views for that matrix + are invalidated. + + :tparam PlusOp: + a stateless type with a call operator of signature :code:`scalar_type + operator()(scalar_type, scalar_type)` implementing the addition of the + semiring + + :tparam ProdOp: + a stateless type with a call operator of signature :code:`scalar_type + operator()(scalar_type, scalar_type)` implementing the multiplication of + the semiring + + :tparam ZeroOp: + a stateless type with a call operator of signature :code:`scalar_type + operator()()` returning the zero of the semiring (the additive identity + element) + + :tparam OneOp: + a stateless type with a call operator of signature :code:`scalar_type + operator()()` returning the one of the semiring (the multiplicative + identity element) + + :tparam Scalar: + the type of the entries in the matrices (the type of elements in the + underlying semiring) + + +.. cpp:class:: template \ + DynamicRowView final + + This class is the type of row views into a :cpp:any:`DynamicMatrix` with the + same template parameters; see the documentation for :cpp:any:`DynamicMatrix` + for further details. + + .. warning:: + If the underlying matrix is destroyed, then any row views for that matrix + are invalidated. + + :tparam Semiring: + the type of a semiring object which defines the semiring arithmetic (see + requirements below). + + :tparam Scalar: + the type of the entries in the matrices (the type of elements in the + underlying semiring) + +.. toctree:: + :includehidden: + :hidden: + :maxdepth: 1 + + dynamicrowview/begin + dynamicrowview/call_operator + dynamicrowview/comparison_ops + dynamicrowview/constructors + dynamicrowview/end + dynamicrowview/operator_plus_equals + dynamicrowview/operator_plus + dynamicrowview/operator_prod_equals + dynamicrowview/operator_prod + dynamicrowview/size + dynamicrowview/subscript_operator + dynamicrowview/types + +Member types +------------ + +.. list-table:: + :widths: 50 50 + :header-rows: 1 + + * - Member type + - Definition + * - :ref:`scalar_type` + - the type of scalars contained in the row (:code:`Scalar`) + * - :ref:`scalar_reference` + - the type of references to scalars contained in the row + * - :ref:`scalar_const_reference` + - the type of const references to scalars contained in the row + * - :ref:`matrix_type` + - type of the underlying matrix of the row view + * - :ref:`Row` + - type of a row for the row view + * - :ref:`iterator` + - type of iterators to entries in the underlying row + * - :ref:`const_iterator` + - type of iterators to entries in the underlying row + +Member functions +---------------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`(constructor)` + - constructs the matrix + * - :ref:`size` + - the length of the row (the template parameter :cpp:any:`C`) + +Iterators +--------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`begin/cbegin` + - returns an iterator to the beginning + * - :ref:`end/cend` + - returns an iterator to the end + +Accessors +--------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`operator()` + - access specified element + * - :ref:`operator[]` + - access specified element + +Arithmetic operators +-------------------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`operator+=` + - add a (matrix, scalar, or row view) to the matrix in place + * - :ref:`operator\*=` + - multiply the matrix by a matrix or scalar in place + * - :ref:`operator+` + - add a (matrix, scalar, or row view) to the matrix + * - :ref:`operator*` + - multiply the matrix by a matrix or scalar + +Comparison operators +-------------------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`operator==` + - compare matrices + * - :ref:`operator!=` + - compare matrices + * - :ref:`operator\<` + - compare matrices + * - :ref:`operator\>` + - compare matrices diff --git a/docs/source-old/matrix/dynamicrowview/begin.rst b/docs/source-old/matrix/dynamicrowview/begin.rst new file mode 100644 index 000000000..49d7a1a8e --- /dev/null +++ b/docs/source-old/matrix/dynamicrowview/begin.rst @@ -0,0 +1,39 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicrowview_begin: + +begin, cbegin +============= + +.. cpp:function:: iterator begin() + + Returns a (random access) iterator pointing at the first entry in the + row. + + :parameters: (None) + + :returns: A value of type :cpp:any:`iterator`. + + :complexity: Constant + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + +.. cpp:function:: const_iterator cbegin() + + Returns a const (random access) iterator pointing at the first entry in the + row. + + :parameters: (None) + + :returns: A value of type :cpp:any:`const_iterator`. + + :complexity: Constant + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. diff --git a/docs/source-old/matrix/dynamicrowview/call_operator.rst b/docs/source-old/matrix/dynamicrowview/call_operator.rst new file mode 100644 index 000000000..3a91eca03 --- /dev/null +++ b/docs/source-old/matrix/dynamicrowview/call_operator.rst @@ -0,0 +1,44 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicrowview_call_operator: + +operator() +========== + +.. cpp:function:: scalar_reference operator()(size_t const i) + + Returns a reference to the specified entry of the matrix. + + :param i: the index of the entry + + :returns: A value of type :cpp:any:`scalar_reference`. + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + Constant + + .. warning:: + No checks on the validity of the parameter ``i`` is performed. + +.. cpp:function:: scalar_const_reference operator()(size_t const i) const + + Returns a const reference to the specified entry of the matrix. + + :param i: the index of the entry + + :returns: A value of type :cpp:any:`scalar_const_reference`. + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + Constant + + .. warning:: + No checks on the validity of the parameter ``i`` is performed. diff --git a/docs/source-old/matrix/dynamicrowview/comparison_ops.rst b/docs/source-old/matrix/dynamicrowview/comparison_ops.rst new file mode 100644 index 000000000..ae9e8a984 --- /dev/null +++ b/docs/source-old/matrix/dynamicrowview/comparison_ops.rst @@ -0,0 +1,82 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicrowview_comparison_ops: + +Comparison operators +==================== + +.. _dynamicrowview_operator_equals: +.. cpp:function:: template \ + bool operator==(U const& that) const + + Equality operator. + + :tparam U: either :cpp:any:`Row` or :cpp:any:`RowView` + + :param that: :cpp:any:`Row` or :cpp:any:`RowView` object for comparison. + + :returns: + Returns ``true`` if the first :cpp:any:`size()` entries of ``that`` equal + the entries of ``this``, and ``false`` if not. + + :complexity: + At worst :math:`O(n)` where :math:`n` is the size of the row view. + + +.. _dynamicrowview_operator_not_equals: +.. cpp:function:: template \ + bool operator!=(U const& that) const + + Inequality operator. + + :tparam U: either :cpp:any:`Row` or :cpp:any:`RowView` + + :param that: :cpp:any:`Row` or :cpp:any:`RowView` object for comparison. + + :returns: + Returns ``true`` if the first :cpp:any:`size()` entries of ``that`` do not + equal the entries of ``this``, and ``false`` otherwise. + + :complexity: + At worst :math:`O(n)` where :math:`n` is the size of the row view. + + +.. _dynamicrowview_operator_less: +.. cpp:function:: template \ + bool operator<(U const& that) const + + Lexicographical comparison of rows. + + :tparam U: either :cpp:any:`Row` or :cpp:any:`RowView` + + :param that: :cpp:any:`Row` or :cpp:any:`RowView` object for comparison. + + :returns: + Returns ``true`` if ``this`` is lex less than that ``that`` and ``false`` + otherwise. + + :complexity: + At worst :math:`O(n)` where :math:`n` is the size of the row view. + + +.. _dynamicrowview_operator_more: +.. cpp:function:: template \ + bool operator>(U const& that) const + + Lexicographical comparison of rows. + + :tparam U: either :cpp:any:`Row` or :cpp:any:`RowView` + + :param that: :cpp:any:`Row` or :cpp:any:`RowView` object for comparison. + + :returns: + Returns ``true`` if ``this`` is lex greater than that ``that`` and + ``false`` otherwise. + + :complexity: + At worst :math:`O(n)` where :math:`n` is the size of the row view. + diff --git a/docs/source-old/matrix/dynamicrowview/constructors.rst b/docs/source-old/matrix/dynamicrowview/constructors.rst new file mode 100644 index 000000000..c6c75b7e8 --- /dev/null +++ b/docs/source-old/matrix/dynamicrowview/constructors.rst @@ -0,0 +1,58 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicrowview_constructors: + +Constructors +============ + +This page contains information about the constructors for the +:cpp:any:`DynamicRowView` class. + +Note that unless copying an existing ``DynamicRowView`` it's most likely that +you will obtain a ``DynamicRowView`` from :cpp:any:`DynamicMatrix::row` or +:cpp:any:`DynamicMatrix::rows`. + + +.. cpp:namespace:: libsemigroups + +Default constructors +-------------------- + +.. cpp:function:: DynamicRowView() = default + + Default constructor. + +.. cpp:function:: DynamicRowView(DynamicRowView const&) = default + + Default copy constructor. + +.. cpp:function:: DynamicRowView(DynamicRowView&&) = default + + Default move constructor. + +.. cpp:function:: DynamicRowView& operator=(DynamicRowView const&) = default + + Default copy assignment operator. + +.. cpp:function:: DynamicRowView& operator=(DynamicRowView&&) = default + + Default move assignment operator. + +Constructor from Row +-------------------- + +.. cpp:function:: explicit DynamicRowView(Row const& r) + + Construct a row view from a Row. + + :param r: the row. + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + Constant. diff --git a/docs/source-old/matrix/dynamicrowview/end.rst b/docs/source-old/matrix/dynamicrowview/end.rst new file mode 100644 index 000000000..2b98c8517 --- /dev/null +++ b/docs/source-old/matrix/dynamicrowview/end.rst @@ -0,0 +1,40 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicrowview_end: + +end, cend +========= + +.. cpp:function:: iterator end() + + Returns a (random access) iterator pointing one passed the last entry of the + row. + + :parameters: (None) + + :returns: + A value of type ``iterator``. + + :complexity: Constant + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + +.. cpp:function:: const_iterator cend() + + Returns a const (random access) iterator pointing one passed the last entry + of the row. + + :parameters: (None) + + :returns: + A value of type ``const_iterator``. + + :complexity: Constant + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. diff --git a/docs/source-old/matrix/dynamicrowview/operator_plus.rst b/docs/source-old/matrix/dynamicrowview/operator_plus.rst new file mode 100644 index 000000000..a4c52fd99 --- /dev/null +++ b/docs/source-old/matrix/dynamicrowview/operator_plus.rst @@ -0,0 +1,29 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicrowview_operator_plus: + +operator+ +========= + +.. cpp:function:: Row operator+(StaticRowView const& that) + + Sums a row view with another row view and returns a newly allocated Row. + + :param that: the row view to add to ``this``. + + :returns: A value of type :cpp:any:`Row` + + :throws: + If the implementation of the semiring addition throws or + ``std::bad_alloc`` is thrown. + + :complexity: + :math:`O(m)` where :math:`m` is :cpp:any:`size` + + .. warning:: + The two row views must be of the same size, although this is not + verified by the implementation. diff --git a/docs/source-old/matrix/dynamicrowview/operator_plus_equals.rst b/docs/source-old/matrix/dynamicrowview/operator_plus_equals.rst new file mode 100644 index 000000000..e4496a306 --- /dev/null +++ b/docs/source-old/matrix/dynamicrowview/operator_plus_equals.rst @@ -0,0 +1,43 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicrowview_operator_plus_equals: + +operator+= +========== + +.. cpp:function:: void operator+=(DynamicRowView const& that) + + Sums a row view with another row view in-place. + + :param that: the row view to add to ``this``. + + :returns: (None) + + :throws: + If the implementation of the semiring addition throws. + + :complexity: + :math:`O(m)` where :math:`m` is :cpp:any:`size` + + .. warning:: + The two row views must be of the same size, although this is not + verified by the implementation. + + +.. cpp:function:: void operator+=(scalar_type const a) + + Adds a scalar to every entry of the row in-place. + + :param a: the scalar to add to ``this``. + + :returns: (None) + + :complexity: + :math:`O(m)` where :math:`m` is :cpp:any:`size` + + :throws: + If the implementation of the semiring addition throws. diff --git a/docs/source-old/matrix/dynamicrowview/operator_prod.rst b/docs/source-old/matrix/dynamicrowview/operator_prod.rst new file mode 100644 index 000000000..c0b43e4ef --- /dev/null +++ b/docs/source-old/matrix/dynamicrowview/operator_prod.rst @@ -0,0 +1,27 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicrowview_operator_prod: + +operator* +========= + +.. cpp:function:: Row operator*(scalar_type const a) const + + Multiplies every entry of the row by a scalar. + + :param a: the scalar. + + :returns: + A value of type Row containing the original row multiplied by the scalar + ``a``. + + :complexity: + :math:`O(m)` where :math:`m` is :cpp:any:`size` + + :throws: + If the implementation of the semiring addition throws or + ``std::bad_alloc`` is thrown. diff --git a/docs/source-old/matrix/dynamicrowview/operator_prod_equals.rst b/docs/source-old/matrix/dynamicrowview/operator_prod_equals.rst new file mode 100644 index 000000000..6eaabbad2 --- /dev/null +++ b/docs/source-old/matrix/dynamicrowview/operator_prod_equals.rst @@ -0,0 +1,24 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicrowview_operator_prod_equals: + +operator*= +========== + +.. cpp:function:: void operator*=(scalar_type const a) + + Multiplies every entry of the row by a scalar in-place. + + :param a: the scalar to add to every entry of ``this``. + + :returns: (None) + + :throws: + If the implementation of the semiring multiplication throws. + + :complexity: + :math:`O(m)` where :math:`m` is :cpp:any:`size` diff --git a/docs/source-old/matrix/dynamicrowview/size.rst b/docs/source-old/matrix/dynamicrowview/size.rst new file mode 100644 index 000000000..ada1ad1fe --- /dev/null +++ b/docs/source-old/matrix/dynamicrowview/size.rst @@ -0,0 +1,23 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicrowview_size: + +size +==== + +.. cpp:function:: size_t size() const noexcept + + Returns the size of the underlying row. + + :parameters: (None) + + :returns: A value of type ``size_t``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant diff --git a/docs/source-old/matrix/dynamicrowview/subscript_operator.rst b/docs/source-old/matrix/dynamicrowview/subscript_operator.rst new file mode 100644 index 000000000..564b33dff --- /dev/null +++ b/docs/source-old/matrix/dynamicrowview/subscript_operator.rst @@ -0,0 +1,44 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _dynamicrowview_subscript_operator: + +operator[] +========== + +.. cpp:function:: scalar_reference operator[](size_t const i) + + Returns a reference to the specified entry of the matrix. + + :param i: the index of the entry + + :returns: A value of type :cpp:any:`scalar_reference`. + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + Constant + + .. warning:: + No checks on the validity of the parameter ``i`` is performed. + +.. cpp:function:: scalar_const_reference operator[](size_t const i) const + + Returns a const reference to the specified entry of the matrix. + + :param i: the index of the entry + + :returns: A value of type :cpp:any:`scalar_const_reference`. + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + Constant + + .. warning:: + No checks on the validity of the parameter ``i`` is performed. diff --git a/docs/source-old/matrix/dynamicrowview/types.rst b/docs/source-old/matrix/dynamicrowview/types.rst new file mode 100644 index 000000000..83108877f --- /dev/null +++ b/docs/source-old/matrix/dynamicrowview/types.rst @@ -0,0 +1,48 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +DynamicRowView member types +=========================== + +This page contains information about the member types of the +:cpp:any:`DynamicRowView` class. + +.. _dynamicrowview_scalar_type: +.. cpp:type:: scalar_type = Scalar + + The type of the entries in the matrix. + +.. _dynamicrowview_scalar_reference: +.. cpp:type:: scalar_reference = Scalar& + + The type of references to the entries in the matrix (might not be + :code:`Scalar&`). + +.. _dynamicrowview_scalar_const_reference: +.. cpp:type:: scalar_const_reference = Scalar const& + + The type of references to the entries in the matrix (might not be + :code:`Scalar const&`). + +.. _dynamicrowview_mat_type: +.. cpp:type:: matrix_type = DynamicMatrix + + The type of the matrix underlying a :cpp:any:`DynamicRowView`. + +.. _dynamicrowview_row_type: +.. cpp:type:: Row = Mat::Row + + The type of a row of a DynamicRowView. + +.. _dynamicrowview_iterator: +.. cpp:type:: iterator = Mat::iterator + + The type of iterators into the row view. + +.. _dynamicrowview_const_iterator: +.. cpp:type:: const_iterator = Mat::const_iterator + + The type of const iterators into the row view. diff --git a/docs/source-old/matrix/helpers/bitset_row_basis.rst b/docs/source-old/matrix/helpers/bitset_row_basis.rst new file mode 100644 index 000000000..019d834c2 --- /dev/null +++ b/docs/source-old/matrix/helpers/bitset_row_basis.rst @@ -0,0 +1,128 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +bitset_row_basis +================ + +.. cpp:namespace:: libsemigroups::matrix_helpers + +This page contains details of the function templates for finding the row basis +of a boolean matrix represented as bitsets that belong to the namespace +``matrix_helper``. + +.. cpp:function:: template \ + void bitset_row_basis(Container&& rows, std::decay_t& result) + + Appends a basis for the space spanned by the bitsets in ``rows`` to the + container ``result``. + + :tparam Mat: + a type such that :cpp:any:`IsBMat\` is ``true``. + + :tparam Container: + a container type (such as ``detail::StaticVector1``, for example). The + ``Container::value_type`` must be ``BitSet`` or ``std::bitset`` + for some ``M``. + + :param rows: container of spanning rows represented by bitsets. + + :param result: container for the resulting rowbasis + + :returns: (None) + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(r ^ 2 c)` where :math:`r` is the size of ``rows`` and + :math:`c` is the size of each bitset in ``rows``. + +Helper functions +---------------- + +.. cpp:function:: template \ + std::decay_t bitset_row_basis(Container&& rows) + + Returns a basis for the space spanned by the bitsets in ``rows``. + + :tparam Mat: + a type such that :cpp:any:`IsBMat\` is ``true``. + + :tparam Container: + a container type (such as ``detail::StaticVector1``, for example). The + ``Container::value_type`` must be ``BitSet`` or ``std::bitset`` + for some ``M``. + + :param rows: container of spanning rows represented by bitsets. + + :returns: + A container of type ``std::decay_t`` containing the row basis + consisting of bitsets. + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(r ^ 2 c)` where :math:`r` is the size of ``rows`` and + :math:`c` is the size of each bitset in ``rows``. + +.. cpp:function:: template ::value> \ + detail::StaticVector1, M> bitset_row_basis(Mat const& x) + + Returns a basis for the space spanned by the rows of the boolean matrix + ``x``. + + :tparam Mat: + a type such that :cpp:any:`IsBMat\` is ``true``. + + :tparam M: + an upper bound for the dimensions of the returned container. If + :cpp:any:`IsStaticMatrix\` is ``true``, then ``M`` is the number of + rows (or columns) in the square matrix ``x``. Otherwise, if + :cpp:any:`IsDynamicMatrix\` is ``true``, then ``M`` is + :cpp:any:`BitSet<1>::max_size()`. + + :param x: the boolean matrix. + + :returns: + A container of type ``detail::StaticVector1, M>>`` containing + the row basis of ``x`` consisting of bitsets. + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(r ^ 2 c)` where :math:`r` is the number of rows in ``x`` and + :math:`c` is the number of columns in ``x``. + + +.. cpp:function:: template \ + void bitset_row_basis(Mat const& x, Container& result) + + Appends a basis for the rowspace of the boolean matrix ``x`` to the + container ``result``. + + :tparam Mat: + a type such that :cpp:any:`IsBMat\` is ``true``. + + :tparam Container: + a container type (such as ``detail::StaticVector1``, for example). The + ``Container::value_type`` must be ``BitSet`` or ``std::bitset`` + for some ``M``. + + :param x: the boolean matrix. + + :param result: container for the resulting rowbasis + + :returns: (None) + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(r ^ 2 c)` where :math:`r` is the number of rows in ``x`` and + :math:`c` is the number of columns in ``x``. diff --git a/docs/source-old/matrix/helpers/bitset_rows.rst b/docs/source-old/matrix/helpers/bitset_rows.rst new file mode 100644 index 000000000..9c33f7a58 --- /dev/null +++ b/docs/source-old/matrix/helpers/bitset_rows.rst @@ -0,0 +1,149 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +bitset_rows +=========== + +.. cpp:namespace:: libsemigroups::matrix_helpers + +This page contains details of the function templates for finding the rows of a +boolean matrix as bitsets that belong to the namespace ``matrix_helper``. + +The main function is: + +:cpp:any:`template \ void bitset_rows(Container&&, detail::StaticVector1\, R>&)` + +which converts the rows stored in the first argument to bitsets and appends +them to the second argument. + +There are several helper functions which allow the main function to be called +without specifying the second argument or where a matrix is given instead of a +container of rowviews. + +The main function +----------------- + +.. cpp:function:: template \ + void bitset_rows(Container&& views, \ + detail::StaticVector1, R>& result) + + Converts the rows represented by the items in ``views`` to bit sets. + + :tparam Mat: + the type of matrix. This must be a type so that :cpp:any:`IsBMat\` is + ``true``. + :tparam R: + an upper bound for the number of rows in ``views``. This value must be at most + :cpp:any:`BitSet<1>::max_size()`. + :tparam C: + an upper bound for the number of columns in each row represented in + ``views``. This value must be at most :cpp:any:`BitSet<1>::max_size()`. + :tparam Container: + the type of the container ``views``, should be ``std::vector`` or + ``detail::StaticVector1``. + + :param views: a container of ``Mat::RowView`` or ``std::vector``. + :param result: a static vector of bitsets to contain the resulting bit sets. + + :returns: (None). + + :exceptions: + Throws if ``Container::push_back`` throws, or the :cpp:any:`BitSet` + constructor throws. + + :complexity: + :math:`O(mn)` where :math:`m` is the number of rows in ``views`` and + and :math:`n` is the number of columns in any vector in ``views``. + +Helpers +------- + +.. cpp:function:: template \ + auto bitset_rows(Container&& views) + + Returns a :cpp:any:`detail::StaticVector1\, R>` containing the + rows in ``views`` converted to :cpp:any:`BitSet\` s. + + :tparam Mat: + the type of matrix. This must be a type so that :cpp:any:`IsBMat\` is + ``true``. + :tparam R: + an upper bound for the number of rows in ``views``. This value must be at most + :cpp:any:`BitSet<1>::max_size()`. + :tparam C: + an upper bound for the number of columns in each row represented in + ``views``. This value must be at most :cpp:any:`BitSet<1>::max_size()`. + :tparam Container: + the type of the container ``views``, should be ``std::vector`` or + ``detail::StaticVector1``. + + :param views: a container of ``Mat::RowView`` or ``std::vector``. + + :returns: A value of type :cpp:any:`detail::StaticVector1\, R>`. + + :exceptions: + Throws if + :cpp:any:`void bitset_rows(Container&&, detail::StaticVector1\, R>&)` + throws, or ``std::bad_alloc`` is thrown by the + :cpp:any:`detail::StaticVector1\, R>` constructor throws. + + :complexity: + :math:`O(mn)` where :math:`m` is the number of rows in ``views`` and + and :math:`n` is the number of columns in any vector in ``views``. + + +.. cpp:function:: template \ + void bitset_rows(Mat const& x, \ + detail::StaticVector1, R>& result) + + Computes the rows of the matrix ``x`` as bitsets and appends them to + ``result``. + + :tparam Mat: + the type of matrix. This must be a type so that :cpp:any:`IsBMat\` is + ``true``. + :tparam R: + an upper bound for the number of rows in ``views``. This value must be at most + :cpp:any:`BitSet<1>::max_size()`. + :tparam C: + an upper bound for the number of columns in each row represented in + ``views``. This value must be at most :cpp:any:`BitSet<1>::max_size()`. + + :param x: the boolean matrix. + :param result: the container to append the rows of ``x`` to. + + :returns: (None). + + :exceptions: + Throws if + :cpp:any:`void bitset_rows(Container&&, detail::StaticVector1\, R>&)` + throws. + + :complexity: + :math:`O(mn)` where :math:`m` is the number of rows in ``x`` and + and :math:`n` is the number of columns in ``x``. + +.. cpp:function:: template \ + auto bitset_rows(Mat const& x) + + Computes the rows of the matrix ``x`` as bitsets. + + :tparam Mat: + the type of matrix. This must be a type so that :cpp:any:`IsBMat\` is + ``true``. + + :param x: the boolean matrix. + :returns: A value of type :cpp:any:`detail::StaticVector1\, R>`. + + :exceptions: + Throws if + :cpp:any:`void bitset_rows(Container&&, detail::StaticVector1\, R>&)` + throws, or ``std::bad_alloc`` is thrown by the + :cpp:any:`detail::StaticVector1\, R>` constructor throws. + + :complexity: + :math:`O(mn)` where :math:`m` is the number of rows in ``x`` and + and :math:`n` is the number of columns in ``x``. diff --git a/docs/source-old/matrix/helpers/pow.rst b/docs/source-old/matrix/helpers/pow.rst new file mode 100644 index 000000000..6c8fde143 --- /dev/null +++ b/docs/source-old/matrix/helpers/pow.rst @@ -0,0 +1,43 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +pow +=== + +.. cpp:namespace:: libsemigroups::matrix_helpers + +.. cpp:function:: template \ + Mat pow(Mat const& x, typename Mat::scalar_type e) + + Returns the matrix ``x`` to the power ``e``. This function template is + defined in namespace :cpp:any:`matrix_helpers`. + + :param x: the matrix (must have equal number of rows and columns) + :param e: the exponent (must be :math:`\geq 0`) + + :returns: + A value of type ``Mat``. If ``e`` is ``0``, then the identity matrix is + returned; if ``e`` is ``1``, then a copy of the parameter ``x`` is + returned. + + :throws: + :cpp:any:`LibsemigroupsException` if ``typename Mat::scalar_type`` is a + signed type and the parameter ``e`` is less than ``0``. + + This function does not to throw any other + :cpp:any:`LibsemigroupsException` s. It might throw ``std::bad_alloc`` if + the algorithm cannot allocate enough memory. + + :complexity: + :math:`O(m\log_2(e))` where :math:`m` is the dimension of the matrix ``x`` + and :math:`e` is the parameter ``e``. + + **Example** + + .. code-block:: + + auto x == ProjMaxPlusMat<>::make({{-2, 2, 0}, {-1, 0, 0}, {1, -3, 1}})); + matrix_helpers::pow(x, 100); // returns {{-1, 0, -1}, {-2, -1, -2}, {-1, 0, -1}} diff --git a/docs/source-old/matrix/helpers/row_basis.rst b/docs/source-old/matrix/helpers/row_basis.rst new file mode 100644 index 000000000..bcf491523 --- /dev/null +++ b/docs/source-old/matrix/helpers/row_basis.rst @@ -0,0 +1,117 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +row_basis +========= + +.. cpp:namespace:: libsemigroups::matrix_helpers + +This page contains details of the function templates for finding the row basis +of certain types of matrix in the namespace ``matrix_helper``. + +.. cpp:function:: template >> \ + void row_basis(Mat const& x, Container& result) + + Appends a basis (consisting of row views) for the row space of the matrix + ``x`` to the container ``result``. + + :tparam Mat: + a type such that the value of :cpp:any:`IsMatrix` is ``true``. + + :tparam Container: + a container type (such as ``std::vector``, for example). + + :param x: the matrix. + + :param result: the container to append the basis to the row space to. + + :returns: (None) + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(r ^ 2 c)` where :math:`r` is the number of rows in ``x`` and + :math:`c` is the number of columns in ``x``. + +.. cpp:function:: template >> \ + std::vector row_basis(Mat const& x) + + Returns a vector (consisting of row views) that is a basis for the row + space of the non-static matrix ``x``. + + :tparam Mat: + a type such that the value of :cpp:any:`IsDynamicMatrix` is ``true``. + + :param x: the matrix. + + :returns: + A ``std::vector`` of :cpp:any:`Mat::RowView`. + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(r ^ 2 c)` where :math:`r` is the number of rows in ``x`` and + :math:`c` is the number of columns in ``x``. + + +.. cpp:function:: template >> \ + detail::StaticVector1 \ + row_basis(Mat const& x) + + Returns a static vector (consisting of row views) that is a basis for the row + space of the static matrix ``x``. + + :tparam Mat: + a type such that the value of :cpp:any:`IsStaticMatrix` is ``true``. + + :param x: the matrix. + + :returns: + A static vector of :cpp:any:`Mat::RowView`. + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(r ^ 2 c)` where :math:`r` is the number of rows in ``x`` and + :math:`c` is the number of columns in ``x``. + + +.. cpp:function:: template \ + void row_basis(Container& views, Container& result) + + Appends a basis for the space spanned by the row + views or bit sets in ``views`` to the container ``result``. + + :tparam Mat: + a type such that the value of :cpp:any:`IsMaxPlusTruncMat\` or + :cpp:any:`IsBMat\` is ``true``. + + :tparam Container: + a container type (such as ``std::vector``, for example). The + ``Container::value_type`` must be ``Mat::RowView``, or if ``Mat`` is + ``BMat`` for some ``N``, then ``Container::value_type`` can + additionally be ``BitSet`` or ``std::bitset`` where ``M`` is greater + than or equal to ``N``. + + :param views: container of spanning row views or bit sets + + :param result: container for the resulting row basis + + :returns: (None) + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(r ^ 2 c)` where :math:`r` is the size of ``views`` and + :math:`c` is the size of each row view or bit set in ``views``. diff --git a/docs/source-old/matrix/helpers/row_space_size.rst b/docs/source-old/matrix/helpers/row_space_size.rst new file mode 100644 index 000000000..32f58460a --- /dev/null +++ b/docs/source-old/matrix/helpers/row_space_size.rst @@ -0,0 +1,43 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +row_space_size +============== + +.. cpp:namespace:: libsemigroups::matrix_helpers + +.. cpp:function:: template \ + size_t row_space_size(Mat const& x) + + Returns the size of the row space of the matrix ``x``. This is currently + only implemented for types of matrix ``Mat`` where :cpp:any:`IsBMat\` is + ``true``. This function template is defined in namespace + :cpp:any:`matrix_helpers`. + + :param x: the matrix + + :returns: A value of type ``size_t``. + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + It might throw ``std::bad_alloc`` if the algorithm cannot allocate enough + memory. + + :complexity: + :math:`O(mn)` where :math:`m` is the size of the row basis of ``x`` and + :math:`n` is the size of the row space. + + .. warning:: + + If :math:`k` is the dimension of the matrix ``x``, then :math:`n` + can be as large as :math:`2 ^ k`. + + **Example** + + .. code-block:: + + auto x = BMat<>::make({{1, 0, 0}, {0, 0, 1}, {0, 1, 0}}); + matrix_helpers::row_space_size(x); // returns 7 diff --git a/docs/source-old/matrix/helpers/rows.rst b/docs/source-old/matrix/helpers/rows.rst new file mode 100644 index 000000000..335a154ae --- /dev/null +++ b/docs/source-old/matrix/helpers/rows.rst @@ -0,0 +1,52 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +rows +==== + +.. cpp:namespace:: libsemigroups::matrix_helpers + +This page contains details of the function templates for finding the rows of a +matrix in the namespace ``matrix_helper``. + +For dynamic matrices +-------------------- + +.. cpp:function:: template >> \ + std::vector \ + rows(T const& x) + + Returns a vector of row views into all of the rows of the dynamic matrix + ``x``. + + :param x: the matrix. + + :returns: A vector of ``T::RowView`` of size ``x.number_of_rows()``. + + :exceptions: Throws if ``T::rows`` throws, or ``std::bad_alloc`` is thrown. + + :complexity: + :math:`O(m)` where :math:`m` is the number of rows in the matrix ``x``. + +For static matrices +------------------- + +.. cpp:function:: template >> \ + detail::StaticVector1 rows(T const& x) + + Returns a static vector of row views into all of the rows of the static matrix + ``x``. Static vectors have the same interface as ``std::vector`` but their + capacity is defined at compile time. + + :param x: the matrix + + :returns: A static vector of ``T::RowView`` of size ``x.number_of_rows()``. + + :exceptions: Throws if ``T::rows`` throws, or ``std::bad_alloc`` is thrown. + + :complexity: + :math:`O(m)` where :math:`m` is the number of rows in the matrix ``x``. diff --git a/docs/source-old/matrix/index.rst b/docs/source-old/matrix/index.rst new file mode 100644 index 000000000..7e6a9654e --- /dev/null +++ b/docs/source-old/matrix/index.rst @@ -0,0 +1,102 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Matrix +====== + +There are several different classes in ``libsemigroups`` for representing +matrices over various semirings. There are up to three different +representations for every type of matrix: + +1. those whose dimension and arithmetic operations can be defined at compile + time: :cpp:any:`StaticMatrix`. +2. those whose arithmetic operation can be defined at compile time but whose + dimensions can be set at run time: :cpp:any:`DynamicMatrix` +3. those whose arithmetic operations and dimensions can be set at run time: + :cpp:any:`DynamicMatrix` + +It's unlikely that you will want to use the classes described on this page +directly, but rather through the aliases described on the other matrix pages +(such as, for example, :cpp:any:`BMat`). + +Over specific semirings +----------------------- + +The following matrix classes are provided which define matrices over some +specific semirings: + +.. toctree:: + :maxdepth: 1 + + bmat/index + intmat + maxplusmat + minplusmat + maxplustruncmat + minplustruncmat + ntpmat + projmaxplus + + +Over arbitrary semirings +------------------------ + +The following general matrix classes are provided which can be used to define +matrices over arbitrary semirings: + +.. toctree:: + :maxdepth: 1 + + dynamicmatrix-compile + dynamicmatrix-run + staticmatrix + variable-templates + validation + + +Row views +--------- + +A row view is a lightweight representation of a row of a matrix. The following +row view classes are provided: + +.. toctree:: + :maxdepth: 1 + + dynamicrowview + staticrowview + + +Helpers +------- + +The namespace :cpp:any:`matrix_helpers` contains a number of helper functions +for certain types of matrices: + +.. toctree:: + :maxdepth: 1 + + helpers/pow + helpers/rows + helpers/row_basis + helpers/row_space_size + helpers/bitset_rows + helpers/bitset_row_basis + +Adapters +--------------- + +There are various specialisations of the adapters described on `this +page` for the matrices described on this page: + +.. toctree:: + :maxdepth: 1 + + adapters/complexity + adapters/degree + adapters/increasedegreeby + adapters/one + adapters/product diff --git a/docs/source-old/matrix/intmat.rst b/docs/source-old/matrix/intmat.rst new file mode 100644 index 000000000..748280f74 --- /dev/null +++ b/docs/source-old/matrix/intmat.rst @@ -0,0 +1,129 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Integer matrices +================ + +Defined in ``matrix.hpp``. + +This page describes the functionality for :math:`m \times n` matrices of +integers for arbitrary dimensions :math:`m` and :math:`n`. There are two types +of such matrices those whose dimension is known at compile-time, and those +where it is not. Both types can be accessed via the alias template +:cpp:any:`IntMat\`: if ``R`` or ``C`` has value ``0``, then the +dimensions can be set at run time, otherwise ``R`` and ``C`` are the dimension. +The default value of ``R`` is ``0``, and of ``C`` is ``R``. + +The alias :cpp:any:`IntMat\` is either :cpp:any:`StaticMatrix` or +:cpp:any:`DynamicMatrix`, please refer to the documentation of these class +templates for more details. The only substantial difference in the interface +of :cpp:any:`StaticMatrix` and :cpp:any:`DynamicMatrix` is that the former can +be default constructed and the latter should be constructed using the +dimensions. + +**Example** + +.. code-block:: cpp + + IntMat<3> m; // default construct an uninitialized 3 x 3 static matrix + IntMat<> m(4, 4); // construct an uninitialized 4 x 4 dynamic matrix + + +.. cpp:struct:: template \ + IntegerPlus + + This is a stateless struct with a single call operator of signature: + ``Scalar operator()(Scalar const x, Scalar const y) const noexcept`` + which returns the usual sum ``x + y`` of ``x`` and ``y``; representing + addition in the integer semiring. + +.. cpp:struct:: template \ + IntegerProd + + This is a stateless struct with a single call operator of signature: + ``Scalar operator()(Scalar const x, Scalar const y) const noexcept`` + which returns the usual product ``x * y`` of ``x`` and ``y``; representing + multiplication in the integer semiring. + + +.. cpp:struct:: template \ + IntegerZero + + This is a stateless struct with a single call operator of signature: + ``Scalar operator()() const noexcept`` which returns ``0``; representing the + additive identity of the integer semiring. + + +.. cpp:struct:: template \ + IntegerOne + + This is a stateless struct with a single call operator of signature: + ``Scalar operator()() const noexcept`` which returns ``1``; representing the + multiplicative identity of the integer semiring. + + +.. cpp:type:: template \ + DynamicIntMat \ + = DynamicMatrix, \ + IntegerProd, \ + IntegerZero, \ + IntegerOne, \ + Scalar> + + Alias for the type of dynamic integer matrices where the dimensions of the + matrices can be defined at run time. + + :tparam Scalar: + The type of the entries in the matrix (default: ``int``). + + +.. cpp:type:: template \ + StaticIntMat = StaticMatrix, \ + IntegerProd, \ + IntegerZero, \ + IntegerOne, \ + R, \ + C, \ + Scalar> + + :tparam R: + the number of rows of the matrices. A value of ``0`` (the default value) + indicates that the dimensions will be set at run time. + + :tparam C: + the number of columns of the matrices. A value of ``0`` + indicates that the dimensions will be set at run time (the default value + is ``R``). + + :tparam Scalar: + The type of the entries in the matrix (default: ``int``). + + +.. cpp:type:: template \ + IntMat = std::conditional_t, \ + StaticIntMat> + + Alias template for integer matrices. + + :tparam R: + the number of rows of the matrices. A value of ``0`` (the default value) + indicates that the dimensions will be set at run time. + + :tparam C: + the number of columns of the matrices. A value of ``0`` + indicates that the dimensions will be set at run time (the default value + is ``R``). + + :tparam Scalar: + the type of the entries in the matrix (default: ``int``). + +.. cpp:var:: template \ + static constexpr bool IsIntMat + + This variable has value ``true`` if the template parameter ``T`` is the same + as :cpp:any:`IntMat\` for some values of ``R``, ``C``, and + ``Scalar``. diff --git a/docs/source-old/matrix/maxplusmat.rst b/docs/source-old/matrix/maxplusmat.rst new file mode 100644 index 000000000..f9721a0d3 --- /dev/null +++ b/docs/source-old/matrix/maxplusmat.rst @@ -0,0 +1,137 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Max-plus matrices +================= + +Defined in ``matrix.hpp``. + +This page describes the functionality for :math:`n \times n` matrices over the +max-plus semiring for arbitrary dimension :math:`n`. There are two types of +such matrices those whose dimension is known at compile-time, and those where +it is not. Both types can be accessed via the alias template +:cpp:any:`MaxPlusMat\`: if ``N`` has value ``0``, then the dimensions +can be set at run time, otherwise ``N`` is the dimension. The default value of +``N`` is ``0``. + +The alias :cpp:any:`MaxPlusMat\` is either :cpp:any:`StaticMatrix` or +:cpp:any:`DynamicMatrix`, please refer to the documentation of these class +templates for more details. The only substantial difference in the interface +of :cpp:any:`StaticMatrix` and :cpp:any:`DynamicMatrix` is that the former can +be default constructed and the latter should be constructed using the +dimensions. + +**Example** + +.. code-block:: cpp + + MaxPlusMat<3> m; // default construct an uninitialized 3 x 3 static matrix + MaxPlusMat<> m(4, 4); // construct an uninitialized 4 x 4 dynamic matrix + + +.. cpp:struct:: template \ + MaxPlusPlus + + This is a stateless struct with a single call operator of signature: + ``Scalar operator()(Scalar const x, Scalar const y) const noexcept`` + that returns :math:`x \oplus y` which is defined by + + .. math:: + + x\oplus y = + \begin{cases} + \max\{x, y\} & \text{if } x \neq -\infty\text{ and }y \neq -\infty \\ + -\infty & \text{if } x = -\infty \text{ or }y = -\infty; \\ + \end{cases} + + representing addition in the max-plus semiring. + +.. cpp:struct:: template \ + MaxPlusProd + + This is a stateless struct with a single call operator of signature: + ``Scalar operator()(Scalar const x, Scalar const y) const noexcept`` + that returns :math:`x \otimes y` which is defined by + + .. math:: + + x\otimes y = + \begin{cases} + x + y & \text{if } x \neq -\infty\text{ and }y \neq -\infty \\ + -\infty & \text{if } x = -\infty \text{ or }y = -\infty; \\ + \end{cases} + + representing multiplication in the max-plus semiring. + + +.. cpp:struct:: template \ + MaxPlusZero + + This is a stateless struct with a single call operator of signature: + ``Scalar operator()() const noexcept`` which returns :math:`-\infty`; + representing the additive identity of the max-plus semiring. + + +.. cpp:type:: template \ + DynamicMaxPlusMat \ + = DynamicMatrix, \ + MaxPlusProd, \ + MaxPlusZero, \ + IntegerZero, \ + Scalar> + + Alias for the type of dynamic max-plus matrices where the dimensions of the + matrices can be defined at run time. + + :tparam Scalar: + The type of the entries in the matrix. + + +.. cpp:type:: template \ + StaticMaxPlusMat = StaticMatrix, \ + MaxPlusProd, \ + MaxPlusZero, \ + IntegerZero, \ + R, \ + C, \ + Scalar> + + Alias for static max-plus matrices whose arithmetic and dimensions are + defined at compile-time. + + :tparam R: the number of rows. + + :tparam C: the number of columns. + + :tparam Scalar: + The type of the entries in the matrix. + + +.. cpp:type:: template \ + MaxPlusMat = std::conditional_t, \ + StaticMaxPlusMat> + + Alias template for max-plus matrices. + + :tparam R: + the number of rows. A value of ``0`` indicates that the value will be set + at run time (default: ``0``). + + :tparam C: + the number of columns. A value of ``0`` indicates that the value will be + set at run time (default: ``R``). + + :tparam Scalar: + The type of the entries in the matrix (default: ``int``). + +.. cpp:var:: template \ + static constexpr bool IsMaxPlusMat + + This variable has value ``true`` if the template parameter ``T`` is the same + as :cpp:any:`MaxPlusMat\` for some value of ``N`` and ``Scalar``. diff --git a/docs/source-old/matrix/maxplustruncmat.rst b/docs/source-old/matrix/maxplustruncmat.rst new file mode 100644 index 000000000..95aab682e --- /dev/null +++ b/docs/source-old/matrix/maxplustruncmat.rst @@ -0,0 +1,291 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. cpp:namespace:: libsemigroups + +Truncated max-plus matrices +=========================== + +Defined in ``matrix.hpp``. + +This page describes the functionality for :math:`n \times n` matrices over the +finite quotient of the max-plus semiring by the congruence :math:`t = t + 1` +for arbitrary :math:`n` and :math:`t`. The value :math:`t` is referred to as +the *threshold*. + +There are three types of such matrices where: + +1. the dimension is known at compile-time; +2. the dimension is to be defined a run time but the arithmetic operations + are known at compile-time (i.e. the value of :math:`t` is known at compile + time) +3. both the dimension and the arithmetic operations (i.e. :math:`t`) are to be + defined a run time. + +All three of these types can be accessed via the alias template +:cpp:any:`MaxPlusTruncMat\`: if ``T`` has value ``0``, then the +threshold can be set at run time, and if ``R`` or ``C`` is ``0``, then the +dimension can be set at run time. The default value of ``T`` is ``0``, ``R`` +is ``0``, and of ``C`` is ``R``. + +The alias :cpp:any:`MaxPlusTruncMat\` is either +:cpp:any:`StaticMatrix` or :cpp:any:`DynamicMatrix`, please refer to the +documentation of these class templates for more details. The only substantial +difference in the interface of :cpp:any:`StaticMatrix` and +:cpp:any:`DynamicMatrix` is that the former can be default constructed and the +latter should be constructed using the dimensions. + +**Example** + +.. code-block:: cpp + + MaxPlusTruncMat<11, 3> m; // default construct an uninitialized 3 x 3 static matrix with threshold 11 + MaxPlusTruncMat<11> m(4, 4); // construct an uninitialized 4 x 4 dynamic matrix with threshold 11 + MaxPlusTruncSemiring sr(11); // construct a truncated max-plus semiring with threshold 11 + MaxPlusTruncMat<> m(sr, 5, 5); // construct an uninitialized 5 x 5 dynamic matrix with threshold 11 (defined at run time) + + +.. cpp:struct:: template \ + MaxPlusTruncProd + + This is a stateless struct with a single call operator of signature: + ``Scalar operator()(Scalar const x, Scalar const y) const noexcept`` + that returns :math:`x \otimes y` which is defined by + + .. math:: + + x\otimes y = + \begin{cases} + \min\{x + y, T\} & \text{if } x \neq -\infty\text{ and }y \neq -\infty \\ + -\infty & \text{if } x = -\infty \text{ or }y = -\infty; \\ + \end{cases} + + representing multiplication in the quotient of the max-plus semiring by the + congruence :math:`T = T + 1`. + + +.. cpp:class:: template \ + MaxPlusTruncSemiring final + + This class represents the **max-plus truncated semiring** consists of the + integers :math:`\{0, \ldots , t\}` for some value :math:`t` (called the + **threshold** of the semiring) and :math:`-\infty`. Instances of this class + can be used to define the value of the threshold :math:`t` at run time. + + :tparam Scalar: + the type of the elements of the semiring. This must be a signed integer + type. + + .. cpp:function:: MaxPlusTruncSemiring() = delete + + Deleted default constructor. + + .. cpp:function:: MaxPlusTruncSemiring(MaxPlusTruncSemiring const&) = default + + Default copy constructor. + .. cpp:function:: MaxPlusTruncSemiring(MaxPlusTruncSemiring&&) = default + + Default move constructor. + + .. cpp:function:: MaxPlusTruncSemiring& operator=(MaxPlusTruncSemiring const&) \ + = default + + Default copy assignment operator. + + .. cpp:function:: MaxPlusTruncSemiring& operator=(MaxPlusTruncSemiring&&) \ + = default + + Default move assignment operator. + + .. cpp:function:: explicit MaxPlusTruncSemiring(Scalar const threshold) + + Construct from threshold. + + :param threshold: the threshold. + + :throws: + :cpp:any:`LibsemigroupsException` if ``threshold`` is less than zero. + + :complexity: Constant. + + .. cpp:function:: Scalar zero() const noexcept + + Returns :math:`-\infty`; representing the additive identity of the + quotient of the max-plus semiring. + + :parameters: (None) + + :returns: A value of type ``Scalar``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant. + + .. cpp:function:: Scalar one() const noexcept + + Returns :math:`0`; representing the multiplicative identity of the + quotient of the max-plus semiring. + + :parameters: (None) + + :returns: A value of type ``Scalar``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant. + + .. cpp:function:: Scalar plus(Scalar const x, Scalar const y) const noexcept + + Returns :math:`x \oplus y` which is defined by + + .. math:: + + x\oplus y = + \begin{cases} + \max\{x, y\} & \text{if } x \neq -\infty\text{ and }y \neq -\infty \\ + -\infty & \text{if } x = -\infty \text{ or }y = -\infty; \\ + \end{cases} + + representing addition in the max-plus semiring (and its quotient). + + :param x: scalar + :param y: scalar + + :returns: A value of type ``Scalar``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant. + + .. cpp:function:: Scalar prod(Scalar const x, Scalar const y) const noexcept + + Returns :math:`x \otimes y` which is defined by + + .. math:: + + x\otimes y = + \begin{cases} + \min\{x + y, t\} & \text{if } x \neq -\infty\text{ and }y \neq -\infty \\ + -\infty & \text{if } x = -\infty \text{ or }y = -\infty; \\ + \end{cases} + + where :math:`t` is the threshold; representing multiplication in the + quotient of the max-plus semiring. + + :param x: scalar + :param y: scalar + + :returns: A value of type ``Scalar``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant. + + .. cpp:function:: Scalar threshold() const noexcept + + Returns the threshold value used to construct ``this``. + + :parameters: (None) + + :returns: A value of type ``Scalar``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant. + + +.. cpp:type:: template \ + DynamicMaxPlusTruncMatSR = \ + DynamicMatrix, Scalar> + + Alias for truncated max-plus matrices with dimensions and threshold defined + at runtime. + + :tparam Scalar: + The type of the entries in the matrix. + + +.. cpp:type:: template \ + DynamicMaxPlusTruncMat \ + = DynamicMatrix, \ + MaxPlusTruncProd, \ + MaxPlusZero, \ + IntegerZero, \ + Scalar> + + Alias for the type of dynamic max-plus matrices where the dimension + is defined at run time, but the threshold is defined at compile-time. + + :tparam T: + the threshold. + + :tparam Scalar: + the type of the entries in the matrix. + + +.. cpp:type:: template \ + StaticMaxPlusTruncMat = StaticMatrix, \ + MaxPlusTruncProd, \ + MaxPlusZero, \ + IntegerZero, \ + R, \ + C, \ + Scalar> + + Alias for static max-plus truncated matrices where the threshold and + dimensions are defined at compile-time. + + :tparam T: the threshold. + + :tparam R: the number of rows. + + :tparam C: the number of columns. + + :tparam Scalar: + The type of the entries in the matrix. + + +.. cpp:type:: template \ + MaxPlusTruncMat = std::conditional_t< \ + R == 0 || C == 0, \ + std::conditional_t, \ + DynamicMaxPlusTruncMat>, \ + StaticMaxPlusTruncMat> + + :tparam T: + the threshold. A value of ``0`` indicates that the value will be set at + run time (default: ``0``). + + :tparam R: + the number of rows. A value of ``0`` indicates that the value will be set + at run time (default: ``0``). + + :tparam C: + the number of columns. A value of ``0`` indicates that the value will be + set at run time (default: ``R``). + + :tparam Scalar: + The type of the entries in the matrix (default: ``int``). + + +.. cpp:var:: template \ + static constexpr bool IsMaxPlusTruncMat + + This variable has value ``true`` if the template parameter ``T`` is the same + as :cpp:any:`MaxPlusTruncMat\` for some values of ``T``, + ``R``, ``C``, and ``Scalar``; and ``false`` if it is not. diff --git a/docs/source-old/matrix/minplusmat.rst b/docs/source-old/matrix/minplusmat.rst new file mode 100644 index 000000000..49bfd6c2d --- /dev/null +++ b/docs/source-old/matrix/minplusmat.rst @@ -0,0 +1,137 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Min-plus matrices +================= + +Defined in ``matrix.hpp``. + +This page describes the functionality for :math:`n \times n` matrices over the +min-plus semiring for arbitrary dimension :math:`n`. There are two types of +such matrices those whose dimension is known at compile-time, and those where +it is not. Both types can be accessed via the alias template +:cpp:any:`MinPlusMat\`: if ``N`` has value ``0``, then the dimensions +can be set at run time, otherwise ``N`` is the dimension. The default value of +``N`` is ``0``. + +The alias :cpp:any:`MinPlusMat\` is either :cpp:any:`StaticMatrix` or +:cpp:any:`DynamicMatrix`, please refer to the documentation of these class +templates for more details. The only substantial difference in the interface +of :cpp:any:`StaticMatrix` and :cpp:any:`DynamicMatrix` is that the former can +be default constructed and the latter should be constructed using the +dimensions. + +**Example** + +.. code-block:: cpp + + MinPlusMat<3> m; // default construct an uninitialized 3 x 3 static matrix + MinPlusMat<> m(4, 4); // construct an uninitialized 4 x 4 dynamic matrix + + +.. cpp:struct:: template \ + MinPlusPlus + + This is a stateless struct with a single call operator of signature: + ``Scalar operator()(Scalar const x, Scalar const y) const noexcept`` + that returns :math:`x \oplus y` which is defined by + + .. math:: + + x\oplus y = + \begin{cases} + \min\{x, y\} & \text{if } x \neq \infty\text{ and }y \neq \infty \\ + \infty & \text{if } x = \infty \text{ or }y = \infty; \\ + \end{cases} + + representing addition in the min-plus semiring. + +.. cpp:struct:: template \ + MinPlusProd + + This is a stateless struct with a single call operator of signature: + ``Scalar operator()(Scalar const x, Scalar const y) const noexcept`` + that returns :math:`x \otimes y` which is defined by + + .. math:: + + x\otimes y = + \begin{cases} + x + y & \text{if } x \neq \infty\text{ and }y \neq \infty \\ + \infty & \text{if } x = \infty \text{ or }y = \infty; \\ + \end{cases} + + representing multiplication in the min-plus semiring. + + +.. cpp:struct:: template \ + MinPlusZero + + This is a stateless struct with a single call operator of signature: + ``Scalar operator()() const noexcept`` which returns :math:`\infty`; + representing the additive identity of the min-plus semiring. + + +.. cpp:type:: template \ + DynamicMinPlusMat \ + = DynamicMatrix, \ + MinPlusProd, \ + MinPlusZero, \ + IntegerZero, \ + Scalar> + + Alias for the type of dynamic min-plus matrices where the dimensions of the + matrices can be defined at run time. + + :tparam Scalar: + The type of the entries in the matrix. + + +.. cpp:type:: template \ + StaticMinPlusMat = StaticMatrix, \ + MinPlusProd, \ + MinPlusZero, \ + IntegerZero, \ + R, \ + C, \ + Scalar> + + Alias for static min-plus matrices whose arithmetic and dimensions are + defined at compile-time. + + :tparam R: the number of rows. + + :tparam C: the number of columns. + + :tparam Scalar: + The type of the entries in the matrix. + +.. cpp:type:: template \ + MinPlusMat = std::conditional_t, \ + StaticMinPlusMat> + + Alias template for min-plus matrices. + + :tparam R: + the number of rows. A value of ``0`` indicates that the value will be set + at run time (default: ``0``). + + :tparam C: + the number of columns. A value of ``0`` indicates that the value will be + set at run time (default: ``R``). + + :tparam Scalar: + The type of the entries in the matrix (default: ``int``). + + +.. cpp:var:: template \ + static constexpr bool IsMinPlusMat + + This variable has value ``true`` if the template parameter ``T`` is the same + as :cpp:any:`MinPlusMat\` for some value of ``N`` and ``Scalar``. diff --git a/docs/source-old/matrix/minplustruncmat.rst b/docs/source-old/matrix/minplustruncmat.rst new file mode 100644 index 000000000..912c2c038 --- /dev/null +++ b/docs/source-old/matrix/minplustruncmat.rst @@ -0,0 +1,291 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. cpp:namespace:: libsemigroups + +Truncated min-plus matrices +=========================== + +Defined in ``matrix.hpp``. + +This page describes the functionality for :math:`n \times n` matrices over the +finite quotient of the min-plus semiring by the congruence :math:`t = t + 1` +for arbitrary :math:`n` and :math:`t`. The value :math:`t` is referred to as +the *threshold*. + +There are three types of such matrices where: + +1. the dimension is known at compile-time; +2. the dimension is to be defined a run time but the arithmetic operations + are known at compile-time (i.e. the value of :math:`t` is known at compile + time) +3. both the dimension and the arithmetic operations (i.e. :math:`t`) are to be + defined a run time. + +All three of these types can be accessed via the alias template +:cpp:any:`MinPlusTruncMat\`: if ``T`` has value ``0``, then the +threshold can be set at run time, and if ``R`` or ``C`` is ``0``, then the +dimension can be set at run time. The default value of ``T`` is ``0``, ``R`` +is ``0``, and of ``C`` is ``R``. + +The alias :cpp:any:`MinPlusTruncMat\` is either +:cpp:any:`StaticMatrix` or :cpp:any:`DynamicMatrix`, please refer to the +documentation of these class templates for more details. The only substantial +difference in the interface of :cpp:any:`StaticMatrix` and +:cpp:any:`DynamicMatrix` is that the former can be default constructed and the +latter should be constructed using the dimensions. + +**Example** + +.. code-block:: cpp + + MinPlusTruncMat<11, 3> m; // default construct an uninitialized 3 x 3 static matrix with threshold 11 + MinPlusTruncMat<11> m(4, 4); // construct an uninitialized 4 x 4 dynamic matrix with threshold 11 + MinPlusTruncSemiring sr(11); // construct a truncated min-plus semiring with threshold 11 + MinPlusTruncMat<> m(sr, 5, 5); // construct an uninitialized 5 x 5 dynamic matrix with threshold 11 (defined at run time) + + +.. cpp:struct:: template \ + MinPlusTruncProd + + This is a stateless struct with a single call operator of signature: + ``Scalar operator()(Scalar const x, Scalar const y) const noexcept`` + that returns :math:`x \otimes y` which is defined by + + .. math:: + + x\otimes y = + \begin{cases} + \min\{x + y, T\} & \text{if } x \neq \infty\text{ and }y \neq \infty \\ + \infty & \text{if } x = \infty \text{ or }y = \infty; \\ + \end{cases} + + representing multiplication in the quotient of the min-plus semiring by the + congruence :math:`T = T + 1`. + + +.. cpp:class:: template \ + MinPlusTruncSemiring final + + This class represents the **min-plus truncated semiring** consists of the + integers :math:`\{0, \ldots , t\}` for some value :math:`t` (called the + **threshold** of the semiring) and :math:`\infty`. Instances of this class + can be used to define the value of the threshold :math:`t` at run time. + + :tparam Scalar: + the type of the elements of the semiring. This must be an integral type. + + .. cpp:function:: MinPlusTruncSemiring() = delete + + Deleted default constructor. + + .. cpp:function:: MinPlusTruncSemiring(MinPlusTruncSemiring const&) = default + + Default copy constructor. + .. cpp:function:: MinPlusTruncSemiring(MinPlusTruncSemiring&&) = default + + Default move constructor. + + .. cpp:function:: MinPlusTruncSemiring& operator=(MinPlusTruncSemiring const&) \ + = default + + Default copy assignment operator. + + .. cpp:function:: MinPlusTruncSemiring& operator=(MinPlusTruncSemiring&&) \ + = default + + Default move assignment operator. + + .. cpp:function:: explicit MinPlusTruncSemiring(Scalar const threshold) + + Construct from threshold. + + :param threshold: the threshold. + + :throws: + :cpp:any:`LibsemigroupsException` if :cpp:any:`Scalar` is a + signed type and ``threshold`` is less than zero. + + :complexity: Constant. + + .. cpp:function:: Scalar zero() const noexcept + + Returns :math:`\infty`; representing the additive identity of the + quotient of the min-plus semiring. + + :parameters: (None) + + :returns: A value of type ``Scalar``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant. + + .. cpp:function:: Scalar one() const noexcept + + Returns :math:`0`; representing the multiplicative identity of the + quotient of the min-plus semiring. + + :parameters: (None) + + :returns: A value of type ``Scalar``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant. + + .. cpp:function:: Scalar plus(Scalar const x, Scalar const y) const noexcept + + Returns :math:`x \oplus y` which is defined by + + .. math:: + + x\oplus y = + \begin{cases} + \min\{x, y\} & \text{if } x \neq \infty\text{ and }y \neq \infty \\ + \infty & \text{if } x = \infty \text{ or }y = \infty; \\ + \end{cases} + + representing addition in the min-plus semiring (and its quotient). + + :param x: scalar + :param y: scalar + + :returns: A value of type ``Scalar``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant. + + .. cpp:function:: Scalar prod(Scalar const x, Scalar const y) const noexcept + + Returns :math:`x \otimes y` which is defined by + + .. math:: + + x\otimes y = + \begin{cases} + \min\{x + y, t\} & \text{if } x \neq \infty\text{ and }y \neq \infty \\ + \infty & \text{if } x = \infty \text{ or }y = \infty; \\ + \end{cases} + + where :math:`t` is the threshold; representing multiplication in the + quotient of the min-plus semiring. + + :param x: scalar + :param y: scalar + + :returns: A value of type ``Scalar``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant. + + .. cpp:function:: Scalar threshold() const noexcept + + Returns the threshold value used to construct ``this``. + + :parameters: (None) + + :returns: A value of type ``Scalar``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant. + + +.. cpp:type:: template \ + DynamicMinPlusTruncMatSR = \ + DynamicMatrix, Scalar> + + Alias for truncated min-plus matrices with dimensions and threshold defined + at runtime. + + :tparam Scalar: + The type of the entries in the matrix. + + +.. cpp:type:: template \ + DynamicMinPlusTruncMat \ + = DynamicMatrix, \ + MinPlusTruncProd, \ + MinPlusZero, \ + IntegerZero, \ + Scalar> + + Alias for the type of dynamic min-plus matrices where the dimension + is defined at run time, but the threshold is defined at compile-time. + + :tparam T: + the threshold. + + :tparam Scalar: + the type of the entries in the matrix. + + +.. cpp:type:: template \ + StaticMinPlusTruncMat = StaticMatrix, \ + MinPlusTruncProd, \ + MinPlusZero, \ + IntegerZero, \ + R, \ + C, \ + Scalar> + + Alias for static min-plus truncated matrices where the threshold and + dimensions are defined at compile-time. + + :tparam T: the threshold. + + :tparam R: the number of rows. + + :tparam C: the number of columns. + + :tparam Scalar: + The type of the entries in the matrix. + + +.. cpp:type:: template \ + MinPlusTruncMat = std::conditional_t< \ + R == 0 || C == 0, \ + std::conditional_t, \ + DynamicMinPlusTruncMat>, \ + StaticMinPlusTruncMat> + + :tparam T: + the threshold. A value of ``0`` indicates that the value will be set at + run time (default: ``0``). + + :tparam R: + the number of rows. A value of ``0`` indicates that the value will be set + at run time (default: ``0``). + + :tparam C: + the number of columns. A value of ``0`` indicates that the value will be + set at run time (default: ``R``). + + :tparam Scalar: + The type of the entries in the matrix (default: ``int``). + + +.. cpp:var:: template \ + static constexpr bool IsMinPlusTruncMat + + This variable has value ``true`` if the template parameter ``T`` is the same + as :cpp:any:`MinPlusTruncMat\` for some values of ``T``, + ``R``, ``C``, and ``Scalar``; and ``false`` if it is not. diff --git a/docs/source-old/matrix/ntpmat.rst b/docs/source-old/matrix/ntpmat.rst new file mode 100644 index 000000000..7fae67a41 --- /dev/null +++ b/docs/source-old/matrix/ntpmat.rst @@ -0,0 +1,340 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Matrices over the natural numbers quotiented by (t = t + p) +=========================================================== + +Defined in ``matrix.hpp``. + +This page describes the functionality for :math:`n \times n` matrices over the +finite quotient of the usual semiring of natural number by the congruence +:math:`t = t + p` for arbitrary :math:`n`, :math:`t`, and :math:`p`. The value +:math:`t` is referred to as the *threshold* and :math:`p` is called the +*period*. The matrices of this type are referred to by the acronym **ntp** +matrices, for "natural threshold period". The :cpp:any:`NTPSemiring` has +elements :math:`\{0, 1, ..., t, t + 1, ..., t + p - 1\}` where :math:`t`, and +:math:`p` are the threshold and period, respectively; addition and +multiplication in the :cpp:any:`NTPSemiring` is defined below. + +There are three types of such matrices where: + +1. the dimension is known at compile-time; +2. the dimension is to be defined a run time but the arithmetic operations + are known at compile-time (i.e. the values of :math:`t` and :math:`p` are + known at compile time) +3. both the dimension and the arithmetic operations (i.e. :math:`t` and + :math:`p`) are to be defined a run time. + +All three of these types can be accessed via the alias template +:cpp:any:`NTPMat\`: if ``T`` and ``P`` have value ``0``, +then the threshold and period can be set at run time, and if ``R`` or ``C`` is +``0``, then the dimension can be set at run time. The default values of ``T``, +``P``, and ``R`` are ``0``, and the default value of ``C`` is ``R``. + +The alias :cpp:any:`NTPMat\` is either +:cpp:any:`StaticMatrix` or :cpp:any:`DynamicMatrix`, please refer to the +documentation of these class templates for more details. The only substantial +difference in the interface of :cpp:any:`StaticMatrix` and +:cpp:any:`DynamicMatrix` is that the former can be default constructed and the +latter should be constructed using the dimensions. + +**Example** + +.. code-block:: cpp + + NTPMat<11, 2, 3> m; // default construct an uninitialized 3 x 3 static matrix with threshold 11, period 2 + NTPMat<11, 2> m(4, 4); // construct an uninitialized 4 x 4 dynamic matrix with threshold 11, period 2 + NTPSemiring sr(11, 2); // construct an ntp semiring with threshold 11, period 2 + NTPMat<> m(sr, 5, 5); // construct an uninitialized 5 x 5 dynamic matrix with threshold 11, period 2 + + +.. cpp:struct:: template \ + NTPPlus + + This is a stateless struct with a single call operator of signature: + ``Scalar operator()(Scalar const x, Scalar const y) const noexcept`` + that returns :math:`x \oplus y` which is defined by + + .. math:: + + x\oplus y = + \begin{cases} + x + y & \text{if } x + y \leq T \\ + T + ((x + y) - T \pmod{P}) & \text{if } x + y > T + \end{cases} + + representing addition in the quotient of the semiring natural numbers by + the congruence :math:`(T = T + P)`. + +.. cpp:struct:: template \ + NTPProd + + This is a stateless struct with a single call operator of signature: + ``Scalar operator()(Scalar const x, Scalar const y) const noexcept`` + that returns :math:`x \otimes y` which is defined by + + .. math:: + + x\otimes y = + \begin{cases} + xy & \text{if } xy \leq T \\ + T + ((xy - T) \pmod{P}) & \text{if } xy > T + \end{cases} + + representing multiplication in the quotient of the semiring natural numbers + by the congruence :math:`(T = T + P)`. + +.. cpp:class:: template \ + NTPSemiring final + + This class represents the **ntp semiring** consists of the integers + :math:`\{0, 1, ..., t, t + 1, ..., t + p - 1\}` for some :math:`t` and + :math:`p` (called the **threshold** and **period**). Instances of this class + can be used to define the value of the threshold :math:`t` and period + :math:`p` at run time. + + :tparam Scalar: the type of the elements of the semiring. + + .. cpp:function:: NTPSemiring() = delete + + Deleted default constructor. + + .. cpp:function:: NTPSemiring(NTPSemiring const&) = default + + Default copy constructor. + .. cpp:function:: NTPSemiring(NTPSemiring&&) = default + + Default move constructor. + + .. cpp:function:: NTPSemiring& operator=(NTPSemiring const&) \ + = default + + Default copy assignment operator. + + .. cpp:function:: NTPSemiring& operator=(NTPSemiring&&) \ + = default + + Default move assignment operator. + + .. cpp:function:: explicit NTPSemiring(Scalar const t, Scalar const p) + + Construct from threshold and period. + + :param t: the threshold (:math:`t \geq 0`). + :param p: the period (:math:`p > 0`). + + :throws: + :cpp:any:`LibsemigroupsException` if ``t`` is less than zero. + + :throws: + :cpp:any:`LibsemigroupsException` if ``p`` is less than or equal to + zero. + + :complexity: Constant. + + .. cpp:function:: Scalar zero() const noexcept + + Returns :math:`0`; representing the additive identity of the + quotient of the semiring of natural numbers. + + :parameters: (None) + + :returns: A value of type ``Scalar``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant. + + .. cpp:function:: Scalar one() const noexcept + + Returns :math:`1`; representing the additive identity of the + quotient of the semiring of natural numbers. + + :parameters: (None) + + :returns: A value of type ``Scalar``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant. + + .. cpp:function:: Scalar plus(Scalar const x, Scalar const y) const noexcept + + Returns :math:`x \oplus y` which is defined by + + .. math:: + + x\oplus y = + \begin{cases} + x + y & \text{if } x + y \leq \texttt{threshold()} \\ + \texttt{threshold()} + ((x + y - \texttt{threshold()}) \pmod{\texttt{period()}}) & \text{if } x + y > \texttt{threshold()} + \end{cases} + + representing the addition in the quotient of the semiring of natural + numbers. + + :param x: scalar (:math:`0\leq x < \texttt{threshold()} + \texttt{period()}`) + :param y: scalar (:math:`0\leq y < \texttt{threshold()} + \texttt{period()}`) + + :returns: A value of type ``Scalar``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant. + + .. cpp:function:: Scalar prod(Scalar const x, Scalar const y) const noexcept + + Returns :math:`x \otimes y` which is defined by + + .. math:: + + x\otimes y = + \begin{cases} + xy & \text{if } xy \leq \texttt{threshold()} \\ + \texttt{threshold()} + ((xy - \texttt{threshold()})\pmod{\texttt{period()}}) & \text{if } xy > + \texttt{threshold()} + \end{cases} + + where :math:`t` is the threshold; representing multiplication in the + quotient of the semiring of natural numbers. + + :param x: scalar (:math:`0\leq x < \texttt{threshold()} + \texttt{period()}`) + :param y: scalar (:math:`0\leq y < \texttt{threshold()} + \texttt{period}()`) + + :returns: A value of type ``Scalar``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant. + + .. cpp:function:: Scalar threshold() const noexcept + + Returns the threshold value used to construct ``this``. + + :parameters: (None) + + :returns: A value of type ``Scalar``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant. + + + .. cpp:function:: Scalar period() const noexcept + + Returns the period value used to construct ``this``. + + :parameters: (None) + + :returns: A value of type ``Scalar``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant. + + +.. cpp:type:: template \ + DynamicNTPMatWithSemiring \ + = DynamicMatrix, Scalar> + + Alias for ntp matrices with dimensions, threshold, and period defined + at runtime. + + :tparam Scalar: + The type of the entries in the matrix. + + +.. cpp:type:: template \ + DynamicNTPMatWithoutSemiring \ + = DynamicMatrix, \ + NTPProd, \ + IntegerZero, \ + IntegerOne, \ + Scalar> + + Alias for the type of dynamic ntp matrices where the dimension + is defined at run time, but the threshold and period are defined at + compile-time. + + :tparam T: the threshold. + + :tparam P: the period. + + :tparam Scalar: the type of the entries in the matrix. + + +.. cpp:type:: template \ + StaticNTPMat = StaticMatrix, \ + NTPProd, \ + IntegerZero, \ + IntegerOne, \ + R, \ + C, \ + Scalar> + + Alias for static ntp matrices where the threshold, period, and + dimensions are defined at compile-time. + + :tparam T: the threshold. + + :tparam P: the period. + + :tparam R: the number of rows. + + :tparam C: the number of columns. + + :tparam Scalar: + The type of the entries in the matrix (default: ``int``). + + +.. cpp:type:: template \ + NTPMat = std::conditional_t< \ + R == 0 || C == 0, \ + std::conditional_t, \ + DynamicNTPMatWithoutSemiring>, \ + StaticNTPMat> + + :tparam T: + the threshold. If both ``T`` and ``P`` are ``0``, this indicates that the + value will be set at run time (default: ``0``). + + :tparam P: + the period. If both ``T`` and ``P`` are ``0``, this indicates that the + value will be set at run time (default: ``0``). + + :tparam R: + the number of rows. A value of ``0`` indicates that the value will be set + at run time (default: ``0``). + + :tparam C: + the number of columns. A value of ``0`` indicates that the value will be + set at run time (default: ``R``). + + :tparam Scalar: + The type of the entries in the matrix (default: ``size_t``). + + +.. cpp:var:: template \ + static constexpr bool IsNTPMat + + This variable has value ``true`` if the template parameter ``U`` is the same + as :cpp:any:`NTPMat\` for some values of ``T``, ``P``, + ``R``, ``C``, and ``Scalar``; and ``false`` if it is not. diff --git a/docs/source-old/matrix/projmaxplus.rst b/docs/source-old/matrix/projmaxplus.rst new file mode 100644 index 000000000..a6ffacbd9 --- /dev/null +++ b/docs/source-old/matrix/projmaxplus.rst @@ -0,0 +1,101 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Projective max-plus matrices +============================ + +Defined in ``matrix.hpp``. + +This page describes the functionality for :math:`n \times n` projective +matrices over the max-plus semiring. +Projective max-plus matrices belong to the quotient of the monoid of all +max-plus matrices by the congruence where two matrices are related if they +differ by a scalar multiple; see :cpp:any:`MaxPlusMat`. + + +There are two types of such matrices those whose dimension is known at +compile-time, and those where it is not. Both types can be accessed via the +alias template :cpp:any:`ProjMaxPlusMat\`: if ``R`` or ``C`` has +value ``0``, then the dimensions can be set at run time, otherwise ``R`` and +``C`` are the dimensions. The default value of ``R`` is ``0``, ``C`` is ``R``, +and ``Scalar`` is ``int``. + +Matrices in both these classes are modified when constructed to be in a normal +form which is obtained by subtracting the maximum finite entry in the matrix +from the every finite entry. + +The alias :cpp:any:`ProjMaxPlusMat\` is neither +:cpp:any:`StaticMatrix` nor :cpp:any:`DynamicMatrix`, but has the same +interface as each of these types. An instance of :cpp:any:`ProjMaxPlusMat\` wraps a :cpp:any:`MaxPlusMat`. + +.. note:: + The types :cpp:any:`RowView` and :cpp:any:`Row` are the same as those in the + wrapped matrix. This means that a :cpp:any:`Row` object for a projective + max-plus matrix is never normalised, because if they were they would be + normalised according to their entries, and this might not correspond to the + normalised entries of the matrix. + +Please refer to the documentation of these class templates for more details. +The only substantial difference in the interface of :cpp:any:`StaticMatrix` and +:cpp:any:`DynamicMatrix` is that the former can be default constructed and the +latter should be constructed using the dimensions. + +**Example** + +.. code-block:: cpp + + ProjMaxPlusMat<3> m; // default construct an uninitialized 3 x 3 static matrix + ProjMaxPlusMat<> m(4, 4); // construct an uninitialized 4 x 4 dynamic matrix + + +.. cpp:type:: template \ + StaticProjMaxPlusMat \ + = detail::ProjMaxPlusMat> + + Alias for static projective max-plus matrices whose arithmetic and + dimensions are defined at compile-time. + + :tparam R: the number of rows. + + :tparam C: the number of columns. + + :tparam Scalar: The type of the entries in the matrix. + +.. cpp:type:: template \ + DynamicProjMaxPlusMat \ + = detail::ProjMaxPlusMat> + + Alias for the type of dynamic projective max-plus matrices where the + dimensions of the matrices can be defined at run time. + + :tparam Scalar: The type of the entries in the matrix. + +.. cpp:type:: template \ + ProjMaxPlusMat = \ + std::conditional_t, \ + StaticProjMaxPlusMat> + + Alias template for projective max-plus matrices. + + :tparam R: + the number of rows. A value of ``0`` indicates that the value will be set + at run time (default: ``0``). + + :tparam C: + the number of columns. A value of ``0`` indicates that the value will be + set at run time (default: ``R``). + + :tparam Scalar: + The type of the entries in the matrix (default: ``int``). + +.. cpp:var:: template \ + static constexpr bool IsProjMaxPlusMat + + This variable has value ``true`` if the template parameter ``T`` is the same + as :cpp:any:`ProjMaxPlusMat\` for some values of ``R``, ``C``, + and ``Scalar``; and ``false`` if it is not. diff --git a/docs/source-old/matrix/staticmatrix.rst b/docs/source-old/matrix/staticmatrix.rst new file mode 100644 index 000000000..f298220f4 --- /dev/null +++ b/docs/source-old/matrix/staticmatrix.rst @@ -0,0 +1,198 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +StaticMatrix +============ + +.. highlight:: cpp + +Defined in ``matrix.hpp``. + +.. cpp:class:: template \ + StaticMatrix final + :tparam-line-spec: + + This is a class for matrices where both the arithmetic operations in the + underlying semiring, and the dimensions of the matrices are known at compile + time. + + :tparam PlusOp: + a stateless type with a call operator of signature :code:`scalar_type + operator()(scalar_type, scalar_type)` implementing the addition of the + semiring + + :tparam ProdOp: + a stateless type with a call operator of signature :code:`scalar_type + operator()(scalar_type, scalar_type)` implementing the multiplication of + the semiring + + :tparam ZeroOp: + a stateless type with a call operator of signature :code:`scalar_type + operator()()` returning the zero of the semiring (the additive identity + element) + + :tparam OneOp: + a stateless type with a call operator of signature :code:`scalar_type + operator()()` returning the one of the semiring (the multiplicative + identity element) + + :tparam R: the number of rows of the matrices + + :tparam C: the number of columns of the matrices + + :tparam Scalar: + the type of the entries in the matrices (the type of elements in the + underlying semiring) + + .. note:: + Certain member functions only work for square matrices and some only work + for rows. + +.. toctree:: + :hidden: + + staticmatrix/constructors + staticmatrix/begin + staticmatrix/end + staticmatrix/number_of_rows + staticmatrix/call_operator + staticmatrix/operator_plus_equals + staticmatrix/operator_prod_equals + staticmatrix/operator_plus + staticmatrix/operator_prod + staticmatrix/comparison_ops + staticmatrix/coords + staticmatrix/swap + staticmatrix/transpose + staticmatrix/rows + staticmatrix/row + staticmatrix/types + staticmatrix/staticmemfn + +Member types +------------ + +.. list-table:: + :widths: 50 50 + :header-rows: 1 + + * - Member type + - Definition + * - :ref:`scalar_type` + - the type of scalars contained in the matrix (:code:`Scalar`) + * - :ref:`scalar_reference` + - the type of references to scalars contained in the matrix + * - :ref:`scalar_const_reference` + - the type of const references to scalars contained in the matrix + * - :ref:`Row` + - type of a row of the matrix + * - :ref:`RowView` + - type of a row view int the matrix + * - :ref:`Plus` + - the template parameter :cpp:any:`PlusOp` + * - :ref:`Prod` + - the template parameter :cpp:any:`ProdOp` + * - :ref:`Zero` + - the template parameter :cpp:any:`ZeroOp` + * - :ref:`One` + - the template parameter :cpp:any:`OneOp` + * - :ref:`semiring_type` + - ``void`` + +Member functions +---------------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`(constructor)` + - constructs the matrix + * - :ref:`number_of_rows/number_of_cols` + - the number of rows/columns in the matrix + +Static member functions +----------------------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`make` + - constructs a matrix and checks that its entries are valid + * - :ref:`identity` + - constructs an identity matrix + +Iterators +--------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`begin/cbegin` + - returns an iterator to the beginning + * - :ref:`end/cend` + - returns an iterator to the end + * - :ref:`coords` + - returns the coordinates corresponding to an iterator + +Accessors +--------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`operator()` + - access specified element + * - :ref:`row` + - access specified row + * - :ref:`rows` + - add all rows to a container + +Arithmetic operators +-------------------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`operator+=` + - add a (matrix, scalar, or row view) to the matrix in place + * - :ref:`operator\*=` + - multiply the matrix by a matrix or scalar in place + * - :ref:`operator+` + - add a (matrix, scalar, or row view) to the matrix + * - :ref:`operator*` + - multiply the matrix by a matrix or scalar + +Comparison operators +-------------------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`operator==` + - compare matrices + * - :ref:`operator!=` + - compare matrices + * - :ref:`operator\<` + - compare matrices + * - :ref:`operator\>` + - compare matrices + +Modifiers +--------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`swap` + - swaps the contents + * - :ref:`transpose` + - transposes the matrix diff --git a/docs/source-old/matrix/staticmatrix/begin.rst b/docs/source-old/matrix/staticmatrix/begin.rst new file mode 100644 index 000000000..f32cee971 --- /dev/null +++ b/docs/source-old/matrix/staticmatrix/begin.rst @@ -0,0 +1,52 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticmatrix_begin: + +begin, cbegin +============= + +.. cpp:namespace:: libsemigroups::StaticMatrix + +.. cpp:function:: iterator begin() + + Returns a (random access) iterator pointing at the first entry in the + matrix. + + :returns: + A value of type ``iterator``. + + :complexity: Constant + + :throws: + this function is ``noexcept`` and is guaranteed never to throw. + + :parameters: (None) + + .. warning:: + The order in which entries in the matrix are iterated over is not + specified. + + +.. cpp:function:: const_iterator cbegin() + + Returns a const (random access) iterator pointing at the first entry in the + matrix. + + :returns: + A value of type ``const_iterator``. + + :complexity: Constant + + :throws: + this function is ``noexcept`` and is guaranteed never to throw. + + :parameters: (None) + + .. warning:: + The order in which entries in the matrix are iterated over is not + specified. + diff --git a/docs/source-old/matrix/staticmatrix/call_operator.rst b/docs/source-old/matrix/staticmatrix/call_operator.rst new file mode 100644 index 000000000..cbca38e45 --- /dev/null +++ b/docs/source-old/matrix/staticmatrix/call_operator.rst @@ -0,0 +1,50 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticmatrix_call_operator: + +operator() +========== + +.. cpp:namespace:: libsemigroups::StaticMatrix + +.. cpp:function:: scalar_reference operator()(size_t const r, size_t const c) + + Returns a reference to the specified entry of the matrix. + + :param r: the index of the row of the entry + :param c: the index of the column of the entry + + :returns: A value of type :cpp:any:`scalar_reference`. + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + Constant + + .. warning:: + No checks on the validity of the parameters ``r`` and ``c`` are + performed. + +.. cpp:function:: scalar_const_reference operator()(size_t const r, size_t const c) const + + Returns a const reference to the specified entry of the matrix. + + :param r: the index of the row of the entry + :param c: the index of the column of the entry + + :returns: A value of type :cpp:any:`scalar_const_reference`. + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + Constant + + .. warning:: + No checks on the validity of the parameters ``r`` and ``c`` are + performed. diff --git a/docs/source-old/matrix/staticmatrix/comparison_ops.rst b/docs/source-old/matrix/staticmatrix/comparison_ops.rst new file mode 100644 index 000000000..c019c12e0 --- /dev/null +++ b/docs/source-old/matrix/staticmatrix/comparison_ops.rst @@ -0,0 +1,113 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticmatrix_comparison_ops: + +StaticMatrix comparison operators +================================= + +.. cpp:namespace:: libsemigroups::StaticMatrix + +.. _staticmatrix_operator_equals: + +.. cpp:function:: bool operator==(StaticMatrix const& that) const + + Equality operator. + + :param that: matrix for comparison. + + :returns: + ``true`` if ``*this`` and ``that`` are equal and ``false`` if they are + not. + + :complexity: + At worst :math:`O(mn)` where :math:`m` is the number of rows and + :math:`n` is the number of columns of the matrix. + +.. cpp:function:: bool operator==(RowView const& that) const + + Equality operator. + + :param that: the row view for comparison. + + :returns: + ``true`` if ``*this`` and ``that`` are equal and ``false`` if they are + not. In particular, if ``*this`` has more than one row, then ``false`` + is returned. + + :complexity: + At worst :math:`O(n)` where :math:`n` is the number of columns of the + matrix. + +.. _staticmatrix_operator_not_equals: + +.. cpp:function:: template \ + bool operator!=(T const& that) const + + Inequality operator. + + :tparam T: + either :cpp:any:`StaticMatrix` or :cpp:any:`RowView` + + :param that: the matrix or row view for comparison. + + :returns: + the negation of ``operator==(that)``. + + :complexity: + see :cpp:any:`operator==` + +.. _staticmatrix_operator_less: + +.. cpp:function:: bool operator<(StaticMatrix const& that) const + + Less than operator. + + This operator defines a total order on the set of matrices of the same type, + the details of which is implementation specific. + + :param that: the matrix for comparison. + + :returns: + ``true`` if ``*this`` is less than ``that`` and ``false`` if it is not. + + :complexity: + At worst :math:`O(mn)` where :math:`m` is + :cpp:any:`number_of_rows` + and :math:`n` is :cpp:any:`number_of_cols` + +.. cpp:function:: bool operator<(RowView const& that) const + + Less than operator. + + :param that: the row view for comparison. + + :returns: + ``true`` if ``*this`` is less than ``that``, and ``false`` + otherwise. In particular, if ``*this`` has more than one row, then + ``false`` is returned. + + :complexity: + At worst :math:`O(n)` where :math:`n` is + :cpp:any:`number_of_cols` + +.. _staticmatrix_operator_more: + +.. cpp:function:: bool operator>(StaticMatrix const& that) const + + Greater than operator. + + This operator defines a total order on the set of matrices of the same type, + the details of which is implementation specific. + + :param that: the matrix for comparison. + + :returns: + ``true`` if ``*this`` is less than ``that`` and ``false`` if it is not. + + :complexity: + At worst :math:`O(mn)` where :math:`m` is :cpp:any:`number_of_rows` + and :math:`m` is :cpp:any:`number_of_cols` diff --git a/docs/source-old/matrix/staticmatrix/constructors.rst b/docs/source-old/matrix/staticmatrix/constructors.rst new file mode 100644 index 000000000..f2cbf0d16 --- /dev/null +++ b/docs/source-old/matrix/staticmatrix/constructors.rst @@ -0,0 +1,117 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticmatrix_constructors: + +StaticMatrix +============ + +.. cpp:namespace:: libsemigroups::StaticMatrix + +This page contains information about the constructors for the +:cpp:any:`StaticMatrix` class. + +Default constructors +-------------------- + +.. cpp:function:: StaticMatrix() = default + + Default constructor. + +.. cpp:function:: StaticMatrix(StaticMatrix const&) = default + + Default copy constructor. + +.. cpp:function:: StaticMatrix(StaticMatrix&&) = default + + Default move constructor. + +.. cpp:function:: StaticMatrix& operator=(StaticMatrix const&) = default + + Default copy assignment operator. + +.. cpp:function:: StaticMatrix& operator=(StaticMatrix&&) = default + + Default move assignment operator. + + +Matrix constructors +------------------- + +.. cpp:function:: StaticMatrix( \ + std::initializer_list> m) + + Construct a matrix. + + :param m: the values to be copied into the matrix. + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(mn)` where :math:`m` is the template parameter :code:`R` and + :math:`n` is the template parameter :code:`C`. + + **Example** + + .. code-block:: cpp + + Mat m({{1, 1}, {0, 0}}); + + +.. cpp:function:: StaticMatrix( \ + std::vector> const& m) + + Construct a matrix. + + :param m: the values to be copied into the matrix. + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(mn)` where :math:`m` is the template parameter :code:`R` and + :math:`n` is the template parameter :code:`C`. + + +Row constructors +---------------- + +.. cpp:function:: StaticMatrix(std::initializer_list c) + + Construct a row. + + :param c: the values to be copied into the row. + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(n)` where :math:`n` is the size of the row being + constructed. + + .. warning:: + + This constructor only works for rows, i.e. when the template parameter + :code:`R` is :code:`1`. + +.. cpp:function:: StaticMatrix(RowView const& rv) + + Construct a row from a row view. + + :param rv: the row view. + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(n)` where :math:`n` is the size of the row being + constructed. + + .. warning:: + + This constructor only works for rows, i.e. when the template parameter + :code:`R` is :code:`1`. diff --git a/docs/source-old/matrix/staticmatrix/coords.rst b/docs/source-old/matrix/staticmatrix/coords.rst new file mode 100644 index 000000000..ace9582ee --- /dev/null +++ b/docs/source-old/matrix/staticmatrix/coords.rst @@ -0,0 +1,27 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticmatrix_coords: + +coords +====== + +.. cpp:namespace:: libsemigroups::StaticMatrix + +.. cpp:function:: std::pair \ + coords(const_iterator it) const + + Returns a pair containing the row and columns corresponding to an iterator. + + :param it: the iterator + + :returns: + A value of type ``std::pair``. + + :complexity: Constant + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. diff --git a/docs/source-old/matrix/staticmatrix/end.rst b/docs/source-old/matrix/staticmatrix/end.rst new file mode 100644 index 000000000..00ae4fb3a --- /dev/null +++ b/docs/source-old/matrix/staticmatrix/end.rst @@ -0,0 +1,53 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticmatrix_end: + +end, cend +========= + +.. cpp:namespace:: libsemigroups::StaticMatrix + +.. cpp:function:: iterator end() + + Returns a (random access) iterator pointing one passed the last entry of the + matrix. + + :parameters: (None) + + :returns: + A value of type ``iterator``. + + :complexity: Constant + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + + .. warning:: + The order in which entries in the matrix are iterated over is not + specified. + + +.. cpp:function:: const_iterator cend() + + Returns a const (random access) iterator pointing one passed the last entry + of the matrix. + + :parameters: (None) + + :returns: + A value of type ``const_iterator``. + + :complexity: Constant + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + .. warning:: + The order in which entries in the matrix are iterated over is not + specified. + diff --git a/docs/source-old/matrix/staticmatrix/number_of_rows.rst b/docs/source-old/matrix/staticmatrix/number_of_rows.rst new file mode 100644 index 000000000..ba2a147eb --- /dev/null +++ b/docs/source-old/matrix/staticmatrix/number_of_rows.rst @@ -0,0 +1,42 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticmatrix_number_of_rows: + +number_of_rows, number_of_cols +============================== + +.. cpp:namespace:: libsemigroups::StaticMatrix + +.. cpp:function:: size_t number_of_rows() + + Returns the number of rows of the matrix. + + :returns: + A value of type ``size_t``. + + :complexity: Constant + + :exceptions: + this function is ``noexcept`` and is guaranteed never to throw. + + :parameters: (None) + + +.. cpp:function:: size_t number_of_cols() + + Returns the number of columns of the matrix. + + :returns: + A value of type ``size_t``. + + :complexity: Constant + + :exceptions: + this function is ``noexcept`` and is guaranteed never to throw. + + :parameters: (None) + diff --git a/docs/source-old/matrix/staticmatrix/operator_plus.rst b/docs/source-old/matrix/staticmatrix/operator_plus.rst new file mode 100644 index 000000000..1586caf6e --- /dev/null +++ b/docs/source-old/matrix/staticmatrix/operator_plus.rst @@ -0,0 +1,33 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticmatrix_operator_plus: + +operator+ +========= + +.. cpp:namespace:: libsemigroups::StaticMatrix + +.. cpp:function:: StaticMatrix operator+(StaticMatrix const& that) + + Returns the sum of ``*this`` and ``that``. + + :param that: the matrix to add to ``this``. + + :returns: + a value of type ``StaticMatrix``. + + :throws: + if the implementation of the semiring plus throws, or ``std::bad_alloc`` + if memory cannot be allocated for the result. + + :complexity: + :math:`O(mn)` where :math:`m` is :cpp:any:`StaticMatrix::number_of_rows` + and :math:`m` is :cpp:any:`StaticMatrix::number_of_cols` + + .. warning:: + The matrices must be of the same dimensions, although this is not + verified by the implementation. diff --git a/docs/source-old/matrix/staticmatrix/operator_plus_equals.rst b/docs/source-old/matrix/staticmatrix/operator_plus_equals.rst new file mode 100644 index 000000000..f089513e3 --- /dev/null +++ b/docs/source-old/matrix/staticmatrix/operator_plus_equals.rst @@ -0,0 +1,70 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticmatrix_operator_plus_equals: + +operator+= +========== + +.. cpp:namespace:: libsemigroups::StaticMatrix + +.. cpp:function:: void operator+=(StaticMatrix const& that) + + Redefines ``this`` to be the sum of ``*this`` and ``that``. + + :param that: the matrix to add to ``this``. + + :returns: (None) + + :throws: + if the implementation of the semiring plus throws. + + :complexity: + :math:`O(mn)` where :math:`m` is :cpp:any:`StaticMatrix::number_of_rows` + and :math:`m` is :cpp:any:`StaticMatrix::number_of_cols` + + .. warning:: + The matrices must be of the same dimensions, although this is not + verified by the implementation. + +.. cpp:function:: void operator+=(RowView const& that) + + Redefines ``this`` to be the sum of ``*this`` and ``that``. + + :param that: the matrix to add to ``this``. + + :returns: (None) + + :throws: + if the implementation of the semiring plus throws. + + :complexity: + :math:`O(mn)` where :math:`m` is :cpp:any:`StaticMatrix::number_of_rows` + and :math:`m` is :cpp:any:`StaticMatrix::number_of_cols` + + .. warning:: + This function only works if ``this`` has a single row, i.e. the template + parameter ``R`` is ``1``. + +.. cpp:function:: void operator+=(scalar const a) + + Adds a scalar to every entry of the matrix in-place. + + :param a: the scalar to add to ``this``. + + :returns: (None) + + :throws: + if the implementation of the semiring plus throws. + + :complexity: + :math:`O(mn)` where :math:`m` is :cpp:any:`StaticMatrix::number_of_rows` + and :math:`m` is :cpp:any:`StaticMatrix::number_of_cols` + + .. warning:: + This function only works if ``this`` has a single row, i.e. the template + parameter ``R`` is ``1``. + diff --git a/docs/source-old/matrix/staticmatrix/operator_prod.rst b/docs/source-old/matrix/staticmatrix/operator_prod.rst new file mode 100644 index 000000000..e4ffab046 --- /dev/null +++ b/docs/source-old/matrix/staticmatrix/operator_prod.rst @@ -0,0 +1,33 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticmatrix_operator_prod: + +operator* +======================= + +.. cpp:namespace:: libsemigroups::StaticMatrix + +.. cpp:function:: StaticMatrix operator*(StaticMatrix const& that) + + Returns the product of ``*this`` and ``that``. + + :param that: the matrix to multiply by ``this``. + + :returns: + a value of type ``StaticMatrix``. + + :throws: + if the implementation of the semiring multiplication throws, or + ``std::bad_alloc`` if memory cannot be allocated for the result. + + :complexity: + :math:`O(mn)` where :math:`m` is :cpp:any:`StaticMatrix::number_of_rows` + and :math:`m` is :cpp:any:`StaticMatrix::number_of_cols` + + .. warning:: + The matrices must be of the same dimensions, although this is not + verified by the implementation. diff --git a/docs/source-old/matrix/staticmatrix/operator_prod_equals.rst b/docs/source-old/matrix/staticmatrix/operator_prod_equals.rst new file mode 100644 index 000000000..5c8d040c4 --- /dev/null +++ b/docs/source-old/matrix/staticmatrix/operator_prod_equals.rst @@ -0,0 +1,53 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticmatrix_operator_prod_equals: + +operator*= +========== + +.. cpp:namespace:: libsemigroups::StaticMatrix + +.. cpp:function:: void operator*=(scalar_type const a) + + Multiplies every entry of the matrix by a scalar in-place. + + :param a: the scalar to multiply every entry of ``this``. + + :returns: (None) + + :throws: + if the implementation of the semiring multiplication throws. + + :complexity: + :math:`O(mn)` where :math:`m` is :cpp:any:`number_of_rows` + and :math:`m` is :cpp:any:`number_of_cols` + +.. cpp:function:: void product_inplace(StaticMatrix const& A, StaticMatrix const& B) + + Multiplies ``A`` and ``B`` and stores the result in ``this``. + + Redefines ``this`` to be the product of ``A`` and ``B``. This is in-place + multiplication to avoid allocation of memory for products which do not need + to be stored for future use. + + :param A: the first matrix to multiply + :param B: the second matrix to multiply + + :returns: (None) + + :throws: + Throws if the implementation of the semiring plus or product throws + or ``std::bad_alloc``. + + :complexity: + :math:`O(n ^ 3)` where :math:`n` is :cpp:any:`number_of_rows` + or :cpp:any:`number_of_cols`. + + .. warning:: + + This function only applies to matrices with the same number of rows + and columns. diff --git a/docs/source-old/matrix/staticmatrix/row.rst b/docs/source-old/matrix/staticmatrix/row.rst new file mode 100644 index 000000000..56f85f8e3 --- /dev/null +++ b/docs/source-old/matrix/staticmatrix/row.rst @@ -0,0 +1,25 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticmatrix_row: + +row +=== + +.. cpp:namespace:: libsemigroups::StaticMatrix + +.. cpp:function:: RowView row(size_t i) const + + Returns a row view into the specified row. + + :param i: the row + + :returns: A value of type :cpp:any:`RowView`. + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: Constant diff --git a/docs/source-old/matrix/staticmatrix/rows.rst b/docs/source-old/matrix/staticmatrix/rows.rst new file mode 100644 index 000000000..684192cff --- /dev/null +++ b/docs/source-old/matrix/staticmatrix/rows.rst @@ -0,0 +1,26 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticmatrix_rows: + +rows +==== + +.. cpp:namespace:: libsemigroups::StaticMatrix + +.. cpp:function:: template void rows(T& x) const + + Add row views for every row in the matrix to the container ``T``. + + :param x: a container + + :returns: (None) + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(m)` where :math:`m` is the template parameter :code:`R` diff --git a/docs/source-old/matrix/staticmatrix/staticmemfn.rst b/docs/source-old/matrix/staticmatrix/staticmemfn.rst new file mode 100644 index 000000000..a5b554fd3 --- /dev/null +++ b/docs/source-old/matrix/staticmatrix/staticmemfn.rst @@ -0,0 +1,72 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +StaticMatrix static member functions +==================================== + +.. cpp:namespace:: libsemigroups::StaticMatrix + +.. _staticmatrix_identity: +.. cpp:function:: static StaticMatrix identity() + + Construct the identity matrix. + + :parameters: (None) + + :returns: The identity matrix with ``R = C`` rows and columns. + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(n ^ 2)` where :math:`n` is the template parameter :code:`R` and + :code:`C`. + + .. warning:: + This only works when the template parameters ``R`` and ``C`` are equal + (i.e. for square matrices). + +.. _staticmatrix_make: +.. cpp:function:: static StaticMatrix \ + make(std::initializer_list> il) + + Validates the arguments, constructs a matrix and validates it. + + :param il: the values to be copied into the matrix. + + :returns: the constructed matrix if valid. + + :throws: + :cpp:any:`LibsemigroupsException` if ``il`` does not represent a + matrix of the correct dimensions. + + :throws: + :cpp:any:`LibsemigroupsException` if the constructed matrix + contains values that do not belong to the underlying semiring. + + :complexity: + :math:`O(mn)` where :math:`m` is the number of rows and + :math:`n` is the number of columns of the matrix. + +.. cpp:function:: static StaticMatrix make(std::initializer_list il) + + Constructs a row and validates it. + + :param il: the values to be copied into the row. + + :returns: the constructed row if valid. + + :throws: + :cpp:any:`LibsemigroupsException` if the constructed row contains + values that do not belong to the underlying semiring. + + :complexity: + :math:`O(n)` where :math:`n` is the number of columns of the matrix. + + .. warning:: + + This constructor only works for rows, i.e. when the template parameter + :code:`R` is :code:`1`. diff --git a/docs/source-old/matrix/staticmatrix/swap.rst b/docs/source-old/matrix/staticmatrix/swap.rst new file mode 100644 index 000000000..7ae55a7e8 --- /dev/null +++ b/docs/source-old/matrix/staticmatrix/swap.rst @@ -0,0 +1,25 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticmatrix_swap: + +swap +==== + +.. cpp:namespace:: libsemigroups::StaticMatrix + +.. cpp:function:: void swap(StaticMatrix& that) noexcept + + Swaps the contents of ``this`` with the contents of ``that``. + + :param that: the matrix to swap contents with + + :returns: (None) + + :complexity: Constant + + :exceptions: + this function is ``noexcept`` and is guaranteed never to throw. diff --git a/docs/source-old/matrix/staticmatrix/transpose.rst b/docs/source-old/matrix/staticmatrix/transpose.rst new file mode 100644 index 000000000..703a60bf9 --- /dev/null +++ b/docs/source-old/matrix/staticmatrix/transpose.rst @@ -0,0 +1,31 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticmatrix_transpose: + +transpose +========= + +.. cpp:namespace:: libsemigroups::StaticMatrix + +.. cpp:function:: void transpose() noexcept + + Transposes the matrix in-place. + + :parameters: (None) + + :returns: (None) + + :exceptions: + this function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + :math:`O(mn)` where :math:`m` is the template parameter :code:`R` and + :math:`n` is the template parameter :code:`C`. + + .. warning:: + This only works when the template parameters ``R`` and ``C`` are equal + (i.e. for square matrices). diff --git a/docs/source-old/matrix/staticmatrix/types.rst b/docs/source-old/matrix/staticmatrix/types.rst new file mode 100644 index 000000000..ecb5b9e87 --- /dev/null +++ b/docs/source-old/matrix/staticmatrix/types.rst @@ -0,0 +1,67 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +StaticMatrix member types +========================= + +.. cpp:namespace:: libsemigroups::StaticMatrix + +This page contains information about the member types of the +:cpp:any:`StaticMatrix` class. + +.. _staticmatrix_scalar_type: +.. cpp:type:: scalar_type = Scalar + + The type of the entries in the matrix. + +.. _staticmatrix_scalar_reference: +.. cpp:type:: scalar_reference = Scalar& + + The type of references to the entries in the matrix (might not be + :code:`Scalar&`). + +.. _staticmatrix_scalar_const_reference: +.. cpp:type:: scalar_const_reference = Scalar const& + + The type of references to the entries in the matrix (might not be + :code:`Scalar const&`). + +.. _staticmatrix_row_type: +.. cpp:type:: Row = StaticMatrix + + The type of a row of a :cpp:any:`StaticMatrix`. + +.. _staticmatrix_rowview_type: +.. cpp:type:: RowView = StaticRowView + + The type of a row view into a :cpp:any:`StaticMatrix`. + +.. _staticmatrix_plus: +.. cpp:type:: Plus = PlusOp + + The template parameter ``PlusOp``. + +.. _staticmatrix_prod: +.. cpp:type:: Prod = ProdOp + + The template parameter ``ProdOp``. + +.. _staticmatrix_zero: +.. cpp:type:: Zero = ZeroOp + + The template parameter ``ZeroOp``. + +.. _staticmatrix_one: +.. cpp:type:: One = OneOp + + The template parameter ``OneOp``. + +.. _staticmatrix_semiring_type: +.. cpp:type:: semiring_type = void + + The type of the semiring over which the matrix is defined is ``void`` + because there's no semiring object, the arithmetic is defined by the + template parameters. diff --git a/docs/source-old/matrix/staticrowview.rst b/docs/source-old/matrix/staticrowview.rst new file mode 100644 index 000000000..1521b323c --- /dev/null +++ b/docs/source-old/matrix/staticrowview.rst @@ -0,0 +1,162 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +StaticRowView +============= + +.. highlight:: cpp + +Defined in ``matrix.hpp``. + +.. cpp:class:: template \ + StaticRowView final + :tparam-line-spec: + + This is a class for views into a row of a matrix over a semiring. An + instance of this class provides access to the elements in a row of a matrix + and is cheap to create and copy. Addition, scalar multiplication, and other + standard vector operations are defined for row views. + + This class is the type of row views into a :cpp:any:`StaticMatrix`; see the + documentation for :cpp:any:`StaticMatrix` for further details. + + \warning + If the underlying matrix is destroyed, then any row views for that matrix + are invalidated. + + :tparam PlusOp: + a stateless type with a call operator of signature :code:`scalar_type + operator()(scalar_type, scalar_type)` implementing the addition of the + semiring + + :tparam ProdOp: + a stateless type with a call operator of signature :code:`scalar_type + operator()(scalar_type, scalar_type)` implementing the multiplication of + the semiring + + :tparam ZeroOp: + a stateless type with a call operator of signature :code:`scalar_type + operator()()` returning the zero of the semiring (the additive identity + element) + + :tparam OneOp: + a stateless type with a call operator of signature :code:`scalar_type + operator()()` returning the one of the semiring (the multiplicative + identity element) + + :tparam C: the number of columns of the underlying matrix + + :tparam Scalar: + the type of the entries in the matrices (the type of elements in the + underlying semiring) + +.. toctree:: + :hidden: + + staticrowview/begin + staticrowview/call_operator + staticrowview/comparison_ops + staticrowview/constructors + staticrowview/end + staticrowview/operator_plus_equals + staticrowview/operator_plus + staticrowview/operator_prod_equals + staticrowview/operator_prod + staticrowview/size + staticrowview/subscript_operator + staticrowview/types + +Member types +------------ + +.. list-table:: + :widths: 50 50 + :header-rows: 1 + + * - Member type + - Definition + * - :ref:`scalar_type` + - the type of scalars contained in the row (:code:`Scalar`) + * - :ref:`scalar_reference` + - the type of references to scalars contained in the row + * - :ref:`scalar_const_reference` + - the type of const references to scalars contained in the row + * - :ref:`matrix_type` + - type of the underlying matrix of the row view + * - :ref:`Row` + - type of a row for the row view + * - :ref:`iterator` + - type of iterators to entries in the underlying row + * - :ref:`const_iterator` + - type of iterators to entries in the underlying row + +Member functions +---------------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`(constructor)` + - constructs the matrix + * - :ref:`size` + - the length of the row (the template parameter :cpp:any:`C`) + +Iterators +--------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`begin/cbegin` + - returns an iterator to the beginning + * - :ref:`end/cend` + - returns an iterator to the end + +Accessors +--------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`operator()` + - access specified element + * - :ref:`operator[]` + - access specified element + +Arithmetic operators +-------------------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`operator+=` + - add a (matrix, scalar, or row view) to the matrix in place + * - :ref:`operator\*=` + - multiply the matrix by a matrix or scalar in place + * - :ref:`operator+` + - add a (matrix, scalar, or row view) to the matrix + * - :ref:`operator*` + - multiply the matrix by a matrix or scalar + +Comparison operators +-------------------- + +.. list-table:: + :widths: 50 50 + + * - :ref:`operator==` + - compare matrices + * - :ref:`operator!=` + - compare matrices + * - :ref:`operator\<` + - compare matrices + * - :ref:`operator\>` + - compare matrices diff --git a/docs/source-old/matrix/staticrowview/begin.rst b/docs/source-old/matrix/staticrowview/begin.rst new file mode 100644 index 000000000..1c4c744d8 --- /dev/null +++ b/docs/source-old/matrix/staticrowview/begin.rst @@ -0,0 +1,40 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticrowview_begin: + +begin, cbegin +============= + +.. cpp:namespace:: libsemigroups::StaticRowView + +.. cpp:function:: iterator begin() + + Returns a (random access) iterator pointing at the first entry in the + row. + + :parameters: (None) + + :returns: A value of type :cpp:any:`iterator`. + + :complexity: Constant + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + +.. cpp:function:: const_iterator cbegin() + + Returns a const (random access) iterator pointing at the first entry in the + row. + + :parameters: (None) + + :returns: A value of type :cpp:any:`const_iterator`. + + :complexity: Constant + + :throws: + This function is ``noexcept`` and is guaranteed never to throw. diff --git a/docs/source-old/matrix/staticrowview/call_operator.rst b/docs/source-old/matrix/staticrowview/call_operator.rst new file mode 100644 index 000000000..dd1932e9d --- /dev/null +++ b/docs/source-old/matrix/staticrowview/call_operator.rst @@ -0,0 +1,46 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticrowview_call_operator: + +operator() +========== + +.. cpp:namespace:: libsemigroups::StaticRowView + +.. cpp:function:: scalar_reference operator()(size_t const i) + + Returns a reference to the specified entry of the matrix. + + :param i: the index of the entry + + :returns: A value of type :cpp:any:`scalar_reference`. + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + Constant + + .. warning:: + No checks on the validity of the parameter ``i`` is performed. + +.. cpp:function:: scalar_const_reference operator()(size_t const i) const + + Returns a const reference to the specified entry of the matrix. + + :param i: the index of the entry + + :returns: A value of type :cpp:any:`scalar_const_reference`. + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + Constant + + .. warning:: + No checks on the validity of the parameter ``i`` is performed. diff --git a/docs/source-old/matrix/staticrowview/comparison_ops.rst b/docs/source-old/matrix/staticrowview/comparison_ops.rst new file mode 100644 index 000000000..c3423c49c --- /dev/null +++ b/docs/source-old/matrix/staticrowview/comparison_ops.rst @@ -0,0 +1,84 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticrowview_comparison_ops: + +StaticRowView comparison operators +================================== + +.. cpp:namespace:: libsemigroups::StaticRowView + +.. _staticrowview_operator_equals: +.. cpp:function:: template \ + bool operator==(U const& that) const + + Equality operator. + + :tparam U: either :cpp:any:`Row` or :cpp:any:`RowView` + + :param that: :cpp:any:`Row` or :cpp:any:`RowView` object for comparison. + + :returns: + Returns ``true`` if the first :cpp:any:`size()` entries of ``that`` equal + the entries of ``this``, and ``false`` if not. + + :complexity: + At worst :math:`O(n)` where :math:`n` is the size of the row view. + + +.. _staticrowview_operator_not_equals: +.. cpp:function:: template \ + bool operator!=(U const& that) const + + Inequality operator. + + :tparam U: either :cpp:any:`Row` or :cpp:any:`RowView` + + :param that: :cpp:any:`Row` or :cpp:any:`RowView` object for comparison. + + :returns: + Returns ``true`` if the first :cpp:any:`size()` entries of ``that`` dp not + equal the entries of ``this``, and ``false`` otherwise. + + :complexity: + At worst :math:`O(n)` where :math:`n` is the size of the row view. + + +.. _staticrowview_operator_less: +.. cpp:function:: template \ + bool operator<(U const& that) const + + Lexicographical comparison of rows. + + :tparam U: either :cpp:any:`Row` or :cpp:any:`RowView` + + :param that: :cpp:any:`Row` or :cpp:any:`RowView` object for comparison. + + :returns: + Returns ``true`` if ``this`` is lex less than that ``that`` and ``false`` + otherwise. + + :complexity: + At worst :math:`O(n)` where :math:`n` is the size of the row view. + + +.. _staticrowview_operator_more: +.. cpp:function:: template \ + bool operator>(U const& that) const + + Lexicographical comparison of rows. + + :tparam U: either :cpp:any:`Row` or :cpp:any:`RowView` + + :param that: :cpp:any:`Row` or :cpp:any:`RowView` object for comparison. + + :returns: + Returns ``true`` if ``this`` is lex greater than that ``that`` and + ``false`` otherwise. + + :complexity: + At worst :math:`O(n)` where :math:`n` is the size of the row view. + diff --git a/docs/source-old/matrix/staticrowview/constructors.rst b/docs/source-old/matrix/staticrowview/constructors.rst new file mode 100644 index 000000000..6094e699a --- /dev/null +++ b/docs/source-old/matrix/staticrowview/constructors.rst @@ -0,0 +1,57 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticrowview_constructors: + +StaticRowView +============= + +.. cpp:namespace:: libsemigroups::StaticRowView + +This page contains information about the constructors for the +:cpp:any:`StaticRowView` class. + +Note that unless copying an existing ``StaticRowView`` it's most likely that +you will obtain a ``StaticRowView`` from :cpp:any:`StaticMatrix::row` or +:cpp:any:`StaticMatrix::rows`. + +Default constructors +-------------------- + +.. cpp:function:: StaticRowView() = default + + Default constructor. + +.. cpp:function:: StaticRowView(StaticRowView const&) = default + + Default copy constructor. + +.. cpp:function:: StaticRowView(StaticRowView&&) = default + + Default move constructor. + +.. cpp:function:: StaticRowView& operator=(StaticRowView const&) = default + + Default copy assignment operator. + +.. cpp:function:: StaticRowView& operator=(StaticRowView&&) = default + + Default move assignment operator. + +Constructor from Row +-------------------- + +.. cpp:function:: explicit StaticRowView(Row const& r) + + Construct a row view from a Row. + + :param r: the row. + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + Constant. diff --git a/docs/source-old/matrix/staticrowview/end.rst b/docs/source-old/matrix/staticrowview/end.rst new file mode 100644 index 000000000..6d0369550 --- /dev/null +++ b/docs/source-old/matrix/staticrowview/end.rst @@ -0,0 +1,42 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticrowview_end: + +end, cend +========= + +.. cpp:namespace:: libsemigroups::StaticRowView + +.. cpp:function:: iterator end() + + Returns a (random access) iterator pointing one passed the last entry of the + row. + + :parameters: (None) + + :returns: + A value of type ``iterator``. + + :complexity: Constant + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + +.. cpp:function:: const_iterator cend() + + Returns a const (random access) iterator pointing one passed the last entry + of the row. + + :parameters: (None) + + :returns: + A value of type ``const_iterator``. + + :complexity: Constant + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. diff --git a/docs/source-old/matrix/staticrowview/operator_plus.rst b/docs/source-old/matrix/staticrowview/operator_plus.rst new file mode 100644 index 000000000..5d8e67eac --- /dev/null +++ b/docs/source-old/matrix/staticrowview/operator_plus.rst @@ -0,0 +1,31 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticrowview_operator_plus: + +operator+ +========= + +.. cpp:namespace:: libsemigroups::StaticRowView + +.. cpp:function:: Row operator+(StaticRowView const& that) + + Sums a row view with another row view and returns a newly allocated Row. + + :param that: the row view to add to ``this``. + + :returns: A value of type :cpp:any:`Row` + + :throws: + If the implementation of the semiring addition throws or + ``std::bad_alloc`` is thrown. + + :complexity: + :math:`O(m)` where :math:`m` is :cpp:any:`size` + + .. warning:: + The two row views must be of the same size, although this is not + verified by the implementation. diff --git a/docs/source-old/matrix/staticrowview/operator_plus_equals.rst b/docs/source-old/matrix/staticrowview/operator_plus_equals.rst new file mode 100644 index 000000000..545b3a403 --- /dev/null +++ b/docs/source-old/matrix/staticrowview/operator_plus_equals.rst @@ -0,0 +1,46 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticrowview_operator_plus_equals: + +operator+= +========== + +.. cpp:namespace:: libsemigroups::StaticRowView + +.. cpp:function:: void operator+=(StaticRowView const& that) + + Sums a row view with another row view in-place. + Redefines ``this`` to be the sum of ``*this`` and ``that``. + + :param that: the row view to add to ``this``. + + :returns: (None) + + :throws: + If the implementation of the semiring addition throws. + + :complexity: + :math:`O(m)` where :math:`m` is :cpp:any:`size` + + .. warning:: + The two row views must be of the same size, although this is not + verified by the implementation. + + +.. cpp:function:: void operator+=(scalar_type const a) + + Adds a scalar to every entry of the row in-place. + + :param a: the scalar to add to ``this``. + + :returns: (None) + + :complexity: + :math:`O(m)` where :math:`m` is :cpp:any:`size` + + :throws: + If the implementation of the semiring addition throws. diff --git a/docs/source-old/matrix/staticrowview/operator_prod.rst b/docs/source-old/matrix/staticrowview/operator_prod.rst new file mode 100644 index 000000000..5d9ef9c18 --- /dev/null +++ b/docs/source-old/matrix/staticrowview/operator_prod.rst @@ -0,0 +1,29 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticrowview_operator_prod: + +operator* +========= + +.. cpp:namespace:: libsemigroups::StaticRowView + +.. cpp:function:: Row operator*(scalar_type const a) const + + Multiplies every entry of the row by a scalar. + + :param a: the scalar. + + :returns: + A value of type Row containing the original row multiplied by the scalar + ``a``. + + :complexity: + :math:`O(m)` where :math:`m` is :cpp:any:`size` + + :throws: + If the implementation of the semiring addition throws or + ``std::bad_alloc`` is thrown. diff --git a/docs/source-old/matrix/staticrowview/operator_prod_equals.rst b/docs/source-old/matrix/staticrowview/operator_prod_equals.rst new file mode 100644 index 000000000..4a21d61e0 --- /dev/null +++ b/docs/source-old/matrix/staticrowview/operator_prod_equals.rst @@ -0,0 +1,26 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticrowview_operator_prod_equals: + +operator*= +========== + +.. cpp:namespace:: libsemigroups::StaticRowView + +.. cpp:function:: void operator*=(scalar_type const a) + + Multiplies every entry of the row by a scalar in-place. + + :param a: the scalar to add to every entry of ``this``. + + :returns: (None) + + :throws: + If the implementation of the semiring multiplication throws. + + :complexity: + :math:`O(m)` where :math:`m` is :cpp:any:`size` diff --git a/docs/source-old/matrix/staticrowview/size.rst b/docs/source-old/matrix/staticrowview/size.rst new file mode 100644 index 000000000..755fbc8e0 --- /dev/null +++ b/docs/source-old/matrix/staticrowview/size.rst @@ -0,0 +1,25 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticrowview_size: + +size +==== + +.. cpp:namespace:: libsemigroups::StaticRowView + +.. cpp:function:: size_t size() const noexcept + + Returns the size of the underlying row. + + :parameters: (None) + + :returns: A value of type ``size_t``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: Constant diff --git a/docs/source-old/matrix/staticrowview/subscript_operator.rst b/docs/source-old/matrix/staticrowview/subscript_operator.rst new file mode 100644 index 000000000..f2817e54d --- /dev/null +++ b/docs/source-old/matrix/staticrowview/subscript_operator.rst @@ -0,0 +1,46 @@ +.. Copyright (c) 2019-20, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _staticrowview_subscript_operator: + +operator[] +========== + +.. cpp:namespace:: libsemigroups::StaticRowView + +.. cpp:function:: scalar_reference operator[](size_t const i) + + Returns a reference to the specified entry of the matrix. + + :param i: the index of the entry + + :returns: A value of type :cpp:any:`scalar_reference`. + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + Constant + + .. warning:: + No checks on the validity of the parameter ``i`` is performed. + +.. cpp:function:: scalar_const_reference operator[](size_t const i) const + + Returns a const reference to the specified entry of the matrix. + + :param i: the index of the entry + + :returns: A value of type :cpp:any:`scalar_const_reference`. + + :exceptions: + This function guarantees not to throw a :cpp:any:`LibsemigroupsException`. + + :complexity: + Constant + + .. warning:: + No checks on the validity of the parameter ``i`` is performed. diff --git a/docs/source-old/matrix/staticrowview/types.rst b/docs/source-old/matrix/staticrowview/types.rst new file mode 100644 index 000000000..0011e363a --- /dev/null +++ b/docs/source-old/matrix/staticrowview/types.rst @@ -0,0 +1,50 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +StaticRowView member types +========================== + +.. cpp:namespace:: libsemigroups::StaticRowView + +This page contains information about the member types of the +:cpp:any:`StaticRowView` class. + +.. _staticrowview_scalar_type: +.. cpp:type:: scalar_type = Scalar + + The type of the entries in the matrix. + +.. _staticrowview_scalar_reference: +.. cpp:type:: scalar_reference = Scalar& + + The type of references to the entries in the matrix (might not be + :code:`Scalar&`). + +.. _staticrowview_scalar_const_reference: +.. cpp:type:: scalar_const_reference = Scalar const& + + The type of references to the entries in the matrix (might not be + :code:`Scalar const&`). + +.. _staticrowview_mat_type: +.. cpp:type:: matrix_type = StaticMatrix + + The type of the matrix underlying a StaticRowView. + +.. _staticrowview_row_type: +.. cpp:type:: Row = Mat::Row + + The type of a row of a StaticRowView. + +.. _staticrowview_iterator: +.. cpp:type:: iterator = Mat::iterator + + The type of iterators into the row view. + +.. _staticrowview_const_iterator: +.. cpp:type:: const_iterator = Mat::const_iterator + + The type of const iterators into the row view. diff --git a/docs/source-old/matrix/validation.rst b/docs/source-old/matrix/validation.rst new file mode 100644 index 000000000..62594d706 --- /dev/null +++ b/docs/source-old/matrix/validation.rst @@ -0,0 +1,82 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Validation +========== + +.. cpp:namespace:: libsemigroups + +The function :cpp:any:`validate_matrix` can be used to check that a matrix is +valid (i.e. that its entries belong to the underlying semiring). + + +.. cpp:function:: template \ + void validate(Mat const& m) + + Throws an exception if the matrix is invalid. + + The overloaded static member functions :cpp:any:`DynamicMatrix::make` and + :cpp:any:`StaticMatrix::make` use this function to verify that the + constructed matrix is valid. + + :tparam Mat: a type for which :cpp:any:`IsMatrix` is ``true``. + + :param m: the matrix to validate. + + :returns: (None). + + :throws: A :cpp:any:`LibsemigroupsException` if the matrix ``m`` is invalid. + + :complexity: + At worst :math:`O(nk)` where :math:`n` is the number of rows in the matrix + ``m`` and :math:`k` is the number of columns. + + +Threshold and period +==================== + +.. cpp:function:: template \ + typename Mat::scalar_type matrix_threshold(Mat const& m) + + Returns the threshold of a matrix (if any). + + This value is only defined for :cpp:any:`MaxPlusTruncMat`, + :cpp:any:`MinPlusTruncMat`, and :cpp:any:`NTPMat`. If ``Mat`` is another + type of matrix, then :cpp:any:`UNDEFINED` is returned. + + :tparam Mat: a type for which :cpp:any:`IsMatrix` is ``true``. + + :param m: the matrix. + + :returns: A value of type ``typename Mat::scalar_type``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: + Constant. + + +.. cpp:function:: template \ + typename Mat::scalar_type matrix_period(Mat const& m) + + Returns the period of a matrix (if any). + + This value is only defined for :cpp:any:`NTPMat`. If ``Mat`` is another + type of matrix, then :cpp:any:`UNDEFINED` is returned. + + :tparam Mat: a type for which :cpp:any:`IsMatrix` is ``true``. + + :param m: the matrix. + + :returns: A value of type ``typename Mat::scalar_type``. + + :exceptions: + This function is ``noexcept`` and is guaranteed never to throw. + + :complexity: + Constant. + diff --git a/docs/source-old/matrix/variable-templates.rst b/docs/source-old/matrix/variable-templates.rst new file mode 100644 index 000000000..bc02088ff --- /dev/null +++ b/docs/source-old/matrix/variable-templates.rst @@ -0,0 +1,39 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Variable templates +================== + +Defined in ``matrix.hpp``. + +This page contains documentation for several variable templates related to +matrices. + +.. cpp:var:: template \ + static constexpr bool IsMatrix + + This variable has value ``true`` if the template parameter ``T`` is either + :cpp:any:`DynamicMatrix` or :cpp:any:`StaticMatrix`; and ``false`` + otherwise. + +.. cpp:var:: template \ + static constexpr bool IsStaticMatrix + + This variable has value ``true`` if the template parameter ``T`` is + :cpp:any:`StaticMatrix`; and ``false`` otherwise. + +.. cpp:var:: template \ + static constexpr bool IsDynamicMatrix + + This variable has value ``true`` if the template parameter ``T`` is + :cpp:any:`DynamicMatrix`; and ``false`` otherwise. + + +.. cpp:var:: template \ + static constexpr bool IsMatWithSemiring + + This variable has value ``true`` if the template parameter ``T`` is + :cpp:any:`DynamicMatrix\`; and ``false`` otherwise. diff --git a/docs/source-old/misc.rst b/docs/source-old/misc.rst new file mode 100644 index 000000000..22e017645 --- /dev/null +++ b/docs/source-old/misc.rst @@ -0,0 +1,22 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Miscellaneous +============= + +In this section we describe some miscellaneous functionality in +``libsemigroups``. + +.. toctree:: + :maxdepth: 1 + + adapters + constants + exception + report + _generated/libsemigroups__runner + types + ukkonen diff --git a/docs/source-old/order.rst b/docs/source-old/order.rst new file mode 100644 index 000000000..fe610c2bb --- /dev/null +++ b/docs/source-old/order.rst @@ -0,0 +1,40 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _order: + +Orders +====== + +Declared in ``order.hpp``. + +This file contains documentation for several class and function templates for +comparing words or strings with respect to certain reduction orderings. + +Functions +~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + api/lexicographical_compare_references.rst + api/lexicographical_compare_pointers.rst + api/shortlex_compare_iterators.rst + api/shortlex_compare_references.rst + api/shortlex_compare_pointers.rst + api/recursive_path_compare_iterators.rst + api/recursive_path_compare_references.rst + api/recursive_path_compare_pointers.rst + +Types +~~~~~ + +.. toctree:: + :maxdepth: 1 + + api/lexicographicalcompare_struct.rst + api/shortlexcompare_struct.rst + api/recursivepathcompare_struct.rst diff --git a/docs/source-old/pbr.rst b/docs/source-old/pbr.rst new file mode 100644 index 000000000..1af8bf3e2 --- /dev/null +++ b/docs/source-old/pbr.rst @@ -0,0 +1,34 @@ +.. Copyright (c) 2021, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +PBRs +==== + +Defined in ``pbr.hpp``. + +This page contains the documentation for functionality in ``libsemigroups`` for +partitioned binary relations; see :cite:`Martin2013aa` for more details. + +.. toctree:: + :maxdepth: 2 + + _generated/libsemigroups__pbr + +Validating +~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + api/pbr_validate.rst + +Helper variable templates +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + _generated/libsemigroups__ispbr diff --git a/docs/source-old/perm.rst b/docs/source-old/perm.rst new file mode 100644 index 000000000..c41dda1d4 --- /dev/null +++ b/docs/source-old/perm.rst @@ -0,0 +1,36 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Permutations +============ + +Defined in ``transf.hpp``. + +This page contains the documentation for functionality in ``libsemigroups`` for +permutations. + +.. toctree:: + :maxdepth: 2 + + _generated/libsemigroups__perm + +Validating +~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + api/perm_validate.rst + +Helper variable templates +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + _generated/libsemigroups__isstatic + _generated/libsemigroups__isdynamic + _generated/libsemigroups__isperm diff --git a/docs/source-old/pperm.rst b/docs/source-old/pperm.rst new file mode 100644 index 000000000..ef8d3996b --- /dev/null +++ b/docs/source-old/pperm.rst @@ -0,0 +1,36 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Partial Permutations +==================== + +Defined in ``transf.hpp``. + +This page contains the documentation for functionality in ``libsemigroups`` for +partial permutations. + +.. toctree:: + :maxdepth: 2 + + _generated/libsemigroups__pperm + +Validating +~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + api/pperm_validate.rst + +Helper variable templates +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + _generated/libsemigroups__isstatic + _generated/libsemigroups__isdynamic + _generated/libsemigroups__ispperm diff --git a/docs/source-old/present.rst b/docs/source-old/present.rst new file mode 100644 index 000000000..3f9760116 --- /dev/null +++ b/docs/source-old/present.rst @@ -0,0 +1,18 @@ +.. Copyright (c) 2022, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Presentations +============= + +This page describes the functionality for semigroup and monoid presentations in +``libsemigroups``. + +.. toctree:: + :maxdepth: 1 + + _generated/libsemigroups__presentation.rst + api/present-helper.rst + api/make-present.rst diff --git a/docs/source-old/ptransf.rst b/docs/source-old/ptransf.rst new file mode 100644 index 000000000..1ff6370b8 --- /dev/null +++ b/docs/source-old/ptransf.rst @@ -0,0 +1,32 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Partial Transformations +======================= + +Defined in ``transf.hpp``. + +This page contains the documentation for functionality in ``libsemigroups`` for +partial transformations. + +.. toctree:: + :maxdepth: 3 + + _generated/libsemigroups__dynamicptransf + _generated/libsemigroups__staticptransf + _generated/libsemigroups__ptransf + _generated/libsemigroups__ptransfpolymorphicbase + +Helper variable templates +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + _generated/libsemigroups__isderivedfromptransf + _generated/libsemigroups__isstatic + _generated/libsemigroups__isdynamic + _generated/libsemigroups__isptransf diff --git a/docs/source-old/report.rst b/docs/source-old/report.rst new file mode 100644 index 000000000..769ce7bf9 --- /dev/null +++ b/docs/source-old/report.rst @@ -0,0 +1,14 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +ReportGuard +=========== + +Declared in ``report.hpp``. + +.. doxygenstruct:: libsemigroups::ReportGuard + :project: libsemigroups + :members: diff --git a/docs/source-old/semigroupe.rst b/docs/source-old/semigroupe.rst new file mode 100644 index 000000000..5ead3cfcd --- /dev/null +++ b/docs/source-old/semigroupe.rst @@ -0,0 +1,51 @@ +Semigroupe +========== + +The algorithm implemented in the class ``FroidurePin`` +is based on `Algorithms for computing finite +semigroups `__, `Expository +Slides `__, and +`Semigroupe +2.01 `__ +by Jean-Eric Pin. + +Some of the features of `Semigroupe +2.01 `__ +are not yet implemented in ``FroidurePin``, this is a work in progress. +Missing features include those for: + +- Green’s relations, or classes +- finding a zero +- minimal ideal, principal left/right ideals, or indeed any ideals +- inverses +- local submonoids +- the kernel +- variety tests. + +These may be included in a future version. + +``libsemigroups`` performs roughly the same as `Semigroupe +2.01 `__ +when there is a known upper bound on the size of the semigroup being +enumerated, and this is used to initialise the data structures for the +semigroup; see ``libsemigroups::FroidurePin::reserve`` for more details. Note +that in `Semigroupe +2.01 `__ +it is always necessary to provide such an upper bound, but in +``libsemigroups`` it is not. + +The ``FroidurePin`` class has some advantages over `Semigroupe +2.01 `__ + +- there is a (hopefully) convenient C++ API, which makes it relatively + easy to create and manipulate semigroups and monoids +- more types of elements are supported +- it is relatively straightforward to add support for further types of + elements +- it is possible to enumerate a certain number of elements of a + semigroup or monoid (say if you are looking for an element with a + particular property), to stop, and then to start the enumeration + again at a later point +- it is possible to add more generators after a semigroup or monoid has + been constructed, without losing or having to recompute any + information that was previously known diff --git a/docs/source-old/semigroups.rst b/docs/source-old/semigroups.rst new file mode 100644 index 000000000..144b42134 --- /dev/null +++ b/docs/source-old/semigroups.rst @@ -0,0 +1,40 @@ +.. Copyright (c) 2019-2022, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Semigroups +========== + +.. cpp:namespace:: libsemigroups + +``libsemigroups`` implements several algorithms for computing the structure of +a finite semigroup or monoid. The main implementations are of the Froidure-Pin, +Konieczny, and Schreier-Sims (for permutation groups) algorithms; see the links +below for further details. + +The implementations of these algorithms are generic, and can be easily adapted +for user-defined types. In other words, it is possible to directly apply these +algorithms to any type that satisfy some minimal prerequisites, via traits +classes and/or the adapters described here. + +Many of the classes for semigroups in ``libsemigroups`` can be used +"interactively", in the sense that they can be run for a particular amount of +time, or until some condition is met; for further details see, for example, +:cpp:any:`void Runner::run_for(std::chrono::nanoseconds)` and +:cpp:func:`Runner::run_until`. + +The classes for semigroups and monoids in ``libsemigroups`` are: + +.. toctree:: + :maxdepth: 1 + + _generated/libsemigroups__froidurepinbase + _generated/libsemigroups__froidurepin + api/make-froidure-pin + _generated/libsemigroups__froidurepintraits + konieczny + _generated/libsemigroups__schreiersims + _generated/libsemigroups__schreiersimstraits + api/schreiersims-helper diff --git a/docs/source-old/sims1.rst b/docs/source-old/sims1.rst new file mode 100644 index 000000000..4693506b8 --- /dev/null +++ b/docs/source-old/sims1.rst @@ -0,0 +1,21 @@ +.. Copyright (c) 2022, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Sims1 +===== + +.. cpp:namespace:: libsemigroups + +The classes in ``libsemigroups`` for related to Sim's low index congruence +algorithm are: + +.. toctree:: + :maxdepth: 1 + + _generated/libsemigroups__sims1 + _generated/libsemigroups__sims1stats + _generated/libsemigroups__reporc + _generated/libsemigroups__minimalreporc diff --git a/docs/source-old/stephen.rst b/docs/source-old/stephen.rst new file mode 100644 index 000000000..befa6bd07 --- /dev/null +++ b/docs/source-old/stephen.rst @@ -0,0 +1,19 @@ +.. Copyright (c) 2022, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Stephen's procedure for finitely presented semigroups +===================================================== + +.. cpp:namespace:: libsemigroups + +This page contains links to the functionality in ``libsemigroups`` related to +Stephen's procedure for finitely presented semigroups. + +.. toctree:: + :maxdepth: 1 + + _generated/libsemigroups__stephen + api/stephen-helpers diff --git a/docs/source-old/transf.rst b/docs/source-old/transf.rst new file mode 100644 index 000000000..cf5d2ba75 --- /dev/null +++ b/docs/source-old/transf.rst @@ -0,0 +1,36 @@ +.. Copyright (c) 2019-21, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Transformations +=============== + +Defined in ``transf.hpp``. + +This page contains the documentation for functionality in ``libsemigroups`` for +transformations. + +.. toctree:: + :maxdepth: 2 + + _generated/libsemigroups__transf + +Validating +~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + api/transf_validate.rst + +Helper variable templates +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + _generated/libsemigroups__isstatic + _generated/libsemigroups__isdynamic + _generated/libsemigroups__istransf diff --git a/docs/source-old/types.rst b/docs/source-old/types.rst new file mode 100644 index 000000000..c9262cdda --- /dev/null +++ b/docs/source-old/types.rst @@ -0,0 +1,26 @@ +.. Copyright (c) 2019, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Types +===== + +``libsemigroups`` contains some type aliases, which are described in this +section. + +.. doxygenenum:: libsemigroups::tril + :project: libsemigroups + +.. doxygentypedef:: libsemigroups::letter_type + :project: libsemigroups + +.. doxygentypedef:: libsemigroups::word_type + :project: libsemigroups + +.. doxygentypedef:: libsemigroups::relation_type + :project: libsemigroups + +.. doxygenstruct:: libsemigroups::SmallestInteger + :project: libsemigroups diff --git a/docs/source-old/ukkonen.rst b/docs/source-old/ukkonen.rst new file mode 100644 index 000000000..027140e8b --- /dev/null +++ b/docs/source-old/ukkonen.rst @@ -0,0 +1,21 @@ +.. Copyright (c) 2023, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +Ukkonen +======= + +``libsemigroups`` contains an implementation of Ukkonen's algorithm for +constructing a generalised suffix tree representing a collection of words. + +The classes and structs related to Ukkonen's algorithm in ``libsemigroups`` are: + +.. toctree:: + :maxdepth: 1 + + _generated/libsemigroups__ukkonen + _generated/libsemigroups__ukkonen__node + _generated/libsemigroups__ukkonen__state + api/ukkonen-helper.rst diff --git a/docs/source-old/words.rst b/docs/source-old/words.rst new file mode 100644 index 000000000..d62a249b0 --- /dev/null +++ b/docs/source-old/words.rst @@ -0,0 +1,26 @@ +.. Copyright (c) 2020, J. D. Mitchell + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. _words: + +Words +===== + +This file contains documentation for functions for generating words and strings +in a given range and in a certain order. + +Functions +~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + api/silo.rst + api/sislo.rst + api/wilo.rst + api/wislo.rst + api/number_of_words.rst + api/literals.rst