v2.0.1

Yawning-Titan v2.0.1 is a bugfix release for #56 [BUG] Rendering and GIF saving is broken.

🎉 What's New

GUI

• Added new options in the Run page for separate generation of Animated GIFs and WEBM videos

  • This can be found under the Evaluation tab
    

  • If both Animated GIF and WEBM videos are to be generated, the video will be shown as the preview

Python API

• Separated saving of Animated GIFs and WEBM videos, so that they can be generated independently of each other
  

🐛 Bug Fixes

• Fixed an issue where an error occurs if no webm_output_directory is provided when the ActionLoop.gif_action_loop() is called
• WEBM files are now generated in the USER_DIR/yawning_titan/videos by default, but can be overridden by providing a path to webm_output_directory

💫 How to Install & Run

First time installing Yawning-Titan?

Windows (Powershell)

mkdir ~\yawning_titan
cd ~\yawning_titan
Invoke-WebRequest -OutFile yawningtitan-2.0.1-py3-none-any.whl -Uri https://github.com/dstl/YAWNING-TITAN/releases/download/v2.0.1/yawningtitan-2.0.1-py3-none-any.whl
python3 -m venv .venv
attrib +h .venv /s /d # Hides the .venv directory
.\.venv\Scripts\activate
pip install --upgrade pip==23.0.1
pip install wheel==0.38.4 --upgrade
pip install setuptools==66 --upgrade
pip install yawningtitan-2.0.1-py3-none-any.whl
yawning-titan --install-completion
yawning-titan setup

Unix

sudo apt-get install python3-venv
mkdir ~/yawning_titan
cd ~/yawning_titan
wget https://github.com/dstl/YAWNING-TITAN/releases/download/v2.0.1/yawningtitan-2.0.1-py3-none-any.whl
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip==23.0.1
pip install wheel==0.38.4 --upgrade
pip install setuptools==66 --upgrade
pip install yawningtitan-2.0.1-py3-none-any.whl
yawning-titan --install-completion
yawning-titan setup

Updating an existing install?

Windows (Powershell)

cd ~\yawning_titan
Invoke-WebRequest -OutFile yawningtitan-2.0.1-py3-none-any.whl -Uri https://github.com/dstl/YAWNING-TITAN/releases/download/v2.0.1/yawningtitan-2.0.1-py3-none-any.whl
.\.venv\Scripts\activate
pip install --upgrade pip==23.0.1
pip install wheel==0.38.4 --upgrade
pip install setuptools==66 --upgrade
pip install yawningtitan-2.0.1-py3-none-any.whl --upgrade
yawning-titan --install-completion
yawning-titan setup

Unix

cd ~/yawning_titan
cwget https://github.com/dstl/YAWNING-TITAN/releases/download/v2.0.1/yawningtitan-2.0.1-py3-none-any.whl
source .venv/bin/activate
pip install --upgrade pip==23.0.1
pip install wheel==0.38.4 --upgrade
pip install setuptools==66 --upgrade
pip install yawningtitan-2.0.1-py3-none-any.whl --upgrade
yawning-titan --install-completion
yawning-titan setup

Installing Yawning-Titan from Source?

CD to where you want to store the Yawning-Titan source code, then:

Windows (Powershell)

git clone https://github.com/dstl/YAWNING-TITAN.git
python3 -m venv venv
.\venv\Scripts\activate
pip install --upgrade pip==23.0.1
pip install wheel==0.38.4 --upgrade
pip install setuptools==66 --upgrade
pip install build
pip install -e .[dev]
cd docs
make.bat html
cd ..\scripts
.\copy_docs_to_gui_static.bat
cd ..
python -m build
pip install .\dist\yawningtitan-2.0.1-py3-none-any.whl --upgrade
yawning-titan --install-completion
yawning-titan setup

Unix

git clone https://github.com/dstl/YAWNING-TITAN.git
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip==23.0.1
pip install wheel==0.38.4 --upgrade
pip install setuptools==66 --upgrade
pip install build
pip install -e .[dev]
cd docs
make html
cd ../scripts
./copy_docs_to_gui_static.sh
cd ..
python -m build
pip install .\dist\yawningtitan-2.0.1-py3-none-any.whl --upgrade
yawning-titan --install-completion
yawning-titan setup

Running Yawning-Titan from the GUI

Windows (Powershell)

cd ~\yawning_titan
.\.venv\Scripts\activate
yawning-titan gui

Unix

cd ~/yawning_titan
source .venv/bin/activate
yawning-titan gui

