holobench 1.25.1__py3-none-any.whl → 1.26.3__py3-none-any.whl

bencher/example/example_holosweep_objects.py

@@ -0,0 +1,111 @@
+# THIS IS NOT A WORKING EXAMPLE YET
+
+# pylint: disable=duplicate-code,unused-argument
+
+
+import bencher as bch
+import math
+import random
+import numpy as np
+import holoviews as hv
+
+from strenum import StrEnum
+from enum import auto
+
+
+class Function(StrEnum):
+    fn_cos = auto()
+    fn_sin = auto()
+    fn_log = auto()
+    fn_arctan = auto()
+
+    def call(self, arg) -> float:
+        """Calls the function defined by the name of the enum
+
+        Returns:
+            float: The result of calling the function defined by the enum
+        """
+        return getattr(np, self.removeprefix("fn_"))(arg)
+
+
+class FunctionInputs(bch.ParametrizedSweep):
+    phase = bch.FloatSweep(
+        default=0, bounds=[0, math.pi], doc="Input angle", units="rad", samples=5
+    )
+
+    freq = bch.FloatSweep(default=1, bounds=[0, math.pi], doc="Input angle", units="rad", samples=5)
+
+    theta = bch.FloatSweep(
+        default=0, bounds=[0, math.pi], doc="Input angle", units="rad", samples=10
+    )
+
+    compute_fn = bch.EnumSweep(Function)
+
+
+class FunctionOutputs(bch.ParametrizedSweep):
+    fn_output = bch.ResultVar(units="v", doc="sin of theta with some noise")
+
+    out_sum = bch.ResultVar(units="v", doc="The sum")
+
+    hmap = bch.ResultHmap()
+
+    hmap2 = bch.ResultHmap()
+
+
+def bench_fn(self, **kwargs) -> dict:
+    fin = FunctionInputs()
+    fin.update_params_from_kwargs(**kwargs)
+
+    output = FunctionOutputs()
+
+    output.fn_output = fin.compute_fn.call(fin.phase + fin.freq * fin.theta) + random.uniform(0, 0)
+    output.hmap = hv.Text(0, 0, f"{fin.phase}\n{fin.freq}\n {fin.theta}")
+    output.hmap2 = hv.Ellipse(0, 0, 1)
+    return output
+
+
+def plot_holo(self, plot=True) -> hv.core.ViewableElement:
+    """Plots a generic representation of the object that is not a basic hv datatype. In this case its an image of the values of the object, but it could be any representation of the object, e.g. a screenshot of the object state"""
+    if plot:
+        pt = hv.Text(0, 0, f"{self.phase}\n{self.freq}\n {self.theta}")
+        pt *= hv.Ellipse(0, 0, 1)
+        return pt
+    return None
+
+
+def example_holosweep(
+    run_cfg: bch.BenchRunCfg = bch.BenchRunCfg(), report: bch.BenchReport = bch.BenchReport()
+) -> bch.Bench:
+    # wv = PlotFunctions()
+
+    bench = bch.Bench(
+        "waves", bench_fn, worker_input_cfg=FunctionInputs, run_cfg=run_cfg, report=report
+    )
+
+    res = bench.plot_sweep(
+        "phase",
+        input_vars=[FunctionInputs.param.theta, FunctionInputs.param.freq],
+        result_vars=[
+            FunctionOutputs.param.fn_output,
+            FunctionOutputs.param.hmap,
+            FunctionOutputs.param.hmap2,
+        ],
+    )
+
+    # bench.report.append(res.summarise_sweep())
+    # bench.report.append(res.to_optuna())
+    # bench.report.append(res.get_best_holomap())
+    # bench.report.append(res.to_curve(), "Slider view")
+    # bench.report.append(res.to_holomap().layout())
+    # print(res.to_holomap())
+    bench.report.append(res.to_holomap())
+    # bench.report.append(res.to_holomap())
+
+    return bench
+
+
+if __name__ == "__main__":
+    bench_run = bch.BenchRunner("bench_runner_test", run_cfg=bch.BenchRunCfg())
+
+    bench_run.add_run(example_holosweep)
+    bench_run.run(level=4, show=True)

