Skip to content

Commit d564895

Browse files
kurbecokurbeco
committed
Schola v1.1.1
1 parent ca48420 commit d564895

File tree

17 files changed

+410
-120
lines changed

17 files changed

+410
-120
lines changed

‎Docs/Sphinx/Makefile‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,14 +12,9 @@ BUILDDIR = _build
1212
help:
1313
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
1414

15-
.PHONY: help Makefile all
1615

17-
all:
18-
doxygen ../Doxygen/Doxyfile
19-
breathe-apidoc -o API/Unreal ../Doxygen/xml
20-
rm -r ./API/Unreal/file
21-
rm ./API/Unreal/filelist.rst
22-
@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
16+
17+
.PHONY: help Makefile
2318

2419
# Catch-all target: route all unknown targets to Sphinx using the new
2520
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).

‎Docs/Sphinx/conf.py‎

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
88

99
project = 'Schola'
10-
copyright = '2023-2024, Advanced Micro Devices Inc.'
10+
copyright = "Copyright (c) 2023-2025 Advanced Micro Devices, Inc. All Rights Reserved."
1111
author = 'Advanced Micro Devices'
1212

1313
import sys
@@ -72,6 +72,35 @@
7272
'logo_only': True,
7373
}
7474

75+
PYTHON_VERSION = "Python 3.9 to 3.12 "
76+
UNREAL_VERSION = "Unreal Engine 5.5"
77+
UNREAL_VERSION_EXACT = "5.5.2"
78+
79+
rst_prolog =f"""
80+
.. |py_version| replace:: {PYTHON_VERSION}
81+
.. _`py_version`: https://www.python.org/downloads/release/python-3919/
82+
83+
.. |unreal_version| replace:: ({UNREAL_VERSION_EXACT} is recommended for reproducibility)
84+
85+
.. |unreal_version_win| replace:: {UNREAL_VERSION}
86+
.. _`unreal_version_win`: https://www.unrealengine.com/en-US/download
87+
88+
.. |unreal_version_linux| replace:: {UNREAL_VERSION}
89+
.. _`unreal_version_linux`: https://www.unrealengine.com/en-US/download
90+
91+
92+
.. |ubuntu_version| replace:: Ubuntu 22.04
93+
.. _`ubuntu_version`: https://releases.ubuntu.com/jammy/
94+
.. |ubuntu_version_exact| replace:: (22.04.4 Desktop x86 64-bit is recommended for reproducibility)
95+
96+
.. |windows_11| replace:: Windows 11
97+
.. _`windows_11`: https://www.microsoft.com/en-us/software-download/windows11
98+
99+
.. |windows_10| replace:: Windows 10
100+
.. _`windows_10`: https://www.microsoft.com/en-us/software-download/windows10
101+
102+
.. |vs_version| replace:: (Visual Studio Professional 2022 (64-bit) - LTSC 17.8 is recommended for reproducibility)
103+
"""
75104

76105
# -- Options for todo extension ----------------------------------------------
77106
# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration

‎Docs/Sphinx/examples/example_outlines/pong.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ The Pong environment features two agents playing a collaborative game of pong. T
66
.. csv-table::
77

88
"Num Agents", "2"
9-
"Observation Space", "DictSpace({'Camera_SCS_SceneColorHDR_RTF_RGBA8_R_W16_H16': make_camera_space(16,16,num_channels=1)})"
9+
"Observation Space", "DictSpace({'Camera_SCS_SceneColorHDR_RTF_RGBA8_R_W16_H16': make_camera_space(64,64,num_channels=1)})"
1010
"Action Space", "DictSpace({'Teleport_Y_50,00': DiscreteSpace(3)})"
1111
"Num Vectorized Copies", "2"
1212

