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

bencher/example/inputs_1D/example_1_int_in_1_out.py

@@ -0,0 +1,98 @@
+"""This file has some examples for how to perform basic benchmarking parameter sweeps"""
+
+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],
+            [1, 1, 1, 1],
+            [2, 1, 1, 0],
+            [2, 2, 0, 0],
+            [2, 2, 1, 1],
+        ]
+
+        self.call_count = [0] * len(self.data)
+
+    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]
+        print(index, repeat)
+        return self.data[index][repeat - 1]
+
+
+class Example1D(bch.ParametrizedSweep):
+    """Example 1D parameter sweep class with one input dimension and one output dimension."""
+
+    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")
+
+    def __init__(self, **params):
+        """Initialize the Example1D sweep with a data source.
+
+        Args:
+            **params: Parameters to pass to the parent class constructor
+        """
+        super().__init__(**params)
+        self.data1 = DataSource()
+
+    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 output of the parameter sweep
+        """
+        self.update_params_from_kwargs(**kwargs)
+        self.output = self.data1.call(self.index)
+        return super().__call__(**kwargs)
+
+
+def example_1_int_in_1_out(
+    run_cfg: bch.BenchRunCfg = None, report: bch.BenchReport = None
+) -> bch.Bench:
+    """This example shows how to sample a 1-dimensional integer variable and plot
+    the result of 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()
+    return bench
+
+
+if __name__ == "__main__":
+    run_config = bch.BenchRunCfg()
+    report_obj = bch.BenchReport()
+    example_1_int_in_1_out(run_config, report_obj)
+
+    run_config.repeats = 4
+    example_1_int_in_1_out(run_config, report_obj)
+
+    # run_cfg.over_time = True
+    # for i in range(4):
+    #     example_1_in_2_out(run_cfg, report_obj)
+
+    report_obj.show()

bencher/example/inputs_1D/example_1_int_in_2_out.py

@@ -0,0 +1,101 @@
+"""This file has examples for how to perform basic benchmarking parameter sweeps"""
+
+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],
+            [1, 1, 1, 1],
+            [2, 1, 1, 0],
+            [2, 2, 0, 0],
+            [2, 2, 1, 1],
+        ]
+
+        self.call_count = [0] * len(self.data)
+
+    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]
+        return self.data[index][repeat - 1]
+
+
+class Example1D(bch.ParametrizedSweep):
+    """Example 1D parameter sweep class with one input dimension 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) -> 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)
+        return super().__call__(**kwargs)
+
+
+def example_1_int_in_2_out(
+    run_cfg: bch.BenchRunCfg = None, report: bch.BenchReport = None
+) -> bch.Bench:
+    """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()
+
+    # bench.report.append(bench.get_result().to_heatmap())
+    return bench
+
+
+if __name__ == "__main__":
+    run_config = bch.BenchRunCfg()
+    report_obj = bch.BenchReport()
+    example_1_int_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, report_obj)
+
+    # run_config.auto_plot = True
+    # example_1_in_2_out(run_config, report_obj)
+    report_obj.show()

bencher/example/inputs_1D/example_1_int_in_2_out_repeats.py