bencher/example/example_holosweep_tap.py

@@ -0,0 +1,144 @@
+# THIS IS NOT A WORKING EXAMPLE YET
+
+# pylint: disable=duplicate-code,unused-argument
+
+
+import bencher as bch
+import math
+import random
+import numpy as np
+import holoviews as hv
+
+from strenum import StrEnum
+from enum import auto
+
+
+class Function(StrEnum):
+    fn_cos = auto()
+    fn_sin = auto()
+    fn_log = auto()
+    fn_arctan = auto()
+
+    def call(self, arg) -> float:
+        """Calls the function defined by the name of the enum
+
+        Returns:
+            float: The result of calling the function defined by the enum
+        """
+        return getattr(np, self.removeprefix("fn_"))(arg)
+
+
+class PlotFunctions(bch.ParametrizedSweep):
+    phase = bch.FloatSweep(
+        default=0, bounds=[0, math.pi], doc="Input angle", units="rad", samples=5
+    )
+
+    freq = bch.FloatSweep(default=1, bounds=[0, math.pi], doc="Input angle", units="rad", samples=5)
+
+    theta = bch.FloatSweep(
+        default=0, bounds=[0, math.pi], doc="Input angle", units="rad", samples=10
+    )
+
+    compute_fn = bch.EnumSweep(Function)
+
+    fn_output = bch.ResultVar(units="v", doc="sin of theta with some noise")
+
+    out_sum = bch.ResultVar(units="v", doc="The sum")
+
+    hmap = bch.ResultHmap()
+
+    def __call__(self, plot=True, **kwargs) -> dict:
+        self.update_params_from_kwargs(**kwargs)
+        noise = 0.1
+
+        self.fn_output = self.compute_fn.call(self.phase + self.freq * self.theta) + random.uniform(
+            0, noise
+        )
+        self.hmap = self.plot_holo(plot)
+
+        return self.get_results_values_as_dict()
+
+    def plot_holo(self, plot=True) -> hv.core.ViewableElement:
+        """Plots a generic representation of the object that is not a basic hv datatype. In this case its an image of the values of the object, but it could be any representation of the object, e.g. a screenshot of the object state"""
+        if plot:
+            pt = hv.Text(0, 0, f"phase:{self.phase}\nfreq:{self.freq}\ntheta:{self.theta}")
+            pt *= hv.Ellipse(0, 0, 1)
+            return pt
+        return None
+
+    def calc_vec(self, **kwargs) -> dict:
+        theta = self.param.theta.values()
+        kwargs.pop("theta", 0)
+        dat = [self.__call__(plot=False, theta=i, **kwargs)["fn_output"] for i in theta]
+        # print(dat)
+        self.out_sum = sum(dat)
+        self.hmap = hv.Curve((theta, dat), "theta", "voltage")
+        # pt = hv.Text(0, 0, f"{self.compute_fn}\n{self.phase}\n{self.freq}")
+        # pt *= hv.Ellipse(0, 0, 1)
+        return self.get_results_values_as_dict()
+
+
+def example_holosweep_tap(
+    run_cfg: bch.BenchRunCfg = bch.BenchRunCfg(), report: bch.BenchReport = bch.BenchReport()
+) -> bch.Bench:
+    wv = PlotFunctions()
+
+    run_cfg.use_optuna = True
+    run_cfg.auto_plot = False
+    bench = bch.Bench("waves", wv, run_cfg=run_cfg, report=report)
+
+    res = bench.plot_sweep(
+        "phase",
+        input_vars=[PlotFunctions.param.theta, PlotFunctions.param.freq],
+        result_vars=[PlotFunctions.param.fn_output, PlotFunctions.param.hmap],
+        run_cfg=run_cfg,
+    )
+
+    bench.report.append(res.describe_sweep())
+    bench.report.append(res.to_heatmap_tap(PlotFunctions.param.fn_output))
+
+    return bench
+
+
+def example_holosweep_tap_slider(
+    run_cfg: bch.BenchRunCfg = bch.BenchRunCfg(), report: bch.BenchReport = bch.BenchReport()
+) -> bch.Bench:  # pragma: no cover
+    wv = PlotFunctions()
+
+    run_cfg.use_optuna = True
+    bench = bch.Bench("waves", wv, run_cfg=run_cfg, report=report)
+
+    res = bench.plot_sweep(
+        "phase",
+        input_vars=[PlotFunctions.param.theta, PlotFunctions.param.freq, PlotFunctions.param.phase],
+        result_vars=[PlotFunctions.param.fn_output],
+        run_cfg=run_cfg,
+    )
+
+    print(res.get_best_trial_params())
+    bench.report.append(res.get_best_holomap())
+
+    heatmap = res.to_heatmap().opts(tools=["hover", "tap"])
+    posxy = hv.streams.Tap(source=heatmap, x=0, y=0)
+    sld1 = wv.param.phase.as_slider()
+
+    def tap_plot(x, y):
+        print(x, y)
+        selres = bch.get_nearest_coords(res.ds, theta=x, freq=y, phase=sld1.value, repeat=1)
+        return res.hmaps[bch.hmap_canonical_input(selres)]
+
+    tap_dmap = hv.DynamicMap(tap_plot, streams=[posxy])
+
+    bench.report.append_tab(heatmap + tap_dmap, "Interactive Heatmap")
+    bench.report.append(sld1)
+
+    bench.report.append_tab(res.to_curve(), "Slider view")
+
+    return bench
+
+
+if __name__ == "__main__":
+    example_holosweep_tap(bch.BenchRunCfg()).report.show()
+
+
+# todo  https://discourse.holoviz.org/t/pointdraw-as-parameterized-class/3539

