Add FroidurePin algorithm by jswent · Pull Request #36 · libsemigroups/Semigroups.jl

jswent · 2026-02-08T13:23:31Z

Addresses #32. Opening for visibility, final PR will be rebased when #33 and #35 are merged.

add FroidurePinBase binding
add FroidurePin<E> template instantiations
add high-level FroidurePin julia API

codecov-commenter · 2026-02-08T13:32:03Z

Codecov Report

❌ Patch coverage is 4.97238% with 172 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@2feb9d5). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
src/froidure-pin.jl	0.00%	138 Missing ⚠️
src/libsemigroups/runner.jl	0.00%	25 Missing ⚠️
src/libsemigroups/word-graph.jl	50.00%	9 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #36   +/-   ##
=======================================
  Coverage        ?   49.82%           
=======================================
  Files           ?       10           
  Lines           ?      570           
  Branches        ?        0           
=======================================
  Hits            ?      284           
  Misses          ?      286           
  Partials        ?        0

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

note that position, current_position conflicts with Julia Base.*, so we need to reference Semigroups.position, etc. directly

james-d-mitchell · 2026-02-10T10:53:30Z

test/test_froidure_pin.jl

+@testset "FroidurePin inherited FroidurePinBase methods" begin
+    LS = Semigroups.LibSemigroups
+
+    t1 = LS.Transf1(StdVector{UInt8}(UInt8[1, 0, 2]))


I think we shouldn't be testing the lower-level stuff, only its higher level equivalents (it is these after all that we want to be used and working). I.e. I think here you are testing the implementation, which might change even if the API doesn't.

oops didn't mean to commit these tests. I was going to work on porting test suite from C++/Python tomorrow which will replace this file

james-d-mitchell · 2026-02-10T10:55:23Z

src/froidure-pin.jl

+# ============================================================================
+
+"""
+    length(S::FroidurePin) -> Int


This should be called size the name length conflicts with something else. Was there a reason to call it length?

Only because overloading Base.length is the standard convention for data structures, but I just looked at Python and saw that there is no overload for len - so I'm assuming you'd rather use size?

james-d-mitchell · 2026-02-10T10:56:04Z

src/froidure-pin.jl

+# Display
+# ============================================================================
+
+function Base.show(io::IO, S::FroidurePin{E}) where {E}


This shouldn't be necessary, use to_human_readable_repr from libsemigroups itself, to avoid code duplication.

james-d-mitchell · 2026-02-10T10:57:56Z

src/froidure-pin.jl

+Return the 1-based position of `x` in `S`, or `nothing` if not found.
+Triggers full enumeration.
+"""
+function position(S::FroidurePin{E}, x::E) where {E}


This doesn't seem to work as expected:

S = FroidurePin([Transf([1, 1, 2]), Transf([2, 1, 3]), Transf([2, 3, 1])]) julia> position(S, S[10]) ERROR: MethodError: no method matching position(::FroidurePin{Transf{UInt8}}, ::Transf{UInt8}) The function `position` exists, but no method is defined for this combination of argument types. Closest candidates are: position(::Base.JuliaSyntax.ParseState, ::Any...) @ Base /private/tmp/julia-20260101-8411-jav5tg/julia-1.12.3/base/JuliaSyntax/src/parser.jl:116 position(::Base.JuliaSyntax.ParseStream) @ Base /private/tmp/julia-20260101-8411-jav5tg/julia-1.12.3/base/JuliaSyntax/src/parse_stream.jl:956 position(::Base.Filesystem.File) @ Base filesystem.jl:348 ... Stacktrace: [1] top-level scope @ REPL[19]:1

not sure why

Ah yeah I wasn't sure what to do about this so I just left it TBD; should've made a note.

So position is defined in Julia's Base (Base.position) which is designated for IO streams, exporting this function directly causes a conflict. We can overload Base.position so this functionality works, but I was going to do some research first and make sure there aren't any underlying problems since it was designed for separate purpose. I'm assuming this is fine and what I'll end up doing, but wanted to look at some similar packages first.

Right now you can use it by calling Semigroups.position. Or if you want to use it directly you can run:

import Semigroups: position position(args)

in your repl.

james-d-mitchell · 2026-02-10T11:00:38Z

src/froidure-pin.jl

+_to_word_0based(word) = StdVector{CxxULong}(CxxULong[w - 1 for w in word])
+
+# Check if C++ returned UNDEFINED and convert to nothing (with +1 shift)
+_maybe_undefined(val::UInt32) = is_undefined(val, UInt32) ? nothing : Int(val) + 1