@@ -0,0 +1,99 @@
+"""This file has examples for how to perform basic benchmarking parameter sweeps with repeats"""
+
+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],
+            [1, 1, 1, 1],
+            [2, 1, 1, 0],
+            [2, 2, 0, 0],
+            [2, 2, 1, 1],
+        ]
+
+        self.call_count = [0] * len(self.data)
+
+    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]
+        return self.data[index][repeat - 1]
+
+
+class Example1D(bch.ParametrizedSweep):
+    """Example 1D parameter sweep class with one input dimension 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) -> 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)
+        return super().__call__(**kwargs)
+
+
+def example_1_int_in_2_out_repeats(
+    run_cfg: bch.BenchRunCfg = None, report: bch.BenchReport = None
+) -> bch.Bench:
+    """This example shows how to sample a 1-dimensional integer variable with multiple repeats
+    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
+    """
+
+    from importlib.metadata import version
+
+    print(version("holobench"))
+    if run_cfg is None:
+        run_cfg = bch.BenchRunCfg()
+    run_cfg.repeats = 4
+    bench = Example1D().to_bench(run_cfg, report)
+    bench.plot_sweep()
+    return bench
+
+
+if __name__ == "__main__":
+    run_config = bch.BenchRunCfg()
+    report_obj = bch.BenchReport()
+    example_1_int_in_2_out_repeats(run_config, report_obj)
+    report_obj.show()

bencher/example/inputs_1_float/example_1_float_0_cat_in_2_out.py

@@ -0,0 +1,117 @@
+"""This file demonstrates benchmarking with 1 float input and 0 categorical inputs with 2 output variables.
+
+It benchmarks a single algorithm configuration across different problem sizes to show
+how performance scales, using simulated performance data to illustrate benchmarking basics.
+"""
+
+import random
+import math
+import bencher as bch
+
+random.seed(0)
+
+
+class Algorithm0CatBenchmark(bch.ParametrizedSweep):
+    """Example class for benchmarking algorithm performance with just problem size.
+
+    This class demonstrates how to structure a benchmark with one float parameter and
+    no categorical parameters, producing multiple output metrics. It uses simulated
+    performance data that follows realistic patterns while being deterministic.
+    """
+
+    # Float input parameter
+    problem_size = bch.FloatSweep(default=100, bounds=[1, 100], doc="Size of the problem to solve")
+
+    # Using fixed "iterative" algorithm, "array" data structure, and "basic" optimization level
+
+    # Output metrics
+    execution_time = bch.ResultVar(units="ms", doc="Execution time in milliseconds")
+    memory_usage = bch.ResultVar(units="MB", doc="Memory usage in megabytes")
+
+    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 calculation
+        base_time = 1.0  # ms
+        base_memory = 0.1  # MB
+
+        # Size factor (non-linear relationship with problem size)
+        size_factor_time = math.log10(self.problem_size) ** 1.5
+        size_factor_memory = math.sqrt(self.problem_size) / 10
+
+        # Fixed "iterative" algorithm factors (from previous example)
+        algo_time_factor = 0.8  # Iterative is faster
+        algo_memory_factor = 0.7  # Iterative uses less memory
+
+        # Fixed "array" data structure factors (from previous example)
+        ds_time_factor = 0.9  # Arrays have faster access
+        ds_memory_factor = 1.1  # Arrays use slightly more contiguous memory
+
+        # Fixed "basic" optimization level factors (from previous example)
+        opt_time_factor = 1.0
+        opt_memory_factor = 1.0
+
+        # Calculate final metrics with some random variation
+        time_multiplier = (
+            algo_time_factor * ds_time_factor * opt_time_factor * random.uniform(0.9, 1.1)
+        )
+        memory_multiplier = (
+            algo_memory_factor * ds_memory_factor * opt_memory_factor * random.uniform(0.95, 1.05)
+        )
+
+        self.execution_time = base_time * size_factor_time * time_multiplier
+        self.memory_usage = base_memory * size_factor_memory * memory_multiplier
+
+        return super().__call__(**kwargs)
+
+
+def example_1_float_0_cat_in_2_out(
+    run_cfg: bch.BenchRunCfg = None, report: bch.BenchReport = None
+) -> bch.Bench:
+    """This example demonstrates benchmarking with 1 float input and 0 categorical inputs.
+
+    It creates a synthetic benchmark that simulates performance characteristics of an
+    algorithm configuration across different problem sizes. The benchmark uses fixed
+    "iterative" algorithm, "array" data structure, and "basic" optimization level,
+    producing realistic patterns of execution time and memory usage without actually
+    executing real algorithms.
+
+    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  # Slightly more repeats to show variance
+    bench = Algorithm0CatBenchmark().to_bench(run_cfg, report)
+    bench.plot_sweep(
+        title="Algorithm Performance Benchmark (1 Float, 0 Categorical Variables)",
+        description="Analyzing how execution time and memory usage scale with problem size",
+        post_description="""
+        This benchmark illustrates how algorithm performance scales with problem size.
+        
+        Key observations:
+        - Execution time increases non-linearly with problem size (logarithmic relationship)
+        - Memory usage scales more gradually (square root relationship)
+        - All tests were performed with an iterative algorithm on array data structure with basic optimization
+        - Small variations in performance metrics simulate the natural fluctuations seen in real benchmarks
+        - This type of benchmark is useful for understanding scaling properties of a single algorithm configuration
+        """,
+    )
+    return bench
+
+
+if __name__ == "__main__":
+    example_1_float_0_cat_in_2_out().report.show()

bencher/example/inputs_1_float/example_1_float_1_cat_in_2_out.py

