Parameter Sweeps¶

If you’ve used Comsol before you’ll be familiar with the notion of a parameter sweep: specify one model and then run it several times for many combinations of parameters.

We start the parameter sweep by defining a ParameterSet

Parameter Sets¶

Parameter sets define a set of parameters which are swept together. For example if you wanted to move the fish it’s x and y cooridinates would have to sweep together. When parameters are swept together we refer this is a serial sweep.

In this example we’ll create a ParameterSet named example_set which which will have 2 parameters (parameter_1 and parameter_2), parameter names don’t need to follow any pattern and could have been named alice and bob.

The rebuild_mesh flag specifies whether or not these parameters require the mesh to be recomputed. If these parameters affect something structural (e.g. coordinates of an object) then the mesh must be rebuilt for the model to update. However if something “physics-esque” is being changed (e.g. conductivity) then the mesh does not need to be rebuilt. Since meshing is an expensive operation minimizing re-meshing is in your best interest.

Note

There are almost no restrictions on parameters. We can see here that p2 is heterogenous and incoherent. As long as your downstream code can handle the parameter value then fish2eod will accept it. The only requirement is that all parameters in a ParameterSet have the same number of steps (same length)

"""Example creating a ParameterSet"""
from fish2eod import ParameterSet

p1 = [0, 1, 2, 3]  # some sequence of parameters for first paramer
p2 = [100, 200, "q", -3.14]  # some sequence of parameters for second parameter

"""
Define a ParameterSet named example_set with two parameters named

parameter_1 and parameter_2

Additionally instruct fish2eod to rebuild the mesh for each new parameter
"""
ParameterSet("example_set", parameter_1=p1, parameter_2=p2, rebuild_mesh=True)

(Source code)

This example creates 4 steps of parameters

(0, 100)
(1, 200)
(2, “q”)
(3, -3.14)

Parameter Sweeps¶

A ParameterSweep takes one or more ParameterSets and arranges them optimally. When specifying multiple sets they are swept combinatorially (i.e. the cartesian product of the sets, or every combination of the 2 or more). The ParameterSweep additionally sorts the parameters to minimize remeshing.

"""Example creating a ParameterSweep"""
from fish2eod import ParameterSet, ParameterSweep

p1 = [0, 1, 2, 3]  # some sequence of parameters for first paramer
p2 = [100, 200, "q", -3.14]  # some sequence of parameters for second parameter
p3 = ["a", "b"]

"""
Define a ParameterSet named example_set with two parameters named

parameter_1 and parameter_2

Additionally instruct fish2eod to not rebuild the mesh for each new parameter
"""
set_1 = ParameterSet("example_set", parameter_1=p1, parameter_2=p2, rebuild_mesh=False)

"""
Define a ParameterSet named example_set_2 with one parameters named parameter_3

Additionally instruct fish2eod to rebuild the mesh for each new parameter
"""
set_2 = ParameterSet("example_set_2", parameter_3=p3, rebuild_mesh=True)

"""
Crate the parameter sweep
"""
ps = ParameterSweep(set_1, set_2)

(Source code)

This example creates 8 steps of parameters

(0, 100, “a”)
(1, 200, “a”)
(2, “q”, “a”)
(3, -3.14, “a”)
(0, 100, “b”)
(1, 200, “b”)
(2, “q”, “b”)
(3, -3.14, “b”)

You’ll notice that set_1 is iterated before set_2 meaning that only 2 remeshes need to occur instead of 8

Running Parameter Sweeps¶

Creating a ParameterSweep is the precursor to running the sweep.

Sweeps are run using an IterativeSolver. In this example we will move an object around beside the fish

from tempfile import TemporaryDirectory

from fish2eod import (
    BaseFishModel,
    Circle,
    IterativeSolver,
    ParameterSet,
    ParameterSweep,
)


class PreyClass(BaseFishModel):
    """Class to show parameter sweeps of a prey"""

    def add_geometry(self, prey_x, prey_y, **kwargs):
        prey = Circle([prey_x, prey_y], 0.5)
        self.model_geometry.add_domain("prey_domain", prey, sigma=1)


"""
Define ParameterSets for the prey_x and prey_y
"""
prey_x = ParameterSet("px", prey_x=[5, 10], rebuild_mesh=True)
prey_y = ParameterSet("py", prey_y=[3, 6], rebuild_mesh=True)
ps = ParameterSweep(prey_x, prey_y)
model_name = "prey_example"
save_path = TemporaryDirectory().name  # give a real path when doing this

solver = IterativeSolver(model_name, save_path, PreyClass, ps, fish_x=[0, 20], fish_y=[0, 20])
# solver.run()

(Source code)

Importantly with an IterativeSolver some parameters may need to be specified but not part of the sweep (fish coordinates in this example). Any fixed parameters may be specified in the IterativeSolver by adding them as parameters as you would for a Model constructor

Special Parameter Sets¶

To make life easy for basic parameter sets we provied classes for specifing sweeps over eod phase (EODPhase) and fish coordinates (FishPosition). Please read their documentations for use case.