Contributors

• @ChrisMcCarthyDev part of the Yawning-Titan dev team.
• @czar-ec-envitia part of the Yawning-Titan dev team.

Full Changelog: v2.0.0...v2.0.1

v2.0.0

✨ What's New

Yawning-Titan CLI

• Yawning-Titan now comes with a command line interface using tiangolo/Typer. This serves as the main entry point to Yawning-Titan for those using Yawning-Titan out-of-the-box. It enables things like setup, rebuilding DBs, viewing logs, starting the GUI, starting Jupyter Lab. After installing, you can use yawning-titan --help to see the available commands
  

Yawning-Titan GUI

The Yawning-Titan GUI enables full standard use of Yawning-Titan out-of-the-box. Currently, the the GUI capabilities are:

• Create, save, edit, and remove Game Modes in the GameModeDB.
• Create, save, edit, and remove Networks in the NetworkDB.
• Configure a Yawning-Titan run session.
• Run a Yawning-Titan run session and view all metrics and log outputs.
• Other miscellaneous things like:
  • View documentation.
  • Submit feature request.
  • Submit bug ticket.
  • View release notes.

Since the v2.0.0b1 beta preview:

• Added a compatibility check between Game Modes and Networks
• Added a mini-viewport that displays where the current view is in relation to the full network graph
  
• Added an option to set an automatic layout for the network

Yawning-Titan

• Migrated from setup.py to pyproject.toml - This is a reaction to pypa/pip #8368 Deprecate call to setup.py install when building a wheel failed for source distributions without pyproject.toml, and the issues this has caused with legacy packages like openai/gym (see: dstl/YAWNING-TITAN #44 Yawning-Titan install failing due to Gym not compatible with setuptools>=67 ).

📚 Documentation

The Yawning-Titan docs have been revamped:

• The pradyunsg/furo is now being used to enable responsive light and dark mode.
• Code blocks that required both Windows (Powershell) and Unix code are now presented as tabbed code blocks using coldfix/sphinx-code-tabs.
• All codeblocks now have a copy button using executablebooks/sphinx-copybutton.

The latest Yawning-Titan docs can be viewed at https://dstl.github.io/YAWNING-TITAN/.

⚠️ Known Issues

Yawning-Titan GUI

• During Red Agent configuration, clicking on any Use text box toggles the Use in the skills section. The associated toggles are not affected and toggle as expected.
• The docs displayed in the GUI are offline built docs. As they're built from the Sphinx docs which are designed to work in a web browser, external links do now work from with the Yawning-Titan GUI when left clicked. To open external links, right click on the link and click Open in New Tab.
• Clicking on the About button from a minimised/contracted Hamburger Menu does nothing. This is because the About section has several menu sub-items. To view the About section, expand the Hamburger menu, then click the + sign to the right of About.

🛠 Engineering Notes

• As the docs viewed within the GUI and built and hosted lcoally, if your're making amendments to Yawning-Titan and rebuilding the gui, you'll need to rebuild and transport the built docs too. To do this:

  Windows (Powershell)

  cd docs
  make.bat clean
  make.bat html
  cd ..\scripts
  .\copy_docs_to_gui_static.bat

  Bash

  cd docs
  make clean
  make html
  cd ../scripts
  ./copy_docs_to_gui_static.sh

💫 How to Install & Run

First time installing Yawning-Titan?

Windows (Powershell)

mkdir ~\yawning_titan
cd ~\yawning_titan
Invoke-WebRequest -OutFile yawningtitan-2.0.0-py3-none-any.whl -Uri https://github.com/dstl/YAWNING-TITAN/releases/download/v2.0.0/yawningtitan-2.0.0-py3-none-any.whl
python3 -m venv .venv
attrib +h .venv /s /d # Hides the .venv directory
.\.venv\Scripts\activate
pip install --upgrade pip==23.0.1
pip install wheel==0.38.4 --upgrade
pip install setuptools==66 --upgrade
pip install yawningtitan-2.0.0-py3-none-any.whl
yawning-titan --install-completion
yawning-titan setup

Unix

sudo apt-get install python3-venv
mkdir ~/yawning_titan
cd ~/yawning_titan
wget https://github.com/dstl/YAWNING-TITAN/releases/download/v2.0.0/yawningtitan-2.0.0-py3-none-any.whl
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip==23.0.1
pip install wheel==0.38.4 --upgrade
pip install setuptools==66 --upgrade
pip install yawningtitan-2.0.0-py3-none-any.whl
yawning-titan --install-completion
yawning-titan setup

