xpermLibraryLink

This is a fork of xperm C-sources used in the xAct project. The purpose of this fork is to replace the WSTP connection used by the original xperm C-source by a newer and faster LibraryLink connection. This is a shared library that is loaded on-demand when required. This branch also contains an experimental canonicalizer inspired by Ben Niehoff's work; see the implementation status below.

Wolfram Language paclet

The wrapper is available as the xPermLibraryLink paclet in the xAct`xPermLibraryLink` context. Build and install it for the current user:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --target install-paclet --parallel

Then, in a fresh Wolfram kernel:

PacletDataRebuild[]; (* Only if you install this paclet for the first time *)
Needs["xAct`xPermLibraryLink`"];
LoadxPermLibraryLink[Automatic, True]

Needs loads xPerm when necessary. LoadxPermLibraryLink uses the native library bundled with this paclet; True selects the Niehoff canonicalizer. Use LoadxPermLibraryLink[] for the original xPerm canonicalizer and UnloadxPermLibraryLink[] to restore xPerm's previous native definitions and availability flag. Loading the package alone does not replace those definitions. Manual WSTP uninstallation is unnecessary: activation replaces its definitions and preserves them for restoration on unload.

See PACLET.md for prerequisites, installation, archive creation, context migration, and integration tests.

Version 0.3.1 provides Mathematica's built-in TensorReduce as a third backend, with per-call selection:

LoadxPermLibraryLink[Method -> "Niehoff"];
ToCanonical[expr, Method -> "TensorReduce"]
ToCanonical[expr, Method -> "xPerm"]

CanonicalPerm accepts the same backend names. Existing boolean loader calls remain supported. See backend selection for defaults, xTensor's existing derivative Method, and how the symbolic tensor adapter represents the signed permutation problem.

Algorithm and source documentation

The Doxygen guide connects both production backends to their papers and explains the implementation choices. Start with the algorithm overview, then read the permutation conventions, the Butler–Portugal walkthrough, and the Niehoff paper-to-code map. The guide includes a runnable symmetry-propagation example, API contracts, source links, and the reasons for the pruning refinements.

To generate searchable HTML with Doxygen 1.9.1 or newer (Graphviz optional):

cmake -S . -B build-docs -DBUILD_LIBRARYLINK=OFF -DBUILD_TESTING=OFF \
  -DBUILD_DOCUMENTATION=ON
cmake --build build-docs --target docs

Open build-docs/documentation/html/index.html. This target needs neither Wolfram Language nor its SDK. See documentation build instructions for configuration and maintenance. That guide also explains LaTeX/PDF output (DOCUMENTATION_PDF=ON, target docs-pdf) and selecting the documentation targets in VS Code CMake Tools.

Prerequisites

• A working installation of xAct.
• Wolfram Language 12.1 or newer for the paclet format, with a licensed kernel for the paclet and install-paclet targets. Runtime validation is described in PACLET.md.
• CMake >= 3.15 (only for building from source).
• A C\C++ compiler (only for building from source).

Precompiled libraries

The original libraries under binaries/ predate the fixes on this branch. Build the paclet to include the current native library. A distributed .paclet archive can be installed with PacletInstall["/absolute/path/to/archive.paclet"]; there is no need to copy its native library onto $LibraryPath.

Status of the Niehoff branch

The C++ canonicalizer implements incremental label orbits, total-slot-symmetry inference, dummy-partner propagation, early sign checks, and redundant-instance pruning based on Niehoff's Faster tensor canonicalization. The formerly factorial symmetric-contraction family now retains one configuration per step. The code remains experimental: arbitrary groups, including symmetry of whole pairs without individual slot swaps, can still require factorial search. See ACCELERATION.md for the exact scope, invariants, tests, and comparisons with the GitHub baseline.

canonicalizeLegacyInput and LL_niehoff_canonical_perm use the existing signed permutation data layout (the last two points encode the sign). Canonical results are lexicographically minimal in natural slot/label order, independently of the supplied stabilizer-chain base. This convention can differ from the original xPerm canonical representative. Unlisted real labels are fixed. Dummy pairs preserve their listed variance when there is no metric; pairs and repeated labels need not be listed in ascending order.

The extended API treats each total-symmetry subset as an additional declaration of symmetric or antisymmetric slot permutations. It combines these with the supplied slot generators and rebuilds the group. Subset entries are unordered, must be disjoint, and cannot contain sign points. The production search infers valid total subsets from both legacy and extended inputs and uses them for propagation and pruning.

Build and run the independent small-group oracle and LibraryLink boundary tests without a Wolfram installation:

cmake -S . -B build-tests -DBUILD_LIBRARYLINK=OFF -DCMAKE_BUILD_TYPE=Release
cmake --build build-tests --parallel
ctest --test-dir build-tests --output-on-failure

See BUILD.md for shared-library and sanitizer builds. Existing files under binaries/ are upstream artifacts and are not rebuilt by source changes; rebuild the library to use these fixes.

See ASSESSMENT.md for the paper comparison, confirmed defects, repairs, validation results, and remaining algorithmic work.