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

bencher/example/inputs_1_float/example_1_float_3_cat_in_2_out.py

@@ -0,0 +1,140 @@
+"""This file demonstrates benchmarking with 1 float and 3 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 AlgorithmBenchmark(bch.ParametrizedSweep):
+    """Example class for benchmarking algorithm performance with various parameters.
+
+    This class demonstrates how to structure a benchmark with one float parameter and
+    three 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"
+    )
+    optimization_level = bch.StringSweep(
+        ["none", "basic", "advanced"], doc="Level of optimization applied"
+    )
+
+    # 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
+
+        # Optimization level factor
+        if self.optimization_level == "none":
+            opt_time_factor = 1.5
+            opt_memory_factor = 0.8
+        elif self.optimization_level == "basic":
+            opt_time_factor = 1.0
+            opt_memory_factor = 1.0
+        else:  # advanced
+            opt_time_factor = 0.6
+            opt_memory_factor = 1.2  # Better time but more memory usage
+
+        # 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_3_cat_in_2_out(
+    run_cfg: bch.BenchRunCfg = None, report: bch.BenchReport = None
+) -> bch.Bench:
+    """This example demonstrates benchmarking with 1 float and 3 categorical inputs.
+
+    It creates a synthetic benchmark that simulates performance characteristics of different
+    algorithm configurations, varying problem size (float), algorithm type, data structure,
+    and optimization level. The benchmark 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 = AlgorithmBenchmark().to_bench(run_cfg, report)
+    bench.plot_sweep(
+        title="Algorithm Performance Benchmark (1 Float, 3 Categorical Variables)",
+        description="Comparing execution time and memory usage across problem sizes and algorithm configurations",
+        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
+        - Advanced optimization improves speed but can increase memory usage
+        - Performance characteristics vary significantly based on the combination of all parameters
+        """,
+    )
+    return bench
+
+
+if __name__ == "__main__":
+    example_1_float_3_cat_in_2_out().report.show()

bencher/example/inputs_2D/example_2_cat_in_4_out_repeats.py

@@ -0,0 +1,104 @@
+"""This file demonstrates benchmarking with categorical inputs and multiple outputs with repeats.
+
+It simulates comparing programming languages and development environments, measuring
+performance and developer productivity metrics.
+"""
+
+import random
+import bencher as bch
+
+random.seed(42)  # Fixed seed for reproducibility
+
+
+class ProgrammingBenchmark(bch.ParametrizedSweep):
+    """Benchmark class comparing programming languages and development environments."""
+
+    language = bch.StringSweep(
+        ["Python", "JavaScript", "Rust", "Go"], doc="Programming language being benchmarked"
+    )
+    environment = bch.StringSweep(
+        ["Development", "Testing", "Production"], doc="Environment configuration"
+    )
+
+    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 parameter sweep for the given inputs.
+
+        Args:
+            **kwargs: Additional parameters to update before executing
+
+        Returns:
+            dict: Dictionary containing the outputs of the parameter sweep
+        """
+        self.update_params_from_kwargs(**kwargs)
+
+        # Base values that will be modified by language and environment
+        base_execution = 0
+        base_memory = 0
+
+        # Different languages have different performance characteristics
+        if self.language == "Python":
+            base_execution = 150
+            base_memory = 80
+        elif self.language == "JavaScript":
+            base_execution = 100
+            base_memory = 60
+        elif self.language == "Rust":
+            base_execution = 20
+            base_memory = 15
+        elif self.language == "Go":
+            base_execution = 40
+            base_memory = 30
+
+        # Environment affects performance
+        if self.environment == "Development":
+            # Dev environments have debugging overhead
+            env_exec_modifier = 1.5
+            env_mem_modifier = 1.3
+        elif self.environment == "Testing":
+            # Testing has moderate overhead
+            env_exec_modifier = 1.2
+            env_mem_modifier = 1.1
+        else:  # Production
+            # Production is optimized
+            env_exec_modifier = 1.0
+            env_mem_modifier = 1.0
+
+        # Calculate final values with some randomness
+        self.execution_time = base_execution * env_exec_modifier * random.uniform(0.9, 1.1)
+        self.memory_usage = base_memory * env_mem_modifier * random.uniform(0.95, 1.05)
+
+        return super().__call__(**kwargs)
+
+
+def example_2_cat_in_4_out_repeats(
+    run_cfg: bch.BenchRunCfg = None, report: bch.BenchReport = None
+) -> bch.Bench:
+    """This example compares performance metrics across programming languages and environments.
+
+    It demonstrates how to sample categorical variables with multiple repeats
+    and plot the results of two output variables.
+
+    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 = 15  # Run multiple times to get statistical significance
+    bench = ProgrammingBenchmark().to_bench(run_cfg, report)
+    bench.plot_sweep(
+        title="Programming Language and Environment Performance Metrics",
+        description="Comparing execution time and memory usage across different programming languages and environments",
+    )
+    return bench
+
+
+if __name__ == "__main__":
+    example_2_cat_in_4_out_repeats().report.show()