‎Docs/Sphinx/guides/doc_fragments/pip_install.rst‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
Make sure pip is updated before installing the schola python package from `Plugins/Schola/Resources/python`.
2+
3+
.. code-block:: bash
4+
5+
python -m pip install --upgrade pip
6+
pip install ./Plugins/Schola/Resources/python[all]
7+
8+
.. note::
9+
10+
Schola installs the cpu version of pytorch by default, to install other versions of pytorch follow the instructions at `Pytorch Get Started <https://pytorch.org/get-started/locally/>`_.
11+
12+
.. note::
13+
14+
To install Pytorch with ROCm on Linux, we recommend following the guide at `Install Pytorch for Radeon GPUs <https://rocm.docs.amd.com/projects/radeon/en/latest/docs/install/native_linux/install-pytorch.html#>`_.

‎Docs/Sphinx/guides/doc_fragments/prerequisites.rst‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
Install Prerequisites
2+
---------------------
3+
4+
.. tabs::
5+
6+
.. group-tab:: Linux
7+
8+
- |ubuntu_version|_. |ubuntu_version_exact|
9+
- |unreal_version_linux|_. |unreal_version|
10+
- |py_version|_
11+
12+
.. note::
13+
While other Integrated Development Environments (IDEs) can be used, `Visual Studio Code <https://code.visualstudio.com/download>`_ is recommended along with the `C/C++ Extension Pack <https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools>`_. Please see the `Unreal Engine documentation <https://dev.epicgames.com/documentation/en-us/unreal-engine/setting-up-visual-studio-code-for-unreal-engine>`_ for more information.
14+
15+
.. group-tab:: Windows
16+
17+
- |windows_11|_ or |windows_10|_
18+
- |unreal_version_win|_. |unreal_version|
19+
- |py_version|_
20+
21+
.. note::
22+
While other Integrated Development Environments (IDEs) can be used, `Visual Studio <https://visualstudio.microsoft.com/vs/>`__ is recommended. |vs_version|
23+
24+
Follow the `Visual Studio setup guide <https://dev.epicgames.com/documentation/en-us/unreal-engine/setting-up-visual-studio-development-environment-for-cplusplus-projects-in-unreal-engine?application_version=5.5>`_ from Epic Games to setup your Visual Studio environment for working with Unreal.

‎Docs/Sphinx/guides/guides_toc.rst‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@ Guides
88
setup_schola
99
setup_examples
1010
running_schola
11+
setting_up_inference
12+
running_from_cli
13+
choosing_an_environment_type
1114
setup_distributed_training
1215
extending_launch
13-
choosing_an_environment_type
16+
tips_and_tricks