Updating an existing install?

Windows (Powershell)

cd ~\yawning_titan
Invoke-WebRequest -OutFile yawningtitan-2.0.0-py3-none-any.whl -Uri https://github.com/dstl/YAWNING-TITAN/releases/download/v2.0.0/yawningtitan-2.0.0-py3-none-any.whl
.\.venv\Scripts\activate
pip install --upgrade pip==23.0.1
pip install wheel==0.38.4 --upgrade
pip install setuptools==66 --upgrade
pip install yawningtitan-2.0.0-py3-none-any.whl --upgrade
yawning-titan --install-completion
yawning-titan setup

Unix

cd ~/yawning_titan
cwget https://github.com/dstl/YAWNING-TITAN/releases/download/v2.0.0/yawningtitan-2.0.0-py3-none-any.whl
source .venv/bin/activate
pip install --upgrade pip==23.0.1
pip install wheel==0.38.4 --upgrade
pip install setuptools==66 --upgrade
pip install yawningtitan-2.0.0-py3-none-any.whl --upgrade
yawning-titan --install-completion
yawning-titan setup

Installing Yawning-Titan from Source?

CD to where you want to store the Yawning-Titan source code, then:

Windows (Powershell)

git clone https://github.com/dstl/YAWNING-TITAN.git
python3 -m venv venv
.\venv\Scripts\activate
pip install --upgrade pip==23.0.1
pip install wheel==0.38.4 --upgrade
pip install setuptools==66 --upgrade
pip install build
pip install -e .[dev]
cd docs
make.bat html
cd ..\scripts
.\copy_docs_to_gui_static.bat
cd ..
python -m build
pip install .\dist\yawningtitan-2.0.0-py3-none-any.whl --upgrade
yawning-titan --install-completion
yawning-titan setup

Unix

git clone https://github.com/dstl/YAWNING-TITAN.git
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip==23.0.1
pip install wheel==0.38.4 --upgrade
pip install setuptools==66 --upgrade
pip install build
pip install -e .[dev]
cd docs
make html
cd ../scripts
./copy_docs_to_gui_static.sh
cd ..
python -m build
pip install .\dist\yawningtitan-2.0.0-py3-none-any.whl --upgrade
yawning-titan --install-completion
yawning-titan setup

Running Yawning-Titan from the GUI

Windows (Powershell)

cd ~\yawning_titan
.\.venv\Scripts\activate
yawning-titan gui

Unix

cd ~/yawning_titan
source .venv/bin/activate
yawning-titan gui

Running Yawning-Titan from the Jupyter Lab

Windows (Powershell)

cd ~\yawning_titan
.\.venv\Scripts\activate
yawning-titan notebooks

Unix

cd ~/yawning_titan
source .venv/bin/activate
cd notebooks
jupyter lab

Contributors

• @ChrisMcCarthyDev part of the Yawning-Titan dev team.
• @czar-ec-envitia part of the Yawning-Titan dev team.
• @Rumbelows part of the Yawning-Titan dev team.
• @RiccardoGTolli made their first contribution in #46

Full Changelog: v1.1.1...v2.0.0

v2.0.0b1

Yawning-Titan v2.0.0b1

Yawning-Titan v2.0.0b1 is the first public preview/beta release of the Yawning-Titan GUI! 🙌

🎉 What's New

Yawning-Titan GUI

The Yawning-Titan GUI enables full standard use of Yawning-Titan out-of-the-box. Currently, the the GUI capabilities are:

• Create, save, edit, and remove Game Modes in the GameModeDB.
• Create, save, edit, and remove Networks in the NetworkDB.
• Configure a Yawning-Titan run session.
• Run a Yawning-Titan run session and view all metrics and log outputs.
• Other miscellaneous things like:
  • View documentation.
  • Submit feature request.
  • Submit bug ticket.

⚠️ Known Issues

When choosing networks and game modes in ‘Run session’ page there is currently not a compatibility check between game modes and networks to ensure that only compatible pairs can be used together in a YawningTitanRun.

🛠 Engineering Notes

Beta Release

This is a beta release of the Yawning-Titan GUI. While efforts have been made to squash all bugs, we fully expect there to be one or two little critters still hiding in there!

✨ How to Install & Run

First time installing Yawning-Titan?

Windows

mkdir ~\yawning_titan
cd ~\yawning_titan
python3 -m venv .venv
attrib +h .venv /s /d # Hides the .venv directory
.\.venv\Scripts\activate
mkdir v2.0.0b1
cd v2.0.0b1
git clone https://github.com/dstl/YAWNING-TITAN.git
cd YAWNING-TITAN
git checkout release/2.0.0b1
pip install -e .[dev]

