ml-peg 0.5.0

ML Performance and Extrapolation Guide

ML-PEG: ML Performance and Extrapolation Guide

🔗 See our live guide: https://ml-peg.stfc.ac.uk

Contents

• Getting started
• Features
• Development
• Docker/Podman images
• License

Getting started

Dependencies

All required and optional dependencies can be found in pyproject.toml.

Installation

The latest stable release of ML-PEG, including its dependencies, can be installed from PyPI by running:

python3 -m pip install ml-peg

To get all the latest changes, ML-PEG can be installed from GitHub:

python3 -m pip install git+https://github.com/ddmms/ml-peg.git

Features

More details coming soon!

Development

Please ensure you have consulted our contribution guidelines and coding style before proceeding.

We recommend installing uv for dependency management when developing for ML-PEG:

1. Install uv
2. Install ML-PEG with dependencies in a virtual environment:

git clone https://github.com/ddmms/ml-peg
cd ml-peg
uv sync # Create a virtual environment and install dependencies
source .venv/bin/activate
pre-commit install  # Install pre-commit hooks
pytest -v  # Discover and run all tests

Please refer to the online documentation for information about contributing new benchmarks and models.

Command-line interface

To help run calculations, analysis, and the application, we provide the ml_peg command line tool, which is installed with the package. This provides the following commands:

ml_peg app
ml_peg calc
ml_peg analyse
ml_peg download
ml_peg list

For example, to run the X23 test with mace-mp-0a and orb-v3-consv-inf-omat, you can run:

ml_peg calc --test X23 --models mace-mp-0a,orb-v3-consv-inf-omat

A description of each subcommand, as well as valid options, can be listed using the --help option. For example:

ml_peg calc --help

The ml_peg list command provides a further set of subcommands:

ml_peg list calcs
ml_peg list analysis
ml_peg list app
ml_peg list models

which list the available tests and categories that may be run for ml_peg calc, ml_peg analyse and ml_peg app, and the MLIPs that these can be run for.

Tutorials

We encourage developers new to the ML-PEG framework to work through the detailed step-by-step guides provided by our Jupyter Notebook tutorials:

• Adding a New Benchmark

Docker/Podman images

You can use Docker or Podman to build and/or run the ML-PEG app yourself.

[!TIP] The commands below will assume you are using Docker. To use Podman, replace docker with podman, e.g. podman pull, podman build, and podman run.

A Docker image with the latest changes can be pulled from the GitHub container registry, following the command that can be found under this repository's packages.

[!NOTE] Currently, this repository only contains images for the linux/amd64 platform. On MacOS with ARM silicon, this can often still be run by setting --platform linux/amd64 when using docker run.

Alternatively, to build the container yourself, you can use the Dockerfile provided. From the ml-peg directory, run:

docker build -t ml-peg-app -f containers/Dockerfile .

Once built, you can mount your current application data and start the app by running:

docker run --volume ./ml_peg/app/data:/app/ml_peg/app/data  --publish 8050:8050 ml-peg-app

[!TIP] Ensure ml_peg/app/data is populated with results before running the container.

A compressed zip file containing the current live data can be found at http://s3.echo.stfc.ac.uk/ml-peg-data/app/data/data.tar.gz.

This may also be downloaded through the command line using

ml_peg download --key app/data/data.tar.gz  --filename data.tar.gz

Alternatively, you can use the compose.yml file provided, via Docker Compose:

docker compose -f containers/compose.yml up -d

The app should now be accessible at http://localhost:8050.

License

GNU General Public License version 3