‎Docs/Sphinx/guides/running_from_cli.rst‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
Running with a Standalone Environment from CLI
2+
==============================================
3+
4+
Running Schola from the command line interface (CLI) is a powerful way to interact with the system. This guide will walk you through the steps to run Schola from the CLI, including how to set up your environment and execute commands.
5+
6+
7+
Building Your Environment
8+
-------------------------
9+
10+
Before you can run a standalone executable from the Command-line with Schola, you need to build your environment into a standalone executable. This involves packaging your Unreal Engine project which is detailed in the `official unreal engine documentation <https://dev.epicgames.com/documentation/en-us/unreal-engine/packaging-unreal-engine-projects>`_.
11+
12+
Running From CLI
13+
----------------
14+
15+
To launch a standalone environment (i.e. A game built in Development or Shipping mode), you can use the following command:
16+
17+
.. tabs::
18+
.. group-tab:: Stable Baselines 3
19+
.. code-block:: bash
20+
21+
schola-sb3 --launch-unreal --executable-path <PATH_TO_EXECUTABLE>
22+
23+
.. group-tab:: Ray
24+
.. code-block:: bash
25+
26+
schola-rllib --launch-unreal --executable-path <PATH_TO_EXECUTABLE>
27+
28+
The `<PATH_TO_EXECUTABLE>` should be replaced with the path to your packaged Unreal Engine executable.
29+
30+
31+
Headless Mode
32+
~~~~~~~~~~~~~
33+
34+
Schola can be run in headless mode, which is useful for running scripts or automating tasks. To run Schola in headless mode, use the following command:
35+
36+
.. tabs::
37+
.. group-tab:: Stable Baselines 3
38+
.. code-block:: bash
39+
40+
schola-sb3 --launch-unreal --executable-path <PATH_TO_EXECUTABLE> --headless
41+
42+
.. group-tab:: Ray
43+
.. code-block:: bash
44+
45+
schola-rllib --launch-unreal --executable-path <PATH_TO_EXECUTABLE> --headless
46+
47+
This command will start Schola without the graphical user interface (GUI), allowing for accelerated simulation speeds.
48+
49+
.. note::
50+
Any features requiring rendering will not work when running in headless mode (e.g. :cpp:class:`CameraObserver <UCameraObserver>`).
51+
52+
Fixed Simulation Timestep
53+
~~~~~~~~~~~~~~~~~~~~~~~~~
54+
55+
Schola allows you to set a fixed frames per second (FPS) for the simulation. This can be useful for ensuring consistent performance across different runs. To set a fixed FPS, use the following command:
56+
57+
.. tabs::
58+
.. group-tab:: Stable Baselines 3
59+
.. code-block:: bash
60+
61+
schola-sb3 --launch-unreal --executable-path <PATH_TO_EXECUTABLE> --fps <FPS>
62+
63+
.. group-tab:: Ray
64+
.. code-block:: bash
65+
66+
schola-rllib --launch-unreal --executable-path <PATH_TO_EXECUTABLE> --fps <FPS>
67+
68+
Replace `<FPS>` with the desired frames per second value. For example, to set the FPS to 30, use:
69+
70+
.. tabs::
71+
.. group-tab:: Stable Baselines 3
72+
.. code-block:: bash
73+
74+
schola-sb3 --launch-unreal --executable-path <PATH_TO_EXECUTABLE> --fps 30
75+
76+
.. group-tab:: Ray
77+
.. code-block:: bash
78+
79+
schola-rllib --launch-unreal --executable-path <PATH_TO_EXECUTABLE> --fps 30
80+
81+
.. note::
82+
The FPS determines the delta used when calculating updates in Unreal Engine, however the number of timesteps simulated per second is independant of this setting. For example if `--fps=100` and Unreal simulates your environment at 1000fps then for every second in the real world, 10 seconds in the environment will be simulated.
83+
84+
Controlling The Map
85+
~~~~~~~~~~~~~~~~~~~
86+
87+
Schola allows you to specify the map to load when launching the environment. To do this, use the `--map` argument followed by the path to the map. For example:
88+
89+
.. tabs::
90+
.. group-tab:: Stable Baselines 3
91+
.. code-block:: bash
92+
93+
schola-sb3 --launch-unreal --executable-path <PATH_TO_EXECUTABLE> --map <MAP_NAME>
94+
95+
.. group-tab:: Ray
96+
.. code-block:: bash
97+
98+
schola-rllib --launch-unreal --executable-path <PATH_TO_EXECUTABLE> --map <MAP_NAME>
99+
100+
The map should be specified as a relative path from the `Content` folder, with content replaced with `Game` For exammple `/Content/LevelOne/Map` would be specified as `Game/LevelOne/Map`.
101+
102+
.. note::
103+
The map must be a valid Unreal Engine map file. If the map is not found or isn't specified, Schola will default to the main map specified in the project settings.
104+
105+
.. note::
106+
The map parameter will not work with Shipping builds by default, you need to take additional steps to allow the map to be loaded based on a command line flag.
107+
108+
109+
Additional Settings
110+
~~~~~~~~~~~~~~~~~~~
111+
112+
For details on settings specific to Stable Baselines 3 and RLLib see, :doc:`/scripts/schola-rllib` and :doc:`/scripts/schola-sb3` respectively.