Unix

sudo apt-get install python3-venv
mkdir ~/yawning_titan
cd ~/yawning_titan
python3 -m venv .venv
source .venv/bin/activate
mkdir v2.0.0b1
cd v2.0.0b1
git clone https://github.com/dstl/YAWNING-TITAN.git
cd YAWNING-TITAN
git checkout release/2.0.0b1
pip install -e .[dev]

Updating an existing install?

Windows

cd ~\yawning_titan
.\.venv\Scripts\activate
mkdir v2.0.0b1
cd v2.0.0b1
git clone https://github.com/dstl/YAWNING-TITAN.git
cd YAWNING-TITAN
git checkout release/2.0.0b1
pip install -e .[dev]

Unix

cd ~/yawning_titan
source .venv/bin/activate
mkdir v2.0.0b1
cd v2.0.0b1
git clone https://github.com/dstl/YAWNING-TITAN.git
cd YAWNING-TITAN
git checkout release/2.0.0b1
pip install -e .[dev]

Run the Yawning-Titan GUI

First, we need to reset the default entries in the NetworkDB and GameModeDB:

Windows

cd ~\yawning_titan
.\.venv\Scripts\activate
py  ./v2.0.0b1/YAWNING-TITAN/scripts/reset_network_and_game_mode_db_defaults.py

Unix

cd ~/yawning_titan
source .venv/bin/activate
python ./v2.0.0b1/YAWNING-TITAN/scripts/reset_network_and_game_mode_db_defaults.py

Now with the DBs reset, we can start the Django server:

Windows

cd ~\yawning_titan
.\.venv\Scripts\activate
cd ./v2.0.0b1/YAWNING-TITAN/
py manage.py runserver

Unix

cd ~/yawning_titan
source .venv/bin/activate
cd ./v2.0.0b1/YAWNING-TITAN/
python manage.py runserver

Contributors

• @ChrisMcCarthyDev part of the Yawning-Titan dev team.
• @Rumbelows part of the Yawning-Titan dev team.
• @czar-ec-envitia part of the Yawning-Titan dev team.

Full Changelog: v1.1.1...v2.0.0b1

v1.1.1

YAWNING-TITAN v1.1.1

Yawning-Titan v1.1.1 is a bugfix version for Yawning-Titan v1.1.0.

🐛 Bug Fixes

VERSION file not included in MANIFEST.in or in data_files in the setup.py

The VERSION file which acts as the single source of truth for the Yawning-Titan version number was not included in a MANIFEST.in file or as data_files in the setup.py. This caused the install from a sdist .tar.gz file to fail as a VERSION file didn't exist.

✨ How to Install & Run

First time installing Yawning-Titan?

Windows

mkdir ~\yawning_titan
cd ~\yawning_titan
python3 -m venv .venv
attrib +h .venv /s /d # Hides the .venv directory
.\.venv\Scripts\activate
pip install <path to the downloaded yawningtitan-1.1.1.tar.gz file>

Unix

mkdir ~/yawning_titan
cd ~/yawning_titan
python3 -m venv .venv
source .venv/bin/activate
pip install <path to the downloaded yawningtitan-1.1.1.tar.gz file>

Updating an existing install?

Windows

cd ~\yawning_titan
.\.venv\Scripts\activate
pip install <path to the downloaded yawningtitan-1.1.1.tar.gz file>

Unix

cd ~/yawning_titan
source .venv/bin/activate
pip install <path to the downloaded yawningtitan-1.1.1.tar.gz file>

Run Yawning-Titan in Jupyter Lab

Windows

cd ~\yawning_titan
.\.venv\Scripts\activate
cd ~\yawning_titan\notebooks
jupyter lab

Unix

cd ~/yawning_titan
source .venv/bin/activate
cd ~/yawning_titan/notebooks
jupyter lab

Contributors

• @ChrisMcCarthyDev part of the Yawning-Titan dev team.

Full Changelog: v1.1.0...v1.1.1

v1.1.0

YAWNING-TITAN v1.1.0

🎉 What's New

Config Revamp

Game Mode

The GameMode classes have been remodelled. The remodelling and rebuild:

• Makes for more intuitive traversing of the config paths.
• Promotes code reusability by reusing group classes for commonly grouped config items.
• Allows automatic config validation at every level.
• Is backwards compatible with the old style game mode config YAML files.

