holobench 1.41.0__py3-none-any.whl → 1.43.0__py3-none-any.whl

bencher/example/inputs_0D/example_0_in_2_out.py

@@ -5,14 +5,14 @@ import random
 
 
 class SimpleFloat0D(bch.ParametrizedSweep):
-    """This class has 0 input dimensions and 1 output dimensions.  It samples from a gaussian distribution"""
+    """This class has 0 input dimensions and 2 output dimensions. It samples from Gaussian distributions"""
 
     # This defines a variable that we want to plot
     output1 = bch.ResultVar(units="ul", doc="a sample from a gaussian distribution")
     output2 = bch.ResultVar(units="ul", doc="a sample from a gaussian distribution")
 
     def __call__(self, **kwargs) -> dict:
-        """Generate a sample from a uniform distribution
+        """Generate samples from Gaussian distributions
 
         Returns:
             dict: a dictionary with all the result variables in the ParametrisedSweep class as named key value pairs.
@@ -26,7 +26,16 @@ class SimpleFloat0D(bch.ParametrizedSweep):
 def example_0_in_2_out(
     run_cfg: bch.BenchRunCfg = None, report: bch.BenchReport = None
 ) -> bch.Bench:
-    """This example shows how to sample a 1 dimensional float variable and plot the result of passing that parameter sweep to the benchmarking function"""
+    """This example shows how to sample a 0-dimensional variable (no input parameters)
+    that produces two output values and plot the results.
+
+    Args:
+        run_cfg: Configuration for the benchmark run
+        report: Report to append the results to
+
+    Returns:
+        bch.Bench: The benchmark object
+    """
 
     bench = SimpleFloat0D().to_bench(run_cfg, report)
     bench.plot_sweep()

bencher/example/inputs_0_float/example_0_cat_in_2_out.py

@@ -0,0 +1,88 @@
+"""This file demonstrates benchmarking with 0 categorical inputs and 2 output variables.
+
+It benchmarks a single Python operation configuration to showcase output variations
+using simulated performance data to illustrate how benchmarking works with fixed inputs.
+"""
+
+import random
+import bencher as bch
+
+random.seed(0)
+
+
+class PythonOperations0CatBenchmark(bch.ParametrizedSweep):
+    """Example class for benchmarking with no categorical variables.
+
+    This class demonstrates how to structure a benchmark with fixed inputs
+    and multiple output metrics. It uses simulated performance data that follows realistic
+    patterns while being deterministic and reproducible.
+    """
+
+    # All inputs are fixed (list data structure, read operation, medium size)
+
+    execution_time = bch.ResultVar(units="ms", doc="Execution time in milliseconds")
+    memory_peak = bch.ResultVar(units="KB", doc="Peak memory usage in kilobytes")
+
+    def __call__(self, **kwargs) -> dict:
+        """Execute the benchmark for the given set of parameters.
+
+        Args:
+            **kwargs: Parameters to update before executing
+
+        Returns:
+            dict: Dictionary containing the benchmark results
+        """
+        self.update_params_from_kwargs(**kwargs)
+
+        # Base values for list read operation on medium data
+        base_time = 28.0  # ms
+        base_memory = 960.0  # KB
+
+        # Add significant variance to show distribution of results
+        # even with fixed inputs
+        self.execution_time = base_time * random.gauss(0.75, 1.25)
+        self.memory_peak = base_memory * random.gauss(0.80, 1.20)
+
+        return super().__call__(**kwargs)
+
+
+def example_0_cat_in_2_out(
+    run_cfg: bch.BenchRunCfg = None, report: bch.BenchReport = None
+) -> bch.Bench:
+    """This example demonstrates benchmarking with no categorical variables and multiple output metrics.
+
+    It creates a synthetic benchmark that simulates performance variations when repeatedly running
+    the same operation (list read operation on medium data). This example shows that even with
+    fixed inputs, repeated benchmark runs produce variations in performance metrics.
+
+    Args:
+        run_cfg: Configuration for the benchmark run
+        report: Report to append the results to
+
+    Returns:
+        bch.Bench: The benchmark object
+    """
+
+    if run_cfg is None:
+        run_cfg = bch.BenchRunCfg()
+    run_cfg.repeats = 100  # More repeats to show distribution
+    bench = PythonOperations0CatBenchmark().to_bench(run_cfg, report)
+    bench.plot_sweep(
+        title="Python List Read Operation Performance (Fixed Inputs)",
+        description="Distribution of execution time and peak memory usage across multiple runs",
+        post_description="""
+        This benchmark illustrates how performance metrics vary even with fixed inputs.
+        
+        Key observations:
+        - Each run uses the same configuration: list data structure, read operation, medium data size
+        - Despite identical inputs, performance metrics show natural variations
+        - This variance simulates real-world system fluctuations that occur in benchmarking
+        - With no categorical variables, the benchmark helps establish baseline performance
+          distribution for a single configuration
+        """,
+    )
+    return bench
+
+
+if __name__ == "__main__":
+    example_0_cat_in_2_out().report.show()

