From 5f2af068188e323a254c4015690e9a6cac781cdc Mon Sep 17 00:00:00 2001
From: u214892 <u214892@sbb.ch>
Date: Wed, 18 Sep 2019 20:09:10 +0200
Subject: [PATCH] #174 #33 #149 cleanup sphinx
---
docs/changelog_index.rst | 8 +++
docs/conf.py | 4 +-
docs/gettingstarted.rst | 15 ++---
docs/index.rst | 6 +-
...ions.rst => intro_observation_actions.rst} | 0
docs/intro_observationbuilder.rst | 22 +++----
docs/localevaluation.rst | 19 +++---
docs/specifications/rendering.md | 6 +-
docs/specifications/specifications.md | 5 +-
docs/specifications_index.rst | 12 ++++
flatland/core/env.py | 5 +-
flatland/core/env_observation_builder.py | 7 ++-
flatland/core/env_prediction_builder.py | 4 +-
flatland/core/grid/grid_utils.py | 35 ++++++-----
flatland/core/grid/rail_env_grid.py | 2 -
flatland/core/transition_map.py | 10 ++--
flatland/envs/observations.py | 60 ++++++++++++-------
flatland/envs/rail_generators.py | 12 ++--
flatland/envs/schedule_generators.py | 13 ++--
make_docs.py | 6 +-
20 files changed, 143 insertions(+), 108 deletions(-)
create mode 100644 docs/changelog_index.rst
rename docs/{observation_actions.rst => intro_observation_actions.rst} (100%)
create mode 100644 docs/specifications_index.rst
diff --git a/docs/changelog_index.rst b/docs/changelog_index.rst
new file mode 100644
index 00000000..081c500f
--- /dev/null
+++ b/docs/changelog_index.rst
@@ -0,0 +1,8 @@
+Changes
+=======
+
+.. toctree::
+ :maxdepth: 2
+
+ changelog.md
+ flatland_2.0.md
diff --git a/docs/conf.py b/docs/conf.py
index 9cfc10f9..66f5183f 100755
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -48,7 +48,6 @@ source_suffix = {
'.md': 'markdown',
}
-
# The master toctree document.
master_doc = 'index'
@@ -159,3 +158,6 @@ texinfo_documents = [
'One line description of project.',
'Miscellaneous'),
]
+
+# https://stackoverflow.com/questions/12206334/sphinx-autosummary-toctree-contains-reference-to-nonexisting-document-warnings
+numpydoc_show_class_members = False
diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst
index 0cfa43bb..8bde9adf 100644
--- a/docs/gettingstarted.rst
+++ b/docs/gettingstarted.rst
@@ -1,9 +1,9 @@
-=====
+===============
Getting Started
-=====
+===============
Overview
---------------
+--------
Following are three short tutorials to help new users get acquainted with how
to create RailEnvs, how to train simple DQN agents on them, and how to customize
@@ -17,7 +17,7 @@ To use flatland in a project:
Part 1 : Basic Usage
---------------
+--------------------
The basic usage of RailEnv environments consists in creating a RailEnv object
endowed with a rail generator, that generates new rail networks on each reset,
@@ -120,7 +120,7 @@ The complete code for this part of the Getting Started guide can be found in
Part 2 : Training a Simple an Agent on Flatland
---------------
+-----------------------------------------------
This is a brief tutorial on how to train an agent on Flatland.
Here we use a simple random agent to illustrate the process on how to interact with the environment.
The corresponding code can be found in examples/training_example.py and in the baselines repository
@@ -153,7 +153,7 @@ The difficulty of a railway network depends on the dimensions (`width` x `height
By varying the number of start and goal connections (nr_start_goal) and the number of extra railway elements added (nr_extra)
the number of alternative paths of each agents can be modified. The more possible paths an agent has to reach its target the easier the task becomes.
Here we don't specify any observation builder but rather use the standard tree observation. If you would like to use a custom obervation please follow
- the instructions in the next tutorial.
+the instructions in the next tutorial.
Feel free to vary these parameters to see how your own agent holds up on different setting. The evalutation set of railway configurations will
cover the whole spectrum from easy to complex tasks.
@@ -188,7 +188,7 @@ The environment returns an array of new observations, reward dictionary for all
This information can be used to update the policy of your agent and if done['__all__'] == True the episode terminates.
Part 3 : Customizing Observations and Level Generators
---------------
+------------------------------------------------------
Example code for generating custom observations given a RailEnv and to generate
random rail maps are available in examples/custom_observation_example.py and
@@ -257,6 +257,7 @@ random (but consistent) agents along with their targets and initial directions,
given a rail map (GridTransitionMap object) and the desired number of agents:
.. code-block:: python
+
agents_position, agents_direction, agents_target = get_rnd_agents_pos_tgt_dir_on_rail(
rail_map,
num_agents)
diff --git a/docs/index.rst b/docs/index.rst
index f644f73e..ba35554a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,13 +10,13 @@ Welcome to flatland's documentation!
about_flatland
gettingstarted
intro_observationbuilder
- specifications/specifications.md
+ intro_observation_actions
+ specifications_index
modules
FAQ
localevaluation
contributing
- changelog.md
- flatland_2.0.md
+ changelog_index
authors
diff --git a/docs/observation_actions.rst b/docs/intro_observation_actions.rst
similarity index 100%
rename from docs/observation_actions.rst
rename to docs/intro_observation_actions.rst
diff --git a/docs/intro_observationbuilder.rst b/docs/intro_observationbuilder.rst
index 4386f9e0..50d65fd4 100644
--- a/docs/intro_observationbuilder.rst
+++ b/docs/intro_observationbuilder.rst
@@ -1,9 +1,9 @@
-=====
+==============================================================
Getting Started with custom observations and custom predictors
-=====
+==============================================================
Overview
---------------
+--------
One of the main objectives of the Flatland-Challenge_ is to find a suitable observation (relevant features for the problem at hand) to solve the task. Therefore **Flatland** was built with as much flexibility as possible when it comes to building your custom observations: observations in Flatland environments are fully customizable.
Whenever an environment needs to compute new observations for each agent, it queries an object derived from the :code:`ObservationBuilder` base class, which takes the current state of the environment and returns the desired observation.
@@ -12,7 +12,7 @@ Whenever an environment needs to compute new observations for each agent, it que
.. _Flatland-Challenge: https://www.aicrowd.com/challenges/flatland-challenge
Example 1 : Simple (but useless) observation
---------------------------------------------------------
+--------------------------------------------
In this first example we implement all the functions necessary for the observation builder to be valid and work with **Flatland**.
Custom observation builder objects need to derive from the `flatland.core.env_observation_builder.ObservationBuilder`_
base class and must implement two methods, :code:`reset(self)` and :code:`get(self, handle)`.
@@ -300,9 +300,9 @@ When building your custom observation builder, you might want to aggregate and d
Transitions maps
~~~~~~~~~~~~~~~~
-The transition maps build the base for all movement in the environment. They contain all the information about allowed transitions for the agent at any given position. Because railway movement is limited to the railway tracks, these are important features for any controller that want to interact with the environment. All functionality and features of a transition map can be found here_
+The transition maps build the base for all movement in the environment. They contain all the information about allowed transitions for the agent at any given position. Because railway movement is limited to the railway tracks, these are important features for any controller that want to interact with the environment. All functionality and features of a transition map can be found here_.
-.. _here:https://gitlab.aicrowd.com/flatland/flatland/blob/master/flatland/core/transition_map.py
+.. _here: https://gitlab.aicrowd.com/flatland/flatland/blob/master/flatland/core/transition_map.py
**Get Transitions for cell**
@@ -312,7 +312,7 @@ To access the possible transitions at any given cell there are different possibi
2. When more detailed information about the cell in general is necessary you can also get the full transitions of a cell by calling :code:`transition_int = env.rail.get_full_transitions(*position)`. This will return an :code:`int16` for the cell representing the allowed transitions. To understand the transitions returned it is best to represent it as a binary number :code:`bin(transition_int)`, where the bits have to following meaning: :code:`NN NE NS NW EN EE ES EW SN SE SS SW WN WE WS WW`. For example the binary code :code:`1000 0000 0010 0000`, represents a straigt where an agent facing north can transition north and an agent facing south can transition south and no other transitions are possible. To get a better feeling what the binary representations of the elements look like go to this Link_
-.. _Link:https://gitlab.aicrowd.com/flatland/flatland/blob/master/flatland/core/grid/rail_env_grid.py#L29
+.. _Link: https://gitlab.aicrowd.com/flatland/flatland/blob/master/flatland/core/grid/rail_env_grid.py#L29
These two objects can be used for example to detect switches that are usable by other agents but not the observing agent itself. This can be an important feature when actions have to be taken in order to avoid conflicts.
@@ -350,9 +350,11 @@ All the agent in the initiated environment can be found in the :code:`env.agents
Beyond the basic agent information we can also access more details about the agents type by looking at speed data:
- Agent max speed :code:`agent.speed_data["speed"]` wich defines the traveling speed when the agent is moving.
-- Agent position fraction :code:``agent.speed_data["position_fraction"]` which is a number between 0 and 1 and indicates when the move to the next cell will occur. Each speed of an agent is 1 or a smaller fraction. At each :code:`env.step()` the agent moves at its fractional speed forwards and only changes to the next cell when the cumulated fractions are :code:`agent.speed_data["position_fraction"] >= 1.`
-- Agent can move at different speed which can be set up by modifying the agent.speed_data within the schedule_generator. For example refer this Link_
-.. _Link:https://gitlab.aicrowd.com/flatland/flatland/blob/master/flatland/envs/schedule_generators.py#L59
+- Agent position fraction :code:`agent.speed_data["position_fraction"]` which is a number between 0 and 1 and indicates when the move to the next cell will occur. Each speed of an agent is 1 or a smaller fraction. At each :code:`env.step()` the agent moves at its fractional speed forwards and only changes to the next cell when the cumulated fractions are :code:`agent.speed_data["position_fraction"] >= 1.`
+- Agent can move at different speed which can be set up by modifying the agent.speed_data within the schedule_generator. For example refer this _Link_Schedule_Generators.
+
+.. _Link_Schedule_Generators: https://gitlab.aicrowd.com/flatland/flatland/blob/master/flatland/envs/schedule_generators.py#L59
+
**Agent malfunction information**
Similar to the speed data you can also access individual data about the malfunctions of an agent. All data is available through :code:`agent.malfunction_data` with:
diff --git a/docs/localevaluation.rst b/docs/localevaluation.rst
index abfab39a..10f9001b 100644
--- a/docs/localevaluation.rst
+++ b/docs/localevaluation.rst
@@ -1,22 +1,21 @@
-=====
+================
Local Evaluation
-=====
+================
This document explains you how to locally evaluate your submissions before making
an official submission to the competition.
Requirements
---------------
+------------
* **flatland-rl** : We expect that you have `flatland-rl` installed by following the instructions in :doc:`installation`.
* **redis** : Additionally you will also need to have `redis installed <https://redis.io/topics/quickstart>`_ and **should have it running in the background.**
Test Data
---------------
+---------
-* **test env data** : You can `download and untar the test-env-data <https://www.aicrowd.com/challenges/flatland-challenge/dataset_files>`_,
-at a location of your choice, lets say `/path/to/test-env-data/`. After untarring the folder, the folder structure should look something like :
+* **test env data** : You can `download and untar the test-env-data <https://www.aicrowd.com/challenges/flatland-challenge/dataset_files>`, at a location of your choice, lets say `/path/to/test-env-data/`. After untarring the folder, the folder structure should look something like:
.. code-block:: console
@@ -48,11 +47,10 @@ Evaluation Service
flatland-evaluator --tests /path/to/test-env-data/
RemoteClient
-------------------
+------------
+
+* **run client** : Some `sample submission code can be found in the starter-kit <https://github.com/AIcrowd/flatland-challenge-starter-kit/>`_, but before you can run your code locally using `FlatlandRemoteClient`, you will have to set the `AICROWD_TESTS_FOLDER` environment variable to the location where you previous untarred the folder with `the test-env-data`:
-* **run client** : Some `sample submission code can be found in the starter-kit <https://github.com/AIcrowd/flatland-challenge-starter-kit/>`_,
-but before you can run your code locally using `FlatlandRemoteClient`, you will have to set the `AICROWD_TESTS_FOLDER` environment variable to the location where you
-previous untarred the folder with `the test-env-data`:
.. code-block:: console
@@ -64,3 +62,4 @@ previous untarred the folder with `the test-env-data`:
# and then finally run your code
python run.py
+
diff --git a/docs/specifications/rendering.md b/docs/specifications/rendering.md
index 46f53d0e..baba1c06 100644
--- a/docs/specifications/rendering.md
+++ b/docs/specifications/rendering.md
@@ -4,8 +4,8 @@
This doc specifies the software to meet the requirements in the Visualization requirements doc.
## References
-- [Visualization Requirements](Specifications/Visualization)
-- [Core Spec](Specifications/Core)
+- [Visualization Requirements](visualization)
+- [Core Spec](./core)
## Interfaces
### Interface with Environment Component
@@ -72,4 +72,4 @@ To-be-filled
#### Overlay dynamic primitives over the background at each time step.
-No point trying to figure out changes. Need to explicitly draw every primitive anyways (that’s how these renders work).
\ No newline at end of file
+No point trying to figure out changes. Need to explicitly draw every primitive anyways (that’s how these renders work).
diff --git a/docs/specifications/specifications.md b/docs/specifications/specifications.md
index ec680147..7d002594 100644
--- a/docs/specifications/specifications.md
+++ b/docs/specifications/specifications.md
@@ -11,7 +11,7 @@ In a humand-readable language, they provide
## Overview
[Diagram Source](https://confluence.sbb.ch/x/pQfsSw)
-## [Core](core)
+
## Rail Generators and Schedule Generators
@@ -330,6 +330,3 @@ RailEnv.step()
self.get()
...
```
-
-## [Rendering](rendering)
-## [Railway](railway)
diff --git a/docs/specifications_index.rst b/docs/specifications_index.rst
new file mode 100644
index 00000000..ce42dad5
--- /dev/null
+++ b/docs/specifications_index.rst
@@ -0,0 +1,12 @@
+Flatland Specs
+==============
+
+.. toctree::
+ :maxdepth: 2
+
+ specifications/specifications.md
+ specifications/core.md
+ specifications/railway.md
+ specifications/rendering.md
+ specifications/specifications.md
+ specifications/visualization.md
diff --git a/flatland/core/env.py b/flatland/core/env.py
index 3b17b531..2dc983c5 100644
--- a/flatland/core/env.py
+++ b/flatland/core/env.py
@@ -15,6 +15,7 @@ class Environment:
Agents are identified by agent ids (handles).
Examples:
+
>>> obs = env.reset()
>>> print(obs)
{
@@ -40,6 +41,7 @@ class Environment:
"train_0": {}, # info for train_0
"train_1": {}, # info for train_1
}
+
"""
def __init__(self):
@@ -51,7 +53,8 @@ class Environment:
"""
Resets the env and returns observations from agents in the environment.
- Returns:
+ Returns
+ -------
obs : dict
New observations for each agent.
"""
diff --git a/flatland/core/env_observation_builder.py b/flatland/core/env_observation_builder.py
index 65434ce9..ba79e7fc 100644
--- a/flatland/core/env_observation_builder.py
+++ b/flatland/core/env_observation_builder.py
@@ -2,10 +2,11 @@
ObservationBuilder objects are objects that can be passed to environments designed for customizability.
The ObservationBuilder-derived custom classes implement 2 functions, reset() and get() or get(handle).
-+ Reset() is called after each environment reset, to allow for pre-computing relevant data.
++ `reset()` is called after each environment reset, to allow for pre-computing relevant data.
+
++ `get()` is called whenever an observation has to be computed, potentially for each agent independently in case of \
+multi-agent environments.
-+ Get() is called whenever an observation has to be computed, potentially for each agent independently in
-case of multi-agent environments.
"""
import numpy as np
diff --git a/flatland/core/env_prediction_builder.py b/flatland/core/env_prediction_builder.py
index b4a2c287..c1026fe0 100644
--- a/flatland/core/env_prediction_builder.py
+++ b/flatland/core/env_prediction_builder.py
@@ -3,9 +3,9 @@ PredictionBuilder objects are objects that can be passed to environments designe
The PredictionBuilder-derived custom classes implement 2 functions, reset() and get([handle]).
If predictions are not required in every step or not for all agents, then
-+ Reset() is called after each environment reset, to allow for pre-computing relevant data.
++ `reset()` is called after each environment reset, to allow for pre-computing relevant data.
-+ Get() is called whenever an step has to be computed, potentially for each agent independently in
++ `get()` is called whenever an step has to be computed, potentially for each agent independently in \
case of multi-agent environments.
"""
diff --git a/flatland/core/grid/grid_utils.py b/flatland/core/grid/grid_utils.py
index f51d2859..09e664f2 100644
--- a/flatland/core/grid/grid_utils.py
+++ b/flatland/core/grid/grid_utils.py
@@ -1,25 +1,27 @@
import numpy as np
-def position_to_coordinate(depth, positions):
- """Converts coordinates to positions:
- [ (0,0) (0,1) .. (0,w-1)
- (1,0) (1,1) (1,w-1)
- ...
- (d-1,0) (d-1,1) (d-1,w-1)
- ]
+def position_to_coordinate(depth: int, positions):
+ """Converts coordinates to positions::
+
+ [ (0,0) (0,1) .. (0,w-1)
+ (1,0) (1,1) (1,w-1)
+ ...
+ (d-1,0) (d-1,1) (d-1,w-1)
+ ]
-->
- [ 0 d .. (w-1)*d
- 1 d+1
- ...
- d-1 2d-1 w*d-1
- ]
+ [ 0 d .. (w-1)*d
+ 1 d+1
+ ...
+ d-1 2d-1 w*d-1
+ ]
- :param depth:
- :param positions:
- :return:
+ Parameters
+ ----------
+ depth : int
+ positions : List[Tuple[int,int]]
"""
coords = ()
for p in positions:
@@ -29,7 +31,8 @@ def position_to_coordinate(depth, positions):
def coordinate_to_position(depth, coords):
"""
- Converts positions to coordinates:
+ Converts positions to coordinates::
+
[ 0 d .. (w-1)*d
1 d+1
...
diff --git a/flatland/core/grid/rail_env_grid.py b/flatland/core/grid/rail_env_grid.py
index fe85abd7..05cd6977 100644
--- a/flatland/core/grid/rail_env_grid.py
+++ b/flatland/core/grid/rail_env_grid.py
@@ -6,8 +6,6 @@ class RailEnvTransitions(Grid4Transitions):
Special case of `GridTransitions` over a 2D-grid, with a pre-defined set
of transitions mimicking the types of real Swiss rail connections.
- --------------------------------------------------------------------------
-
As no diagonal transitions are allowed in the RailEnv environment, the
possible transitions for RailEnv from a cell to its neighboring ones
are represented over 16 bits.
diff --git a/flatland/core/transition_map.py b/flatland/core/transition_map.py
index ce6ceda6..7c9b9b48 100644
--- a/flatland/core/transition_map.py
+++ b/flatland/core/transition_map.py
@@ -61,7 +61,7 @@ class TransitionMap:
def get_transition(self, cell_id, transition_index):
"""
Return the status of whether an agent in cell `cell_id` can perform a
- movement along transition `transition_index (e.g., the NESW direction
+ movement along transition `transition_index` (e.g., the NESW direction
of movement, for agents on a grid).
Parameters
@@ -205,7 +205,7 @@ class GridTransitionMap(TransitionMap):
def get_transition(self, cell_id, transition_index):
"""
Return the status of whether an agent in cell `cell_id` can perform a
- movement along transition `transition_index (e.g., the NESW direction
+ movement along transition `transition_index` (e.g., the NESW direction
of movement, for agents on a grid).
Parameters
@@ -374,8 +374,7 @@ class GridTransitionMap(TransitionMap):
"""
Check validity of cell at rcPos = tuple(row, column)
Checks that:
- - surrounding cells have inbound transitions for all the
- outbound transitions of this cell.
+ - surrounding cells have inbound transitions for all the outbound transitions of this cell.
These are NOT checked - see transition.is_valid:
- all transitions have the mirror transitions (N->E <=> W->S)
@@ -426,8 +425,7 @@ class GridTransitionMap(TransitionMap):
"""
Check validity of cell at rcPos = tuple(row, column)
Checks that:
- - surrounding cells have inbound transitions for all the
- outbound transitions of this cell.
+ - surrounding cells have inbound transitions for all the outbound transitions of this cell.
These are NOT checked - see transition.is_valid:
- all transitions have the mirror transitions (N->E <=> W->S)
diff --git a/flatland/envs/observations.py b/flatland/envs/observations.py
index 58e56d7e..ab85aed7 100644
--- a/flatland/envs/observations.py
+++ b/flatland/envs/observations.py
@@ -6,7 +6,6 @@ import pprint
import numpy as np
from flatland.core.env_observation_builder import ObservationBuilder
-from flatland.core.grid.grid4 import Grid4TransitionsEnum
from flatland.core.grid.grid4_utils import get_new_position
from flatland.core.grid.grid_utils import coordinate_to_position
@@ -79,10 +78,12 @@ class TreeObsForRailEnv(ObservationBuilder):
The observation vector is composed of 4 sequential parts, corresponding to data from the up to 4 possible
movements in a RailEnv (up to because only a subset of possible transitions are allowed in RailEnv).
The possible movements are sorted relative to the current orientation of the agent, rather than NESW as for
- the transitions. The order is:
+ the transitions. The order is::
+
[data from 'left'] + [data from 'forward'] + [data from 'right'] + [data from 'back']
- Each branch data is organized as:
+ Each branch data is organized as::
+
[root node information] +
[recursive branch data from 'left'] +
[... from 'forward'] +
@@ -91,39 +92,50 @@ class TreeObsForRailEnv(ObservationBuilder):
Each node information is composed of 9 features:
- #1: if own target lies on the explored branch the current distance from the agent in number of cells is stored.
+ #1:
+ if own target lies on the explored branch the current distance from the agent in number of cells is stored.
- #2: if another agents target is detected the distance in number of cells from the agents current location
+ #2:
+ if another agents target is detected the distance in number of cells from the agents current location\
is stored
- #3: if another agent is detected the distance in number of cells from current agent position is stored.
+ #3:
+ if another agent is detected the distance in number of cells from current agent position is stored.
- #4: possible conflict detected
- tot_dist = Other agent predicts to pass along this cell at the same time as the agent, we store the
+ #4:
+ possible conflict detected
+ tot_dist = Other agent predicts to pass along this cell at the same time as the agent, we store the \
distance in number of cells from current agent position
0 = No other agent reserve the same cell at similar time
- #5: if an not usable switch (for agent) is detected we store the distance.
+ #5:
+ if an not usable switch (for agent) is detected we store the distance.
- #6: This feature stores the distance in number of cells to the next branching (current node)
+ #6:
+ This feature stores the distance in number of cells to the next branching (current node)
- #7: minimum distance from node to the agent's target given the direction of the agent if this path is chosen
+ #7:
+ minimum distance from node to the agent's target given the direction of the agent if this path is chosen
- #8: agent in the same direction
- n = number of agents present same direction
+ #8:
+ agent in the same direction
+ n = number of agents present same direction \
(possible future use: number of other agents in the same direction in this branch)
0 = no agent present same direction
- #9: agent in the opposite direction
- n = number of agents present other direction than myself (so conflict)
+ #9:
+ agent in the opposite direction
+ n = number of agents present other direction than myself (so conflict) \
(possible future use: number of other agents in other direction in this branch, ie. number of conflicts)
0 = no agent present other direction than myself
- #10: malfunctioning/blokcing agents
+ #10:
+ malfunctioning/blokcing agents
n = number of time steps the oberved agent remains blocked
- #11: slowest observed speed of an agent in same direction
+ #11:
+ slowest observed speed of an agent in same direction
1 if no agent is observed
min_fractional speed otherwise
@@ -488,10 +500,10 @@ class GlobalObsForRailEnv(ObservationBuilder):
Gives a global observation of the entire rail environment.
The observation is composed of the following elements:
- - transition map array with dimensions (env.height, env.width, 16),
+ - transition map array with dimensions (env.height, env.width, 16),\
assuming 16 bits encoding of transitions.
- - Two 2D arrays (map_height, map_width, 2) containing respectively the position of the given agent
+ - Two 2D arrays (map_height, map_width, 2) containing respectively the position of the given agent\
target and the positions of the other agents targets.
- A 3D array (map_height, map_width, 4) wtih
@@ -545,14 +557,14 @@ class LocalObsForRailEnv(ObservationBuilder):
Gives a local observation of the rail environment around the agent.
The observation is composed of the following elements:
- - transition map array of the local environment around the given agent,
- with dimensions (view_height,2*view_width+1, 16),
+ - transition map array of the local environment around the given agent, \
+ with dimensions (view_height,2*view_width+1, 16), \
assuming 16 bits encoding of transitions.
- - Two 2D arrays (view_height,2*view_width+1, 2) containing respectively,
+ - Two 2D arrays (view_height,2*view_width+1, 2) containing respectively, \
if they are in the agent's vision range, its target position, the positions of the other targets.
- - A 2D array (view_height,2*view_width+1, 4) containing the one hot encoding of directions
+ - A 2D array (view_height,2*view_width+1, 4) containing the one hot encoding of directions \
of the other agents at their position coordinates, if they are in the agent's vision range.
- A 4 elements array with one hot encoding of the direction.
@@ -560,6 +572,8 @@ class LocalObsForRailEnv(ObservationBuilder):
Use the parameters view_width and view_height to define the rectangular view of the agent.
The center parameters moves the agent along the height axis of this rectangle. If it is 0 the agent only has
observation in front of it.
+
+ .. deprecated:: 2.0.0
"""
def __init__(self, view_width, view_height, center):
diff --git a/flatland/envs/rail_generators.py b/flatland/envs/rail_generators.py
index 64ab775a..f2dc5c46 100644
--- a/flatland/envs/rail_generators.py
+++ b/flatland/envs/rail_generators.py
@@ -263,13 +263,13 @@ def random_rail_generator(cell_type_relative_proportion=[1.0] * 11) -> RailGener
"""
Dummy random level generator:
- fill in cells at random in [width-2, height-2]
- - keep filling cells in among the unfilled ones, such that all transitions
- are legit; if no cell can be filled in without violating some
- transitions, pick one among those that can satisfy most transitions
- (1,2,3 or 4), and delete (+mark to be re-filled) the cells that were
+ - keep filling cells in among the unfilled ones, such that all transitions\
+ are legit; if no cell can be filled in without violating some\
+ transitions, pick one among those that can satisfy most transitions\
+ (1,2,3 or 4), and delete (+mark to be re-filled) the cells that were\
incompatible.
- - keep trying for a total number of insertions
- (e.g., (W-2)*(H-2)*MAX_REPETITIONS ); if no solution is found, empty the
+ - keep trying for a total number of insertions\
+ (e.g., (W-2)*(H-2)*MAX_REPETITIONS ); if no solution is found, empty the\
board and try again from scratch.
- finally pad the border of the map with dead-ends to avoid border issues.
diff --git a/flatland/envs/schedule_generators.py b/flatland/envs/schedule_generators.py
index 9ec89182..c008a9db 100644
--- a/flatland/envs/schedule_generators.py
+++ b/flatland/envs/schedule_generators.py
@@ -115,22 +115,19 @@ def sparse_schedule_generator(speed_ratio_map: Mapping[float, float] = None) ->
return generator
-def random_schedule_generator(speed_ratio_map: Mapping[float, float] = None) -> ScheduleGenerator:
+def random_schedule_generator(speed_ratio_map: Optional[Mapping[float, float]] = None) -> ScheduleGenerator:
"""
Given a `rail` GridTransitionMap, return a random placement of agents (initial position, direction and target).
Parameters
----------
- rail : GridTransitionMap
- The railway to place agents on.
- num_agents : int
- The number of agents to generate a speed for
- speed_ratio_map : Mapping[float,float]
- A map of speeds mappint to their ratio of appearance. The ratios must sum up to 1.
+ speed_ratio_map : Optional[Mapping[float, float]]
+ A map of speeds mapping to their ratio of appearance. The ratios must sum up to 1.
+
Returns
-------
Tuple[List[Tuple[int,int]], List[Tuple[int,int]], List[Tuple[int,int]], List[float]]
- initial positions, directions, targets speeds
+ initial positions, directions, targets speeds
"""
def generator(rail: GridTransitionMap, num_agents: int, hints: Any = None) -> ScheduleGeneratorProduct:
diff --git a/make_docs.py b/make_docs.py
index 9a954d6a..0a805e59 100644
--- a/make_docs.py
+++ b/make_docs.py
@@ -29,14 +29,14 @@ for file in glob.glob(r'./*.md'):
print(file)
shutil.copy(file, 'docs/')
-subprocess.call(['sphinx-apidoc', '--force', '-a', '-e', '-o', 'docs/', 'flatland', '-H', '"Flatland Reference"'])
+subprocess.call(['sphinx-apidoc', '--force', '-a', '-e', '-o', 'docs/', 'flatland', '-H', 'Flatland Reference'])
-os.environ["SPHINXPROJ"] = "flatland"
+os.environ["SPHINXPROJ"] = "Flatland"
os.chdir('docs')
subprocess.call(['python', '-msphinx', '-M', 'clean', '.', '_build'])
# TODO fix sphinx warnings instead of suppressing them...
subprocess.call(['python', '-msphinx', '-M', 'html', '.', '_build'])
-#subprocess.call(['python', '-msphinx', '-M', 'html', '.', '_build', '-Q'])
+# subprocess.call(['python', '-msphinx', '-M', 'html', '.', '_build', '-Q'])
# we do not currrently use pydeps, commented out https://gitlab.aicrowd.com/flatland/flatland/issues/149
# subprocess.call(['python', '-mpydeps', '../flatland', '-o', '_build/html/flatland.svg', '--no-config', '--noshow'])
--
GitLab