To ingest an old-style game mode yaml config file:

legacy_path = <path to your legacy game mode yaml file>

from yawning_titan.game_modes.game_mode import GameMode

game_mode = GameMode.create_from_yaml(
    yaml=legacy_path,
    infer_legacy=True
)

Network & Node

The Network class has been refactored to subclass networkx.Graph. This refactoring:

• Cuts out the need to use 2D adjacency matrix to represent the network, making network creation simpler.
• Decouples network logic from the NetworkInterface class.
• Uses a new Node class as the nodes in place of the old string nodes. This further decouples network and node logic and node attribute lookups from the NetworkInterface class.

TinyDB for Network and Game Mode storage

Yawning-Titan now comes with it’s very own localised lightweight JSON database which is an extension of TinyDB; Think MongoDB without the deps.

The new YawningTitanDB abstract base class class extends TinyDB with:

• Use of a uuid for index and querying.
• Duplicate entries are not possible.
• Default entries “locked” and cannot be edited by the user.

NetworkDB and GameModeDB are subclasses of YawningTitanDB which take and return instances of NetworkDB and GameModeDB respectively.

NetworkSchema and GameModeSchema are classes that implement the structure of Network and GameMode by using a new YawningTitanQuery class. This allows for full querying of the NetworkDB and GameModeDB.

YawningTitanRun Class

• Enables out-of-the-box run of Yawning-Titan to train agents on the default settings. Makes it more accessible.
• Is full configurable.
• Allows trained agents to be both saved locally, and exported to other machines.
• Is the first iteration. Further enhancements will include an evaluation reporting feature and real-time graph rendering.

Move to Jupyter Lab

Yawning-Titan now installs and uses Jupyter Lab instead of Jupyter Notbooks. This gives more of an IDE feel and allows the user to write Python scripts and Jupyter Notebooks all from the same tab and have them all saved in the Yawning-Titan users notebooks directory (~/yawning_titan/notebooks).

New Demo Notebooks Added

Three additional demo notebooks have been included in this release:

• Create a Network.ipynb - Demonstrates how to create a Network using the yawning_titan.networks.network.Network and yawning_titan.networks.node.Node classes.
• Using the Network DB.ipynb - Demonstrates how to use the yawning_titan.networks.network_db.NetworkDB with the yawning_titan.networks.network_db.NetworkQuery and yawning_titan.networks.network_db.NetworkSchema classes.
• Using YawningTitanRun.ipynb - Demonstrates how to use the yawning_titan.yawning_titan_run.YawningTitanRun class.