bencher/example/inputs_0_float/example_1_cat_in_2_out.py

@@ -0,0 +1,98 @@
+"""This file demonstrates benchmarking with 1 categorical input and 2 output variables.
+
+It benchmarks different Python data structures to compare their performance characteristics
+using simulated performance data to illustrate how benchmarking works.
+"""
+
+import random
+import bencher as bch
+
+random.seed(0)
+
+
+class PythonOperations1CatBenchmark(bch.ParametrizedSweep):
+    """Example class for benchmarking different Python data structures using 1 categorical variable.
+
+    This class demonstrates how to structure a benchmark with a single input parameter
+    and multiple output metrics. It uses simulated performance data that follows realistic
+    patterns while being deterministic and reproducible.
+    """
+
+    data_structure = bch.StringSweep(["list", "dict"], doc="Type of data structure to operate on")
+
+    # Using fixed read operation and medium size data
+
+    execution_time = bch.ResultVar(units="ms", doc="Execution time in milliseconds")
+    memory_peak = bch.ResultVar(units="KB", doc="Peak memory usage in kilobytes")
+
+    def __call__(self, **kwargs) -> dict:
+        """Execute the benchmark for the given set of parameters.
+
+        Args:
+            **kwargs: Parameters to update before executing
+
+        Returns:
+            dict: Dictionary containing the benchmark results
+        """
+        self.update_params_from_kwargs(**kwargs)
+
+        # Use deterministic fake data based on parameters
+        # Base values (for read operation on medium data)
+        base_time = 35.0  # ms (medium size, read operation base)
+        base_memory = 800.0  # KB (medium size, read operation base)
+
+        # Adjust for data structure (lists are generally faster but use more memory)
+        if self.data_structure == "list":
+            time_factor = 0.8
+            memory_factor = 1.2
+        else:  # dict
+            time_factor = 1.2
+            memory_factor = 0.9
+
+        # Calculate final metrics with significant variance to show differences
+        self.execution_time = base_time * time_factor * random.gauss(0.80, 1.20)
+        self.memory_peak = base_memory * memory_factor * random.gauss(0.85, 1.15)
+
+        return super().__call__(**kwargs)
+
+
+def example_1_cat_in_2_out(
+    run_cfg: bch.BenchRunCfg = None, report: bch.BenchReport = None
+) -> bch.Bench:
+    """This example demonstrates benchmarking with 1 categorical variable and multiple output metrics.
+
+    It creates a synthetic benchmark that simulates performance characteristics of different
+    Python data structures (list vs dict) using a fixed read operation and medium data size.
+    The benchmark produces realistic patterns of execution time and memory usage without
+    actually executing real operations, making it ideal for learning and demonstration.
+
+    Args:
+        run_cfg: Configuration for the benchmark run
+        report: Report to append the results to
+
+    Returns:
+        bch.Bench: The benchmark object
+    """
+
+    if run_cfg is None:
+        run_cfg = bch.BenchRunCfg()
+    run_cfg.repeats = 5  # Fewer repeats for a quicker benchmark
+    bench = PythonOperations1CatBenchmark().to_bench(run_cfg, report)
+    bench.plot_sweep(
+        title="Python Data Structure Performance Benchmark (1 Variable)",
+        description="Comparing execution time and peak memory usage between lists and dictionaries",
+        post_description="""
+        This benchmark illustrates how different data structures affect performance.
+        
+        Key observations:
+        - Lists generally process faster than dictionaries for read operations
+        - However, lists consume more memory than dictionaries
+        - All tests were performed with read operations on medium-sized datasets
+        - Note that variance in the results simulates real-world measurement fluctuations
+        """,
+    )
+    return bench
+
+
+if __name__ == "__main__":
+    example_1_cat_in_2_out().report.show()