bencher/example/example_image.py

@@ -0,0 +1,155 @@
+import bencher as bch
+import numpy as np
+import math
+import matplotlib.pyplot as plt
+
+
+def polygon_points(radius: float, sides: int, start_angle: float):
+    points = []
+    for ang in np.linspace(0, 360, sides + 1):
+        angle = math.radians(start_angle + ang)
+        points.append(([math.sin(angle) * radius, math.cos(angle) * radius]))
+    return points
+
+
+class BenchPolygons(bch.ParametrizedSweep):
+    sides = bch.IntSweep(default=3, bounds=(3, 7))
+    radius = bch.FloatSweep(default=1, bounds=(0.2, 1))
+    linewidth = bch.FloatSweep(default=1, bounds=(1, 10))
+    linestyle = bch.StringSweep(["solid", "dashed", "dotted"])
+    color = bch.StringSweep(["red", "green", "blue"])
+    start_angle = bch.FloatSweep(default=0, bounds=[0, 360])
+    polygon = bch.ResultImage()
+    area = bch.ResultVar()
+    side_length = bch.ResultVar()
+
+    def __call__(self, **kwargs):
+        self.update_params_from_kwargs(**kwargs)
+        points = polygon_points(self.radius, self.sides, self.start_angle)
+        # self.hmap = hv.Curve(points)
+        self.polygon = self.points_to_polygon_png(points, bch.gen_image_path("polygon"))
+
+        self.side_length = 2 * self.radius * math.sin(math.pi / self.sides)
+        self.area = (self.sides * self.side_length**2) / (4 * math.tan(math.pi / self.sides))
+        return super().__call__()
+
+    def points_to_polygon_png(self, points: list[float], filename: str):
+        """Draw a closed polygon and save to png"""
+        fig = plt.figure(frameon=False)
+        ax = plt.Axes(fig, [0.0, 0.0, 1.0, 1.0], frameon=False)
+        ax.set_axis_off()
+        ax.plot(
+            [p[0] for p in points],
+            [p[1] for p in points],
+            linewidth=self.linewidth,
+            linestyle=self.linestyle,
+            color=self.color,
+        )
+        ax.set_xlim(-1, 1)
+        ax.set_ylim(-1, 1)
+
+        ax.set_aspect("equal")
+        fig.add_axes(ax)
+        fig.savefig(filename, dpi=30)
+
+        return filename
+
+
+def example_image(
+    run_cfg: bch.BenchRunCfg = bch.BenchRunCfg(), report: bch.BenchReport = bch.BenchReport()
+) -> bch.Bench:
+    run_cfg.use_cache = False
+    bench = bch.Bench("polygons", BenchPolygons(), run_cfg=run_cfg, report=report)
+
+    bench.result_vars = ["polygon", "area"]
+
+    bench.add_plot_callback(bch.BenchResult.to_sweep_summary)
+    # bench.add_plot_callback(bch.BenchResult.to_auto, level=2)
+    bench.add_plot_callback(bch.BenchResult.to_panes, level=3)
+    # bench.add_plot_callback(bch.BenchResult.to_panes)
+
+    sweep_vars = ["sides", "radius", "linewidth", "color"]
+
+    # sweep_vars = ["sides", "radius" ]
+
+    for i in range(1, len(sweep_vars)):
+        s = sweep_vars[:i]
+        bench.plot_sweep(
+            f"Polygons Sweeping {len(s)} Parameters",
+            input_vars=s,
+        )
+        bench.report.append(bench.get_result().to_panes())
+
+    return bench
+
+
+def example_image_vid(run_cfg: bch.BenchRunCfg = None, report: bch.BenchReport = None) -> bch.Bench:
+    bench = BenchPolygons().to_bench(run_cfg, report)
+    bench.add_plot_callback(bch.BenchResult.to_sweep_summary)
+    bench.add_plot_callback(
+        bch.BenchResult.to_video_grid,
+        target_duration=0.06,
+        compose_method_list=[
+            bch.ComposeType.right,
+            bch.ComposeType.right,
+            bch.ComposeType.sequence,
+        ],
+    )
+    # from functools import partial
+    # bench.add_plot_callback(bch.BenchResult.to_video_summary)
+    # bench.add_plot_callback(bch.BenchResult.to_video_grid, time_sequence_dimension=0)
+    # bench.add_plot_callback(bch.BenchResult.to_video_grid)
+    # bench.add_plot_callback(bch.BenchResult.to_video_grid, time_sequence_dimension=2)
+    # bench.add_plot_callback(bch.BenchResult.to_video_grid, time_sequence_dimension=3)
+
+    bench.plot_sweep(input_vars=["radius"])
+    # res = bench.plot_sweep(input_vars=["radius"], plot=False)
+    # bench.report.append(res.to_video_grid(target_duration=0.06))
+    bench.plot_sweep(input_vars=["radius", "sides"])
+    # bench.plot_sweep(input_vars=["radius", "sides", "linewidth"])
+    # bench.plot_sweep(input_vars=["radius", "sides", "linewidth", "color"])
+
+    return bench
+
+
+if __name__ == "__main__":
+
+    def simple():
+        bench = BenchPolygons().to_bench(bch.BenchRunCfg(level=4))
+
+        # bench.plot_sweep(input_vars=["sides","color","radius"])
+
+        # res = bench.sweep(input_vars=["sides", "radius"])
+
+        # bench.report.append(res.to_heatmap(target_dimension=3))
+
+        bench.plot_sweep(input_vars=["sides"])
+        bench.plot_sweep(input_vars=["sides", "color"])
+
+        bench.plot_sweep(input_vars=["sides", "radius"])
+
+        # bench.report.append(res.to_line(target_dimension=1))
+
+        return bench
+
+    def example_image_vid_sequential(
+        run_cfg: bch.BenchRunCfg = bch.BenchRunCfg(), report: bch.BenchReport = bch.BenchReport()
+    ) -> bch.Bench:
+        bench = BenchPolygons().to_bench(run_cfg, report)
+        bench.add_plot_callback(bch.BenchResult.to_title)
+        bench.add_plot_callback(bch.BenchResult.to_video_grid)
+        bench.sweep_sequential(input_vars=["radius", "sides", "linewidth", "color"], group_size=4)
+        return bench
+
+    # def example_image_pairs()
+
+    ex_run_cfg = bch.BenchRunCfg()
+    ex_run_cfg.use_sample_cache = True
+    # ex_run_cfg.debug = True
+    # ex_run_cfg.repeats = 2
+    ex_run_cfg.level = 4
+    example_image_vid(ex_run_cfg).report.show()
+    # simple().report.show()
+
+    # example_image_vid_sequential(ex_run_cfg).report.show()
+    # example_image(ex_run_cfg).report.show()

