Benchmark framework

.github/workflows/publish.yml

@@ -11,7 +11,7 @@ permissions:
   pages: write
 
 env:
-  MODO_VERSION: v0.11.10
+  MODO_VERSION: v0.11.12
   HUGO_VERSION: 0.148.2
 
 jobs:

AGENTS.md

@@ -0,0 +1,31 @@
+# Agent Guidelines for Larecs
+
+## Build/Test Commands
+- Run all tests: `pixi run mojo test -I src/ test/`
+- Run single test: `pixi run mojo test -I src/ test/<filename>.mojo`
+- Format code: `pixi run mojo format src test benchmark`
+- Generate docs: `pixi run mojo doc -o docs/src/larecs.json src/larecs`
+
+## Code Style
+- Use snake_case for functions/variables, PascalCase for types
+- Use `fn` for static functions, `def` for dynamic functions
+- Prefer `var` for mutable, immutable by default
+- Use `inout` parameters for mutation, not return modified values
+- Include comprehensive type hints with Mojo's progressive typing
+- Use `@parameter` for compile-time constants, `@always_inline` for critical paths
+- Leverage SIMD types `SIMD[type, width]` for vectorization
+- Apply traits: `Copyable`, `Movable`, `Stringable` appropriately
+- Use manual memory management with `UnsafePointer` when needed
+- Include docstrings for public APIs
+- Reference Mojo docs for LLMs: https://docs.modular.com/llms-mojo.txt
+
+## Error Handling & Safety
+- Follow borrow checker principles for memory safety
+- Prefer stack allocation and RAII patterns
+- Use `debug_warn()` utility for debug messages
+
+## Performance Focus
+- This is a performance-critical ECS library
+- Memory layout and cache efficiency are crucial
+- Always consider vectorization opportunities
+- Update benchmarks when making performance changes

benchmark/bitmask_benchmark.mojo

@@ -43,7 +43,7 @@ fn benchmark_bitmask_flip_1_000_000(mut bencher: Bencher) capturing:
     @parameter
     fn bench_fn() capturing:
         for _ in range(1_000_000):
-            mask.flip(val)
+            mask.flip_mut(val)
             keep(mask._bytes)
 
     bencher.iter[bench_fn]()
@@ -75,19 +75,6 @@ fn benchmark_bitmask_contains_any_1_000_000(mut bencher: Bencher) capturing:
     bencher.iter[bench_fn]()
 
 
-fn benchmark_mask_filter_1_000_000(mut bencher: Bencher) capturing:
-    mask = BitMask(0, 1, 2).without()
-    bits = BitMask(0, 1, 2)
-
-    @always_inline
-    @parameter
-    fn bench_fn() capturing:
-        for _ in range(1_000_000):
-            keep(mask.matches(bits))
-
-    bencher.iter[bench_fn]()
-
-
 fn benchmark_bitmask_eq_1_000_000(mut bencher: Bencher) capturing:
     mask1 = get_random_bitmask()
     mask2 = mask1
@@ -202,9 +189,6 @@ fn run_all_bitmask_benchmarks(mut bench: Bench) raises:
     bench.bench_function[benchmark_bitmask_eq_1_000_000](
         BenchId("10^6 * bitmask_eq")
     )
-    bench.bench_function[benchmark_mask_filter_1_000_000](
-        BenchId("10^6 * mask_filter")
-    )
     # bench.bench_function[benchmark_bitmask_get_indices_1_000_000](
     #     BenchId("10^6 * get_indices")
     # )

benchmark/custom_benchmark.mojo

@@ -3,16 +3,202 @@ from benchmark import (
     BenchId,
     BenchConfig as BenchConfig_,
     Bench as Bench_,
+    Format,
 )
+from pathlib import Path
 from time import perf_counter_ns
 from collections import Dict
+from larecs.bitmask import BitMask
 
 
 fn DefaultConfig() raises -> BenchConfig_:
     """Returns the default configuration for benchmarking."""
     config = BenchConfig_(min_runtime_secs=2, max_batch_size=50)
     config.verbose_timing = True