bencher/example/inputs_0_float/example_2_cat_in_2_out.py

@@ -0,0 +1,107 @@
+"""This file demonstrates benchmarking with 2 categorical inputs and 2 output variables.
+
+It benchmarks different Python operations to compare their performance characteristics
+using simulated performance data to illustrate how benchmarking works.
+"""
+
+import random
+import bencher as bch
+
+random.seed(0)
+
+
+class PythonOperations2CatBenchmark(bch.ParametrizedSweep):
+    """Example class for benchmarking different Python operations using 2 categorical variables.
+
+    This class demonstrates how to structure a benchmark with two input parameters
+    and multiple output metrics. It uses simulated performance data that follows realistic
+    patterns while being deterministic and reproducible.
+    """
+
+    data_structure = bch.StringSweep(["list", "dict"], doc="Type of data structure to operate on")
+    operation_type = bch.StringSweep(["read", "write"], doc="Type of operation to perform")
+
+    # Using fixed medium size data instead of a variable
+
+    execution_time = bch.ResultVar(units="ms", doc="Execution time in milliseconds")
+    memory_peak = bch.ResultVar(units="KB", doc="Peak memory usage in kilobytes")
+
+    def __call__(self, **kwargs) -> dict:
+        """Execute the benchmark for the given set of parameters.
+
+        Args:
+            **kwargs: Parameters to update before executing
+
+        Returns:
+            dict: Dictionary containing the benchmark results
+        """
+        self.update_params_from_kwargs(**kwargs)
+
+        # Use deterministic fake data based on parameters
+        # Base values that will be modified by our parameters
+        base_time = 50.0  # ms (medium size base)
+        base_memory = 1000.0  # KB (medium size base)
+
+        # Adjust for data structure (lists are generally faster but use more memory)
+        if self.data_structure == "list":
+            time_factor = 0.8
+            memory_factor = 1.2
+        else:  # dict
+            time_factor = 1.2
+            memory_factor = 0.9
+
+        # Adjust for operation type (reads are faster than writes)
+        if self.operation_type == "read":
+            time_factor *= 0.7
+            memory_factor *= 0.8
+        else:  # write
+            time_factor *= 1.4
+            memory_factor *= 1.3
+
+        # Calculate final metrics with variance
+        self.execution_time = base_time * time_factor * random.gauss(0.85, 1.15)
+        self.memory_peak = base_memory * memory_factor * random.gauss(0.90, 1.10)
+
+        return super().__call__(**kwargs)
+
+
+def example_2_cat_in_2_out(
+    run_cfg: bch.BenchRunCfg = None, report: bch.BenchReport = None
+) -> bch.Bench:
+    """This example demonstrates benchmarking with 2 categorical variables and multiple output metrics.
+
+    It creates a synthetic benchmark that simulates performance characteristics of different
+    Python operations, varying data structures and operation types using a fixed medium data size.
+    The benchmark produces realistic patterns of execution time and memory usage without actually
+    executing real operations, making it ideal for learning and demonstration.
+
+    Args:
+        run_cfg: Configuration for the benchmark run
+        report: Report to append the results to
+
+    Returns:
+        bch.Bench: The benchmark object
+    """
+
+    if run_cfg is None:
+        run_cfg = bch.BenchRunCfg()
+    run_cfg.repeats = 5  # Fewer repeats for a quicker benchmark
+    bench = PythonOperations2CatBenchmark().to_bench(run_cfg, report)
+    bench.plot_sweep(
+        title="Python Operations Performance Benchmark (2 Variables)",
+        description="Comparing execution time and peak memory usage across Python data structures and operations",
+        post_description="""
+        This benchmark illustrates how different data structures and operations affect performance.
+        
+        Key observations:
+        - Lists generally process faster than dictionaries for these operations
+        - Read operations outperform write operations as expected
+        - All tests were performed with a fixed medium-sized dataset
+        - Note that variance in the results simulates real-world measurement fluctuations
+        """,
+    )
+    return bench
+
+
+if __name__ == "__main__":
+    example_2_cat_in_2_out().report.show()