In the python bindings we generally returned UNDEFINED instead of the perhaps more canonical None, this was to make it more similar to the C++ bindings, and to simplify some of the code. If you want to use nothing here instead of UNDEFINED I don't object, just wanted to point out that it should be consistently used everywhere, and that this convention should be recorded somewhere in the CONTRIBUTING.md file.

We should discuss tmr and weigh pros/cons. My justification was to keep it as close to Julian convention as possible for easier integration into other libraries, but I'm not attached to it.

james-d-mitchell · 2026-02-10T11:02:18Z

src/froidure-pin.jl

+"""
+    FroidurePin(gens::AbstractVector{E}) where {E}
+
+Construct a FroidurePin semigroup from a vector of generators.


I'd really prefer the doc to be copied/generated from the C++ doc rather than partially (and not completely accurately, sorry!) paraphrased here. This will increasingly become an issue the more stuff we add/change/etc.

Sorry I should've made a note that the docs are not ready. I'm going to delete and rebuild this after #33 and #35 get merged and write up the full docstrings and update docs site.

Re: generating docs automatically, I looked at it briefly and it seemed it was going to be easier to just copy/paste/edit manually but we can discuss tmr if doing that programmatically would be better for LTS.

james-d-mitchell

This generally looks amazing, there are one or two persistent issues though:

reimplementing things that already exist in libsemigroups in this instance show
it'd be good if we could start copying/generating the doc from libsemigroups itself.

jswent · 2026-02-10T11:51:36Z

@james-d-mitchell sounds good, will make these changes tmr. Does the WordGraph/Runner functionality look okay to you?

jswent · 2026-02-10T11:56:03Z

Todo list for final PR:

Change from Base.length -> size
Call to_human_readable_repr for Base.show
Overload Base.position
Port over test suite from C++/Python
Copy and edit docstrings from C++
Update docs site algorithms page

jswent and others added 21 commits February 7, 2026 12:58

feat: add Runner, RunnerState

46c1d74

run formatter

b7b7093

fix: attempt fmt fix for consteval ubuntu

baade42

feat: run_until! TimePeriod input, convert implicitly

44ee3ed

runner: update dependencies

55042a2

runner: add run_until! using @safe_cfunction + fptr

f08aa22

runner: fix exports

17f9a3f

runner: add basic binding tests

8f03fb7

remove Dates compat, unnecessary

748e827

Merge branch 'main' into add-runner

20b99b2

fix: bad merge import

5da656c

fix: non-negative input to run_for!

71f8b16

fix formatter imports again

d416cd2

add basic read-only WordGraph for FroidurePin

403c76b

add some basic tests for WordGraph

fc140f0

Merge branch 'add-wordgraph' into add-froidure-pin

0b8fa73

add FroidurePinBase bindings

71ab653

run formatter

be30a3a

add FroidurePin C++ template instantiations

86639aa

update build for FroidurePin<E>

bcd27d4

add tests for FroidurePin<E> C++ bindings

c2e8cae

jswent added this to the v0.0.1 milestone Feb 8, 2026

jswent added enhancement New feature or request bindings Related to C++ bindings code or C++ <-> Julia interaction algorithms labels Feb 8, 2026

jswent requested a review from james-d-mitchell February 8, 2026 13:23

jswent added 3 commits February 8, 2026 14:10

add FroidurePin julia type defs and constructor

eeee0ea

add FroidurePin runner config

02f5e38

add FroidurePin position, products, idempotents

6fb112c

note that position, current_position conflicts with Julia Base.*, so we need to reference Semigroups.position, etc. directly

jswent added 2 commits February 8, 2026 16:49

froidure-pin: add factorization, words, structure, elements

1557faa

froidure-pin: rules, cayley_graph, mutators

556195e

james-d-mitchell reviewed Feb 10, 2026

View reviewed changes

jswent force-pushed the main branch from a31c4ff to af5ae4a Compare February 18, 2026 21:08

Conversation

jswent commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov-commenter commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jswent Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

james-d-mitchell left a comment

Choose a reason for hiding this comment

Uh oh!

jswent commented Feb 10, 2026

Uh oh!

jswent commented Feb 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jswent commented Feb 8, 2026 •

edited

Loading

codecov-commenter commented Feb 8, 2026 •

edited

Loading

jswent Feb 10, 2026 •

edited

Loading