Adding the isolated state to the observation (GitHub Issue #12)

GitHub Issue: Suggestion: adding the isolated state to observation · Issue #12 · dstl/YAWNING-TITAN

Isolation cost/reward (GitHub Issue #9)

GitHub Issue: Isolation cost/reward · Issue #9 · dstl/YAWNING-TITAN

🐛 Bug Fixes

Incorrect reward for blue agent reaching max_steps (GitHub Issue #10)

This was an issue raised on the dstl/YAWNING-TITAN repo by a member of the community (john-cardiff - Overview). This fixed an issue whereby the Blue Agent was being rewarded incorrectly for reaching max steps.

GitHub Issue: Incorrect reward for blue agent reaching max_steps · Issue #10 · dstl/YAWNING-TITAN

🛠 Engineering Notes

Test Package Overhaul

The Yawning-Titan tests have been overhauled completely. A test NetworkDB and GameModeDB are available as fixtures in the test package. These DBs are just patches of the main NetworkDB and GameModeDB so they work in the exact same way. All tests now use these DBs for accessing GameMode and Network instances. All tests are now marked as unit_test, integration_test, or e2e_integration_test.

Release Wheel Builds

As part of releases moving forward we'll be building wheels for Windows, Linux, and MacOS on Python 3.8, 3.9, and 3.10.

✨ How to Install & Run

First time installing Yawning-Titan?

Windows

mkdir ~\yawning_titan
cd ~\yawning_titan
python3 -m venv .venv
attrib +h .venv /s /d # Hides the .venv directory
.\.venv\Scripts\activate
pip install <path to downloaded yawningtitan .tar.gz file>

Unix

mkdir ~/yawning_titan
cd ~/yawning_titan
python3 -m venv .venv
source .venv/bin/activate
pip install <path to downloaded yawningtitan .tar.gz file>

Updating an existing install?

Windows

cd ~\yawning_titan
.\.venv\Scripts\activate
pip install <path to downloaded yawningtitan .tar.gz file>

Unix

cd ~/yawning_titan
source .venv/bin/activate
pip install <path to downloaded yawningtitan .tar.gz file>

Run Yawning-Titan in Jupyter Lab

Windows

cd ~\yawning_titan
.\.venv\Scripts\activate
cd ~\yawning_titan\notebooks
jupyter lab

Unix

cd ~/yawning_titan
source .venv/bin/activate
cd ~/yawning_titan/notebooks
jupyter lab

Contributors

• @ChrisMcCarthyDev part of the Yawning-Titan dev team.
• @Rumbelows part of the Yawning-Titan dev team.
• @czar-ec-envitia part of the Yawning-Titan dev team.

Full Changelog: v1.0.1...v1.1.0

v1.0.1

YAWNING-TITAN v1.0.1

🐛 Bug Fixes

#30 - # Signature of NetworkInterface causing issues in a few files

This was an issue raised on the dstl/YAWNING-TITAN repo by a member of the community (https://github.com/forrestmckee). This had been an oversight on our part when implementing the updated configs and NetworkInterface instantiation throughout the codebase in v1.0.0.

Issue: #30

🧹 House Keeping

• The papertrail directory with test outputs has been dropped as tests can now be viewed in GitHub Actions.
• An old latex docs build in docs has been dropped.
• Type hints in some config classes have been updated/added.
• Dependencies have been updated. (Poetry will be introduced in a future version to manage dependencies).

☠️ Known Issues

• The start_jupyter_session method in yawning_titan.notebooks.jupyter currently only works on Windows operating system. Follow these steps to get a session running from Linux or MacOS:
  • cd to the NOTEBOOKS_DIR with: cd ~/yawning_titan/notebooks.
  • Activate your env where Yawning-Titan is installed with: source <path to Python bin> activate.
  • Spin-up a Jupyter notebook session with: Jupyter notebook.

✨ How to Install & Run

Install Yawning-Titan

As this is the first versioned release of Yawning-Titan that has lots of API breaking changes, it is recommended that all users perform a new installation by following the code block below for your desired operating system, replacing the <path to downloaded yawningtitan-1.0.1.tar.gz> with the location of the downloaded yawningtitan-1.0.1.tar.gz file.

Windows

mkdir ~\yawning_titan
cd ~\yawning_titan
python3 -m venv .venv
attrib +h .venv /s /d # Hides the .venv directory
.\.venv\Scripts\activate
pip install <path to downloaded yawningtitan-1.0.1.tar.gz>

Unix

mkdir ~/yawning_titan
cd ~/yawning_titan
python3 -m venv .venv
source .venv/bin/activate
pip install <path to downloaded yawningtitan-1.0.1.tar.gz>

Run Jupyter from your Yawning-Titan Virtual Environment

Windows

cd ~\yawning_titan
.\.venv\Scripts\activate
cd notebooks
jupyter notebook

Unix

cd ~/yawning_titan
source .venv/bin/activate
cd notebooks
jupyter notebook

Install Yawning-Titan Dev Environment

The Yawning-Titan repo can be cloned and installed as a dev environment for user customisation. Follow the code block below for your desired operating system.

Windows

mkdir ~\yawning_titan
mkdir ~\yawning_titan\src
cd ~\yawning_titan\src
git clone https://github.com/dstl/YAWNING-TITAN.git
cd YAWNING-TITAN
python3 -m venv .venv
attrib +h .venv /s /d # Hides the .venv directory
.\.venv\Scripts\activate
pip install -e .[dev]

Unix

mkdir ~/yawning_titan
mkdir ~/yawning_titan/src
cd ~/yawning_titan/src
git clone https://github.com/dstl/YAWNING-TITAN.git
cd YAWNING-TITAN
python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

Contributors

• @ChrisMcCarthyDev part of the Yawning-Titan dev team.
• @Rumbelows part of the Yawning-Titan dev team.

Full Changelog: v1.0.0...v1.0.1

v1.0.0

YAWNING-TITAN v1.0.0

🎉 What's New

OS-Agnostic

Yawning-Titan is now OS-agnostic('ish). There are two parts to this.

💻 v1.0.0 has been tested on Windows 10 (Pro build 19045.2251), Ubuntu (18.04 LTS, 20.04 LTS, 22.04 LTS), and MacOS (Catalina 10.15.7). While Yawning-Titan should work on most variations/distros and custom builds of the three operating systems listed above, it has not been possible to test this.

Dynamic Paths

Hard-coded file paths have been removed and replaced with dynamic path creation using combinations of pathlib.Path and/or os.path.join.

Ray 3.0.0 Beta Support for Windows

The previous version of Yawning-Titan used the latest release build of Ray, Ray version 2.., which does not support Windows. While it was possible to get this working with a number of tweaks in the backend, we felt this was very cumbersome. The standard pip install ray[rllib]==2.1.0 on Windows just doesn’t work for some:

(venv) PS C:\Users\sandbox\source\repos\methodsanalytics\YAWNING-TITAN> pip install ray[rllib]==2.1.0
ERROR: Could not find a version that satisfies the requirement ray[rllib]==2.1.0 (from versions: none)
ERROR: No matching distribution found for ray[rllib]==2.1.0

Ray are working towards windows support in version 3.., and thus have released Ray version 3.0.0.dev0 Beta version.

Ray currently supports Linux, MacOS and Windows. Ray on Windows is currently in beta.

Source: https://docs.ray.io/en/latest/ray-overview/installation.html

After extensive testing of Ray version 3.0.0.dev0 with Yawning-Titan, the decision was made to include it as a dependency in setup.py.

Packaged & Installable

Yawning-Titan is slowly progressing from a GitHub repo that is cloned and used from the directory it is cloned into, to a piece of packaged software that is installed on a machine and used without needing to clone the repo. For this to happen, anything that sat outside of the repo that was required for its use, needed to be brought in and installed as package data. The current list of package data is:

• yawning_titan/config/_package_data/logging_config.yaml
• yawning_titan/config/_package_data/game_modes/default_game_mode.yaml
• yawning_titan/config/_package_data/game_modes/low_skill_red_with_random_infection_perfect_detection.yaml
• yawning_titan/notebooks/_package_data/sb3/End to End Generic Env Example - Env Creation, Agent Train and Agent Rendering.ipynb
• yawning_titan/notebooks/_package_data/sb3/Using an Evaluation Callback to monitor progress during training.ipynb
• yawning_titan/notebooks/_package_data/Creating and playing as a Keyboard Agent.ipynb

App Directories

Yawning-Titan now comes with a set of application directories and user directories. These directories are used by Yawning-Titan to store default files, data, config etc., but also provide the user with a home to store their custom config, Jupyter notebooks, agents etc. The directories are created automatically when Yawning-Titan is installed. Below shows the Yawning-Titan directory tree for Windows, Linux, and Mac operating systems:

Windows

~/
├─ AppData/
│  │  ├─ yawning_titan/
│  │  ├─ app_images/
│  │  ├─ config/
│  │  ├─ db/
│  │  ├─ docs/
│  │  ├─ logs/
├─ yawning_titan/
│  ├─ agents/
│  ├─ game_modes/
│  ├─ images/
│  ├─ notebooks/

Linux

~/
├─ .cache/
│  ├─ yawning_titan/
│  │  ├─ log/
├─ .config/
│  ├─ yawning_titan/
├─ .local/
│  ├─ share/
│  │  ├─ yawning_titan/
│  │  │  ├─ app_images/
│  │  │  ├─ db/
│  │  │  ├─ docs/
├─ yawning_titan/
│  ├─ agents/
│  ├─ game_modes/
│  ├─ images/
│  ├─ notebooks/

MacOs

~/
├─ Library/
│  ├─ Application Support/
│  │  ├─ Logs/
│  │  │  ├─ yawning_titan/
│  │  │  │  ├─ log/
│  │  ├─ Preferences/
│  │  │  ├─ yawning_titan/
│  │  ├─ yawning_titan/
│  │  │  ├─ app_images/
│  │  │  ├─ db/
│  │  │  ├─ docs/
├─ yawning_titan/
│  ├─ agents/
│  ├─ game_modes/
│  ├─ images/
│  ├─ notebooks/

Platform Logging

Logging has been setup and is configured in Yawning-Titan’s top-level init.py. Logging is formatted using the YAWNING-TITAN.yawning_titan.config._package_data.logging_config.yaml. Logs are sent to two handlers:

• debug_console_handler, a StreamHandler that send logs to stderr at DEBUG level.
• info_rotating_file_handler, a RotatingFileHandler that send logs to LOG_DIR/yawning_titan.log at INFO level. The maximum log file size is 10MB and it will rotate 10 times, therefore no more than 110MB of logs will ever exist.

Loggers have a format: '%(asctime)s::%(levelname)s::%(name)s::%(funcName)s::%(lineno)s::%(message)s'

Config Classes

A structure of Python Data Classes has been built to:

• Encapsulate the creation and validation of game mode and network configs.
• To enable the creation of custom game modes and networks using a GUI (currently in development).
• To decouple the game mode config from the network config.
• To provide documentation of config key/value pairs as docstrings.

The classes utilise Python Data Classes for automatic __init__, __hash__, __eq__, __repr__, and __dict__, but still use traditional OOP getters and setters to enable docstrings to be used by Sphinx. An abstract base class, yawning_titan.config.game_config.config_abc.ConfigABC, has been defined that has a to_dict() method, and create(config_dict) and validate(config_dict) abstract class methods.

GameModeConfig

The yawning_titan.config.game_config.game_mode_config.GameModeConfig class now serves as the main config class for the game rules. GameModeConfig has a single instance of RedAgentConfig, BlueAgentConfig, GameRulesConfig, ObservationSpaceConfig, ResetConfig, RewardsConfig, and MiscellaneousConfig. The GameModeConfig class has the following methods:

• create(config_dict) - This method is a factory method that takes a parsed .yaml config file as a Python dictionary and returns an instance of GameModeConfig.
• GameModeConfig.create_from_yaml(config_path - This class method takes a .yaml config file path, reads and parses it into a Python dictionary, and passes it to create before returning the created instance of GameModeConfig. The config_path parameter has a default value of default_game_mode_path().
• to_dict(key_upper) - The method serializes the GameModeConfig as a Python dict. If key_upper=True, the top-level keys (red, blue, game_rules observation_space, reset, rewards, miscellaneous) are uppercase to match the config .yaml files.
• to_yaml(config_path) - Calls to_dict_key_upper=True) and then dumps the returned dict down to .yaml at the provided config path.

Below is a UML class diagram of the GameModeConfig.

NetworkConfig

The yawning_titan.config.network_config.network_config.NetworkConfig class now serves as the main config class for the network. The NetworkConfig class has the following methods:

• create - This method is a factory method that takes a parsed .yaml config file as a Python dictionary and returns an instance of NetworkConfig.
• create_from_args - This method is a factory method that takes a matrix and positions, and optional entry_nodes, vulnerabilities, and high_value_nodes, and returns an instance of NetworkConfig.

Below is a UML class diagram of the NetworkConfig.

High Value Target Terminology Changes

For added clarity, the term “high value target” has been changed to “high value node”. This change reflects situations where a node in a network may be of high value but is not defined as a target node. This change affects all config .yaml files, with keys containing high_value_target now containing high_value_node.

Multiple High Value Nodes

A network can now contain multiple high value nodes as opposed to just one. By defining multiple high value nodes in a network, an agent has more chances to ‘instantly win’.

• Can now specify the number of high value targets in the game via number_of_high_value_nodes in GameRulesConfig.
• Can now specify the exact nodes that will be high value nodes by providing a list of strings to NetworkConfig.high_value_nodes.
• choose_high_value_target_placement_at_random renamed to choose_high_value_nodes_placement_at_random.
• choose_high_value_target_furthest_away_from_entry renamed to choose_high_value_nodes_furthest_away_from_entry.
• choose_new_high_value_target_on_reset renamed to choose_new_high_value_nodes_on_reset.

Seeds and Randomisation

There are 3 primary sources of RNGs in the system; random, numpy.random and the user of sets – which although not designed to be random add random behaviour due to element retrieval being non deterministic.

This behaviour can now be overwritten through added specificity of deterministic=True parameters added to action loops and an additional random_seed setting in the miscellaneous section of the config file. This serves to propagate deterministic behaviour throughout the game and training episodes.

In order to correctly proporgate the seed to the agent training module the user must manually set the seed in the training algorithm class thusly.

agent = PPO(
      PPOMlp, env, verbose=1, seed=env.network_interface.random_seed
)

This manual requirement is counter intuitive and should hopefully be phase...

v0.1.0

What's Changed

• Implement the method for the DCBOAgent class by @sammy32507 in #1
• Bump numpy from 1.20.0 to 1.22.0 by @dependabot in #2
• Pinning Gym to 0.21.0 to ensure compatability with Stable Baselines 3 by @br0kej in #5
• Adding pre-commit to dev setup.py and implementing an initial Github Actions CI pipeline by @br0kej in #3
• Adding a CPU Capable Docker Container by @br0kej in #6

New Contributors

• @sammy32507 made their first contribution in #1
• @dependabot made their first contribution in #2
• @br0kej made their first contribution in #5

Full Changelog: https://github.com/dstl/YAWNING-TITAN/commits/v0.1.0