bencher/example/inputs_0_float/example_3_cat_in_2_out.py

@@ -0,0 +1,111 @@
+"""This file demonstrates benchmarking with 3 categorical inputs and 2 output variables.
+
+It benchmarks different Python operations to compare their performance characteristics
+using simulated performance data to illustrate how benchmarking works.
+"""
+
+import random
+import bencher as bch
+
+random.seed(0)
+
+
+class PythonOperationsBenchmark(bch.ParametrizedSweep):
+    """Example class for benchmarking different Python operations using categorical variables.
+
+    This class demonstrates how to structure a benchmark with multiple input parameters
+    and multiple output metrics. It uses simulated performance data that follows realistic
+    patterns while being deterministic and reproducible.
+    """
+
+    data_structure = bch.StringSweep(["list", "dict"], doc="Type of data structure to operate on")
+    operation_type = bch.StringSweep(["read", "write"], doc="Type of operation to perform")
+    data_size = bch.StringSweep(["small", "medium"], doc="Size of data to process")
+
+    execution_time = bch.ResultVar(units="ms", doc="Execution time in milliseconds")
+    memory_peak = bch.ResultVar(units="KB", doc="Peak memory usage in kilobytes")
+
+    def __call__(self, **kwargs) -> dict:
+        """Execute the benchmark for the given set of parameters.
+
+        Args:
+            **kwargs: Parameters to update before executing
+
+        Returns:
+            dict: Dictionary containing the benchmark results
+        """
+        self.update_params_from_kwargs(**kwargs)
+
+        # Use deterministic fake data based on parameters
+        # Base values that will be modified by our parameters
+        base_time = 10.0  # ms
+        base_memory = 100.0  # KB
+
+        # Adjust for data structure (lists are generally faster but use more memory)
+        if self.data_structure == "list":
+            time_factor = 0.8
+            memory_factor = 1.2
+        else:  # dict
+            time_factor = 1.2
+            memory_factor = 0.9
+
+        # Adjust for operation type (reads are faster than writes)
+        if self.operation_type == "read":
+            time_factor *= 0.7
+            memory_factor *= 0.8
+        else:  # write
+            time_factor *= 1.4
+            memory_factor *= 1.3
+
+        # Adjust for data size
+        if self.data_size == "medium":
+            time_factor *= 5
+            memory_factor *= 10
+
+        # Calculate final metrics with increased variance
+        self.execution_time = base_time * time_factor * random.gauss(0.85, 1.15)
+        self.memory_peak = base_memory * memory_factor * random.gauss(0.90, 1.10)
+
+        return super().__call__(**kwargs)
+
+
+def example_3_cat_in_2_out(
+    run_cfg: bch.BenchRunCfg = None, report: bch.BenchReport = None
+) -> bch.Bench:
+    """This example demonstrates benchmarking with categorical variables and multiple output metrics.
+
+    It creates a synthetic benchmark that simulates performance characteristics of different
+    Python operations, varying data structures, operation types, and data sizes. The benchmark
+    produces realistic patterns of execution time and memory usage without actually executing
+    real operations, making it ideal for learning and demonstration.
+
+    Args:
+        run_cfg: Configuration for the benchmark run
+        report: Report to append the results to
+
+    Returns:
+        bch.Bench: The benchmark object
+    """
+
+    if run_cfg is None:
+        run_cfg = bch.BenchRunCfg()
+    run_cfg.repeats = 5  # Fewer repeats for a quicker benchmark
+    bench = PythonOperationsBenchmark().to_bench(run_cfg, report)
+    bench.plot_sweep(
+        title="Python Operations Performance Benchmark",
+        description="Comparing execution time and peak memory usage across Python data structures and operations",
+        post_description="""
+        This benchmark illustrates how different data structures and operations affect performance.
+        
+        Key observations:
+        - Lists generally process faster than dictionaries for these operations
+        - Read operations outperform write operations as expected
+        - Medium-sized data requires significantly more resources than small data
+        - Note that variance in the results simulates real-world measurement fluctuations
+        """,
+    )
+    return bench
+
+
+if __name__ == "__main__":
+    example_3_cat_in_2_out().report.show()

bencher/example/inputs_1D/example1d_common.py