bencher/example/example_levels.py

@@ -0,0 +1,181 @@
+import bencher as bch
+from bencher.utils import int_to_col
+
+import math
+import holoviews as hv
+from typing import Any, List
+import panel as pn
+from holoviews import opts
+
+
+class LevelsExample(bch.ParametrizedSweep):
+    xval = bch.FloatSweep(bounds=[0, 3.14])
+    yval = bch.FloatSweep(bounds=[0, 3.14])
+    level = bch.IntSweep(default=1, bounds=[1, 6])
+
+    output = bch.ResultVar(units="v")
+    hmap = bch.ResultHmap()
+
+    def __call__(self, **kwargs: Any) -> Any:
+        self.update_params_from_kwargs(**kwargs)
+        self.output = math.sin(self.xval) + math.cos(self.yval)
+        self.hmap = hv.Points((self.xval, self.yval)).opts(
+            marker="o", size=110 - self.level * 20, color=int_to_col(self.level - 1)
+        )
+
+        return self.get_results_values_as_dict()
+
+
+class RunWithLevel(bch.ParametrizedSweep):
+    level = bch.IntSweep(default=1, bounds=[1, 8])
+    dimensions = bch.IntSweep(default=1, bounds=[1, 2])
+
+    level_samples = bch.ResultVar()
+
+    def __call__(self, **kwargs) -> dict():
+        self.update_params_from_kwargs(**kwargs)
+
+        self.level_samples = int(
+            pow(
+                len(bch.FloatSweep(bounds=[0, 1]).with_level(self.level).values()),
+                self.dimensions,
+            )
+        )
+        return self.get_results_values_as_dict()
+
+
+def run_with_dim(bench: bch.Bench, dims: List[bch.SweepBase]) -> List[bch.BenchResult]:
+    results = []
+    for level in range(1, 6):
+        print(level)
+        res = bench.plot_sweep(
+            f"Level:{level}",
+            input_vars=dims,
+            const_vars=LevelsExample.get_input_defaults(
+                [LevelsExample.param.level.with_const(level)]
+            ),
+            result_vars=[LevelsExample.param.output, LevelsExample.param.hmap],
+            run_cfg=bch.BenchRunCfg(level=level, auto_plot=False),
+        )
+
+        results.append(res)
+    return results
+
+
+def run_levels_1D(bench: bch.Bench) -> bch.Bench:
+    results = run_with_dim(bench, [LevelsExample.param.xval])
+    bench.report.append_title("Using Levels to define sample density")
+
+    bench1 = bch.Bench("levels", RunWithLevel(), run_cfg=bch.BenchRunCfg(auto_plot=False))
+    res1 = bench1.plot_sweep("Levels", input_vars=[RunWithLevel.param.level])
+
+    bench.report.append_markdown(
+        "Sample levels let you perform parameter sweeps without having to decide how many samples to take when defining the class.  If you perform a sweep at level 2, then all the points are reused when sampling at level 3.  The higher levels reuse the points from lower levels to avoid having to recompute potentially expensive samples. The other advantage is that it enables a workflow where you can quickly see the results of the sweep at a low resolution to sense check the code, and then run it at a high level to get the fidelity you want.  When calling a sweep at a high level, you can publish the intermediate lower level results as the computiation continues so that you can track the progress of the computation and end the sweep early when you have sufficient resolution",
+        width=600,
+    )
+    row = pn.Row()
+    row.append(res1.to_table())
+    # row.append(res1.to_curve().opts(shared_axes=False))
+    row.append(res1.to_curve())
+
+    bench.report.append(row)
+
+    bench.report.append_markdown(
+        "Level 1 returns a single point at the lower bound of the parameter. Level 2 uses the uppper and lower bounds of the parameter. All subsequent levels are created by adding a sample between each previously calculated sample to ensure that all previous values can be reused while retaining an equal sample spacing.  The following plots show the sample points as circles and the corresponding plot of a sin function sampled at that level.",
+        width=600,
+    )
+
+    combined_pts = hv.Overlay()
+    combined_curve = hv.Overlay()
+    for it, r in enumerate(results):
+        lvl = it + 1
+        row = pn.Row()
+        pts = r.to_holomap().overlay().opts(title=f"Sample Points for level: {lvl}", height=300)
+        ds = r.to_hv_dataset()
+        crv = r.to_curve_ds(ds.data).opts(shared_axes=False, height=300) * r.to_hv_dataset(
+            bch.ReduceType.NONE
+        ).to(hv.Scatter).opts(
+            title=f"Function Values for level: {lvl}", size=5, height=300, shared_axes=False
+        )
+
+        combined_pts *= pts
+        combined_curve *= crv
+        row.append(pts)
+        row.append(crv)
+        bench.report.append_markdown(f"## {r.bench_cfg.title}")
+        bench.report.append(row)
+
+    bench.report.append_markdown(
+        "This plot overlays the previous plots into a single image. It shows how each level overlaps the previous level"
+    )
+
+    bench.report.append(pn.Row(combined_pts, combined_curve))
+    return bench
+
+
+def run_levels_2D(bench: bch.Bench) -> bch.Bench:
+    results = run_with_dim(bench, [LevelsExample.param.xval, LevelsExample.param.yval])
+    bench.report.append_markdown("# Using Levels to define 2D sample density", "Levels 2D")
+
+    bench1 = bch.Bench("lol", RunWithLevel(), run_cfg=bch.BenchRunCfg(auto_plot=False))
+    res1 = bench1.plot_sweep(
+        "Levels",
+        input_vars=[RunWithLevel.param.level],
+        const_vars=[RunWithLevel.param.dimensions.with_const(2)],
+    )
+    row = pn.Row()
+    row.append(res1.to_table())
+    # row.append(res1.to_curve().opts(shared_axes=False))
+    row.append(res1.to_curve())
+
+    bench.report.append(row)
+
+    for it, r in enumerate(results):
+        lvl = it + 1
+        row = pn.Row()
+        bench.report.append_markdown(f"## {r.bench_cfg.title}")
+        row.append(
+            r.to_holomap()
+            .overlay()
+            .opts(title=f"Sample Points for level: {lvl}", shared_axes=False)
+        )
+        row.append(
+            r.to_heatmap_single(r.bench_cfg.result_vars[0], bch.ReduceType.NONE).opts(
+                title=f"Function Value Heatmap for level: {lvl}", shared_axes=False
+            )
+        )
+        bench.report.append(row)
+
+    bench.report.append_markdown(
+        "This plot overlays the previous plots into a single image. It shows how each level overlaps the previous level"
+    )
+    overlay = hv.Overlay()
+    for lvl, r in enumerate(results):
+        overlay *= (
+            r.to_holomap()
+            .overlay()
+            .opts(width=1000, height=1000, show_legend=False, shared_axes=False)
+        )
+
+    bench.report.append(overlay)
+    return bench
+
+
+def run_levels(
+    run_cfg: bch.BenchRunCfg = bch.BenchRunCfg(), report: bch.BenchReport = bch.BenchReport()
+) -> bch.Bench:
+    hv.extension("bokeh")
+    opts.defaults(
+        opts.Curve(show_legend=False),
+        opts.Points(show_legend=False),
+    )
+
+    bench = bch.Bench("Levels", LevelsExample(), run_cfg=run_cfg, report=report)
+    bench = run_levels_1D(bench)
+    bench = run_levels_2D(bench)
+
+    return bench
+
+
+if __name__ == "__main__":
+    run_levels().report.show()