bencher/example/inputs_2_float/example_2_float_0_cat_in_2_out.py

@@ -0,0 +1,98 @@
+"""Demonstration of benchmarking with 2 float inputs and 0 categorical inputs producing a distinct pattern.
+
+The two float inputs create a visually distinctive surface shape.
+"""
+
+import random
+import math
+import bencher as bch
+
+random.seed(0)
+
+
+class Pattern0CatBenchmark(bch.ParametrizedSweep):
+    """Benchmark demonstrating patterns with two float inputs and no categorical variables."""
+
+    # Float input parameters
+    x_value = bch.FloatSweep(default=100, bounds=[1, 100], doc="X value parameter")
+    y_value = bch.FloatSweep(default=10, bounds=[1, 100], doc="Y value parameter")
+
+    # No categorical input parameters
+
+    # Output metrics
+    response_a = bch.ResultVar(units="units", doc="Response variable A")
+    response_b = bch.ResultVar(units="units", doc="Response variable B")
+
+    def __call__(self, **kwargs) -> dict:
+        """Generate responses with a distinctive pattern based on x and y values."""
+        self.update_params_from_kwargs(**kwargs)
+
+        # Normalize inputs to [0,1]
+        x = self.x_value / 100
+        y = self.y_value / 100
+
+        # Using fixed "linear" pattern type
+        base_a = 2 * x + 3 * y
+        base_b = 3 * x - y
+
+        # Using fixed "symmetric" symmetry type
+        sym_a = (x + y) ** 2
+        sym_b = (x + y) * abs(x - y)
+
+        # Using fixed "smooth" feature type
+        feat_a = math.sin(3 * math.pi * x) * math.sin(3 * math.pi * y)
+        feat_b = math.cos(3 * math.pi * x) * math.cos(3 * math.pi * y)
+
+        # Fixed weights for valley pattern
+        w_a = [1, 2, 0.5]
+        w_b = [1, 1.5, 0.3]
+
+        # Calculate final responses with weights
+        self.response_a = w_a[0] * base_a + w_a[1] * sym_a + w_a[2] * feat_a
+        self.response_b = w_b[0] * base_b + w_b[1] * sym_b + w_b[2] * feat_b
+
+        # Add minimal randomness (to maintain pattern visibility)
+        random_factor = random.uniform(0.98, 1.02)
+        self.response_a *= random_factor
+        self.response_b *= random_factor
+
+        return super().__call__(**kwargs)
+
+
+def example_2_float_0_cat_in_2_out(
+    run_cfg: bch.BenchRunCfg = None, report: bch.BenchReport = None
+) -> bch.Bench:
+    """Benchmark demonstrating a surface pattern based solely on float parameters.
+
+    This example is simplified from the 1-category version by fixing all categorical
+    settings to create a valley pattern.
+
+    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 = Pattern0CatBenchmark().to_bench(run_cfg, report)
+    bench.plot_sweep(
+        title="Pattern Visualization (2 Float, 0 Categorical Variables)",
+        description="Response pattern with a valley shape based on x and y values",
+        post_description="""
+        This example demonstrates a surface pattern created using only two float inputs
+        (x_value and y_value) with no categorical variables. 
+        
+        The pattern showcases a 'valley' shape that exhibits different characteristics
+        across the range of x and y values. This simplified example uses fixed settings
+        equivalent to a linear pattern with symmetric properties and smooth features.
+        """,
+    )
+    return bench
+
+
+if __name__ == "__main__":
+    example_2_float_0_cat_in_2_out().report.show()

bencher/example/inputs_2_float/example_2_float_1_cat_in_2_out.py

@@ -0,0 +1,112 @@
+"""Demonstration of benchmarking with 2 float and 1 categorical input producing visually distinct patterns.
+
+The categorical input has 2 conditions that create distinctly different surface shapes.
+"""
+
+import random
+import math
+import bencher as bch
+
+random.seed(0)
+
+
+class Pattern1CatBenchmark(bch.ParametrizedSweep):
+    """Benchmark demonstrating patterns with distinctive shapes based on pattern type."""
+
+    # Float input parameters
+    x_value = bch.FloatSweep(default=100, bounds=[1, 100], doc="X value parameter")
+    y_value = bch.FloatSweep(default=10, bounds=[1, 100], doc="Y value parameter")
+
+    # Categorical input parameter - with 2 conditions
+    pattern_type = bch.StringSweep(["linear", "exponential"], doc="Pattern relationship")
+    # symmetry_type and feature_type removed
+
+    # Output metrics
+    response_a = bch.ResultVar(units="units", doc="Response variable A")
+    response_b = bch.ResultVar(units="units", doc="Response variable B")
+
+    def __call__(self, **kwargs) -> dict:
+        """Generate responses with distinctly different patterns based on pattern type."""
+        self.update_params_from_kwargs(**kwargs)
+
+        # Normalize inputs to [0,1]
+        x = self.x_value / 100
+        y = self.y_value / 100
+
+        # Set base patterns based on pattern_type
+        if self.pattern_type == "linear":
+            base_a = 2 * x + 3 * y
+            base_b = 3 * x - y
+        else:  # exponential
+            base_a = math.exp(2 * x) * math.exp(y) / math.exp(3)
+            base_b = math.exp(x) * math.exp(2 * y) / math.exp(3)
+
+        # Using fixed "symmetric" symmetry type
+        sym_a = (x + y) ** 2
+        sym_b = (x + y) * abs(x - y)
+
+        # Using fixed "smooth" feature type
+        feat_a = math.sin(3 * math.pi * x) * math.sin(3 * math.pi * y)
+        feat_b = math.cos(3 * math.pi * x) * math.cos(3 * math.pi * y)
+
+        # Simplified weights dictionary for 1 categorical variable
+        weights = {
+            "linear": ([1, 2, 0.5], [1, 1.5, 0.3]),  # Valley pattern
+            "exponential": ([1, 1, 0.3], [1, 0.8, 0.4]),  # Corner peak with ripples
+        }
+
+        # Get the weights for the current pattern type
+        w_a, w_b = weights[self.pattern_type]
+
+        # Calculate final responses with weights
+        if self.pattern_type == "linear":
+            self.response_a = w_a[0] * base_a + w_a[1] * sym_a + w_a[2] * feat_a
+            self.response_b = w_b[0] * base_b + w_b[1] * sym_b + w_b[2] * feat_b
+        else:  # exponential - multiplicative relationship
+            self.response_a = base_a * (1 + w_a[1] * sym_a) * (1 + w_a[2] * feat_a)
+            self.response_b = base_b * (1 + w_b[1] * sym_b) * (1 + w_b[2] * feat_b)
+
+        # Add minimal randomness (to maintain pattern visibility)
+        random_factor = random.uniform(0.98, 1.02)
+        self.response_a *= random_factor
+        self.response_b *= random_factor
+
+        return super().__call__(**kwargs)
+
+
+def example_2_float_1_cat_in_2_out(
+    run_cfg: bch.BenchRunCfg = None, report: bch.BenchReport = None
+) -> bch.Bench:
+    """Benchmark demonstrating visually distinct patterns based on pattern type.
+
+    This example is simplified from the 2-category version by fixing the symmetry_type
+    to "symmetric" and feature_type to "smooth".
+
+    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 = Pattern1CatBenchmark().to_bench(run_cfg, report)
+    bench.plot_sweep(
+        title="Pattern Visualization (2 Float, 1 Categorical Variable)",
+        description="Response patterns with distinctive shapes based on pattern type",
+        post_description="""
+        Pattern Type: Linear (diagonal gradients) vs Exponential (corner-concentrated)
+        
+        Each pattern type produces a unique surface shape that remains visually distinctive
+        even with auto-scaling of the color maps. This example uses fixed "symmetric" symmetry
+        and "smooth" feature settings.
+        """,
+    )
+    return bench
+
+
+if __name__ == "__main__":
+    example_2_float_1_cat_in_2_out().report.show()

