<commit_before>=========================================================
Azrael - For Rocket Scientists Who Cannot Afford a Rocket
=========================================================

The virtual world of the Internet has changed society. Smart innovations in the
non-virtual world, like self driving cars, city wide traffic control systems,
space exploration and more, may do it again. The difference: building and
launching a web service is considerably cheaper than building and launching a
space ship...

Put differently: everyone can contribute to the Internet but only a few
are privy to the resources for a space ship... and *you* are probably not one of
them. Azrael's purpose is to remove this barrier and simulate the (macroscopic)
physics for "stuff" you cannot afford in the real world.

Take the `Rosetta mission
<https://en.wikipedia.org/wiki/Rosetta_%28spacecraft%29>`_ as an example. The
total cost exceeded a Billion dollars and it took years to complete. On the
other hand, to reproduce it in its simplest form for your personal studies you
merely need to simulate the physics of two bodies: an asteroid and a space
probe. The probe has thruster, the asteroid does not. The challenge: write a
controller for the ship to reproduce the original `approach and manoeuvres
<https://en.wikipedia.org/wiki/Rosetta_%28spacecraft%29#Orbit_around_67P>`_.


Technology
==========
Azrael is an API to create bodies and modify their attributes (eg position or
geometry). This API is only accessible via the network. Clients can connect to
it from anywhere and use it to drive the simulation. For instance, they create objects,
control them (like the aforementioned Rosetta probe), render the scene,
progress a Newtonian physics simulation...

Azrael is written in Python yet the network API is language agnostic. The API
accepts Websockets (Java Script in browsers) and ZeroMQ sockets (everything but
Java Script).

To see Azrael in action you may try the demos or watch the `PyCon Australia
2015 <https://youtu.be/JG8-yurFBXM?list=PLs4CJRBY5F1IZYVBLXGX1DRYXHMjUjG8k>`_
presentation.


Not A Game Engine
=================

Azrael does not schedule clients or callbacks - everything happens
asynchronously. It also stores all data in databases and fetching it may incur
unacceptable latency by the standards of a game.

Another point concerns visualisation: Azrael has none. A client may query
object geometries and render them (as seen in the demos) but Azrael itself
would neither know nor care.

That being said, some `example scenarios <https://olitheolix.com/azrael/>`_
appear smooth when served from an AWS C4 instance. This despite the dumb
polling used by the visualisation clients.


Project Status
==============

It is a usable work in progress. The emphasis remains on completing the feature
set to build large simulations. Performance optimisation comes afterwards.

The current API suffices to create objects, define and control boosters,
exert force, upload meshes and more. It also comes with a Newtonian physics
engine (based on `Bullet <http://bulletphysics.org>`_) to simulate elementary
motion. This is already enough for a basic Asteroids simulation.

The project also ships with two simple viewers to render the scene. One uses
PyQT/OpenGL whereas the other runs in the browser.

The `demos/` folder showcases various features of Azrael. Some of them have
dedicated docker-compose files in `demos/docker/` to simplify the setup.


Installation
============

The easiest way to see a demo is with Docker Compose:

.. code-block:: bash

    wget https://github.com/olitheolix/azrael/raw/master/demos/docker/asteroids_autopilot.yml
    docker-compose -f asteroids_autopilot.yml up

Then point your browser (recent Firefox or Chrome) to http://localhost:8080
and fly through the scene with mouse and WASD keys.


From Source (For Developers)
----------------------------

To hack on Azrael you need Linux, Anaconda and Docker (Compose). The
`Dockerfile <_https://github.com/olitheolix/azrael/blob/master/Dockerfile>`_
always constitutes the most up-to-date installation instructions. The following
steps should suffice though:

.. code-block:: bash

   # Get the source code.<commit_msg>Added ReadTheDocs link and demo video.<commit_after>================================================
For Rocket Scientists Who Cannot Afford a Rocket
================================================

The virtual world of the Internet has changed society. Smart innovations in the
non-virtual world, like self driving cars, city wide traffic control systems,
space exploration and more, may do it again. The difference: building and
launching a web service is considerably cheaper than building and launching a
space ship...

Put differently: everyone can contribute to the Internet but only a few
are privy to the resources for a space ship... and *you* are probably not one of
them. Azrael's purpose is to remove this barrier and simulate the (macroscopic)
physics for "stuff" you cannot afford in the real world.