@@ -0,0 +1,124 @@
+"""This file demonstrates benchmarking with 1 float and 1 categorical input with 2 output variables.
+
+It benchmarks different algorithmic implementations to compare their performance characteristics
+using simulated performance data to illustrate how benchmarking works.
+"""
+
+import random
+import math
+import bencher as bch
+
+random.seed(0)
+
+
+class Algorithm1CatBenchmark(bch.ParametrizedSweep):
+    """Example class for benchmarking algorithm performance with fewer parameters.
+
+    This class demonstrates how to structure a benchmark with one float parameter and
+    one categorical parameter, producing multiple output metrics. It uses simulated
+    performance data that follows realistic patterns while being deterministic.
+    """
+
+    # Float input parameter
+    problem_size = bch.FloatSweep(default=100, bounds=[1, 100], doc="Size of the problem to solve")
+
+    # Categorical input parameter
+    algorithm_type = bch.StringSweep(
+        ["recursive", "iterative"], doc="Type of algorithm implementation"
+    )
+
+    # Using fixed "array" data structure and "basic" optimization level
+
+    # Output metrics
+    execution_time = bch.ResultVar(units="ms", doc="Execution time in milliseconds")
+    memory_usage = bch.ResultVar(units="MB", doc="Memory usage in megabytes")
+
+    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 calculation
+        base_time = 1.0  # ms
+        base_memory = 0.1  # MB
+
+        # Size factor (non-linear relationship with problem size)
+        size_factor_time = math.log10(self.problem_size) ** 1.5
+        size_factor_memory = math.sqrt(self.problem_size) / 10
+
+        # Algorithm type factor
+        if self.algorithm_type == "recursive":
+            algo_time_factor = 1.2  # Recursive is slower
+            algo_memory_factor = 1.5  # Recursive uses more memory (stack)
+        else:  # iterative
+            algo_time_factor = 0.8  # Iterative is faster
+            algo_memory_factor = 0.7  # Iterative uses less memory
+
+        # Fixed "array" data structure factors (from previous example)
+        ds_time_factor = 0.9  # Arrays have faster access
+        ds_memory_factor = 1.1  # Arrays use slightly more contiguous memory
+
+        # Fixed "basic" optimization level factors (from previous example)
+        opt_time_factor = 1.0
+        opt_memory_factor = 1.0
+
+        # Calculate final metrics with some random variation
+        time_multiplier = (
+            algo_time_factor * ds_time_factor * opt_time_factor * random.uniform(0.9, 1.1)
+        )
+        memory_multiplier = (
+            algo_memory_factor * ds_memory_factor * opt_memory_factor * random.uniform(0.95, 1.05)
+        )
+
+        self.execution_time = base_time * size_factor_time * time_multiplier
+        self.memory_usage = base_memory * size_factor_memory * memory_multiplier
+
+        return super().__call__(**kwargs)
+
+
+def example_1_float_1_cat_in_2_out(
+    run_cfg: bch.BenchRunCfg = None, report: bch.BenchReport = None
+) -> bch.Bench:
+    """This example demonstrates benchmarking with 1 float and 1 categorical input.
+
+    It creates a synthetic benchmark that simulates performance characteristics of different
+    algorithm implementations, varying problem size (float) and algorithm type. The benchmark
+    uses fixed "array" data structure and "basic" optimization level, producing realistic
+    patterns of execution time and memory usage without actually executing real algorithms.
+
+    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 = 3  # Fewer repeats for a quicker benchmark
+    bench = Algorithm1CatBenchmark().to_bench(run_cfg, report)
+    bench.plot_sweep(
+        title="Algorithm Performance Benchmark (1 Float, 1 Categorical Variable)",
+        description="Comparing execution time and memory usage across problem sizes and algorithm types",
+        post_description="""
+        This benchmark illustrates how different algorithm implementations affect performance across problem sizes.
+        
+        Key observations:
+        - Execution time increases non-linearly with problem size
+        - Iterative algorithms typically outperform recursive ones in both time and memory usage
+        - All tests were performed with array data structure and basic optimization level
+        - The performance gap between recursive and iterative approaches widens as problem size increases
+        """,
+    )
+    return bench
+
+
+if __name__ == "__main__":
+    example_1_float_1_cat_in_2_out().report.show()

bencher/example/inputs_1_float/example_1_float_2_cat_in_2_out.py

@@ -0,0 +1,132 @@
+"""This file demonstrates benchmarking with 1 float and 2 categorical inputs with 2 output variables.
+
+It benchmarks different algorithmic configurations to compare their performance characteristics
+using simulated performance data to illustrate how benchmarking works.
+"""
+
+import random
+import math
+import bencher as bch
+
+random.seed(0)
+
+
+class Algorithm2CatBenchmark(bch.ParametrizedSweep):
+    """Example class for benchmarking algorithm performance with various parameters.
+
+    This class demonstrates how to structure a benchmark with one float parameter and
+    two categorical parameters, producing multiple output metrics. It uses simulated
+    performance data that follows realistic patterns while being deterministic.
+    """
+
+    # Float input parameter
+    problem_size = bch.FloatSweep(default=100, bounds=[1, 100], doc="Size of the problem to solve")
+
+    # Categorical input parameters
+    algorithm_type = bch.StringSweep(
+        ["recursive", "iterative"], doc="Type of algorithm implementation"
+    )
+    data_structure = bch.StringSweep(
+        ["array", "linked_list"], doc="Underlying data structure to use"
+    )
+
+    # Using fixed "basic" optimization level
+
+    # Output metrics
+    execution_time = bch.ResultVar(units="ms", doc="Execution time in milliseconds")
+    memory_usage = bch.ResultVar(units="MB", doc="Memory usage in megabytes")
+
+    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 calculation
+        base_time = 1.0  # ms
+        base_memory = 0.1  # MB
+
+        # Size factor (non-linear relationship with problem size)
+        size_factor_time = math.log10(self.problem_size) ** 1.5
+        size_factor_memory = math.sqrt(self.problem_size) / 10
+
+        # Algorithm type factor
+        if self.algorithm_type == "recursive":
+            algo_time_factor = 1.2  # Recursive is slower
+            algo_memory_factor = 1.5  # Recursive uses more memory (stack)
+        else:  # iterative
+            algo_time_factor = 0.8  # Iterative is faster
+            algo_memory_factor = 0.7  # Iterative uses less memory
+
+        # Data structure factor
+        if self.data_structure == "array":
+            ds_time_factor = 0.9  # Arrays have faster access
+            ds_memory_factor = 1.1  # Arrays use slightly more contiguous memory
+        else:  # linked_list
+            ds_time_factor = 1.3  # Linked lists have slower access
+            ds_memory_factor = 0.9  # Linked lists might use less memory
+
+        # Fixed "basic" optimization level factors (from previous example)
+        opt_time_factor = 1.0
+        opt_memory_factor = 1.0
+
+        # Calculate final metrics with some random variation
+        time_multiplier = (
+            algo_time_factor * ds_time_factor * opt_time_factor * random.uniform(0.9, 1.1)
+        )
+        memory_multiplier = (
+            algo_memory_factor * ds_memory_factor * opt_memory_factor * random.uniform(0.95, 1.05)
+        )
+
+        self.execution_time = base_time * size_factor_time * time_multiplier
+        self.memory_usage = base_memory * size_factor_memory * memory_multiplier
+
+        return super().__call__(**kwargs)
+
+
+def example_1_float_2_cat_in_2_out(
+    run_cfg: bch.BenchRunCfg = None, report: bch.BenchReport = None
+) -> bch.Bench:
+    """This example demonstrates benchmarking with 1 float and 2 categorical inputs.
+
+    It creates a synthetic benchmark that simulates performance characteristics of different
+    algorithm configurations, varying problem size (float), algorithm type, and data structure.
+    The benchmark uses a fixed "basic" optimization level and produces realistic patterns
+    of execution time and memory usage without actually executing real algorithms.
+
+    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 = 3  # Fewer repeats for a quicker benchmark
+    bench = Algorithm2CatBenchmark().to_bench(run_cfg, report)
+    bench.plot_sweep(
+        title="Algorithm Performance Benchmark (1 Float, 2 Categorical Variables)",
+        description="Comparing execution time and memory usage across problem sizes, algorithm types, and data structures",
+        post_description="""
+        This benchmark illustrates how different algorithm configurations affect performance across problem sizes.
+        
+        Key observations:
+        - Execution time generally increases non-linearly with problem size
+        - Iterative algorithms typically outperform recursive ones in both time and memory
+        - Arrays provide faster access than linked lists but may use more memory
+        - All tests were performed with basic optimization level
+        - The combination of algorithm type and data structure creates distinct performance profiles
+        """,
+    )
+    return bench
+
+
+if __name__ == "__main__":
+    example_1_float_2_cat_in_2_out().report.show()