bencher/example/inputs_2_float/example_2_float_2_cat_in_2_out.py

@@ -0,0 +1,122 @@
+"""Demonstration of benchmarking with 2 float and 2 categorical inputs producing visually distinct patterns.
+
+Each categorical input has 2 conditions that create distinctly different surface shapes.
+"""
+
+import random
+import math
+import bencher as bch
+
+random.seed(0)
+
+
+class Pattern2CatBenchmark(bch.ParametrizedSweep):
+    """Benchmark demonstrating patterns with distinctive shapes based on categorical settings."""
+
+    # Float input parameters
+    x_value = bch.FloatSweep(default=100, bounds=[1, 100], doc="X value parameter")
+    y_value = bch.FloatSweep(default=10, bounds=[1, 100], doc="Y value parameter")
+
+    # Categorical input parameters - each with 2 conditions
+    pattern_type = bch.StringSweep(["linear", "exponential"], doc="Pattern relationship")
+    symmetry_type = bch.StringSweep(["symmetric", "asymmetric"], doc="Pattern symmetry")
+    # feature_type removed
+
+    # Output metrics
+    response_a = bch.ResultVar(units="units", doc="Response variable A")
+    response_b = bch.ResultVar(units="units", doc="Response variable B")
+
+    def __call__(self, **kwargs) -> dict:
+        """Generate responses with distinctly different patterns based on categorical inputs."""
+        self.update_params_from_kwargs(**kwargs)
+
+        # Normalize inputs to [0,1]
+        x = self.x_value / 100
+        y = self.y_value / 100
+
+        # Set base patterns based on pattern_type
+        if self.pattern_type == "linear":
+            base_a = 2 * x + 3 * y
+            base_b = 3 * x - y
+        else:  # exponential
+            base_a = math.exp(2 * x) * math.exp(y) / math.exp(3)
+            base_b = math.exp(x) * math.exp(2 * y) / math.exp(3)
+
+        # Apply symmetry effect
+        if self.symmetry_type == "symmetric":
+            sym_a = (x + y) ** 2
+            sym_b = (x + y) * abs(x - y)
+        else:  # asymmetric
+            sym_a = x**2 * y
+            sym_b = x * y**2
+
+        # Using fixed "smooth" feature type
+        feat_a = math.sin(3 * math.pi * x) * math.sin(3 * math.pi * y)
+        feat_b = math.cos(3 * math.pi * x) * math.cos(3 * math.pi * y)
+
+        # Simplified weights dictionary for 2 categorical variables
+        weights = {
+            "linear": {
+                "symmetric": ([1, 2, 0.5], [1, 1.5, 0.3]),  # Valley pattern
+                "asymmetric": ([1, 1.8, 0.7], [1, 1.2, 0.9]),  # Tilted plane with waves
+            },
+            "exponential": {
+                "symmetric": ([1, 1, 0.3], [1, 0.8, 0.4]),  # Corner peak with ripples
+                "asymmetric": ([1, 1.5, 0.4], [1, 1.8, 0.2]),  # Curved gradient
+            },
+        }
+
+        # Get the weights for the current combination
+        w_a, w_b = weights[self.pattern_type][self.symmetry_type]
+
+        # Calculate final responses with weights
+        if self.pattern_type == "linear":
+            self.response_a = w_a[0] * base_a + w_a[1] * sym_a + w_a[2] * feat_a
+            self.response_b = w_b[0] * base_b + w_b[1] * sym_b + w_b[2] * feat_b
+        else:  # exponential - multiplicative relationship
+            self.response_a = base_a * (1 + w_a[1] * sym_a) * (1 + w_a[2] * feat_a)
+            self.response_b = base_b * (1 + w_b[1] * sym_b) * (1 + w_b[2] * feat_b)
+
+        # Add minimal randomness (to maintain pattern visibility)
+        random_factor = random.uniform(0.98, 1.02)
+        self.response_a *= random_factor
+        self.response_b *= random_factor
+
+        return super().__call__(**kwargs)
+
+
+def example_2_float_2_cat_in_2_out(
+    run_cfg: bch.BenchRunCfg = None, report: bch.BenchReport = None
+) -> bch.Bench:
+    """Benchmark demonstrating visually distinct patterns based on 2 categorical settings.
+
+    This example is simplified from the 3-category version by fixing the feature_type to "smooth".
+
+    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 = Pattern2CatBenchmark().to_bench(run_cfg, report)
+    bench.plot_sweep(
+        title="Pattern Visualization (2 Float, 2 Categorical Variables)",
+        description="Response patterns with distinctive shapes based on pattern and symmetry types",
+        post_description="""
+        Pattern Type: Linear (diagonal gradients) vs Exponential (corner-concentrated)
+        Symmetry Type: Symmetric (x/y similarity) vs Asymmetric (x/y difference)
+        
+        Each combination produces a unique pattern shape that remains visually distinctive
+        even with auto-scaling of the color maps. Feature type is fixed to "smooth" in this example.
+        """,
+    )
+    return bench
+
+
+if __name__ == "__main__":
+    example_2_float_2_cat_in_2_out().report.show()