docs: update Docs

Author: FoamScience

README.md

@@ -11,10 +11,11 @@ of OpenFOAM cases.
 - Parameter values are fetched through a YAML/JSON configuration file. Absolutely no code should be needed, add parameters
   to the YAML file and they should be picked up automatically
 - The no-code thing is taken to the extreme, through a YAML config file, you can (need-to):
-  - Specify the template case
-  - Specify how the case is ran
-  - Specify how/where parameters are substituted
-  - Specify how your metrics are computed
+  - Specify the template case. This must be a "complete" (no placeholder), and runnable (as-is) OpenFOAM case.
+  - Specify how the case is ran. Locally, or on SLURM, and specifying the commands to run.
+  - Specify how/where parameters are substituted. `PyFoam` is used for this purpose for now.
+  - Specify how your metrics are computed. These are just shell commands that output a single scalar
+    value to `STDOUT`.
 
 ## How do I try this out?
 
@@ -27,14 +28,17 @@ OpenFOAM-like dictionary (See [single-objective opt. example](examples/local/sin
 for inspiration.
 
 ```bash
-# Clone the repository
+# Install the package
+pip install foambo
+# Clone the repo to get the examples
 git clone https://github.com/FoamScience/OpenFOAM-Multi-Objective-Optimization foamBO
-cd foamBO
-# Install dependencies
-pip3 install -r requirements.txt
+cd foamBO/examples
 ```
 ### Apptainer containers
 
+If you'd like to try this out in Apptainer containers instead, It's recommended to
+(Must have `ansible` installed for this to work):
+
 ```bash
 git clone https://github.com/FoamScience/openfoam-apptainer-packaging /tmp/of_tainers
 git clone https://github.com/FoamScience/OpenFOAM-Multi-Objective-Optimization foamBO
@@ -43,6 +47,12 @@ ansible-playbook /tmp/of_tainers/build.yaml --extra-vars="original_dir=$PWD" --e
 # Get an apptainer container at containers/projects/foambo-<version>.sif
 ```
 
+Each example has some description in its README:
+- [Single-Objective BO of a single-parameter function, ran locally](examples/local/single-objective/README.md)
+- [Multi-Objective BO of a `pitzDaily` case, ran locally and on a SLURM Cluster](examples/local/multi-objective/README.md)
+- [Multi-Objective BO of a `pitzDaily` case, ran on a SLURM cluster](examples/slurm/README.md)
+  and providing "dependent parameters setup" variants.
+
 ## Contribution is welcome!
 
 By either filing issues or opening pull requests, you can contribute to the development

examples/local/multi-objective/README.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-- You need the Python dependencies: `pip install -r requirements.txt`
+- You need the `foamBO` package: `pip install foamBO`
 - You need an OpenFOAM version. Set `FOAMBO_OPENFOAM` to its installation folder.
   `${FOAMBO_OPENFOAM}/etc/bashrc` will be sourced in cases' `Allrun`.
 
@@ -28,26 +28,27 @@ I describe the workflow in two cases:
 > If you're going with option 1, you can skip setting up the cluster. If you intend to adopt option 2, I
 > recommend you still go through option 1
 >
-> This toolkit relies on [ax-platform](https://ax.dev) to do the optimization, so we support what they support.
+> This toolkit relies on [ax-platform](https://ax.dev) to do the optimization, so we support what they support + a few custom things.
 >
 > Here are few nice words about [Bayesian Optimization](https://ax.dev/docs/bayesopt.html). If you want to extend
 > these tools, you might want to take a look at the [Service and Developer APIs](https://ax.dev/docs/api.html)
 
-> Also, Python scripts are [Hydra Applications](https://hydra.cc/docs/intro/), so you can load different configurations
+> Also, `foamBO`, `foamDash` and `validateBO` scripts are [Hydra Applications](https://hydra.cc/docs/intro/),
+> so you can load different configurations
 > and/or override config values from the command line.
 
 ## Features we're exploring
 
 - Zero-code configuration for running parameter variations.
     - As long as you're able to do stuff through Bash.
 - Unattended algorithm selection for the trial generation strategy and Bayesian optimization.
-- Easy to expand; especially for metric evaluation; it's just a --new Python function--.
+- Ease of use; especially for metric evaluation; it's just a --new Python function--.
 
 ## The example problem
 
 To illustrate the somewhat complex workflow of running optimization studies with this toolkit, I picked
 the `pitzDaily` case from the standard tutorials (the one that works with `simpleFOAM`/`RAS`). The case
-can be ran both in serial and in parallel with 2 processors.
+can run both in serial and in parallel with 2 processors.
 
 ![](pitzDaily/pitzDaily.png)
 
@@ -59,7 +60,7 @@ Our objectives are:
 - Execution Time, extracted straight from the solver log files
 - Continuity Errors, also extracted from log files
 
-> Note that we are not particularly interested in the results of the study;
+> Note that we are **not** particularly interested in the results of the study;
 > All we care about is demonstrating how to optimize this problem with Bayesian algorithms.
 
 
@@ -106,17 +107,14 @@ All subsequent operations are supposed to run on the head node.
 > If you don't want to use the cluster, please adapt the paths to your local machine.
 > Don't forget to clone https://github.com/FoamScience/OpenFOAM-Multi-Objective-Optimization
 
-I've only tested the scripts with Python 3.8, so I recommend you use that version too. Just to avoid any
-surprises.
-
 The best option is to get [Miniconda](https://docs.conda.io/en/latest/miniconda.html) and:
 ```bash
 # Remember /axc on the head node, would be slurm-cluster/var/axc on your machine
 cd /axc/multiOptOF
-conda create -n of-opt python=3.8 pip
+conda create -n of-opt python=3.12 pip
 conda activate of-opt
 # This will install a load of packages
-pip install -r requirements.txt
+pip install foambo
 ```
 
 ## Local runs
@@ -131,10 +129,11 @@ for reference.
 
 ### Design parameters
 
-The configuration file has at least three important sections:
+The configuration file has at least four important sections:
 - `problem`: where you describe your problem inputs
 - `meta`: where you describe control settings for the optimization procedure
-- `visualize`: which an optional section for when you run `foamDash.py`
+- `validate`: where you optionally configure how the cross-validation of fitted models should be performed by `validateBO`
+- `visualize`: where you optionally configure how trials are visualized when you run `foamDash`
 
 The first thing is `problem.template_case` which points to the case you want to use as a base template.
 This case is then cloned each time with the help of PyFOAM. `meta.case_subdirs_to_clone` specifies

examples/local/single-objective/README.md

@@ -8,7 +8,7 @@ paper, with parameters `k=1, m=0, lambda=0.01`.
 
 ## Prerequisites
 
-- You only need the Python dependencies: `pip install -r requirements.txt`
+- You only need the `foamBO` package: `pip install foamBO`
 - No OpenFOAM installation is needed.
 
 ## Basic Ax usage
@@ -68,8 +68,9 @@ a single dictionary).
 
 ### Configuration and "OpenFOAM" case
 
-The configuration file usually contains three sections `problem`, `meta` and `visualize`.
-In this example, we can ignore `visualize` as it's necessary only if you run `foamDash.py`. 
+The configuration file usually contains four sections `problem`, `meta`, `validate` and `visualize`.
+In this example, we can ignore `visualize` as it configures how `foamDash` utility visualizes
+the optimization trials and metric evolution.
 
 The first section, `problem`, defines the optimization problem you're treating.
 It points to the base OpenFOAM case (`problem.template_case`) and distinguishes between
@@ -171,19 +172,44 @@ the content:
 x 0;
 ```
 
+After the optimization has gone through all of its trials, you can run the `validateBO` command
+to run some validation routines on the surrogate model. The `validate` section configures
+how to perform the validation:
+
+> It's important not to change the `config.yaml` between running `foamBO` and `validateBO`
+
+```yaml
+validate:
+  cross_validate: True # Run Ax's cross validation (doesn't run new trials)
+  # if no "trials" and no "pareto_frontier" is present, on the cross-validate from Ax
+  # will run
+  trials: # The utility w
+    - x: 0.2
+    - x: 1.0
+    - x: -100
+  # IF it's a multi-objective optimization, you can generate 10 pareto frontier points
+  # and run them to check how the close the prediction is to the actual metric values
+  #pareto_frontier: 10
+  #primary_objective: "metric_1"
+  #secondary_objective: "metric_2"
+```
+
+The `validateBO` will run the trials using the same configuration used to run the experiment's trials,
+and will result in a CSV file `Validate_<cfg.problem.name>_validate_report.csv` which has the required
+data to perform validation analysis.
+
 ### Generating predictions from models trained with foamBO
 
 `foamBO` will periodically save your experiment to a JSON file, and once the optimization is
 stopped, it will write its current state to another JSON. You can load those again into an Ax client:
 ```python
-# You need to load stuff from core.py to be able to de-serialize them
+# You need to load stuff from core.py to be able to de-serialize the custom runners, metrics, ... etc
 from foambo.core import *
 from ax.service.ax_client import AxClient
 from ax.storage.json_store.load import load_experiment
 cl = AxClient().load_from_json_file('SingleObjF1_client_state.json')
 exp = load_experiment(f"SingleObjF1_experiment.json")
 cl._experiment = exp
-exp = load_experiment(f"SingleObjF1_experiment.json")
 cl.get_model_predictions_for_parameterizations([{'x': 100}, {'x': -50}])
 ```
-This then results in very similar results to what `tutorial.py` reports.
+This then should result in very similar results to what `tutorial.py` reports.

examples/slurm/README.md

@@ -5,22 +5,30 @@ challenge. Head to the
 [OFMLHackathon folder](https://github.com/FoamScience/OFMLHackathon/tree/main/2023-07/bayesian-optimization)
 for a more detailed overview.
 
+> The study was performed on a SLURM cluster powered by AWS.
+
 ## Prerequisites
 
-- You need the Python dependencies: `pip install -r requirements.txt`
+- You need the `foamBO`: `pip install foamBO`
 - You need an OpenFOAM version. Set `FOAMBO_OPENFOAM` to its installation folder.
   `${FOAMBO_OPENFOAM}/etc/bashrc` will be sourced in cases' `Allrun`.
 - A SLURM cluster (See [multi-objective opt. tutorial](../local/multi-objective/README)
   for an example cluster)
 - Mesh parametrization is done through a `OpenSCAD -> cfMesh -> ParaView` workflow.
 
+> While `OpenSCAD` is fine for most purposes, I found out later that `madcad` is
+> a better fit for this type of needs because it can export 2D surfaces.
+
 ## PitzDaily with varying lowerWall geometry
 
 The [config.yaml](shape-optimization/config.yaml) file shows how to setup the
 [pitzDaily](shape-optimization/pitzDaily) for shape optimization using SAASBO. This simply
 parameterizes the lower wall of the geometry as a cubic Bezier curve with 8 control
 points, whose coordinates are used as optimization parameters.
 
+> Using SAASBO specifically was done merely for demonstration purposes. In production
+> runs, SAASBO shouldn't be used unless the problem features a huge search space.
+
 ## Dependent parameters
 
 The [config-dependent.yaml](./shape-optimization/config-dependent.yaml) and the corresponding