@@ -4,7 +4,10 @@ import bencher as bch
 
 
 class DataSource:
+    """A simple data source class that provides access to predefined data points."""
+
     def __init__(self):
+        """Initialize the data source with predefined values and call counts."""
         self.data = [
             [0, 0, 0, 0],
             [1, 1, 1, 1],
@@ -16,7 +19,16 @@ class DataSource:
 
         self.call_count = [0] * len(self.data)
 
-    def call(self, index, repeat=None):
+    def call(self, index: int, repeat: int = None) -> int:
+        """Retrieve a data point at the specified index and repeat count.
+
+        Args:
+            index: The index of the data row to access
+            repeat: The specific repeat count to use. If None, uses and increments internal counter
+
+        Returns:
+            int: The value at the specified index and repeat position
+        """
         if repeat is None:
             self.call_count[index] += 1
             repeat = self.call_count[index]
@@ -24,16 +36,31 @@ class DataSource:
 
 
 class Example1D(bch.ParametrizedSweep):
-    index = bch.IntSweep(default=0, bounds=[0, 5], doc="Input angle", units="rad", samples=30)
-    output = bch.ResultVar(units="v", doc="sin of theta")
-    output2 = bch.ResultVar(units="v", doc="-sin of theta")
+    """Example 1D parameter sweep class with one input and two output dimensions."""
+
+    index = bch.IntSweep(default=0, bounds=[0, 5], doc="Input index", units="rad", samples=30)
+    output = bch.ResultVar(units="v", doc="Output value from data source 1")
+    output2 = bch.ResultVar(units="v", doc="Negated output value from data source 2")
 
     def __init__(self, **params):
+        """Initialize the Example1D sweep with two data sources.
+
+        Args:
+            **params: Parameters to pass to the parent class constructor
+        """
         super().__init__(**params)
         self.data1 = DataSource()
         self.data2 = DataSource()
 
-    def __call__(self, **kwargs):
+    def __call__(self, **kwargs) -> dict:
+        """Execute the parameter sweep for the given parameters.
+
+        Args:
+            **kwargs: Additional parameters to update before executing
+
+        Returns:
+            dict: Dictionary containing the outputs of the parameter sweep
+        """
         self.update_params_from_kwargs(**kwargs)
         self.output = self.data1.call(self.index)
         self.output2 = -self.data2.call(self.index)
@@ -43,7 +70,16 @@ class Example1D(bch.ParametrizedSweep):
 def example_1_in_2_out(
     run_cfg: bch.BenchRunCfg = None, report: bch.BenchReport = None
 ) -> bch.Bench:
-    """This example shows how to sample a 1 dimensional float variable and plot the result of passing that parameter sweep to the benchmarking function"""
+    """This example shows how to sample a 1-dimensional integer variable and plot
+    the result of two output variables from that parameter sweep.
+
+    Args:
+        run_cfg: Configuration for the benchmark run
+        report: Report to append the results to
+
+    Returns:
+        bch.Bench: The benchmark object
+    """
     bench = Example1D().to_bench(run_cfg, report)
     bench.plot_sweep()
 
@@ -53,17 +89,17 @@ def example_1_in_2_out(
 
 if __name__ == "__main__":
     run_config = bch.BenchRunCfg()
-    reprt = bch.BenchReport()
-    example_1_in_2_out(run_config, reprt)
+    report_obj = bch.BenchReport()
+    example_1_in_2_out(run_config, report_obj)
 
     run_config.repeats = 4
-    example_1_in_2_out(run_config, reprt)
+    example_1_in_2_out(run_config, report_obj)
 
     # run_config.over_time = True
     # run_config.auto_plot = False
     # for i in range(4):
-    #     example_1_in_2_out(run_config, reprt)
+    #     example_1_in_2_out(run_config, report_obj)
 
     # run_config.auto_plot = True
-    # example_1_in_2_out(run_config, reprt)
-    reprt.show()
+    # example_1_in_2_out(run_config, report_obj)
+    report_obj.show()

bencher/example/inputs_1D/example_0_float_1_cat.py

@@ -0,0 +1,33 @@
+"""This file demonstrates benchmarking with both categorical and float variables."""
+
+import bencher as bch
+from bencher.example.meta.example_meta import BenchableObject
+
+run_cfg = bch.BenchRunCfg()
+run_cfg.repeats = 2  # only shows distance
+run_cfg.level = 4
+bench = BenchableObject().to_bench(run_cfg)
+# bench.worker_class_instance.float2=0.2
+run_cfg.repeats = 1
+# WORKS
+# shows both distance and simple noise
+res = bench.plot_sweep(input_vars=["float1"], result_vars=["distance", "sample_noise"])
+
+# WORKS
+# shows both distance and simple noise
+res = bench.plot_sweep(input_vars=["noisy"], result_vars=["distance", "sample_noise"])
+
+
+run_cfg.repeats = 10  # If i set repeats>1 then floating point variables still work but categorical variables do not
+# WORKS
+# shows both distance and simple noise
+res = bench.plot_sweep(input_vars=["float1"], result_vars=["distance", "sample_noise"])
+
+# BUG
+# only shows distance result var, ignores sample_noise
+res = bench.plot_sweep(input_vars=["noisy"], result_vars=["distance", "sample_noise"])
+
+
+bench.report.append(res.to_tabulator())
+# bench.report.append(res.to_scatter_jitter_single(BenchableObject.param.sample_noise))
+bench.report.show()

bencher/example/inputs_1D/example_1_cat_in_2_out_repeats.py

@@ -0,0 +1,68 @@
+"""This file demonstrates benchmarking with categorical inputs and multiple outputs with repeats."""
+
+import random
+import bencher as bch
+
+random.seed(0)
+
+
+class DataStructureBenchmark(bch.ParametrizedSweep):
+    """Example class for comparing different data structure operations with two output variables."""
+
+    operation = bch.StringSweep(
+        ["list_append", "dict_insert"],
+        doc="Type of data structure operation to benchmark",
+    )
+    execution_time = bch.ResultVar(units="ms", doc="Time taken to complete operations")
+    memory_usage = bch.ResultVar(units="KB", doc="Memory used by the operation")
+
+    def __call__(self, **kwargs) -> dict:
+        """Execute the parameter sweep for the given data structure operation.
+
+        Args:
+            **kwargs: Additional parameters to update before executing
+
+        Returns:
+            dict: Dictionary containing the outputs of the parameter sweep
+        """
+        self.update_params_from_kwargs(**kwargs)
+
+        # Simple simulations of different data structure operations
+        # In a real benchmark, you would implement or measure actual operations
+
+        if self.operation == "list_append":
+            # List append operations (typically fast for adding elements)
+            self.execution_time = random.gauss(mu=5.0, sigma=1.0)
+            self.memory_usage = random.gauss(mu=120.0, sigma=20.0)
+        elif self.operation == "dict_insert":
+            # Dictionary insertions (hash table operations)
+            self.execution_time = random.gauss(mu=6.5, sigma=1.2)
+            self.memory_usage = random.gauss(mu=180.0, sigma=25.0)
+
+        return super().__call__(**kwargs)
+
+
+def example_1_cat_in_2_out_repeats(
+    run_cfg: bch.BenchRunCfg = None, report: bch.BenchReport = None
+) -> bch.Bench:
+    """This example shows how to benchmark different data structure operations with multiple repeats
+    and plot the results of execution time and memory usage.
+
+    Args:
+        run_cfg: Configuration for the benchmark run
+        report: Report to append the results to
+
+    Returns:
+        bch.Bench: The benchmark object
+    """
+
+    if run_cfg is None:
+        run_cfg = bch.BenchRunCfg()
+    run_cfg.repeats = 30  # Increased repeats for better statistical significance
+    bench = DataStructureBenchmark().to_bench(run_cfg, report)
+    bench.plot_sweep()
+    return bench
+
+
+if __name__ == "__main__":
+    example_1_cat_in_2_out_repeats().report.show()

bencher/example/inputs_1D/example_1_float_2_cat_repeats.py

@@ -1,6 +1,9 @@
+"""This file demonstrates benchmarking with both float and categorical variables with repeats."""
+
 import bencher as bch
 from bencher.example.meta.example_meta import BenchableObject
 
+# Configure and run a benchmark with multiple input types and repeats
 run_cfg = bch.BenchRunCfg()
 run_cfg.repeats = 20
 run_cfg.level = 4