Merge pull request #21 from aurora-multiphysics/20-refactor-sledo-to-…

…be-agnostic-to-model-instantiation-tool

undefined

.github/workflows/build-ci.yml

@@ -5,56 +5,42 @@ on:
   # Run the workflow on push to "main" branch
   push:
     branches: [ "main" ]
-  # Run the workflow on pull request to "main" branch
+  # Run the workflow on pull request to "main" branch and ready for review
   pull_request:
     branches: [ "main"]
+    types: [ready_for_review]
   # Run the workflow manually
   workflow_dispatch:
 
 # This section controls which jobs the workflow will run
 jobs:
-  run-linter:
+  lint-and-test:
     runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v3
-
-      - name: Create venv and install requirements
-        run: |
-          python3 -m venv venv
-          . venv/bin/activate
-          pip3 install build --upgrade
-          python3 -m build
-          pip3 install ./dist/*.whl
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install sledo
+        run: pip install .[ci]
 
-      - name: Run linter
+      - name: Clone and install mooseherder
         run: |
-          . venv/bin/activate
-          pip3 install flake8
-          flake8 . --exclude=venv* --count --max-complexity=10 --max-line-length=79 --statistics
-
-  build-and-test:
-    runs-on: ubuntu-latest
-
-    env:
-      PRCOMMITSHA : ${{ github.event.pull_request.head.sha }}
+          cd ..
+          git clone https://github.com/ScepticalRabbit/mooseherder
+          cd sledo
+          pip install ../mooseherder
 
-    steps:
-      - uses: actions/checkout@v3
-
-      - name: Print github context
-        run: echo $PRCOMMITSHA
+      - name: Clone and install catbird
+        run: |
+          cd ..
+          git clone https://github.com/helen-brooks/catbird
+          cd sledo
+          pip install ../catbird
 
-      - name: Docker build (pull request)
-        if:  ${{ github.event.pull_request.head.sha != '' }}
-        run: docker build -t ci-sledo-ubuntu --build-arg build_git_sha=$PRCOMMITSHA docker/sledo-ubuntu/
-
-      - name:  Docker build (push)
-        if:  ${{ github.event.pull_request.head.sha == '' }}
-        run: docker build -t ci-sledo-ubuntu --build-arg build_git_sha=$GITHUB_SHA docker/sledo-ubuntu/
+      - name: Run linter
+        run: flake8 . --exclude=venv* --count --max-complexity=10 --max-line-length=79 --statistics
 
       - name: Run tests
-        run: |
-          pip3 install pytest
-          pytest tests
-  
+        run: pytest tests

.gitignore

@@ -166,4 +166,4 @@ cython_debug/
 results
 
 # Ignore config file
-config.yaml
+moose_config.json

README.md

@@ -2,59 +2,59 @@
 
 SLEDO (Sequential Learning Engineering Design Optimiser) is a tool for optimising parametric component designs, developed for fusion engineering.
 
-Sledo uses Bayesian Optimisation to intelligently select candidate designs from a parametric search space and MOOSE to evaluate the design performance via scalable multiphysics simulation.
+`sledo` uses Bayesian Optimisation to intelligently select candidate designs from a parametric search space and MOOSE to evaluate the design performance via scalable multiphysics simulation.
 
 # Installation
 
 ## Linux
 
-We recommend creating a virtual environment before running `sledo`.
+We recommend using a python virtual environment to install `sledo`.
+Run the following to create and activate a virtual environment in your current working directory.
 Skip this step if you intend to install `sledo` into an existing python environment.
 ```
 python3 -m venv venv
 source venv/bin/activate
 ```
 
 ### Standard install
-To install `sledo`, run the following:
+From the `sledo` root directory (the directory containing this README), ensure your virtual environment is activated and then run:
 ```
-# Ensure `build` package is installed.
-pip3 install build --upgrade
-
-# Build the distribution package.
-python3 -m build
-
-# Install the built distribution.
-pip3 install ./dist/*.whl
+pip install .
 ```
 
-If you intend to use the jupyter notebook tutorials, also run the following line:
+If you intend to use the jupyter notebook tutorials and are using a virtual environment, also run the following line (replacing `venv`` with the name of your virtual environment if it is different):
 ```
 # Enable virtual environment in the tutorial notebooks.
 python3 -m ipykernel install --user --name=venv
 ```
 
-Sledo can now be imported into python as:
+`sledo` can now be imported into python as:
 ```
 import sledo
 ```
 
 To test the installation, run `python3 -c "import sledo"`. If the installation was unsuccessful, an error will be raised.
 
-In order to run simulations, make sure to add the path to your MOOSE app of choice to `config.yaml`.
-
 ### Editable install (developer mode)
-Developers may wish to create an editable installation. This allows changes to the source code to immediately take effect without the need to re-package and re-install sledo. This can be useful when running tests and other scripts.
+Developers may wish to create an editable installation. This allows changes to the source code to immediately take effect without the need to re-install `sledo`. This can be useful when running tests and other scripts.
 
-To install `sledo` this way, run the following:
+To install `sledo` this way, use the `--editable` flag when running the `pip install` line as follows:
 ```
 # Install as an editable installation.
 pip3 install --editable .
 ```
 
 # Getting started
 
-To start using sledo, please refer to the `tutorials` and `examples` folders for example usage.
+To start using `sledo`, please refer to the `tutorials` and `examples` folders for example usage.
+
+Before using `sledo`, please see the following section on providing access to your MOOSE application of choice for running simulations.
+
+## MOOSE (Multiphysics Object Oriented Simulation Environment)
+
+While `sledo` itself is a pure python project, it is intended to be used alongside MOOSE.
+The simplest way to give `sledo` visibility of your MOOSE installation and chosen MOOSE app is to fill in the required paths in `moose_config.json`.
+If you don't have MOOSE installed already, there are several MOOSE applications available alongside `sledo` in the Aurora Multiphysics organisation (https://github.com/aurora-multiphysics), such as `proteus`, `aurora`, and `apollo`; each is focussed on different physics domains, so choose the one appropriate for your design problem.
 
 # Contributors
 
@@ -68,13 +68,14 @@ Lloyd Fletcher, UK Atomic Energy Authority
 
 # Citing Sledo
 
-If using Sledo in your research, please cite the following:
+If using `sledo` in your research, please cite the following:
 
 > Citation TBC
 
-Please also cite Sledo's dependencies as indicated on their individual websites:
+Please also cite `sledo`'s dependencies as indicated on their individual websites:
 
 - MOOSE (https://mooseframework.inl.gov/citing.html)
+- Ray-Tune (https://docs.ray.io/en/latest/tune/index.html#citing-tune)
 - BoTorch (https://botorch.org/docs/papers)
 - NumPy (https://numpy.org/citing-numpy/)
 - SciPy (https://scipy.org/citing-scipy/)

examples/example_1_simple_monoblock.py

@@ -1,37 +1,73 @@
-from sledo.optimiser import Optimiser
-from sledo.simulation import ThermoMechSimulation
-
-DATA_DIR = "./results/example_1"
-
-search_space = (
-    {
-        "name": "Armour height",
-        "type": "range",
-        "hit_name": "monoBArmHeight",
-        "hit_block": "",
-        "bounds": [1e-3, 20e-3],
-    },
-    {
-        "name": "Block width",
-        "type": "range",
-        "hit_name": "monoBWidth",
-        "hit_block": "",
-        "bounds": [17e-3, 34e-3],
-    },
-)
-
-opt = Optimiser(
-    name="simple_monoblock",
-    search_space=search_space,
-    simulation_class=ThermoMechSimulation,
-    data_dir=DATA_DIR,
-)
-
-opt.load_input_file("./input_files/simple_monoblock.i")
-opt.run_optimisation_loop(
-    objective_name="stress",
-    max_iter=20,
-    minimise=True,
-)
-
-opt.pickle()
+"""
+SLEDO Simple Monoblock Example
+
+Example input file for running Bayesian optimisation of a simplified divertor
+monoblock to minimise the peak von misses stress predicted by a
+thermomechanical MOOSE simulation.
+
+(c) Copyright UKAEA 2023-2024.
+"""
+
+from ray import tune
+
+from sledo import Optimiser, MooseHerderDesignEvaluator
+from sledo import SLEDO_ROOT
+
+# This points to the file 'moose_config.json' in sledo root folder.
+# If you haven't already, please make sure you've entered the required paths
+# for your chosen MOOSE app.
+# In general, you don't need to import this as it will be used by default,
+# however you may point to a config file in a different location if you wish
+# to use something else for a given optimisation run.
+from sledo import MOOSE_CONFIG_FILE
+
+# Set the paths required for this example.
+# In general, the user will set their own paths and pass them where required.
+EXAMPLES_DIR = SLEDO_ROOT / "examples"
+INPUT_FILE = EXAMPLES_DIR / "input_files" / "simple_monoblock_thermomech.i"
+WORKING_DIR = EXAMPLES_DIR / "results" / "example_1"
+PICKLE_FILEPATH = WORKING_DIR / "example_1_optimiser.pickle"
+
+if __name__ == "__main__":
+
+    # Set metrics for optimisation. These must exactly match how they appear
+    # in your MOOSE postprocessor. In this case, we are only optimising a
+    # single objective, but the list convention is still used.
+    metrics = ["max_stress"]
+
+    # Instantiate design evaluator.
+    design_evaluator = MooseHerderDesignEvaluator(
+        metrics,
+        INPUT_FILE,  # The base input file to be modified per design iteration.
+        working_dir=WORKING_DIR,  # Directory to store generated files.
+        config_path=MOOSE_CONFIG_FILE,  # Contains required MOOSE paths.
+    )
+
+    # Define a search space according to the Ray Tune API.
+    # Documentation here:
+    # https://docs.ray.io/en/latest/tune/api/search_space.html
+    # The variable names must exactly match how they appear in the MOOSE input
+    # file so that they can be updated for each design iteration.
+    search_space = {
+        "monoBArmHeight": tune.uniform(1e-3, 20e-3),
+        "monoBThick": tune.uniform(0.5e-3, 9e-3),
+    }
+
+    # Instantiate SLEDO optimiser.
+    opt = Optimiser(
+        design_evaluator,
+        search_space,
+        max_total_trials=20,
+        name="simple-monoblock-optimiser",
+        data_dir=WORKING_DIR,
+    )
+
+    # Run optimisation.
+    results = opt.run_optimisation()
+    print(results)
+
+    # Save the optimiser class instance to file.
+    opt.pickle(PICKLE_FILEPATH)
+
+    # To load the optimiser class from file, you can then run.
+    opt = Optimiser.unpickle(PICKLE_FILEPATH)