bencher/example/example_levels2.py

@@ -0,0 +1,37 @@
+import bencher as bch
+
+
+class Square(bch.ParametrizedSweep):
+    """An example of a datatype with an integer and float parameter"""
+
+    x = bch.FloatSweep(default=0, bounds=[0, 6])
+
+    result = bch.ResultVar("ul", doc="Square of x")
+
+    def __call__(self, **kwargs) -> dict:
+        self.update_params_from_kwargs(**kwargs)
+        self.result = self.x * self.x
+        return self.get_results_values_as_dict()
+
+
+def example_levels2(run_cfg: bch.BenchRunCfg = None, report: bch.BenchReport = None) -> bch.Bench:
+    """This example shows how to define a custom set of value to sample from intead of a uniform sweep
+
+    Args:
+        run_cfg (BenchRunCfg): configuration of how to perform the param sweep
+
+    Returns:
+        Bench: results of the parameter sweep
+    """
+
+    bench = Square().to_bench(run_cfg=run_cfg, report=report)
+
+    # These are all equivalent
+    bench.plot_sweep(input_vars=[Square.param.x.with_level(run_cfg.level, 3)])
+    bench.plot_sweep(input_vars=[bch.p("x", max_level=3)])
+
+    return bench
+
+
+if __name__ == "__main__":
+    example_levels2(bch.BenchRunCfg(level=4)).report.show()