-    return config
+    return config^
+
+
+struct ArgTypes:
+    alias path = "--path"
+    alias format = "--format"
+
+
+struct FormatStrings:
+    alias csv = "csv"
+    alias table = "table"
+    alias tabular = "tabular"
+
+    @staticmethod
+    fn contains(str: StringSlice[StaticConstantOrigin]) -> Bool:
+        return (
+            str == FormatStrings.csv
+            or str == FormatStrings.table
+            or str == FormatStrings.tabular
+        )
+
+
+@fieldwise_init
+struct Arg(Copyable, Movable):
+    var type: StringSlice[StaticConstantOrigin]
+    var value: List[StringSlice[StaticConstantOrigin]]
+
+    fn __eq__(self: Self, other: Arg) -> Bool:
+        return self.type == other.type
+
+    fn __eq__(self: Self, other: StringSlice[StaticConstantOrigin]) -> Bool:
+        return self.type == other
+
+
+@register_passable("trivial")
+struct ParserError(EqualityComparable):
+    var type: BitMask.IndexType
+    alias unknown_arg = ParserError(0)
+    alias format_missing = ParserError(1)
+    alias path_missing = ParserError(2)
+
+    fn __init__(out self, type: BitMask.IndexType):
+        self.type = type
+
+    fn __eq__(self: Self, other: ParserError) -> Bool:
+        return self.type == other.type
+
+
+@fieldwise_init
+struct ParserErrors(ImplicitlyCopyable, Movable):
+    var error_mask: BitMask
+
+    fn __init__(out self):
+        self.error_mask = BitMask()
+
+    fn has_errors(self: Self) -> Bool:
+        return not self.error_mask.is_zero()
+
+    fn has_error(self: Self, error: ParserError) -> Bool:
+        return self.error_mask.get(error.type)
+
+    fn add_error(mut self: Self, error: ParserError):
+        self.error_mask.set[True](error.type)
+
+    fn clear_error(mut self: Self, error: ParserError):
+        self.error_mask.set[False](error.type)
+
+    fn get_errors(self: Self) -> List[ParserError]:
+        errors = List[ParserError]()
+        for error_bit in self.error_mask.get_indices():
+            errors.append(ParserError(error_bit))
+        return errors^
+
+
+struct Parser:
+    var args: List[StringSlice[StaticConstantOrigin]]
+    var index: Int
+    var errors: ParserErrors
+
+    fn __init__(out self, var args: List[StringSlice[StaticConstantOrigin]]):
+        self.args = args^
+        self.index = 0
+        self.errors = ParserErrors()
+
+    fn has_next(self: Self) -> Bool:
+        return self.index < len(self.args)
+
+    fn parse_next(mut self: Self) raises -> Arg:
+        type = self.args[self.index]
+        self.index += 1
+
+        value = List[StringSlice[StaticConstantOrigin]]()
+        if type == ArgTypes.path:
+            if not self.has_next():
+                raise Error("Expected a value after --path")
+
+            value.append(self.args[self.index])
+            self.index += 1
+
+            if self.errors.has_error(ParserError.format_missing):
+                raise Error(
+                    "--path specified without --format. Please provide --format"
+                    " first."
+                )
+            elif self.errors.has_error(ParserError.path_missing):
+                self.errors.clear_error(ParserError.path_missing)
+            else:
+                self.errors.add_error(ParserError.format_missing)
+
+        elif type == ArgTypes.format:
+            if not self.has_next():
+                raise Error("Expected a value after --format")
+
+            format_str = self.args[self.index]
+            if not FormatStrings.contains(format_str):
+                raise Error("Unknown format: " + format_str)
+
+            value.append(format_str)
+            self.index += 1
+
+            # but this arg should only appear if the --path arg is also given
+            if self.errors.has_error(ParserError.format_missing):
+                self.errors.clear_error(ParserError.format_missing)
+            elif self.errors.has_error(ParserError.path_missing):
+                raise Error(
+                    "--format specified without --path. Please provide --path"
+                    " first."
+                )
+            else:
+                self.errors.add_error(ParserError.path_missing)
+
+        else:
+            raise Error("Unknown argument: " + type)
+
+        return Arg(type, value^)
+
+    fn parse_all(mut self: Self) raises -> List[Arg]:
+        parsed_args = List[Arg]()
+        while self.has_next():
+            parsed_args.append(self.parse_next())
+        return parsed_args^
+
+
+fn config_from_args(
+    args: VariadicList[StringSlice[StaticConstantOrigin]],
+) raises -> BenchConfig_:
+    """Parses command line arguments to create a BenchConfig.
+
+    Currently supports:
+        --json : Outputs results in JSON format.
+
+    Args:
+        args: The command line arguments.
+
+    Returns:
+        A BenchConfig with the parsed settings.
+    """
+    config = DefaultConfig()
+
+    args_list = List[StringSlice[StaticConstantOrigin]](capacity=len(args))
+    for arg in args:
+        args_list.append(arg)
+
+    parser = Parser(args_list[1:])
+    parsed_args = parser.parse_all()
+
+    if parser.errors.has_errors():
+        error_msgs = List[String]()
+        for error in parser.errors.get_errors():
+            if error == ParserError.format_missing:
+                error_msgs.append("--format specified without --path")
+            elif error == ParserError.path_missing:
+                error_msgs.append("--path specified without --format")
+            elif error == ParserError.unknown_arg:
+                error_msgs.append("Unknown argument")
+        raise Error("Argument parsing errors:\n" + "\n".join(error_msgs^))
+
+    for arg in parsed_args:
+        if arg == ArgTypes.format:
+            config.out_file_format = Format(arg.value[0])
+        elif arg == ArgTypes.path:
+            config.out_file = Path(arg.value[0])
+
+    return config^
 
 
 fn DefaultBench() raises -> Bench_:

benchmark/plots/pixi.toml

@@ -9,7 +9,7 @@ version = "0.4.0"
 [tasks]
 
 [dependencies]
-mojo = ">=25.5,<26"
+mojo = "==0.25.6"
 python = "==3.12"
 matplotlib = ">=3.10.0,<4"
 pandas = ">=2.2"