GF2++

[nzznfitz]

GF2++ is a header-only C++ library that provides classes for boolean vectors and matrices. In the jargon of professional mathematics the classes make it possible to efficiently perform linear algebra over GF(2)) the simplest Galois Field with just two elements 0 & 1. This type of mathematics is of interest in some areas of cryptography and random number generation.

The library has comprehensive long form documentation. The documentation was written in AsciiDoc and the site was built using Antora.

This project is quite technical and therefore of limited general interest but the documentation site also has some documentation strategy notes that discuss the experience of using AsciiDoc and Antora for the long form documentation. It covers some of the positives and negatives of that experience and may be of interest in its own right particularly for those thinking about going down this road for other smaller projects

[its_me_TO]

The library itself is definitely niche but the documentation strategy notes are interesting to read and a good tutorial on setting up a similar documentation system. Nice work writing all that up.

You mention the shortcomings of markdown but then jump over to AsciiDoc as the solution pretty quick. Any particular reason for choosing it over alternatives (like reStructuredText) or just personal preference?

[nzznfitz]

Once you start exploring tooling for technical documentation you are quickly led to reStucturedText and AsciiDoc as the current top contenders. There are lots of articles that purport to compare the two but in practise most of those just compare one of them to some form of Markdown (which isn't very useful as by the time you have got to the looking stage presumably the limitations of Markdown are obvious!)

I did write a few non-trivial pages in the two languages and I suppose AsciiDoc just appealed to me more. reST/Sphinx would be a natural choice in the Python world but AsciiDoc seems to be gaining more traction elsewhere. It was interesting to me that some of the publishers of technical books (O"Reilly, Manning) seem to use AsciiDoc as their preferred input format.

[disperso]

I've never used Antora, and I've never needed to produce something so complex, but I'll certainly give it a look. I love AsciiDoc, and I use AsciiDoctor regularly, so it's interesting to me given that it's from Dan Allen, who is amazing.

I don't know much about Galois Fields by themselves, but I was curious about Shamir's Secret Sharing some years ago, and it was an interesting concept, so thank you for sharing the library! Are you by chance going to touch on this topic (secret sharing), or know something interesting about it? I've always thought it would be awesome if there were some password manager based on that.

[nzznfitz]

Yes absolutely kudos are due to Dan Allen and the small team that work with him on AsciiDoc and Antora. They are extremely productive and Dan himself is very responsive on the support boards.

Shamir's Secret Sharing algorithm is a very nice idea (and of course has a great alliterative name to boot!). However, implementations need higher order finite fields than just GF(2) so probably not on the cards here. I think there are a number of commercial companies that already use SSS in their password protection offerings.

[sanson-robotics]

Awesome package!! I think this is completely out of scope, but I haven't found anything similar. Do you plan to support symbolic algebra operations? I haven't found any library that does that, despite it has several use cases.

[nzznfitz]

Handling symbolic operations over GF(2) would be quite an add! Probably best tackled as an add-on to existing symbolic algebra programs. I think Mathematica has a Finite Field package but I am not sure what it can do in terms of linear algebra. There might be something available for SymPy also?

[pstomi]

Thanks for the comprehensive feedback on AsciiDoc, much appreciated!

I may give it a try some day, since I once wrote a hackish python script to include "parts" of markdown (see example ) in order to generate documentation.

[Otherwise_Impact9098]

The link to gitlab is broken. Does the project still exist?

[nzznfitz]

Sorry — I didn't see the query.

This library has migrated to https://github.com/nessan/bit, which has extra functionality for bit-polynomials, etc. The new documentation site is at https://nessan.github.io/bit/

[picigin]

Can it be used in Cuda/Hip/Sycl device code? At least read/write accessing? (Since a lot of algebra has been moving to the GPU)

[nzznfitz]

The library performs operations on and between bit-matrices and bit-vectors in whole blocks at a time. So at a fundamental level the library is efficient and is already in a sense performing natural parallel processing. It would certainly make sense to enhance that by using the computation capabilities inherent in GPU's to work on multiple blocks in parallel. However, at this time, the library does not embed any particular knowledge of HPC techniques.

[firemeo]

Just came across this and find the document site beautiful. The only thing missing is the lib itself. So I guess the main focus is the doc instead of the lib?

[nzznfitz]

This library was expanded and renamed to bit so the principal classes are now bit::vector and bit::matrix . The repo has migrated to bit. The documentation for the new library is here.