bencher/example/example_pareto.py

@@ -0,0 +1,53 @@
+# pylint: disable=duplicate-code
+
+import bencher as bch
+
+# All the examples will be using the data structures and benchmark function defined in this file
+from bencher.example.benchmark_data import ExampleBenchCfgIn, ExampleBenchCfgOut, bench_function
+
+
+def example_pareto(
+    run_cfg: bch.BenchRunCfg = bch.BenchRunCfg(), report: bch.BenchReport = bch.BenchReport()
+) -> bch.Bench:
+    """Example of how to calculate the pareto front of a parameter sweep
+
+    Args:
+        run_cfg (BenchRunCfg): configuration of how to perform the param sweep
+
+    Returns:
+        Bench: results of the parameter sweep
+    """
+    run_cfg.use_optuna = True
+
+    bench = bch.Bench(
+        "Multi-objective optimisation",
+        bench_function,
+        ExampleBenchCfgIn,
+        run_cfg=run_cfg,
+        report=report,
+    )
+
+    res = bench.plot_sweep(
+        title="Pareto Optimisation with Optuna",
+        description="This example shows how to plot the pareto front of the tradeoff between multiple criteria.  When multiple result variable are defined, and use_optuna=True a pareto plot and the relative importance of each input variable on the output criteria is plotted. A summary of the points on the pareto front is printed as well.  You can use the pareto plot to decide the how to trade off one objective for another.  Pareto plots are suppored for 2D and 3D.  If you have more than 3 result variables the first 3 are selected for the pareto plot.  Plotting 4D surfaces is left as an exercise to the reader",
+        input_vars=[
+            ExampleBenchCfgIn.param.theta,
+            ExampleBenchCfgIn.param.offset,
+        ],
+        result_vars=[ExampleBenchCfgOut.param.out_sin, ExampleBenchCfgOut.param.out_cos],
+        const_vars=ExampleBenchCfgIn.get_input_defaults(
+            [ExampleBenchCfgIn.param.noisy.with_const(True)]
+        ),
+        post_description="""# Post Description 
+This is a slightly unusual way of doing pareto optimisation as we are not using a typical multi-objective optimisation algorithm [TODO, add example].  Instead we are performing a grid search and looking at the resulting pareto plot.  The reason for doing a grid search instead of standard pareto optimisation is that we can produce more isolated plots of how an input affects an output which can help understanding of the parameter space.  Future examples will show how to use grid search to bootstrap further optimisation with a multi objective optimiser""",
+    )
+
+    bench.report.append(res.to_optuna_plots())
+    return bench
+
+
+if __name__ == "__main__":
+    run_cfg_ex = bch.BenchRunCfg()
+    run_cfg_ex.repeats = 2
+    run_cfg_ex.level = 2
+    example_pareto(run_cfg_ex).report.show()