Add Stim source files and README describing slight modifications (NVIDIA#34)

* Add original Stim source files; upcoming commits slightly modify them

Original source of the files was
https://github.com/quantumlib/Stim/tree/47190f4a3afb104c9f0068d0be9fea87d2894a70/src/stim/mem

(Hash aligns with v1.14.0.)

Not all files in this directory were copied over.

* Modify Stim files and add README

Author: bmhowe23

libs/qec/lib/decoders/nv-qldpc-decoder/stim/.clang-format

@@ -0,0 +1 @@
+DisableFormat: true

libs/qec/lib/decoders/nv-qldpc-decoder/stim/README.md

@@ -0,0 +1,11 @@
+# Description
+
+This directory contains a slightly modified copy of specific files from <https://github.com/quantumlib/Stim>. The original files that were copied into here are the minimal set needed to utilize the `stim::simd_bit_table` for binary linear algebra.
+
+The source commit was `47190f4a3afb104c9f0068d0be9fea87d2894a70` (aka `v1.14.0`).
+
+The original source files are copyrighted by Google and licensed under the Apache 2.0 license.
+
+Any modifications to the files are marked with "NVIDIA-MOD".
+
+The main purpose of the modifications (so far) is to simply compile with C++17.

libs/qec/lib/decoders/nv-qldpc-decoder/stim/mem/bit_ref.cc

@@ -0,0 +1,21 @@
+// Copyright 2021 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "stim/mem/bit_ref.h"
+
+using namespace stim;
+
+bit_ref::bit_ref(void *base, size_t init_offset)
+    : byte((uint8_t *)base + (init_offset / 8)), bit_index(init_offset & 7) {
+}

libs/qec/lib/decoders/nv-qldpc-decoder/stim/mem/bit_ref.h

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2021 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef _STIM_MEM_BIT_REF_H
+#define _STIM_MEM_BIT_REF_H
+
+#include <cstddef>
+#include <cstdint>
+
+namespace stim {
+
+/// A reference to a bit within a byte.
+///
+/// Conceptually behaves the same as a `bool &`, as opposed to a `bool *`. For example, the `=` operator overwrites the
+/// contents of the bit being referenced instead of changing which bit is pointed to.
+///
+/// This should behave essentially identically to the weird bit references that come out of a `std::vector<bool>`.
+struct bit_ref {
+    uint8_t *byte;
+    uint8_t bit_index;
+
+    /// Construct a bit_ref from a pointer and a bit offset.
+    /// The offset can be larger than a word.
+    /// Automatically canonicalized so that the offset is less than 8.
+    bit_ref(void *base, size_t offset);
+
+    /// Copy assignment.
+    inline bit_ref &operator=(bool value) {
+        *byte &= ~((uint8_t)1 << bit_index);
+        *byte |= (uint8_t)value << bit_index;
+        return *this;
+    }
+    /// Copy assignment.
+    inline bit_ref &operator=(const bit_ref &value) {
+        *this = (bool)value;
+        return *this;
+    }
+    /// Xor assignment.
+    inline bit_ref &operator^=(bool value) {
+        *byte ^= (uint8_t)value << bit_index;
+        return *this;
+    }
+    /// Bitwise-and assignment.
+    inline bit_ref &operator&=(bool value) {
+        *byte &= ((uint8_t)value << bit_index) | ~(1 << bit_index);
+        return *this;
+    }
+    /// Bitwise-or assignment.
+    inline bit_ref &operator|=(bool value) {
+        *byte |= (uint8_t)value << bit_index;
+        return *this;
+    }
+    /// Swap assignment.
+    inline void swap_with(bit_ref other) {
+        bool b = (bool)other;
+        other = (bool)*this;
+        *this = b;
+    }
+
+    /// Implicit conversion to bool.
+    inline operator bool() const {  // NOLINT(google-explicit-constructor,hicpp-explicit-conversions)
+        return (*byte >> bit_index) & 1;
+    }
+};
+
+}  // namespace stim
+
+#endif

libs/qec/lib/decoders/nv-qldpc-decoder/stim/mem/bitword.h

@@ -0,0 +1,183 @@
+/*
+ * Copyright 2021 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <cstddef>
+
+#ifndef _STIM_MEM_BIT_WORD_H
+#define _STIM_MEM_BIT_WORD_H
+
+namespace stim {
+
+/// A `bitword` is a bag of bits that can be operated on in a SIMD-esque fashion
+/// by individual CPU instructions.
+///
+/// This template would not have to exist, except that different architectures and
+/// operating systems expose different interfaces between native types like
+/// uint64_t and intrinsics like __m256i. For example, in some contexts, __m256i
+/// values can be operated on by operators (e.g. you can do `a ^= b`) while in
+/// other contexts this does not work. The bitword template implementations define
+/// a common set of methods required by stim to function, so that the same code
+/// can be compiled to use 256 bit registers or 64 bit registers as appropriate.
+template <size_t bit_size>
+struct bitword;
+
+template <size_t W>
+inline bool operator==(const bitword<W> &self, const bitword<W> &other) {
+    return self.to_u64_array() == other.to_u64_array();
+}
+
+template <size_t W>
+inline bool operator<(const bitword<W> &self, const bitword<W> &other) {
+    auto v1 = self.to_u64_array();
+    auto v2 = other.to_u64_array();
+    for (size_t k = 0; k < v1.size(); k++) {
+        if (v1[k] != v2[k]) {
+            return v1[k] < v2[k];
+        }
+    }
+    return false;
+}
+
+template <size_t W>
+inline bool operator!=(const bitword<W> &self, const bitword<W> &other) {
+    return !(self == other);
+}
+
+template <size_t W>
+inline bool operator==(const bitword<W> &self, int other) {
+    return self == (bitword<W>)other;
+}
+template <size_t W>
+inline bool operator!=(const bitword<W> &self, int other) {
+    return self != (bitword<W>)other;
+}
+template <size_t W>
+inline bool operator==(const bitword<W> &self, uint64_t other) {
+    return self == (bitword<W>)other;
+}
+template <size_t W>
+inline bool operator!=(const bitword<W> &self, uint64_t other) {
+    return self != (bitword<W>)other;
+}
+template <size_t W>
+inline bool operator==(const bitword<W> &self, int64_t other) {
+    return self == (bitword<W>)other;
+}
+template <size_t W>
+inline bool operator!=(const bitword<W> &self, int64_t other) {
+    return self != (bitword<W>)other;
+}
+
+template <size_t W>
+std::ostream &operator<<(std::ostream &out, const bitword<W> &v) {
+    out << "bitword<" << W << ">{";
+    auto u = v.to_u64_array();
+    for (size_t k = 0; k < u.size(); k++) {
+        for (size_t b = 0; b < 64; b++) {
+            if ((b | k) && (b & 7) == 0) {
+                out << ' ';
+            }
+            out << ".1"[(u[k] >> b) & 1];
+        }
+    }
+    out << '}';
+    return out;
+}
+
+template <size_t W>
+inline bitword<W> operator<<(const bitword<W> &self, uint64_t offset) {
+    return self.shifted((int)offset);
+}
+
+template <size_t W>
+inline bitword<W> operator>>(const bitword<W> &self, uint64_t offset) {
+    return self.shifted(-(int)offset);
+}
+
+template <size_t W>
+inline bitword<W> &operator<<=(bitword<W> &self, uint64_t offset) {
+    self = (self << offset);
+    return self;
+}
+
+template <size_t W>
+inline bitword<W> &operator>>=(bitword<W> &self, uint64_t offset) {
+    self = (self >> offset);
+    return self;
+}
+
+template <size_t W>
+inline bitword<W> operator<<(const bitword<W> &self, int offset) {
+    return self.shifted((int)offset);
+}
+
+template <size_t W>
+inline bitword<W> operator>>(const bitword<W> &self, int offset) {
+    return self.shifted(-(int)offset);
+}
+
+template <size_t W>
+inline bitword<W> &operator<<=(bitword<W> &self, int offset) {
+    self = (self << offset);
+    return self;
+}
+
+template <size_t W>
+inline bitword<W> &operator>>=(bitword<W> &self, int offset) {
+    self = (self >> offset);
+    return self;
+}
+
+template <size_t W>
+inline bitword<W> operator&(const bitword<W> &self, int mask) {
+    return self & bitword<W>(mask);
+}
+template <size_t W>
+inline bitword<W> operator&(const bitword<W> &self, uint64_t mask) {
+    return self & bitword<W>(mask);
+}
+template <size_t W>
+inline bitword<W> operator&(const bitword<W> &self, int64_t mask) {
+    return self & bitword<W>(mask);
+}
+template <size_t W>
+inline bitword<W> operator|(const bitword<W> &self, int mask) {
+    return self | bitword<W>(mask);
+}
+template <size_t W>
+inline bitword<W> operator|(const bitword<W> &self, uint64_t mask) {
+    return self | bitword<W>(mask);
+}
+template <size_t W>
+inline bitword<W> operator|(const bitword<W> &self, int64_t mask) {
+    return self | bitword<W>(mask);
+}
+template <size_t W>
+inline bitword<W> operator^(const bitword<W> &self, int mask) {
+    return self ^ bitword<W>(mask);
+}
+template <size_t W>
+inline bitword<W> operator^(const bitword<W> &self, uint64_t mask) {
+    return self ^ bitword<W>(mask);
+}
+template <size_t W>
+inline bitword<W> operator^(const bitword<W> &self, int64_t mask) {
+    return self ^ bitword<W>(mask);
+}
+
+}  // namespace stim
+
+#endif