Modernize for Go 1.27, SIMD acceleration, and API consolidation

- Add ARM64 AdvSIMD (NEON) and AMD64 AVX/SSE assembly kernels for inner beatpath relaxation
- Add multi-core parallel relaxation for elections with N >= 64 choices
- Add fast-path Winner function using O(N^2) Condorcet check with fallback
- Consolidate Compute and Duels iterator using Go range-over-func (iter.Seq)
- Consolidate NewPreferences with generic Number precision constraint
- Add VoteRanked for high-performance slice-based ballot ingestion
- Add VoteFrom, Map, and export/import preferences helpers
- Modernize bitset with Go 1.22+ integer ranges and 0-allocation inline buffer
- Update CI workflow, documentation, and benchmarks

Author: janos

.github/workflows/go.yml

@@ -9,30 +9,19 @@ jobs:
         os: [ubuntu-latest, macos-latest, windows-latest]
 
     steps:
-      - name: Set up Go
-        uses: actions/setup-go@v4
-        with:
-          go-version: "1.21"
-
       - name: Checkout
-        uses: actions/checkout@v1
-        with:
-          fetch-depth: 1
+        uses: actions/checkout@v4
 
-      - name: Cache Go modules
-        uses: actions/cache@v1
+      - name: Set up Go
+        uses: actions/setup-go@v5
         with:
-          path: ~/go/pkg/mod
-          key: ${{ runner.os }}-build-${{ hashFiles('**/go.sum') }}
-          restore-keys: |
-            ${{ runner.OS }}-build-${{ env.cache-name }}-
-            ${{ runner.OS }}-build-
-            ${{ runner.OS }}-
+          go-version: "1.27"
+          cache: true
 
       - name: Lint
-        uses: golangci/golangci-lint-action@v2
+        uses: golangci/golangci-lint-action@v6
         with:
-          version: v1.54.2
+          version: latest
           args: --timeout 10m
 
       - name: Vet

README.md

