faultforge 0.2.1__tar.gz → 0.3.0__tar.gz

faultforge-0.3.0/LICENSE

@@ -0,0 +1,35 @@
+Copyright (c) 2025 Marten Roots
+
+The Universal Permissive License (UPL), Version 1.0
+
+Subject to the condition set forth below, permission is hereby granted to any
+person obtaining a copy of this software, associated documentation and/or data
+(collectively the "Software"), free of charge and under any and all copyright
+rights in the Software, and any and all patent rights owned or freely
+licensable by each licensor hereunder covering either (i) the unmodified
+Software as contributed to or provided by such licensor, or (ii) the Larger
+Works (as defined below), to deal in both
+
+(a) the Software, and
+(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+one is included with the Software (each a "Larger Work" to which the Software
+is contributed by such licensors),
+
+without restriction, including without limitation the rights to copy, create
+derivative works of, display, perform, and distribute the Software and make,
+use, sell, offer for sale, import, export, have made, and have sold the
+Software and the Larger Work(s), and to sublicense the foregoing rights on
+either these or other terms.
+
+This license is subject to the following condition:
+The above copyright notice and either this complete permission notice or at
+a minimum a reference to the UPL must be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{faultforge-0.2.1 → faultforge-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: faultforge
-Version: 0.2.1
+Version: 0.3.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
@@ -11,10 +11,15 @@ Requires-Dist: scipy>=1.17.1
 Requires-Dist: timm>=1.0.22
 Requires-Dist: torch>=2.7.1
 Requires-Dist: torchvision>=0.22.1
+License-File: LICENSE
 Summary: A framework for reproducible hardware fault-injection experiments on PyTorch models
-Author-email: Marten Roots <marten.roots@gmail.com>
+Author-email: Marten Roots <marten.roots@gmail.com>, Sven-Markus Loorits <sven.loorits@proton.me>
+License-Expression: UPL-1.0
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/rezzubs/faultforge/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/rezzubs/faultforge/issues
+Project-URL: Repository, https://github.com/rezzubs/faultforge
 
 # FaultForge
 
@@ -34,7 +39,9 @@ its first experiment.
 - [`Fingerprint`](docs/library.md#fingerprint)-based verification: resuming or
   comparing a saved result against a changed configuration fails loudly with
   a precise diff, instead of silently mixing incompatible data.
-- A composable [encoding framework](docs/experiments/encoded_memory.md#encoding-techniques)
+- A generic and extensible system for [reliabilty
+  metrics](src/faultforge/metric.py).
+- A composable [encoding framework](experiments/encoded_memory/README.md#encoding-techniques)
   (`Encoder`/`Encoding`, chainable via `EncoderSequence`) with three built-in
   ECC-style techniques - SECDED (Hamming codes), MSET, and CEP - usable
   standalone or combined.
@@ -42,7 +49,7 @@ its first experiment.
   repeat-free fault-location sampler, and a batched injection API built for
   performance.
 - One ready-made experiment today,
-  [`encoded_memory`](docs/experiments/encoded_memory.md): fault injection into
+  [`encoded_memory`](experiments/encoded_memory/README.md): fault injection into
   ECC-protected model parameters, with built-in CIFAR-10/100 and ImageNet
   model/dataset loading and a CLI for recording and plotting results. It
   doubles as the reference implementation to follow when adding a new
@@ -52,58 +59,59 @@ its first experiment.
 
 ## Installation
 
-FaultForge is split into two packages:
+### Prebuilt packages from PyPI
 
-- [`faultforge`](https://pypi.org/project/faultforge/) - the library.
-- [`faultforge-cli`](https://pypi.org/project/faultforge-cli/) - a CLI built
-  on top of it (installs a `faultforge` command).
+Using pip:
 
 ```sh
-pip install faultforge        # library only
-pip install faultforge-cli    # adds the `faultforge` CLI command
+pip install faultforge
 ```
 
-Building from source requires a Rust toolchain, since the library's
-performance-critical parts are a PyO3 extension compiled with
-[maturin](https://www.maturin.rs/). Install one with your system package
-manager or via [rustup](https://rustup.rs/). No toolchain is needed when
-installing a prebuilt wheel from PyPI.
+Using uv:
+
+```sh
+uv add faultforge
+```
+
+
+[`faultforge`](https://pypi.org/project/faultforge/) is the only package
+published to PyPI - it's the framework only, with no CLI and no ready-made
+experiments. 
 
 ### Installing from source
 
-Both packages live in this repository, under `packages/faultforge` and
-`packages/faultforge_cli`. Point pip at a subdirectory of whichever revision
-you want:
+Building from source requires a Rust toolchain. Install one with your system
+package manager or via [rustup](https://rustup.rs/). This repository's root
+package is the `faultforge` library. Point pip at whichever revision you want:
 
 ```sh
-# latest (main is kept in sync with the newest code going forward)
-pip install 'faultforge @ git+https://github.com/rezzubs/faultforge.git#subdirectory=packages/faultforge'
 
 # latest release (the latest branch tracks the most recent tagged release)
-pip install 'faultforge @ git+https://github.com/rezzubs/faultforge.git@latest#subdirectory=packages/faultforge'
+pip install 'faultforge @ git+https://github.com/rezzubs/faultforge.git@latest'
 
 # a specific released version
-pip install 'faultforge @ git+https://github.com/rezzubs/faultforge.git@v0.2.0#subdirectory=packages/faultforge'
+pip install 'faultforge @ git+https://github.com/rezzubs/faultforge.git@v0.2.1'
 
 # a specific commit
-pip install 'faultforge @ git+https://github.com/rezzubs/faultforge.git@<commit-sha>#subdirectory=packages/faultforge'
-```
+pip install 'faultforge @ git+https://github.com/rezzubs/faultforge.git@<commit-sha>'
 
-Substitute `packages/faultforge_cli` for `packages/faultforge` (and
-`faultforge-cli` for the package name before `@`) to install the CLI the same
-way.
+# development (main is kept in sync with the newest code, can break at any point)
+pip install 'faultforge @ git+https://github.com/rezzubs/faultforge.git'
+```
 
-FaultForge requires Python 3.14 or newer.
+Ready-made experiments (see [Experiments](#experiments) below) aren't published
+to PyPI - install one the same way, pointed at its own subdirectory under
+`experiments/` See each experiment's README for details.
 
 ## Quick example
 
 ```python
-from faultforge.encoding import SecdedEncoder
-from faultforge.experiment import MaxRuns
-from faultforge.experiments.encoded_memory import (
+from encoded_memory import (
     EncodedFaultInjection,
     ReliabilityMetric,
 )
+from faultforge.encoding import SecdedEncoder
+from faultforge.experiment import MaxRuns
 from faultforge.loading import Cifar, CifarDataset, CifarModel
 
 bundle = Cifar(model=CifarModel.ResNet20, dataset=CifarDataset.Cifar10)
@@ -125,17 +133,18 @@ framework's pieces and how they compose.
 
 ## Experiments
 
-FaultForge ships one ready-made experiment today, built as the reference
-implementation for adding your own:
+Ready-made experiments live under [`experiments/`](experiments) as their own
+packages, each pinned to a specific `faultforge` version rather than tracking
+`main`. There's one today, serving as the reference implementation for
+adding your own:
 
-- [Encoded Memory](docs/experiments/encoded_memory.md) - fault injection into
+- [Encoded Memory](experiments/encoded_memory/README.md) - fault injection into
   ECC-protected model parameters, covering the available encoding techniques,
-  the `faultforge encoded-memory` CLI, and using the experiment directly as a
-  library.
+  the `encoded-memory` CLI, and using the experiment directly as a library.
 
 ## Citation
 
-### [Encoded Memory](docs/experiments/encoded_memory.md)
+### [Encoded Memory](experiments/encoded_memory/README.md)
 
 There are two papers related to the encoded memory experiment.
 

{faultforge-0.2.1 → faultforge-0.3.0}/README.md

@@ -16,7 +16,9 @@ its first experiment.
 - [`Fingerprint`](docs/library.md#fingerprint)-based verification: resuming or
   comparing a saved result against a changed configuration fails loudly with
   a precise diff, instead of silently mixing incompatible data.
-- A composable [encoding framework](docs/experiments/encoded_memory.md#encoding-techniques)
+- A generic and extensible system for [reliabilty
+  metrics](src/faultforge/metric.py).
+- A composable [encoding framework](experiments/encoded_memory/README.md#encoding-techniques)
   (`Encoder`/`Encoding`, chainable via `EncoderSequence`) with three built-in
   ECC-style techniques - SECDED (Hamming codes), MSET, and CEP - usable
   standalone or combined.
@@ -24,7 +26,7 @@ its first experiment.
   repeat-free fault-location sampler, and a batched injection API built for
   performance.
 - One ready-made experiment today,
-  [`encoded_memory`](docs/experiments/encoded_memory.md): fault injection into
+  [`encoded_memory`](experiments/encoded_memory/README.md): fault injection into
   ECC-protected model parameters, with built-in CIFAR-10/100 and ImageNet
   model/dataset loading and a CLI for recording and plotting results. It
   doubles as the reference implementation to follow when adding a new
@@ -34,58 +36,59 @@ its first experiment.
 
 ## Installation
 
-FaultForge is split into two packages:
+### Prebuilt packages from PyPI
 
-- [`faultforge`](https://pypi.org/project/faultforge/) - the library.
-- [`faultforge-cli`](https://pypi.org/project/faultforge-cli/) - a CLI built
-  on top of it (installs a `faultforge` command).
+Using pip:
 
 ```sh
-pip install faultforge        # library only
-pip install faultforge-cli    # adds the `faultforge` CLI command
+pip install faultforge
 ```
 
-Building from source requires a Rust toolchain, since the library's
-performance-critical parts are a PyO3 extension compiled with
-[maturin](https://www.maturin.rs/). Install one with your system package
-manager or via [rustup](https://rustup.rs/). No toolchain is needed when
-installing a prebuilt wheel from PyPI.
+Using uv:
+
+```sh
+uv add faultforge
+```
+
+
+[`faultforge`](https://pypi.org/project/faultforge/) is the only package
+published to PyPI - it's the framework only, with no CLI and no ready-made
+experiments. 
 
 ### Installing from source
 
-Both packages live in this repository, under `packages/faultforge` and
-`packages/faultforge_cli`. Point pip at a subdirectory of whichever revision
-you want:
+Building from source requires a Rust toolchain. Install one with your system
+package manager or via [rustup](https://rustup.rs/). This repository's root
+package is the `faultforge` library. Point pip at whichever revision you want:
 
 ```sh
-# latest (main is kept in sync with the newest code going forward)
-pip install 'faultforge @ git+https://github.com/rezzubs/faultforge.git#subdirectory=packages/faultforge'
 
 # latest release (the latest branch tracks the most recent tagged release)
-pip install 'faultforge @ git+https://github.com/rezzubs/faultforge.git@latest#subdirectory=packages/faultforge'
+pip install 'faultforge @ git+https://github.com/rezzubs/faultforge.git@latest'
 
 # a specific released version
-pip install 'faultforge @ git+https://github.com/rezzubs/faultforge.git@v0.2.0#subdirectory=packages/faultforge'
+pip install 'faultforge @ git+https://github.com/rezzubs/faultforge.git@v0.2.1'
 
 # a specific commit
-pip install 'faultforge @ git+https://github.com/rezzubs/faultforge.git@<commit-sha>#subdirectory=packages/faultforge'
-```
+pip install 'faultforge @ git+https://github.com/rezzubs/faultforge.git@<commit-sha>'
 
-Substitute `packages/faultforge_cli` for `packages/faultforge` (and
-`faultforge-cli` for the package name before `@`) to install the CLI the same
-way.
+# development (main is kept in sync with the newest code, can break at any point)
+pip install 'faultforge @ git+https://github.com/rezzubs/faultforge.git'
+```
 
-FaultForge requires Python 3.14 or newer.
+Ready-made experiments (see [Experiments](#experiments) below) aren't published
+to PyPI - install one the same way, pointed at its own subdirectory under
+`experiments/` See each experiment's README for details.
 
 ## Quick example
 
 ```python
-from faultforge.encoding import SecdedEncoder
-from faultforge.experiment import MaxRuns
-from faultforge.experiments.encoded_memory import (
+from encoded_memory import (
     EncodedFaultInjection,
     ReliabilityMetric,
 )
+from faultforge.encoding import SecdedEncoder
+from faultforge.experiment import MaxRuns
 from faultforge.loading import Cifar, CifarDataset, CifarModel
 
 bundle = Cifar(model=CifarModel.ResNet20, dataset=CifarDataset.Cifar10)
@@ -107,17 +110,18 @@ framework's pieces and how they compose.
 
 ## Experiments
 
-FaultForge ships one ready-made experiment today, built as the reference
-implementation for adding your own:
+Ready-made experiments live under [`experiments/`](experiments) as their own
+packages, each pinned to a specific `faultforge` version rather than tracking
+`main`. There's one today, serving as the reference implementation for
+adding your own:
 
-- [Encoded Memory](docs/experiments/encoded_memory.md) - fault injection into
+- [Encoded Memory](experiments/encoded_memory/README.md) - fault injection into
   ECC-protected model parameters, covering the available encoding techniques,
-  the `faultforge encoded-memory` CLI, and using the experiment directly as a
-  library.
+  the `encoded-memory` CLI, and using the experiment directly as a library.
 
 ## Citation
 
-### [Encoded Memory](docs/experiments/encoded_memory.md)
+### [Encoded Memory](experiments/encoded_memory/README.md)
 
 There are two papers related to the encoded memory experiment.
 

{faultforge-0.2.1 → faultforge-0.3.0}/crates/bindings/src/secded.rs

@@ -186,7 +186,11 @@ impl PyEncoding {
         }
 
         let mut encoding = self.to_rust(py)?;
-        encoding.apply_faults(faults.into_iter().map(|(fault, target_bit)| (fault.0, target_bit)));
+        encoding.apply_faults(
+            faults
+                .into_iter()
+                .map(|(fault, target_bit)| (fault.0, target_bit)),
+        );
 
         *self = PyEncoding::from_rust(py, encoding, self.data_bit_count, self.item_counts.clone())?;
 

{faultforge-0.2.1 → faultforge-0.3.0}/crates/memory/src/bit_buffer/impls_numpy.rs

@@ -95,7 +95,9 @@ mod tests {
     fn bijective_1d() {
         let shape = &[7usize];
         let n = total_bits(shape, u8::BITS_COUNT);
-        let outputs: HashSet<_> = (0..n).map(|i| bit_index_to_array_index::<u8>(i, shape)).collect();
+        let outputs: HashSet<_> = (0..n)
+            .map(|i| bit_index_to_array_index::<u8>(i, shape))
+            .collect();
         assert_eq!(outputs.len(), n);
     }
 
@@ -103,7 +105,9 @@ mod tests {
     fn bijective_2d() {
         let shape = &[3usize, 5];
         let n = total_bits(shape, u16::BITS_COUNT);
-        let outputs: HashSet<_> = (0..n).map(|i| bit_index_to_array_index::<u16>(i, shape)).collect();
+        let outputs: HashSet<_> = (0..n)
+            .map(|i| bit_index_to_array_index::<u16>(i, shape))
+            .collect();
         assert_eq!(outputs.len(), n);
     }
 
@@ -111,7 +115,9 @@ mod tests {
     fn bijective_3d() {
         let shape = &[2usize, 3, 4];
         let n = total_bits(shape, u32::BITS_COUNT);
-        let outputs: HashSet<_> = (0..n).map(|i| bit_index_to_array_index::<u32>(i, shape)).collect();
+        let outputs: HashSet<_> = (0..n)
+            .map(|i| bit_index_to_array_index::<u32>(i, shape))
+            .collect();
         assert_eq!(outputs.len(), n);
     }
 

{faultforge-0.2.1 → faultforge-0.3.0}/crates/memory/src/sequence/non_uniform.rs

@@ -107,7 +107,9 @@ where
         It: Iterator<Item = (Fault, usize)>,
     {
         let offsets = self.bit_offsets();
-        let total_bits = *offsets.last().expect("offsets always has at least one element");
+        let total_bits = *offsets
+            .last()
+            .expect("offsets always has at least one element");
 
         for (fault, bit_index) in faults {
             assert!(bit_index < total_bits, "out of bounds");

{faultforge-0.2.1 → faultforge-0.3.0}/pyproject.toml

@@ -1,10 +1,13 @@
 [project]
 name = "faultforge"
-version = "0.2.1"
+version = "0.3.0"
 description = "A framework for reproducible hardware fault-injection experiments on PyTorch models"
 readme = "README.md"
+license = "UPL-1.0"
+license-files = ["LICENSE"]
 authors = [
-    { name = "Marten Roots", email = "marten.roots@gmail.com" }
+    { name = "Marten Roots", email = "marten.roots@gmail.com" },
+    { name = "Sven-Markus Loorits", email = "sven.loorits@proton.me" },
 ]
 requires-python = ">=3.14"
 dependencies = [
@@ -22,9 +25,24 @@ classifiers = [
     "Programming Language :: Python :: Implementation :: PyPy",
 ]
 
+[project.urls]
+Repository = "https://github.com/rezzubs/faultforge"
+Issues = "https://github.com/rezzubs/faultforge/issues"
+Changelog = "https://github.com/rezzubs/faultforge/blob/main/CHANGELOG.md"
+
+[tool.uv.workspace]
+members = ["experiments/encoded_memory"]
+
+[tool.uv]
+default-groups = ["dev"]
+
 [dependency-groups]
 dev = [
+    "hypothesis>=6.148.7",
     "maturin>=1.14.0",
+    "pytest>=9.0.2",
+    "ruff>=0.12.4",
+    "ty>=0.0.49",
 ]
 
 [build-system]
@@ -36,3 +54,9 @@ features = ["pyo3/extension-module"]
 module-name = "faultforge._rust"
 manifest-path = "crates/bindings/Cargo.toml"
 python-source = "src"
+
+[tool.ty.rules]
+missing-override-decorator = "warn"
+
+[tool.ruff]
+target-version = "py314"

{faultforge-0.2.1 → faultforge-0.3.0}/src/faultforge/__init__.py

@@ -20,21 +20,15 @@ submodules for details.
   with its evaluation dataset.
 - `faultforge.progress`: `Progress`, for reporting on long-running operations
   (dataset loading, encoding, fault injection, ...) via periodic log messages.
+- `faultforge.io`: File I/O helpers (`open_text`, `is_compressed`) for
+  reading/writing save files transparently through zstd compression.
 
 To add a new kind of experiment, subclass `Experiment` and reuse
-`faultforge.loading`/`faultforge.dataset` for model and data handling.
-
-**Ready-made experiments**
-
-`faultforge.experiments` holds experiments built on the framework above.
-Currently there is one, `faultforge.experiments.encoded_memory`: encoded-
-memory fault injection, which measures model reliability under simulated
-single-event upsets in error-corrected parameter memory. It's a complete
-example to follow when adding a new experiment. It's built on:
-
-- `faultforge.encoding`: `Encoder`/`Encoding` pairs that transform tensors into
-  a protected representation and back, plus `EncodedModule` for wrapping a
-  `torch.nn.Module` so its parameters live in simulated encoded memory.
+`faultforge.loading`/`faultforge.dataset` for model and data handling. This
+library only holds the reusable framework - ready-made experiments (e.g.
+`encoded_memory`, built on `faultforge.encoding`) live in the repository's
+top-level `experiments/` directory as their own packages, so pulling in
+`faultforge` never drags in an experiment's own dependencies.
 
 **Fault injection primitives**
 
@@ -49,20 +43,16 @@ root rather than in their own submodule:
   `Encoding.apply_faults`/`EncodedModule.apply_faults`) over injecting one fault
   at a time in a loop: applying a batch pays its conversion overhead once for the
   whole batch rather than once per fault.
+- `bitwise_xor`: elementwise bitwise xor of two same-shape, same-dtype tensors
+  (floats bitcast to same-width integers first).
 """
 
 import sys
 
-from faultforge._internal.common import (
-    DEFAULT_BATCH_SIZE,
-    DEFAULT_DEVICE,
-    AnyPath,
-    DeviceLike,
-    is_compressed,
-)
 from faultforge._internal.fault import BitFlip, Fault, StuckAt
 from faultforge._internal.fingerprint import Fingerprint
 from faultforge._internal.tensor import (
+    bitwise_xor,
     tensor_list_dtype,
     tensor_list_fault,
     tensor_list_faults,
@@ -72,16 +62,12 @@ from faultforge._rust import Picker
 from . import _rust
 
 __all__ = [
-    "AnyPath",
     "BitFlip",
-    "DEFAULT_BATCH_SIZE",
-    "DEFAULT_DEVICE",
-    "DeviceLike",
     "Fault",
     "Fingerprint",
     "Picker",
     "StuckAt",
-    "is_compressed",
+    "bitwise_xor",
     "tensor_list_dtype",
     "tensor_list_fault",
     "tensor_list_faults",