Package: piglot
A package for the optimisation of numerical responses.IntroductionWelcome topiglot, a Python tool taylored for the automated optimisation of responses from numerical solvers.
We aim to provide a simple and user-friendly interface that is also easily extendable, allowing integration with other solvers within the community.
Whether you're working on structural analysis, material modelling, fluid dynamics, control systems or astrophysics (to name a few) using, for instance, finite element analysis, spectral methods or Monte Carlo methods,piglotprovides a versatile solution for solving inverse problems.
The primary emphasis is on derivative-free optimisation, ensuring compatibility with black-box solvers in scenarios where gradient information is not available, and cases where the function evaluations may be noisy. We highlight:Integration with solvers:We provide an extensible interface for coupling with physics solvers. As long as your solver can return a time-response for the fields you are interested, you can optimise it withpiglot.Optimisation algorithms:Off the shelf, there are several optimisers included in the package. Among them, we highlight our fully-fledged Bayesian optimisation (based onBoTorch) that supports optimising stochastic and composite objectives and is highly customisable. Additional methods can also be easily implemented withinpiglot.Visualisation tools:You can use the built-in toolpiglot-plotto visualise the results of the optimisation. There are native plotting utilities for the optimised responses, the parameter history, objective history and, for supported solvers, live plotting of the currently running case. Also, an animation of the optimisation process can be exported.Feel free to explore,contribute, and optimise withpiglot!
We recommend starting by reading theGetting startedsection, and then checking the latestdocumentationfor additional details.
You can use ourdiscussionspage for help and ourissue trackerfor reporting problems and suggestions.
If you use this tool in your work, we encourage to open a PR to add it to ourlist of papers.Getting startedWe provide some examples to get you started withpiglot.
There are two modes of operation available: running using the givenpiglotandpiglot-plottools and configuration files, or building the optimisation problem in a Python script.Using configuration filesWe use YAML configuration files to specify the optimisation problem to solve.
This is the simplest form of usingpiglotand is the recommended approach unless you have a strong motive to use Python scripts (describedhere).
A simple analytical curve fitting problem is included to showcase how to use configuration files.To keep things simple, in this case, we fit a quadratic expression of the type $f(x) = a x^2$.
Note that this curve is generally obtained from a physics-based solver when solving an inverse problem.
As a reference, a numerically generated reference from the expression $f(x) = 2 x^2$ is used (provided in theexamples/sample_curve_fitting/reference_curve.txtfile).
We want to find the value for $a$ that better fits our reference (it should be 2).
The configuration file for this example is:iters:10optimiser:botorchparameters:a:[1,0,4]objective:name:fittingsolver:name:curvecases:'case_1':expression:<a> * x ** 2parametric:xbounds:[-5,5]points:100references:'reference_curve.txt':prediction:['case_1']You can find this file inexamples/sample_curve_fitting/config.yamlWe run 10 iterations using thebotorchoptimiser (our interface for Bayesian optimisation), and set the parameterafor optimisation with bounds[0,4]and initial value 1.
Our optimisation objective is the fitting of an analytical curve, with the expression<a> * x ** 2.
The notation<a>indicates that this parameter should be optimised.
We also define a parameterisation using the variable $x$, where we sample the function between[-5,5]with 100 points.
Finally, we compare this generated response (with the labelcase_1) with our reference, given from the filereference_curve.txtTo run this example, open a terminal inside thepiglotrepository, enter theexamples/sample_curve_fittingdirectory and run piglot with the given configuration filecdexamples/sample_curve_fitting
piglotconfig.yamlYou should see an output similar toBoTorch: 100%|██████████████████████████████████████████████████████| 10/10 [00:00<00:00, 17.66it/s, Loss: 8.8505e-08]
Completed 10 iterations in 0.56614s
Best loss:  8.85050592e-08
Best parameters
- a:     1.999508As you can see, piglot correctly identifies theaparameter close to the expected value of 2, and the error of the fitting is in the order of $10^{-8}$.
In addition to these outputs,piglotcreates an output directory, with the same name as the configuration file (minus the extension), where it stores the optimisation data.To visualise the optimisation results, use thepiglot-plotutility.
In the same directory, runpiglot-plotbestconfig.yamlWhich will display the best observed value for the optimisation problem.
You should see the following output in the terminalBest run:
Start Time /s    0.587397
Run Time /s      0.004439
a                1.999508
Name: 18, dtype: object
Hash: 2313718f75bc0445aa71df7d6d4e50ba82ad593d65f3762efdcbed01af338e30
Objective:  8.85050592e-08The script will also plot the best observed response, and its comparison with the reference response:Now, try running (this may take some time)piglot-plotanimationconfig.yamlThis generates an animation for all the function evaluations that have been made throughout the optimisation procedure.
You can find the.giffile(s) inside the output directory, which should give something like:Using Python scriptsAnother way of usingpiglotis via its package and Python modules.
This approach may offer increased flexibility in the setup of the optimisation problem, at the cost of increased complexity and verbosity.
A sample script equivalent to the configuration file for the problem described inthe previous sectionis provided inexamples/sample_curve_fitting/config.py, given by:importosimportshutilfrompiglot.parameterimportParameterSetfrompiglot.solver.solverimportCasefrompiglot.solver.curve.solverimportCurveSolverfrompiglot.solver.curve.fieldsimportCurveInputData,Curvefrompiglot.objectives.fittingimportReference,MSEfrompiglot.objectives.fittingimportFittingObjective,FittingSolverfrompiglot.optimisers.botorch.bayesimportBayesianBoTorch# Set up output and temporary directoriesoutput_dir='config'tmp_dir=os.path.join(output_dir,'tmp')ifos.path.isdir(output_dir):shutil.rmtree(output_dir)os.makedirs(output_dir,exist_ok=True)# Set up optimisation parametersparameters=ParameterSet()parameters.add('a',1.0,0.0,4.0)# Set up the referencereference=Reference('reference_curve.txt',['case_1'],output_dir)# Set up the solver to useinput_data=CurveInputData('case_1','<a> * x ** 2','x',(-5.0,5.0),100)case_1=Case(input_data,{'case_1':Curve()})solver=CurveSolver([case_1],parameters,output_dir,tmp_dir=tmp_dir)# Set up the fitting objectivereferences={reference:['case_1']}fitting_solver=FittingSolver(solver,references)objective=FittingObjective(parameters,fitting_solver,output_dir,MSE())# Set up the optimiser and run optimisationoptimiser=BayesianBoTorch(objective)value,params=optimiser.optimise(10,parameters,output_dir)print(f"Optimal value:{value}")print(f"Optimal parameters:{params}")Run withpythonconfig.pyExample outputBoTorch: 100%|██████████████████████████████████████████████████████| 10/10 [00:00<00:00, 16.75it/s, Loss: 8.9167e-08]
Completed 10 iterations in 0.59692s
Best loss:  8.91673999e-08
Best parameters
- a:     1.999506
Optimal value: 8.916739991036405e-08
Optimal parameters: [1.99950592]InstallationYou can installpiglotby only installing the main scripts or as a standard Python package.
If you only intend to use thepiglotandpiglot-plotbinaries, we strongly recommend the first option, as it avoids having to manage the dependencies in your Python environment.
However, if you wish to use the tools in thepiglotpackage, you may have to resort to the second option.
Currently, we require Python 3.9 onwards.Option 1: Install binariesThis option is recommended for end-users that only need to interact with the providedpiglotandpiglot-plotscripts.
We usepipxto install the package in an isolated environment with the required dependencies (we recommend reading the pipx documentation to check the advantages of using this approach).Installpipxin your system using the instructionshere;In your favourite terminal, run:pipx install piglot;Confirm the package is correctly installed by calling thepiglotandpiglot-plotexecutables.Option 2: Install packageWe recommend this option for users aiming to use thepiglotpackage directly.
Note that this option also provides thepiglotandpiglot-plotscripts, but requires manual handling of the installation environment.In your favourite terminal, run:pip install piglot;Confirm the package is correctly installed by calling thepiglotandpiglot-plotexecutables.Installing additional optimisersWe also support some optional external optimisers, which are not automatically installed along withpiglotto reduce the number of dependencies and the installation cost.
You can either install them along withpiglot, or manually using your package manager.
Their detection is done at runtime and, if not installed, an error will be raised.
Currently, the following optional optimisers are supported:lipo- LIPO optimisergeneticalgorithm- Genetic algorithmpyswarms- Particle swarm optimiserThese can be installed directly from PyPI (with the package names above).
If you wish to installpiglotwith one of these optimisers (which may be required when using apipxinstall), you can run the following commands:pip install piglot[lipo]for the LIPO optimiserpip install piglot[genetic]for the Genetic algorithmpip install piglot[pso]for the Particle swarm optimiser optimiserTo simultaneously install more than one optimiser, for instance, the LIPO and the Particle swarm optimisers, runpip install piglot[lipo,pso].
If you wish to install all optimisers at once, you can runpip install piglot[full].