diff --git a/Readme.md b/Readme.md index 20ad7ebad1..6c8e31f2bc 100644 --- a/Readme.md +++ b/Readme.md @@ -38,7 +38,7 @@ The table below shows our latest release, including our `develop` branch which i | **Version** | **Release Date** | **Source** | **Documentation** | **Download** | **Python Package** | **Unity Package** | |:----------------------:|:-------------------:|:-----------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------------------------------:|:--------------------------------------------------------------------------------------:|:-----------------------------------------------------:|:-------------------------------------------------------------------------------------:| -| **Release 23** | **August 15, 2025** | **[source](https://github.com/Unity-Technologies/ml-agents/tree/release_23)** | **[docs](https://docs.unity3d.com/Packages/com.unity.ml-agents@4.0/manual/index.html)** | **[download](https://github.com/Unity-Technologies/ml-agents/archive/release_23.zip)** | **[1.1.0](https://pypi.org/project/mlagents/1.1.0/)** | **4.0.0** | +| **Release 23** | **August 28, 2025** | **[source](https://github.com/Unity-Technologies/ml-agents/tree/release_23)** | **[docs](https://docs.unity3d.com/Packages/com.unity.ml-agents@4.0/manual/index.html)** | **[download](https://github.com/Unity-Technologies/ml-agents/archive/release_23.zip)** | **[1.1.0](https://pypi.org/project/mlagents/1.1.0/)** | **4.0.0** | | **develop (unstable)** | -- | [source](https://github.com/Unity-Technologies/ml-agents/tree/develop) | [docs](https://github.com/Unity-Technologies/ml-agents/tree/develop/com.unity.ml-agents/Documentation~/index.md) | [download](https://github.com/Unity-Technologies/ml-agents/archive/develop.zip) | -- | -- | diff --git a/com.unity.ml-agents/CHANGELOG.md b/com.unity.ml-agents/CHANGELOG.md index 85214a4356..643d0481f5 100755 --- a/com.unity.ml-agents/CHANGELOG.md +++ b/com.unity.ml-agents/CHANGELOG.md @@ -6,7 +6,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). -## [4.0.0] - 2025-08-15 +## [4.0.0] - 2025-08-28 ### Major Changes #### com.unity.ml-agents (C#) - Upgraded to Inference Engine 2.2.1 (#6212) diff --git a/com.unity.ml-agents/Documentation~/Installation.md b/com.unity.ml-agents/Documentation~/Installation.md index c28600fa2b..f9fde0ff7f 100644 --- a/com.unity.ml-agents/Documentation~/Installation.md +++ b/com.unity.ml-agents/Documentation~/Installation.md @@ -1,9 +1,9 @@ # Installation -To install and use the ML-Agents Toolkit, follow the steps below. Detailed instructions for each step are provided later on this page. +To install and use the ML-Agents Toolkit, follow the steps below. Detailed instructions for each step are provided later on this page. For advanced installation and development setup, see the [Advanced Installation](#advanced-installation) section at the bottom of this page. 1. Install Unity (6000.0 or later) -2. Install Python (>= 3.10.1, <=3.10.12) - we recommend using 3.10.12 -3. Install the `com.unity.ml-agents` Unity package; or clone this repository and install locally (recommended for the latest version and bug fixes) +2. Install Python using conda (>= 3.10.1, <=3.10.12) - we recommend using 3.10.12 +3. Install the `com.unity.ml-agents` Unity package 4. Install `mlagents-envs` 5. Install `mlagents` @@ -11,13 +11,11 @@ To install and use the ML-Agents Toolkit, follow the steps below. Detailed instr [Download](https://unity3d.com/get-unity/download) and install Unity. We strongly recommend that you install Unity through the Unity Hub as it will enable you to manage multiple Unity versions. -### Install **Python 3.10.12** +### Install **Python 3.10.12** using Conda -We recommend [installing](https://www.python.org/downloads/) Python 3.10.12. If you are using Windows, please install the x86-64 version and not x86. If your Python environment doesn't include `pip3`, see these [instructions](https://packaging.python.org/guides/installing-using-linux-tools/#installing-pip-setuptools-wheel-with-linux-package-managers) on installing it. We also recommend using [conda](https://docs.conda.io/en/latest/) or [mamba](https://github.com/mamba-org/mamba) to manage your python virtual environments. +We recommend using [conda](https://docs.conda.io/en/latest/) or [mamba](https://github.com/mamba-org/mamba) to install and manage Python environments. -#### Conda python setup - -Once conda has been installed in your system, open a terminal and execute the following commands to setup a python 3.10.12 virtual environment and activate it. +Once conda has been installed on your system, open a terminal and execute the following commands to setup a Python 3.10.12 virtual environment and activate it: ```shell conda create -n mlagents python=3.10.12 && conda activate mlagents @@ -27,13 +25,40 @@ conda create -n mlagents python=3.10.12 && conda activate mlagents The Unity ML-Agents C# SDK is a Unity Package. You can install the `com.unity.ml-agents` package [directly from the Package Manager registry](https://docs.unity3d.com/Manual/upm-ui-install.html). Please make sure you enable 'Preview Packages' in the 'Advanced' dropdown in order to find the latest Preview release of the package. -**NOTE:** If you do not see the ML-Agents package listed in the Package Manager please follow the advanced installation instructions below. +**NOTE:** If you do not see the ML-Agents package listed in the Package Manager please follow the [Advanced Installation](#advanced-installation) instructions at the bottom of this page. + +### Install Python package + +Installing the `mlagents` Python package involves installing other Python packages that `mlagents` depends on. So you may run into installation issues if your machine has older versions of any of those dependencies already installed. Consequently, our supported path for installing `mlagents` is to leverage Python Virtual Environments. Virtual Environments provide a mechanism for isolating the dependencies for each project and are supported on Mac / Windows / Linux. We offer a dedicated [guide on Virtual Environments](Using-Virtual-Environment.md). + +#### Installing `mlagents` from PyPi + +You can install the ML-Agents Python package directly from PyPi. This is the recommended approach if you installed the C# package via the Package Manager registry. + +**Important:** Ensure you install a Python package version that matches your Unity package version. Check the [release history](https://github.com/Unity-Technologies/ml-agents/releases) to find compatible versions. + +To install, activate your virtual environment and run the following command: + +```shell +python -m pip install mlagents==1.1.0 +``` + +which will install the latest version of ML-Agents Python packages and associated dependencies available on PyPi. If building the wheel for `grpcio` fails, run the following command before installing `mlagents` with pip: + +```shell +conda install "grpcio=1.48.2" -c conda-forge +``` + +When you install the Python package, the dependencies listed in the [setup.py file](https://github.com/Unity-Technologies/ml-agents/blob/release/4.0.0/ml-agents/setup.py) are also installed. These include [PyTorch](Background-PyTorch.md). + + +## Advanced Installation -#### Advanced: Local Installation for Development +### Unity Package: Local Installation for Development You will need to clone the repository if you plan to modify or extend the ML-Agents Toolkit for your purposes, or if you'd like to download our example environments. Some of our tutorials / guides assume you have access to our example environments. -Use the command below to clone the repository +Use the command below to clone the repository: ```sh git clone --branch release_23 https://github.com/Unity-Technologies/ml-agents.git @@ -59,37 +84,11 @@ You can [add the local](https://docs.unity3d.com/Manual/upm-ui-local.html) `com.

Unity Package Manager Window package.json

-If you are going to follow the examples from our documentation, you can open the -`Project` folder in Unity and start tinkering immediately. +If you are going to follow the examples from our documentation, you can open the `Project` folder in Unity and start tinkering immediately. -### Install Python package - -Installing the `mlagents` Python package involves installing other Python packages that `mlagents` depends on. So you may run into installation issues if your machine has older versions of any of those dependencies already installed. Consequently, our supported path for installing `mlagents` is to leverage Python Virtual Environments. Virtual Environments provide a mechanism for isolating the dependencies for each project and are supported on Mac / Windows / Linux. We offer a dedicated [guide on Virtual Environments](Using-Virtual-Environment.md). - -#### Installing `mlagents` from PyPi - -You can install the ML-Agents Python package directly from PyPi. This is the recommended approach if you installed the C# package via the Package Manager registry. +### Python Package: Local Installation for Development -**Important:** Ensure you install a Python package version that matches your Unity package version. Check the [release history](https://github.com/Unity-Technologies/ml-agents/releases) to find compatible versions. - -To install, activate your virtual environment and run the following command: - -```shell -python -m pip install mlagents==1.1.0 -``` - -which will install the latest version of ML-Agents Python packages and associated dependencies available on PyPi. If building the wheel for `grpcio` fails, run the following command before installing `mlagents` with pip: - -```shell -conda install "grpcio=1.48.2" -c conda-forge -``` - -When you install the Python package, the dependencies listed in the [setup.py file](https://github.com/Unity-Technologies/ml-agents/blob/release/4.0.0/ml-agents/setup.py) are also installed. These include [PyTorch](Background-PyTorch.md). - - -#### Advanced: Local Installation for Development - -##### (Windows) Installing PyTorch +#### (Windows) Installing PyTorch On Windows, you'll have to install the PyTorch package separately prior to installing ML-Agents in order to make sure the cuda-enabled version is used, rather than the CPU-only version. Activate your virtual environment and run from the command line: @@ -99,7 +98,7 @@ pip3 install torch~=2.2.1 --index-url https://download.pytorch.org/whl/cu121 Note that on Windows, you may also need Microsoft's Visual C++ Redistributable if you don't have it already. See the [PyTorch installation guide](https://pytorch.org/get-started/locally/) for more installation options and versions. -##### All Platforms +#### All Platforms To install the `mlagents` Python package, activate your virtual environment and run from the command line: @@ -111,8 +110,6 @@ python -m pip install ./ml-agents Note that this will install `mlagents` from the cloned repository, _not_ from the PyPi repository. If you installed this correctly, you should be able to run `mlagents-learn --help`, after which you will see the command line parameters you can use with `mlagents-learn`. - - If you intend to make modifications to `mlagents` or `mlagents_envs`, from the repository's root directory, run: ```sh diff --git a/com.unity.ml-agents/Documentation~/Training-ML-Agents.md b/com.unity.ml-agents/Documentation~/Training-ML-Agents.md index e45df5499e..4842b8a478 100644 --- a/com.unity.ml-agents/Documentation~/Training-ML-Agents.md +++ b/com.unity.ml-agents/Documentation~/Training-ML-Agents.md @@ -357,7 +357,7 @@ Below is a list of the `sampler_type` values supported by the toolkit. - `gaussian` - Gaussian sampler - Samples a single float value from a normal distribution with a given mean and standard deviation. - **parameters** - `mean`, `st_dev` -- `multirange_uniform` - Multirange uniform sampler +- `multirangeuniform` - Multirange uniform sampler - First, samples an interval from a set of intervals in proportion to relative length of the intervals. Then, uniformly samples a single float value from the sampled interval (inclusive). This sampler can take an arbitrary number of intervals in a list in the following format: [[`interval_1_min`, `interval_1_max`], [`interval_2_min`, `interval_2_max`], ...] - **parameters** - `intervals`