‎Docs/Sphinx/guides/setting_up_inference.rst‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
Setting Up Inference
2+
====================
3+
4+
This guide will explain how to use your trained RL agents in inference mode (i.e. without connecting to Python).
5+
6+
7+
.. note::
8+
9+
This guide assumes you have already done a training run using Schola and have either a saved checkpoint have already exported the model to Onnx.
10+
11+
12+
Convert a Checkpoint to Onnx
13+
----------------------------
14+
15+
If you did not export to onnx during training you will need to convert a checkpoint to Onnx, you can use the following scripts to create an Onnx model from your checkpoint:
16+
17+
.. tabs::
18+
19+
.. group-tab:: Stable Baselines 3
20+
.. code-block:: bash
21+
22+
python -m ./Resources/python/scripts/sb3/sb3-to-onnx.py --model-path <CHECKPOINT_PATH> --output-path <ONNX_PATH>
23+
24+
.. group-tab:: Ray
25+
.. code-block:: bash
26+
27+
python -m ./Resources/python/scripts/sb3/rllib-to-onnx.py --policy-checkpoint-path <CHECKPOINT_PATH> --output-path <ONNX_PATH>
28+
29+
These commands will create an Onnx model in a standardized format compatible with Schola that can be used in the next section.
30+
31+
Load an Onnx Model into Unreal Engine
32+
-------------------------------------
33+
34+
Once you have your Onnx model you can import it into Unreal Engine by dragging and dropping the `.onnx` file into the content browser. This will create a new Onnx model data asset in your project.
35+
36+
37+
Creating an Inference Agent
38+
---------------------------
39+
40+
In Schola an inference agent is any object implementing the :cpp:class:`Agent Interface <IInferenceAgent>`. However, we also provide three default implementations to help get the user started :cpp:class:`InferenceComponent <UInferenceComponent>`, :cpp:class:`InferencePawn <AInferencePawn>`, and :cpp:class:`InferenceController <AInferenceController>`. Follow the instructions below to prepare an actor or pawn to be controlled by your trained policy.
41+
42+
.. tabs::
43+
44+
.. group-tab:: Inference Component
45+
46+
To use the Inference Component, add a :cpp:class:`UInferenceComponent` to any actor you want to control with your trained policy.
47+
48+
.. group-tab:: Inference Pawn
49+
50+
To use the Inference Pawn, create a new Pawn inheriting from :cpp:class:`AInferencePawn`. This will create a pawn that can be controlled by your trained policy.
51+
52+
.. group-tab:: Inference Controller
53+
54+
To use the Inference Controller, create a child of :cpp:class:`AInferenceController` and set the controller of the pawn you want to control to your new class.
55+
56+
57+
Once you've created your Inference Agent, go to the `Reinforcement Learning` tab of the details panel and set the Onnx model Property under Policy to the Data Asset created when you imported your onnx model into unreal.

‎Docs/Sphinx/guides/setup_distributed_training.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Before we begin, ensure that you have the following prerequisites installed on y
1212

1313
.. group-tab:: Linux
1414

15-
- `Ubuntu 22.04 <https://releases.ubuntu.com/jammy/>`_ (22.04.4 Desktop x86 64-bit is recommended for reproducibility)
15+
- |ubuntu_version|_ |ubuntu_version_exact|
1616
- `Docker <https://docs.docker.com/engine/install/ubuntu/>`_ (Ensure Docker is installed and running)
1717
- `MicroK8s <https://microk8s.io/docs/>`_ (A lightweight Kubernetes distribution)
1818
- `Ray <https://docs.ray.io/en/latest/installation.html>`_ (A framework for building and running distributed applications)

‎Docs/Sphinx/guides/setup_examples.rst‎

Lines changed: 17 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -4,65 +4,40 @@ Getting Started With Schola Examples
44
This guide will walk you through setting up the Schola Experiments Project to try out some premade reinforcement learning examples with Schola.
55

66