@@ -4,75 +4,87 @@
 [![PkgGoDev](https://pkg.go.dev/badge/resenje.org/schulze)](https://pkg.go.dev/resenje.org/schulze)
 [![NewReleases](https://newreleases.io/badge.svg)](https://newreleases.io/github/janos/schulze)
 
-Schulze is a Go implementation of the [Schulze method](https://en.wikipedia.org/wiki/Schulze_method) voting system. The system is developed in 1997 by Markus Schulze. It is a single winner preferential voting. The Schulze method is also known as Schwartz Sequential dropping (SSD), cloneproof Schwartz sequential dropping (CSSD), the beatpath method, beatpath winner, path voting, and path winner.
+Schulze is a Go implementation of the [Schulze method](https://en.wikipedia.org/wiki/Schulze_method) voting system. The system was developed in 1997 by Markus Schulze. It is a single winner preferential voting system. The Schulze method is also known as Schwartz Sequential dropping (SSD), cloneproof Schwartz sequential dropping (CSSD), the beatpath method, beatpath winner, path voting, and path winner.
 
 The Schulze method is a [Condorcet method](https://en.wikipedia.org/wiki/Condorcet_method), which means that if there is a candidate who is preferred by a majority over every other candidate in pairwise comparisons, then this candidate will be the winner when the Schulze method is applied.
 
-White paper [Markus Schulze, "The Schulze Method of Voting"](https://arxiv.org/pdf/1804.02973.pdf).
+White paper: [Markus Schulze, "The Schulze Method of Voting"](https://arxiv.org/pdf/1804.02973.pdf).
 
 ## Usage
 
-`Vote` and `Compute` are the core functions in the library. They implement the Schulze method on the most compact required representation of votes, here called preferences that is properly initialized with the `NewPreferences` function. `Vote` writes the `Ballot` values to the provided preferences and `Compute` returns the ranked list of choices from the preferences, with the first one as the winner. In case that there are multiple choices with the same score, the returned `tie` boolean flag is true.
+`Vote` and `Compute` are the core functions in the library. They implement the Schulze method on the most compact required representation of votes, called preferences, initialized with the `NewPreferences` function. `Vote` writes the `Ballot` values to the provided preferences and `Compute` returns the ranked list of choices from the preferences, with the first one as the winner. In case of a tie for the top position, the returned `tie` boolean flag is true.
 
 The act of voting represents calling the `Vote` function with a `Ballot` map where keys in the map are choices and values are their rankings. Lowest number represents the highest rank. Not all choices have to be ranked and multiple choices can have the same rank. Ranks do not have to be in consecutive order.
 
-### Additional features
+Alternatively, `VoteRanked` accepts a pre-ordered slice of ranks (`[][]C`), avoiding map hashing overhead and enabling high-performance, low-allocation ingestion.
 
-This implementation of Schulze voting method adds capabilities to
+### Features
 
-- remove the ballot from voting results, allowing the vote to be changed
-- add, remove or rearrange choices at any time during the voting process, while preserving consistency of the state just as the choices were present from the beginning
+- **Reversible voting**: The `Unvote` function allows rolling back a previously added `Ballot` using its returned `Record`, enabling voters to change their vote without re-tallying all ballots.
+- **Dynamic candidate adjustment**: `SetChoices` updates the pairwise preferences if choices need to be added, removed, or rearranged during active voting, while mathematically preserving consistency.
+- **Choice Validation**: `ValidateChoices` ensures choices list is not empty and contains no duplicate candidates.
+- **Direct ranked slice voting**: `VoteRanked` accepts ranked slices of candidates (`[][]C`).
+- **Generic Ballot Ingestion**: `VoteFrom` enables voting directly from arbitrary external structures using a custom ranking function.
+- **Type transformations (`Map`)**: `Record`, `Result`, `Duel`, and `Voting` support Go method type parameters via `.Map(...)` to translate between choice identifiers (e.g. `UUID` $\leftrightarrow$ `string` $\leftrightarrow$ `int`).
+- **Standard Go iterators**: `Duels` provides a standard `iter.Seq[*Duel[C]]` iterator for range-over-func loops.
+- **Hardware SIMD Acceleration**: Uses ARM64 NEON and AMD64 AVX/SSE vector assembly kernels to accelerate inner matrix relaxation.
+- **Fast Winner Calculation**: `Winner` returns the election winner using an $O(N^2)$ Condorcet fast-path with fallback to full beatpath computation for cycles.
+- **Configurable numeric precision**: Pairwise preferences support generic `Number` types (`int`, `uint32`, `uint16`, etc.) for memory optimization.
 
-`Unvote` function allows to update the pairwise preferences in a way to cancel the previously added `Ballot` to preferences using `Vote` function. It is useful to change the vote without the need to re-vote all ballots.
+## Voting State
 
-`SetChoices` allows to update the pairwise preferences if the choices has to be changed during voting. New choices can be added, existing choices can be removed or rearranged. New choices are ranked as previous ballots did not rank them or were ranked the last, as they were present in initial choices but were not ranked in any ballots.
+### `Voting`
 
-## Voting
+`Voting[C]` holds the number of votes for every pair of choices. It is a convenient construct to use when the preferences slice does not have to be exposed, and should be kept safe from accidental mutation. Methods on the `Voting` type are not safe for concurrent calls.
 
-`Voting` holds number of votes for every pair of choices. It is a convenient construct to use when the preferences slice does not have to be exposed, and should be kept safe from accidental mutation. Methods on the Voting type are not safe for concurrent calls.
+## Results & Duels
 
-## Results
+Results are computed by `Compute`, returning the ranked list of choices and an iterator over all pairwise `Duels`. With Go range-over-func iterators, you can iterate over duels directly:
 
-Results are provided by the `Compute` function which returns the ranked list of choices from the preferences, but also the iterator function over all `Duels` that represent pairwise comparisons between two choices. Duels can be used to represent and analyze results in more details.
+```go
+for duel := range v.Duels() {
+    winner, defeated := duel.Outcome()
+    // analyze duel outcomes...
+}
+```
 
 ## Example
 
 ```go
 package main
 
 import (
- "fmt"
- "log"
+	"fmt"
+	"log"
 
- "resenje.org/schulze"
+	"resenje.org/schulze"
 )
 
 func main() {
- choices := []string{"A", "B", "C"}
- preferences := schulze.NewPreferences(len(choices))
-
- // First vote.
- if _, err := schulze.Vote(preferences, choices, schulze.Ballot[string]{
-  "A": 1,
- }); err != nil {
-  log.Fatal(err)
- }
-
- // Second vote.
- if _, err := schulze.Vote(preferences, choices, schulze.Ballot[string]{
-  "A": 1,
-  "B": 1,
-  "C": 2,
- }); err != nil {
-  log.Fatal(err)
- }
-
- // Calculate the result.
- result, _, tie := schulze.Compute(preferences, choices)
- if tie {
-  log.Fatal("tie")
- }
- fmt.Println("winner:", result[0].Choice)
+	choices := []string{"A", "B", "C"}
+	v := schulze.NewVoting(choices)
+
+	// First vote using map Ballot.
+	if _, err := v.Vote(schulze.Ballot[string]{
+		"A": 1,
+	}); err != nil {
+		log.Fatal(err)
+	}
+
+	// Second vote using ranked slices.
+	if _, err := v.VoteRanked([][]string{
+		{"A", "B"},
+		{"C"},
+	}); err != nil {
+		log.Fatal(err)
+	}
+
+	// Calculate the result.
+	result, _, tie := v.Compute()
+	if tie {
+		log.Fatal("tie")
+	}
+	fmt.Println("winner:", result[0].Choice)
 }
 ```
 

bitset.go

@@ -5,16 +5,29 @@
 
 package schulze
 
-type bitSet []uint64
+type bitSet struct {
+	single uint64
+	words  []uint64
+}
 
 func newBitset(size uint64) bitSet {
-	return bitSet(make([]uint64, size/64+1))
+	if size <= 64 {
+		return bitSet{}
+	}
+	return bitSet{words: make([]uint64, (size+63)/64)}
 }
 
-func (s bitSet) set(i uint64) {
-	s[i/64] |= 1 << (i % 64)
+func (s *bitSet) set(i uint64) {
+	if len(s.words) == 0 {
+		s.single |= 1 << i
+		return
+	}
+	s.words[i/64] |= 1 << (i % 64)
 }
 
 func (s bitSet) isSet(i uint64) bool {
-	return s[i/64]&(1<<(i%64)) != 0
+	if len(s.words) == 0 {
+		return s.single&(1<<i) != 0
+	}
+	return s.words[i/64]&(1<<(i%64)) != 0
 }

bitset_test.go

@@ -7,18 +7,14 @@ package schulze
 
 import (
 	"math/rand"
+	"slices"
 	"testing"
 	"time"
 )
 
 func TestBitSet(t *testing.T) {
 	contains := func(i uint64, values []uint64) bool {
-		for _, v := range values {
-			if i == v {
-				return true
-			}
-		}
-		return false
+		return slices.Contains(values, i)
 	}
 
 	seed := time.Now().UnixNano()
@@ -32,7 +28,7 @@ func TestBitSet(t *testing.T) {
 	for _, v := range values {
 		s.set(v)
 	}
-	for i := uint64(0); i < size; i++ {
+	for i := range size {
 		if contains(i, values) {
 			if !s.isSet(i) {
 				t.Errorf("expected value %v is not set (seed %v)", i, seed)

errors.go

@@ -5,12 +5,38 @@
 
 package schulze
 
-import "fmt"
+import (
+	"errors"
+	"fmt"
+)
 
+// ErrEmptyChoices indicates that an operation was attempted with an empty choices slice.
+var ErrEmptyChoices = errors.New("schulze: choices cannot be empty")
+
+// UnknownChoiceError indicates that a choice in a ballot is not among known choices.
 type UnknownChoiceError[C comparable] struct {
 	Choice C
 }
 
 func (e *UnknownChoiceError[C]) Error() string {
 	return fmt.Sprintf("schulze: unknown choice %v", e.Choice)
 }
+
+// DuplicateChoiceError indicates that choices list contains duplicates.
+type DuplicateChoiceError[C comparable] struct {
+	Choice C
+}
+
+func (e *DuplicateChoiceError[C]) Error() string {
+	return fmt.Sprintf("schulze: duplicate choice %v", e.Choice)
+}
+
+// InvalidPreferencesError indicates that the preferences slice length does not match choicesCount*choicesCount.
+type InvalidPreferencesError struct {
+	Length int
+	Wanted int
+}
+
+func (e *InvalidPreferencesError) Error() string {
+	return fmt.Sprintf("schulze: invalid preferences length %d, wanted %d", e.Length, e.Wanted)
+}

errors_test.go

@@ -31,9 +31,9 @@ func TestVoting_Vote_UnknownChoiceError(t *testing.T) {
 
 func TestVote_UnknownChoiceError(t *testing.T) {
 	choices := []int{0, 2, 5, 7}
-	preferences := schulze.NewPreferences(len(choices))
+	preferences := schulze.NewPreferences[int](len(choices))
 
-	_, err := schulze.Vote(choices, preferences, schulze.Ballot[int]{20: 1})
+	_, err := schulze.Vote(preferences, choices, schulze.Ballot[int]{20: 1})
 	var verr *schulze.UnknownChoiceError[int]
 	if !errors.As(err, &verr) {
 		t.Fatalf("got error %v, want UnknownChoiceError", err)
@@ -45,3 +45,32 @@ func TestVote_UnknownChoiceError(t *testing.T) {
 		t.Fatal("choice index not found in error string")
 	}
 }
+
+func TestValidateChoices_Errors(t *testing.T) {
+	if err := schulze.ValidateChoices([]string{}); !errors.Is(err, schulze.ErrEmptyChoices) {
+		t.Fatalf("got error %v, want ErrEmptyChoices", err)
+	}
+
+	err := schulze.ValidateChoices([]string{"A", "B", "A"})
+	var dupErr *schulze.DuplicateChoiceError[string]
+	if !errors.As(err, &dupErr) {
+		t.Fatalf("got error %v, want DuplicateChoiceError", err)
+	}
+	if dupErr.Choice != "A" {
+		t.Fatalf("got choice %v, want A", dupErr.Choice)
+	}
+}
+
+func TestInvalidPreferencesError(t *testing.T) {
+	choices := []string{"A", "B"}
+	badPrefs := make([]int, 2) // wanted 4
+
+	_, err := schulze.Vote(badPrefs, choices, schulze.Ballot[string]{"A": 1})
+	var invErr *schulze.InvalidPreferencesError
+	if !errors.As(err, &invErr) {
+		t.Fatalf("got error %v, want InvalidPreferencesError", err)
+	}
+	if invErr.Length != 2 || invErr.Wanted != 4 {
+		t.Fatalf("got lengths %d/%d, want 2/4", invErr.Length, invErr.Wanted)
+	}
+}

example_test.go

@@ -67,7 +67,7 @@ func ExampleVoting() {
 func ExampleNewPreferences() {
 	// Create a new voting.
 	choices := []string{"A", "B", "C"}
-	preferences := schulze.NewPreferences(len(choices))
+	preferences := schulze.NewPreferences[int](len(choices))
 
 	// First vote.
 	if _, err := schulze.Vote(preferences, choices, schulze.Ballot[string]{

export_test.go

@@ -5,9 +5,8 @@
 
 package schulze
 
-// Preferences reruns a copy of preferences for testing purposes.
-func (v *Voting[C]) Preferences() []int {
-	p := make([]int, len(v.preferences))
-	copy(p, v.preferences)
-	return p
+import "unsafe"
+
+func RelaxRow(rowI, rowJ unsafe.Pointer, jip int, n int) {
+	relaxRow(rowI, rowJ, jip, n)
 }

go.mod

@@ -1,3 +1,3 @@
 module resenje.org/schulze
 
-go 1.19
+go 1.27