API referenceο
Filename: braid.py Description: Main braid class Authors: Baptiste Labat Created: 2025-05-24 Repository: https://github.com/baptistelabat/braidpy License: Mozilla Public License 2.0
- class braidpy.braid.BraidWordNotation(value)ο
-
- ARTIN = 'ARTIN'ο
- ALPHA = 'ALPHA'ο
- DEFAULT = 'DEFAULT'ο
- braidpy.braid.single_crossing_braiding_process(process: Tuple[int | Tuple[int, ...], ...]) List[int]ο
Flattens a tuple of braiding steps into a list of signed crossings.
Each step may be a single crossing or multiple simultaneous crossings. To get Artin generators we need only consecutive single crossing, which is topologically equivalent
- class braidpy.braid.Braid(process: int | Tuple[int | Tuple[BraidProcess, ...], ...], n_strands: int | None = None)ο
Bases:
objectSometimes referred as algebraic braids :param process: list of Artinβs generator, which may group or not by parenthesis (tuples) :type process: BraidProcess :param n_strands: number of strands. Default to the minimum number needed for process :type n_strands: Optional[int]
- property generatorsο
- property main_generatorο
A main generator of a braid word w is the generator with the lowest index https://pure.tue.nl/ws/portalfiles/portal/67742824/630595-1.pdf page 33
- format_to_notation(target: str = '')ο
Inspired from https://github.com/abhikpal/dehornoy/blob/master/braid.py
Allow to format the braidword using several classical notations.:
The Artin representation can also be used in a latex file.
The neutral element is βeβ for the Artin representation and β#β for alpha.
- format(generator_symbols: list[str] = None, inverse_generator_symbols: list[str] = None, zero_symbol: str = 'e', separator: str = '') strο
Allow to format the braid word following different formats.
Note that the power are limited to -1/1 due to the actual braid word definition (not possible to display ΟβΒ² for example)
See also format_to_notation for simpler predefined format
- Parameters:
- Returns:
the formated braid word
- Return type:
- no_zero()ο
Suppress all the zero steps (multiplication by neutral element)
- Returns:
Braid
- word_length()ο
Length of the word including neutral element
- Returns:
the length of the braid word
- Return type:
- word_eq(other)ο
- inverse() Braidο
Return the inverse of the braid This corresponds to the image of the braid in a mirror. Both order and signs are reversed
- Returns:
the inverse braid
- Return type:
- n(n_strands) Braidο
Compact notation to allow to change the number of strands
- Parameters:
n_strands
Returns:
- flip() Braidο
Flip the braid This corresponds to the image of the braid in a mirror on the side of the braid reordered from left to right The strands are reversed, not the order of operations Sign is also changed. This step is often used when braiding
>>> b = Braid([1], 3) >>> basic_3_braid = (b*(b.flip()))**3
- Returns:
the reversed braid
- Return type:
- up_side_down() Braidο
Invert up and down crossing operations
For hair braiding this is called βinversΓ©β
- Returns:
the mirrored braid
- Return type:
- is_reduced() boolο
A braid word w is reduced either if it is the null string, or the empty braid, or if the main generator of w occurs only positively or only negatively. https://pure.tue.nl/ws/portalfiles/portal/67742824/630595-1.pdf page 33
- get_canonical_factors() GarsideCanonicalFactorsο
Get decomposition in left normal form
Relies on math_braid implementation from J. Cha et al, βAn Efficient Implementation of Braid Groupsβ, Advances in Cryptology: Proceedings of ASIACRYPT 2001, Lecture Notes in Computer Science (2001), 144β156. https://www.iacr.org/archive/asiacrypt2001/22480144.pdf
- Returns:
the unique decomposition of the braid according to left convention
- Return type:
GarsideCanonicalFactors
- to_matrix() MutableDenseMatrixο
Convert braid to its (unreduced) Burau matrix representation.
- to_reduced_matrix()ο
Return the reduced Burau representation
odo Implementation not finished
- perm() list[PositiveInt]ο
Compute the permutation corresponding to the braid
This is a braid invariant.
- Returns:
return the final permutation due to braid
- Return type:
- is_palindromic()ο
- is_involutive() boolο
Returns true if inverse of braid word ie the same as braid word This probably works only for the neutral element
- Returns:
True if braid word is involutive
- Return type:
- is_periodic() boolο
braid x is periodic if and only if its nth power or its (n β 1)st power is a power of the half-twist β
https://hal.science/hal-00647035v2/file/B_nNTHClassificationv5.pdf
Periodic braid are roots of β**m https://homepages.math.uic.edu/~jaca2009/notes/Meneses.pdf
- is_brunnian() boolο
A Brunnian braid is a braid that becomes trivial upon removal of any one of its strings. Brunnian braids form a subgroup of the braid group
https://en.wikipedia.org/wiki/Brunnian_link#Brunnian_braids
- Returns:
True if Brunnian
- Return type:
- is_reducible() boolο
- If a braid is reducible, it means that the strands can be separated into groups of strands
(less groups than number of strands), such that each group is running inside one tube. The tubes themselves can form a braid
- Returns:
bool
- to_parametric_strands(amplitude: float = 0.2) List[ParametricStrand]ο
Converts a braid into a list of 3D parametric strand paths.
- Parameters:
braid β The Braid object containing crossing generators.
amplitude β Height of the sine wave for over/under crossings.
- Returns:
A list of ParametricStrand objects representing the strands.
- draw()ο
Draw the braid in the terminal with arrows allowing to better check the differnet operations (with colors !)
- Returns:
return the braid itself to allow to debug in a chain
- Return type:
- plot(style='ext', line_width=3, gap_size=3, color='rainbow', save=False)ο
Plot the braid using library braid-visualiser https://github.com/rexgreenway/braid-visualiser
- Parameters:
style (Optional(str)) β βcompβ or βextβ(default) βcompβ renders the image of the braid in a compact style with crossings parallel to one another if possible. βextβ, for extended, shows the crossings in series.
line_width (Optional(int)) β Default to 3 Thickness of the strands in the figure.
gap_size (Optional(int)) β Default to 3 Amount of space shown at crossings for undercrossing strands.
color (str) β Multicolor strands defined by βrainbowβ. Single fixed colour for all strands can be chosen from: {βbβ: blue, βgβ: green, βrβ: red, βcβ: cyan, βmβ: magenta, βyβ: yellow, βkβ: black, βwβ: white}
save (bool) β if True save to file βtest.svgβ
- Returns:
return the slightly modified braid to allow to debug in a chain
- Return type:
- braidpy.braid.slide_strand(n_slide, start_index=1, sign: int = 1)ο
Combine Artin Generator to move one braid over or under several braids
This is noted as (aiβ¦as) by Garside where i=start_index and s= i+n_slide
Ξ s corresponds to start_index=1 (default) and n_slide=s-1
- braidpy.braid.weave_strand(n_slide, start_index=1, sign: int = 1)ο
Combine Artin Generator to move one braid over/under/over⦠or under/over/under⦠several braids
Filename: artin_generators.py Description: Artinβs generators enables to describe a braid by successive crossing operations Authors: Baptiste Labat Created: 2025-05-30 Repository: https://github.com/baptistelabat/braidpy License: Mozilla Public License 2.0
- class braidpy.artin_generators.a(process: int | Tuple[int | Tuple[BraidProcess, ...], ...], n_strands: int | None = None)ο
Bases:
BraidThis class is a shortcut to be able to use a compact notation with Artinβs generators
Filename: braid_catalog.py Description: A catalog of different remarkable braids Authors: Baptiste Labat Created: 2025-05-30 Repository: https://github.com/baptistelabat/braidpy License: Mozilla Public License 2.0
- braidpy.braid_catalog.garside_half_twist_braid(n_strands: StrictlyPositiveInt) Braidο
Compute the Garside half twist braid also known as Garside element βn or (simply β if n=n_strands-1) βΒ² is known to generate the βcenterβ of the braid group Bn+1. This is the biggest simple element.
It is sometimes called fundamental braid. It can be obtained by recursion βn = Ο1Ο2β¦Οnβ1βnβ1
Demi-vrille
Composition of half_twist is giving a βtorsadeβ
- Parameters:
n_strands (StrictlyPositiveInt) β number of strands
- Returns:
Braid
- braidpy.braid_catalog.full_twist_braid(n_strands: StrictlyPositiveInt) Braidο
Compute the full twist braid βnΒ² which is the square of Garside half twist braid βn It is known to generate the βcenterβ of the braid group Bn.
Vrille
Composition of twist is giving a βtorsadeβ
- Parameters:
n_strands (StrictlyPositiveInt) β number of strands
- Returns:
Braid
- braidpy.braid_catalog.flat3() Tuple[Braid, int]ο
Basic braid with 3 strands going above central braid
ABOK 2965: βFLAT, ENGLISH, ORDINARY or COMMON SINNET is the plat or braid seen in schoolgirl pigtails. It is made of three strands and is the simplest possible plat. To make: Secure three strands together and make the end fast to a hook or nail. Hold two strands in the right hand and one in the left. Bring the outer right strand down across its sister strand and lay it parallel to and below the single left strand. Now bring the upper Ie ft strand down across its sister strand and lay it parallel to and below the single right strand. Repeat alternatelyβ
- Returns:
the braid object describing the single step to realize the braid n: the number of iterations to get back to initial order of strands
- Return type:
- braidpy.braid_catalog.inverted_flat3() Tuple[Braid, int]ο
Basic braid with 3 strands going below central braid
ABOK 2966: βPossibly a quicker but less usual way to make this plat is - to pass the strands at the back, employing only the first and second fingers and the thumbsβ
- Returns:
the braid object describing the single step to realize the braid n: the number of iterations to get back to initial order of strands
- Return type:
- braidpy.braid_catalog.square4() Tuple[Braid, int]ο
Basic round braid with 4 strands
- Returns:
the braid object describing the single step to realize the braid n: the number of iterations to get back to initial order of strands
- Return type:
- braidpy.braid_catalog.asymmetric_flat4() Tuple[Braid, int]ο
Basic flat braid with 4 strands
https://www.youtube.com/watch?v=7lTFIzm9BLY
ABOK 2969: βUnless for some special purpose, this method is usually limited to an odd number of strands, as with an even number of strands the sinnet is unsymmetrical. But I have seen the braid, made as if with three strands in the left hand and one in the right hand, as here pictured, used as edging on theater-seat upholstery. Of course it was machine-made.β
- Returns:
the braid object describing the single step to realize the braid n: the number of iterations to get back to initial order of strands
- Return type:
- braidpy.braid_catalog.flat6() Tuple[Braid, int]ο
This one is probably not unique !
https://www.youtube.com/watch?v=ZHWlYBxL-mA
- Returns:
the braid object describing the single step to realize the braid n: the number of iterations to get back to initial order of strands
- Return type:
- braidpy.braid_catalog.regular_flat6() Tuple[Braid, int]ο
https://www.youtube.com/watch?v=J65kCzm_BtI
- Returns:
the braid object describing the single step to realize the braid n: the number of iterations to get back to initial order of strands
- Return type:
- braidpy.braid_catalog.double_flat3(parallel: bool = True)ο
if parallel = False ABOK 2971: βIf the same method of turning edges is applied where units of two or three parallel round cords are used, instead of single strands, a distinctive sinnet resultsβ
if parallel = True ABOK 2972: βIn this sinnet the strands are double and parallel. The effect is very different from the last, in which the edges were turned.β
- Returns:
the braid object describing the single step to realize the braid n: the number of iterations to get back to initial order of strands
- Return type:
- braidpy.braid_catalog.weave3()ο
This a 3 strands braid were 2 braids are running parallel while the third one is weaving them
ABOK 2973: βThe number of sinnets that are possible with three strands only seem very limited. Three are given on these two facing pages.β
- Returns:
the braid object describing the single step to realize the braid n: the number of iterations to get back to initial order of strands
- Return type:
- braidpy.braid_catalog.abok_2974()ο
With four strands the horizon is somewhat widened.
Returns:
- braidpy.braid_catalog.flat5() Tuple[Braid, int]ο
https://www.youtube.com/watch?v=uRy4wvJwSWA
- Returns:
the braid object describing the single step to realize the braid n: the number of iterations to get back to initial order of strands
- Return type:
- braidpy.braid_catalog.flat_sinnet5()ο
ABOK 2967: βWith more than three strands it is well to secure the strands in a straight line. Two pencils and two elastic bands are sufficient apparatus. FLAT SI~NET may be made with any odd number of strands in the way already described. The outer strands are moved alternately, and the tension is correctly and evenly arranged as each strand is passedβ.
- Returns:
the braid object describing the single step to realize the braid n: the number of iterations to get back to initial order of strands
- Return type:
- braidpy.braid_catalog.flat_sinnet7()ο
ABOK 2968: βSeven strands is about the practical limit of the method. Beyond that there is difficulty in keeping it even. Even if a degree of success is achieved, a very little rough treatment will cause it to distort.β
- Returns:
the braid object describing the single step to realize the braid n: the number of iterations to get back to initial order of strands
- Return type:
Filename: handles_reduction.py Description: Simplification of braid word to get unique braid representation Authors: Baptiste Labat Created: 2025-06-03 Repository: https://github.com/baptistelabat/braidpy License: Mozilla Public License 2.0
- exception braidpy.handles_reduction.HandleReducedButUnexpectedResultο
Bases:
FunctionalExceptionException to be raised if handle reduction is not finishing as expected
- class braidpy.handles_reduction.HandleReductionMode(value)ο
-
- Define the possible options for handle reduction
-full: reduce all handles -compare: partical short circuit reductio which is exiting as long as we can determine if braid is positive, or negative
- FULL = 'FULL'ο
- COMPARE = 'COMPARE'ο
- class braidpy.handles_reduction.HandleReductionResults(generators: tuple[int], sign: int, handle_reduction_mode: braidpy.handles_reduction.HandleReductionMode)ο
Bases:
object- handle_reduction_mode: HandleReductionModeο
- braidpy.handles_reduction.dehornoy_handle_indices(gens: list[int]) tuple[PositiveInt, PositiveInt] | Noneο
Detect the first Dehornoy handle in gens. A handle is of the form g β¦ g^-1, with all intermediates having strictly larger absolute values.
- braidpy.handles_reduction.reduce_handle(segment: list[int]) list[int]ο
Reduces a Dehornoy handle of the form [sigma_m, uβ¦, sigma_m^{-1}] by keeping u and replacing each sigma_{m+1} with sigma_{m+1}^{-1} * sigma_m * sigma_{m+1}.
- Parameters:
segment (list[SignedCrossingIndex]) β segment corresponding to handle
- Returns:
the segment with handle reduced (and no more complete handle, but it may create the start of new one)
- Return type:
list[SignedCrossingIndex]
- Raises:
ValueError β if segment is not a handle
- braidpy.handles_reduction.dehornoy_sign(gens: List[int]) int | Noneο
Check if braid is Dehornoy positive, negative, neutral or if this can not be directly said from braid word
- Parameters:
gens(SignedCrossingIndex β list of Artinβs generator
- Returns:
1 if Dehornoy positive, -1 if Dehornoy negative, 0 if neutral element and None if it can not be said
- Return type:
int|None
- braidpy.handles_reduction.dehornoy_reduce_core(gens: List[int], mode: HandleReductionMode | str = HandleReductionMode.FULL, time_out_s: float = 1) tuple[List[int], int | None]ο
Unified Dehornoy reduction engine.
- Parameters:
-gens (List[SignedCrossingIndex]) β list of Artinβs generators
-mode (HandleReductionMode | str) β βFULLβ: returns the fully reduced word. βCOMPARE`: returns early if positive/neutral/negative.
-time_out_s (Optional(float)) β safety timeout. Default to 1
- Returns:
(reduced_gens, sign) where sign is:
- Return type:
tuple[List[SignedCrossingIndex], int|None]
1 if Dehornoy positive
-1 if Dehornoy negative
0 if neutral element
None in case it can not be said without reducing handles further
- Raises:
Filename: material_braid.py Description: Material braids describe real world braid Authors: Baptiste Labat Created: 2025-05-25 Repository: https://github.com/baptistelabat/braidpy License: Mozilla Public License 2.0
- class braidpy.material_braid.MaterialStrand(func: Callable[[float], tuple], radius: PositiveFloat = 0.005)ο
Bases:
ParametricStrand
Filename: parametric_braid.py Description: A braid describes by a punctured disk Authors: Baptiste Labat Created: 2025-05-25 Repository: https://github.com/baptistelabat/braidpy License: Mozilla Public License 2.0
- class braidpy.parametric_braid.ParametricBraid(strands: list[ParametricStrand])ο
Bases:
object- get_positions_at(t: PositiveFloat) List[Tuple[float, float, float]]ο
Get position of different strands at a given time
- plot(n_sample: StrictlyPositiveInt = 200, plotter: Plotter = Plotter.PLOTLY) ParametricBraidο
Plot the braid in 3D
- Parameters:
n_sample
- Returns:
the braid itself
- Return type:
Filename: utils.py Description: Utility functions, not directly related to braids Authors: Baptiste Labat Created: 2025-05-24 Repository: https://github.com/baptistelabat/braidpy License: Mozilla Public License 2.0
- braidpy.utils.colorize_by_index(text: str, index: int) strο
Colorize a string using a repeating color based on index (starting at 0).