7-
Install Prerequisites
8-
---------------------
9-
10-
.. tabs::
11-
12-
.. group-tab:: Linux
13-
14-
- `Ubuntu 22.04 <https://releases.ubuntu.com/jammy/>`_ (22.04.4 Desktop x86 64-bit is recommended for reproducibility)
15-
- `Unreal Engine 5.5 <https://www.unrealengine.com/en-US/linux>`__ (5.5.2 is recommended for reproducibility)
16-
- `Python 3.9 or newer <https://www.python.org/downloads/release/python-3919/>`_
17-
18-
.. note::
19-
While other Integrated Development Environments (IDEs) can be used, `Visual Studio Code <https://code.visualstudio.com/download>`_ is recommended along with the `C/C++ Extension Pack <https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools>`_. Please see the `Unreal Engine documentation <https://dev.epicgames.com/documentation/en-us/unreal-engine/setting-up-visual-studio-code-for-unreal-engine>`_ for more information.
20-
21-
.. group-tab:: Windows
22-
23-
- `Windows 11 <https://www.microsoft.com/en-us/software-download/windows11>`_ or `Windows 10 <https://www.microsoft.com/en-us/software-download/windows10>`_
24-
- `Unreal Engine 5.5 <https://www.unrealengine.com/en-US/download>`__ (5.5.2 is recommended for reproducibility)
25-
- `Python 3.9 or newer <https://www.python.org/downloads/release/python-3919/>`_
26-
27-
.. note::
28-
While other Integrated Development Environments (IDEs) can be used, `Visual Studio <https://visualstudio.microsoft.com/vs/>`__ is recommended. (Visual Studio Professional 2022 (64-bit) - LTSC 17.8 is recommended for reproducibility)
29-
30-
Follow the `Visual Studio setup guide <https://dev.epicgames.com/documentation/en-us/unreal-engine/setting-up-visual-studio-development-environment-for-cplusplus-projects-in-unreal-engine?application_version=5.5>`_ from Epic Games to setup your Visual Studio environment for working with Unreal.
7+
.. include:: ./doc_fragments/prerequisites.rst
318

329

3310
Install Schola Examples
3411
-----------------------
3512

3613
1. Get the `ScholaExamples` project, either by downloading the source, or via git.
3714

38-
.. tabs::
15+
.. tabs::
3916

40-
.. tab:: Manual Download
41-
42-
1. Download the zipped source code from the `Schola Examples Repository <https://github.com/GPUOpen-LibrariesAndSDKs/ScholaExamples>`__
43-
2. Unzip the project.
17+
.. tab:: Manual Download
18+
19+
1. Download the zipped source code from the `Schola Examples Repository <https://github.com/GPUOpen-LibrariesAndSDKs/ScholaExamples>`__
20+
2. Unzip the project.
4421

45-
.. tab:: Clone Repository
22+
.. tab:: Clone Repository
4623

47-
.. code-block:: bash
24+
.. code-block:: bash
4825
49-
git clone --recurse-submodules https://github.com/GPUOpen-LibrariesAndSDKs/ScholaExamples.git
26+
git clone --recurse-submodules https://github.com/GPUOpen-LibrariesAndSDKs/ScholaExamples.git
5027
51-
.. note::
52-
If you experience an error installing the repository with git due to a large file sizes, run the following command to increase the git buffer size:
28+
.. note::
29+
30+
If you experience an error installing the repository with git due to a large file sizes, run the following command to increase the git buffer size:
5331

54-
.. code-block:: bash
32+
.. code-block:: bash
5533
56-
git config -–global http.postBuffer 524288000
57-
58-
2. Install the schola python package from `./Plugins/Schola/Resources/python`.
59-
60-
.. code-block:: bash
34+
git config -–global http.postBuffer 524288000
6135
62-
pip install ./Plugins/Schola/Resources/python[all]
36+
2.
37+
.. include:: ./doc_fragments/pip_install.rst
6338

6439
3. Launch the Project.
6540

66-
.. seealso::
41+
.. note::
6742

6843
For setting up your project files to run ScholaExample, please refer to the guide on `Project Files for IDEs <https://dev.epicgames.com/documentation/en-us/unreal-engine/how-to-generate-unreal-engine-project-files-for-your-ide>`_ from Epic Games.

0 commit comments

Comments
 (0)