Take the `Rosetta mission
<https://en.wikipedia.org/wiki/Rosetta_%28spacecraft%29>`_ as an example. The
total cost exceeded a Billion dollars and it took years to complete. On the
other hand, to reproduce it in its simplest form for your personal studies you
merely need to simulate the physics of two bodies: an asteroid and a space
probe. The probe has thruster, the asteroid does not. The challenge: write a
controller for the ship to reproduce the original `approach and manoeuvres
<https://en.wikipedia.org/wiki/Rosetta_%28spacecraft%29#Orbit_around_67P>`_.

Technology
==========
Azrael is an API to create bodies and modify their attributes (eg position or
geometry). This API is only accessible via the network. Clients can connect to
it from anywhere and use it to drive the simulation. For instance, they create objects,
control them (like the aforementioned Rosetta probe), render the scene,
progress a Newtonian physics simulation...

Azrael is written in Python yet the network API is language agnostic. The API
accepts Websockets (Java Script in browsers) and ZeroMQ sockets (everything but
Java Script).

To see Azrael in action you may try the demos or watch the `PyCon Australia
2015 <https://youtu.be/JG8-yurFBXM?list=PLs4CJRBY5F1IZYVBLXGX1DRYXHMjUjG8k>`_
presentation.


Demo Video
----------
Here Azrael runs on AWS whereas the rendering and object control runs on my
local computer. Note how the rendering in the browser and standalone Qt program
stay in sync even though they have no knowledge of each other.

.. raw:: html

    <video autoplay="autoplay" loop="loop" width="100%">

      <source src="https://s3-ap-southeast-2.amazonaws.com/olitheolix/azrael/bothviewers.mp4" type="video/mp4" />
      <source src="https://s3-ap-southeast-2.amazonaws.com/olitheolix/azrael/bothviewers.ogv" type="video/ogg" />
      <source src="https://s3-ap-southeast-2.amazonaws.com/olitheolix/azrael/bothviewers.webm" type="video/ogg" />
      Your browser does not support the video tag.
    </video>
    <p>


Not A Game Engine
=================

Azrael does not schedule clients or callbacks - everything happens
asynchronously. It also stores all data in databases and fetching it may incur
unacceptable latency by the standards of a game.

Another point concerns visualisation: Azrael has none. A client may query
object geometries and render them (as seen in the demos) but Azrael itself
would neither know nor care.

That being said, some `example scenarios <https://olitheolix.com/azrael/>`_
appear smooth when served from an AWS C4 instance. This despite the dumb
polling used by the visualisation clients.


Project Status
==============

It is a usable work in progress. The emphasis remains on completing the feature
set to build large simulations. Performance optimisation comes afterwards.

The current API suffices to create objects, define and control boosters,
exert force, upload meshes and more. It also comes with a Newtonian physics
engine (based on `Bullet <http://bulletphysics.org>`_) to simulate elementary
motion. This is already enough for a basic Asteroids simulation.

The project also ships with two simple viewers to render the scene. One uses
PyQT/OpenGL whereas the other runs in the browser.


Demos and Documentation
=======================

The `demos/` folder showcases various features of Azrael. Some of them have
dedicated docker-compose files in `demos/docker/` to simplify the setup.

The API is documented `here <http://azrael.readthedocs.org/en/latest/>`_.


Installation
============

The easiest way to see a demo is with Docker Compose:

.. code-block:: bash

    wget https://github.com/olitheolix/azrael/raw/master/demos/docker/asteroids_autopilot.yml
    docker-compose -f asteroids_autopilot.yml up

Then point your browser (recent Firefox or Chrome) to http://localhost:8080
and fly through the scene with mouse and WASD keys.


From Source (For Developers)
----------------------------

To hack on Azrael you need Linux, Anaconda and Docker (Compose). The
`Dockerfile <_https://github.com/olitheolix/azrael/blob/master/Dockerfile>`_
always constitutes the most up-to-date installation instructions. The following
steps should suffice though:

.. code-block:: bash

   # Get the source code.
{'fraction_non_alphanumeric': 0.0995260663507109, 'fraction_numerical': 0.006570443774235243, 'mean_word_length': 4.477876106194691, 'pattern_counts': {'":': 0, '<': 22, '<?xml version=': 0, '>': 22, 'https://': 15, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2293852', 'n_tokens_mistral': 2586, 'n_tokens_neox': 2379, 'n_words': 1212}