Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

# Référence de la fonction de DeepRacer récompense AWS
<a name="deepracer-reward-function-reference"></a>

 Vous trouverez ci-dessous la référence technique de la fonction de DeepRacer récompense AWS. 

**Topics**
+ [Paramètres d'entrée de la fonction de DeepRacer récompense AWS](deepracer-reward-function-input.md)
+ [Exemples de fonctions de DeepRacer récompense AWS](deepracer-reward-function-examples.md)

# Paramètres d'entrée de la fonction de DeepRacer récompense AWS
<a name="deepracer-reward-function-input"></a>

La fonction de DeepRacer récompense AWS prend un objet de dictionnaire en entrée. 

```
def reward_function(params) :
    
    reward = ...

    return float(reward)
```

L'objet de dictionnaire `params` contient les paires clé-valeur suivantes :

```
{
    "all_wheels_on_track": Boolean,        # flag to indicate if the agent is on the track
    "x": float,                            # agent's x-coordinate in meters
    "y": float,                            # agent's y-coordinate in meters
    "closest_objects": [int, int],         # zero-based indices of the two closest objects to the agent's current position of (x, y).
    "closest_waypoints": [int, int],       # indices of the two nearest waypoints.
    "distance_from_center": float,         # distance in meters from the track center 
    "is_crashed": Boolean,                 # Boolean flag to indicate whether the agent has crashed.
    "is_left_of_center": Boolean,          # Flag to indicate if the agent is on the left side to the track center or not. 
    "is_offtrack": Boolean,                # Boolean flag to indicate whether the agent has gone off track.
    "is_reversed": Boolean,                # flag to indicate if the agent is driving clockwise (True) or counter clockwise (False).
    "heading": float,                      # agent's yaw in degrees
    "objects_distance": [float, ],         # list of the objects' distances in meters between 0 and track_length in relation to the starting line.
    "objects_heading": [float, ],          # list of the objects' headings in degrees between -180 and 180.
    "objects_left_of_center": [Boolean, ], # list of Boolean flags indicating whether elements' objects are left of the center (True) or not (False).
    "objects_location": [(float, float),], # list of object locations [(x,y), ...].
    "objects_speed": [float, ],            # list of the objects' speeds in meters per second.
    "progress": float,                     # percentage of track completed
    "speed": float,                        # agent's speed in meters per second (m/s)
    "steering_angle": float,               # agent's steering angle in degrees
    "steps": int,                          # number steps completed
    "track_length": float,                 # track length in meters.
    "track_width": float,                  # width of the track
    "waypoints": [(float, float), ]        # list of (x,y) as milestones along the track center

}
```

La référence technique plus détaillée pour les paramètres d'entrée est expliquée ci-après. 

## all\$1wheels\$1on\$1track
<a name="reward-function-input-all_wheels_on_track"></a>

**Type : ** `Boolean`

**Plage : ** `(True:False)`

Indicateur `Boolean` qui spécifie si l'agent est sur la piste ou hors piste. Il est hors piste (`False`) si l'une de ses roues est en dehors des limites de la piste. Il est sur la piste (`True`) si toutes les roues sont à l'intérieur des limites de la piste. L'illustration suivante montre que l'agent est sur la piste. 

![\[\]](http://docs.aws.amazon.com/fr_fr/deepracer/latest/developerguide/images/deepracer-reward-function-input-all_wheels_on_track-true.png)


L'illustration suivante montre que l'agent est hors piste.

![\[\]](http://docs.aws.amazon.com/fr_fr/deepracer/latest/developerguide/images/deepracer-reward-function-input-all_wheels_on_track-false.png)


**Exemple : ** *Fonction de récompense utilisant le paramètre `all_wheels_on_track`*

```
def reward_function(params):
    #############################################################################
    '''
    Example of using all_wheels_on_track and speed
    '''

    # Read input variables
    all_wheels_on_track = params['all_wheels_on_track']
    speed = params['speed']

    # Set the speed threshold based your action space
    SPEED_THRESHOLD = 1.0

    if not all_wheels_on_track:
        # Penalize if the car goes off track
        reward = 1e-3
    elif speed < SPEED_THRESHOLD:
        # Penalize if the car goes too slow
        reward = 0.5
    else:
        # High reward if the car stays on track and goes fast
        reward = 1.0

    return float(reward)
```

## closest\$1waypoints
<a name="reward-function-input-closest_waypoints"></a>

**Type :** `[int, int]`

**Plage** : `[(0:Max-1),(1:Max-1)]`

Index de base zéro des deux éléments `waypoint`s les plus proches de la position actuelle de l'agent `(x, y)`. La distance est mesurée par la distance euclidienne par rapport au centre de l'agent. Le premier élément fait référence au point de route le plus proche à l'arrière de l'agent et le second élément fait référence au point de route le plus proche à l'avant de l'agent. `Max` est la longueur de la liste des points de route. Dans l'illustration illustrée dans [waypoints](#reward-function-input-waypoints), la `closest_waypoints` serait `[16, 17]`. 

**Exemple** : Fonction de récompense utilisant le paramètre `closest_waypoints`.

L'exemple de fonction de récompense suivant illustre l'utilisation de `waypoints`, `closest_waypoints` et `heading` pour calculer les récompenses immédiates.

AWS DeepRacer prend en charge les bibliothèques suivantes : math NumPy SciPy, random et Shapely. Pour en utiliser une, ajoutez une instruction d'importation`import supported library`, au-dessus de la définition de votre fonction,`def function_name(parameters)`.

```
# Place import statement outside of function (supported libraries: math, random, numpy, scipy, and shapely)
# Example imports of available libraries
#
# import math
# import random
# import numpy
# import scipy
# import shapely

import math

def reward_function(params):
    ###############################################################################
    '''
    Example of using waypoints and heading to make the car point in the right direction
    '''

    # Read input variables
    waypoints = params['waypoints']
    closest_waypoints = params['closest_waypoints']
    heading = params['heading']

    # Initialize the reward with typical value
    reward = 1.0

    # Calculate the direction of the center line based on the closest waypoints
    next_point = waypoints[closest_waypoints[1]]
    prev_point = waypoints[closest_waypoints[0]]

    # Calculate the direction in radius, arctan2(dy, dx), the result is (-pi, pi) in radians
    track_direction = math.atan2(next_point[1] - prev_point[1], next_point[0] - prev_point[0])
    # Convert to degree
    track_direction = math.degrees(track_direction)

    # Calculate the difference between the track direction and the heading direction of the car
    direction_diff = abs(track_direction - heading)
    if direction_diff > 180:
        direction_diff = 360 - direction_diff

    # Penalize the reward if the difference is too large
    DIRECTION_THRESHOLD = 10.0
    if direction_diff > DIRECTION_THRESHOLD:
        reward *= 0.5

    return float(reward)
​
```

## closest\$1objects
<a name="reward-function-input-closest_objects"></a>

**Type :** `[int, int]`

**Plage** : `[(0:len(objects_location)-1), (0:len(objects_location)-1)]`

 Index de base zéro des deux objets les plus proches de la position actuelle de l'agent (x, y). Le premier index fait référence à l'objet le plus proche derrière l'agent, et le second index fait référence à l'objet le plus proche devant l'agent. S'il n'y a qu'un seul objet, les deux index sont 0. 

## distance\$1from\$1center
<a name="reward-function-input-distance_from_center"></a>

**Type :** `float`

**Plage** : `0:~track_width/2`

Écart, en mètres, entre le centre de l'agent et le centre de la piste. L'écart maximum pouvant être observé se produit lorsque l'une des roues de l'agent est au-delà d'une limite de la piste et, en fonction de la largeur de la bordure de la piste, peut être légèrement inférieure ou supérieure à la moitié de la valeur de `track_width`.

![\[\]](http://docs.aws.amazon.com/fr_fr/deepracer/latest/developerguide/images/deepracer-reward-function-input-distance_from_center.png)


**Exemple :** *Fonction de récompense utilisant le paramètre `distance_from_center`*

```
def reward_function(params):
    #################################################################################
    '''
    Example of using distance from the center
    '''

    # Read input variable
    track_width = params['track_width']
    distance_from_center = params['distance_from_center']

    # Penalize if the car is too far away from the center
    marker_1 = 0.1 * track_width
    marker_2 = 0.5 * track_width

    if distance_from_center <= marker_1:
        reward = 1.0
    elif distance_from_center <= marker_2:
        reward = 0.5
    else:
        reward = 1e-3  # likely crashed/ close to off track

    return float(reward)
```

## heading
<a name="reward-function-input-heading"></a>

**Type :** `float`

**Plage** : `-180:+180`

Direction, en degrés, de l'agent par rapport à l'axe des X du système de coordonnées.

![\[\]](http://docs.aws.amazon.com/fr_fr/deepracer/latest/developerguide/images/deepracer-reward-function-input-heading.png)


**Exemple :** *Fonction de récompense utilisant le paramètre `heading`*

Pour de plus amples informations, veuillez consulter [`closest_waypoints`](#reward-function-input-closest_waypoints).

## is\$1crashed
<a name="reward-function-input-crashed"></a>

**Type :** `Boolean`

**Plage** : `(True:False)`

Indicateur booléen pour indiquer si l'agent a percuté un autre objet (`True`) ou non (`False`) en tant que statut d'achèvement. 

## is\$1left\$1of\$1center
<a name="reward-function-input-is_left_of_center"></a>

**Type :** `Boolean`

**Plage** : `[True : False]`

Indicateur `Boolean` qui indique si l'agent est sur le côté gauche de la piste (`True`) ou sur le côté droit de la piste (`False`) par rapport au centre de la piste. 

## is\$1offtrack
<a name="reward-function-input-offtrack"></a>

**Type :** `Boolean`

**Plage** : `(True:False)`

Indicateur booléen pour indiquer si l'agent a quitté la piste (True) ou non (False) comme statut d'achèvement. 

## is\$1reversed
<a name="reward-function-input-is_reversed"></a>

**Type :** `Boolean`

**Plage** : `[True:False]`

Indicateur booléen pour indiquer si l'agent roule dans le sens des aiguilles d'une montre (True) ou dans le sens inverse des aiguilles d'une montre (False). 

Il est utilisé lorsque vous activez un changement de direction pour chaque épisode. 

## objects\$1distance
<a name="reward-function-input-objects_distance"></a>

**Type :** `[float, … ]`

**Plage** : `[(0:track_length), … ]`

Liste des distances entre les objets de l'environnement par rapport à la ligne de départ. Le ie élément mesure la distance en mètres entre le ie objet et la ligne de départ le long de la ligne centrale de la piste. 

**Note**  
abs \$1 (var1) - (var2) \$1 = à quelle distance la voiture se trouve d'un objet, QUAND var1 = ["objects\$1distance"] [index] et var2 = params ["progress"] \$1params ["track\$1length"]  
Pour obtenir un index de l'objet le plus proche devant le véhicule et de l'objet le plus proche derrière le véhicule, utilisez le paramètre « closest\$1objects ».

## objects\$1heading
<a name="reward-function-input-objects_heading"></a>

**Type :** `[float, … ]`

**Plage** : `[(-180:180), … ]`

Liste des caps des objets en degrés. Le ie élément mesure le cap du ie objet. Pour les objets immobiles, les caps sont égaux à 0. Pour un véhicule bot, la valeur de l'élément correspondant est l'angle de cap du véhicule.

## objects\$1left\$1of\$1center
<a name="reward-function-input-objects_left_of_center"></a>

**Type :** `[Boolean, … ]`

**Plage** : `[True|False, … ]`

Liste d'indicateurs booléens. La valeur du ie élément i indique si le ie objet se trouve à gauche (True) ou à droite (False) du centre de la piste. 

## objects\$1location
<a name="reward-function-input-objects_location"></a>

**Type :** `[(x,y), … ]`

**Plage** : `[(0:N,0:N), … ]`

Liste de tous les emplacements d'objets, chaque emplacement étant un tuple de ([x, y](#reward-function-input-x_y)). 

La taille de la liste est égale au nombre d'objets sur la piste. Notez que des objets peuvent être les obstacles immobiles et des véhicules en mouvement. 

## objects\$1speed
<a name="reward-function-input-objects_speed"></a>

**Type :** `[float, … ]`

**Plage** : `[(0:12.0), … ]`

Liste de vitesses (mètres par seconde) pour les objets sur la piste. Pour les objets immobiles, les vitesses sont égales à 0. Pour un véhicule robot, la valeur est la vitesse que vous avez définie lors de l'entraînement. 

## progress
<a name="reward-function-input-progress"></a>

**Type :** `float`

**Plage** : `0:100`

Pourcentage de piste parcouru.

**Exemple :** *Fonction de récompense utilisant le paramètre `progress`*

Pour de plus amples informations, veuillez consulter [steps](#reward-function-input-steps).

## speed
<a name="reward-function-input-speed"></a>

**Type :** `float`

**Plage** : `0.0:5.0`

Vitesse observée de l'agent, en mètres par seconde (m/s).

![\[\]](http://docs.aws.amazon.com/fr_fr/deepracer/latest/developerguide/images/deepracer-reward-function-input-speed.png)


**Exemple :** *Fonction de récompense utilisant le paramètre `speed`*

Pour de plus amples informations, veuillez consulter [all\$1wheels\$1on\$1track](#reward-function-input-all_wheels_on_track).

## steering\$1angle
<a name="reward-function-input-steering_angle"></a>

**Type :** `float`

**Plage** : `-30:30`

Angle de direction, en degrés, des roues avant par rapport à l'axe central de l'agent. Le signe moins (-) indique une direction vers la droite et le signe plus (\$1) indique une direction vers la gauche. L'axe central de l'agent n'est pas nécessairement parallèle à la ligne centrale de la piste, comme illustré ci-après.

![\[\]](http://docs.aws.amazon.com/fr_fr/deepracer/latest/developerguide/images/deepracer-reward-function-steering.png)


**Exemple :** *Fonction de récompense utilisant le paramètre `steering_angle`*

```
def reward_function(params):
    '''
    Example of using steering angle
    '''

    # Read input variable
    abs_steering = abs(params['steering_angle']) # We don't care whether it is left or right steering

    # Initialize the reward with typical value
    reward = 1.0

    # Penalize if car steer too much to prevent zigzag
    ABS_STEERING_THRESHOLD = 20.0
    if abs_steering > ABS_STEERING_THRESHOLD:
        reward *= 0.8

    return float(reward)
```

## steps
<a name="reward-function-input-steps"></a>

**Type :** `int`

**Plage** : `0:Nstep`

Nombre d'étapes effectuées. Une étape correspond à une action effectuée par l'agent selon la politique actuelle.

**Exemple :** *Fonction de récompense utilisant le paramètre `steps`*

```
def reward_function(params):
    #############################################################################
    '''
    Example of using steps and progress
    '''

    # Read input variable
    steps = params['steps']
    progress = params['progress']

    # Total num of steps we want the car to finish the lap, it will vary depends on the track length
    TOTAL_NUM_STEPS = 300

    # Initialize the reward with typical value
    reward = 1.0

    # Give additional reward if the car pass every 100 steps faster than expected
    if (steps % 100) == 0 and progress > (steps / TOTAL_NUM_STEPS) * 100 :
        reward += 10.0

    return float(reward)
```

## track\$1length
<a name="reward-function-input-track_len"></a>

**Type :** `float`

**Plage** : `[0:Lmax]`

La longueur de la piste en mètres. `Lmax is track-dependent.`

## track\$1width
<a name="reward-function-input-track_width"></a>

**Type :** `float`

**Plage** : `0:Dtrack`

Largeur de la piste, en mètres.

![\[\]](http://docs.aws.amazon.com/fr_fr/deepracer/latest/developerguide/images/deepracer-reward-function-input-track_width.png)


**Exemple :** *Fonction de récompense utilisant le paramètre `track_width`*

```
def reward_function(params):
    #############################################################################
    '''
    Example of using track width
    '''

    # Read input variable
    track_width = params['track_width']
    distance_from_center = params['distance_from_center']

    # Calculate the distance from each border
    distance_from_border = 0.5 * track_width - distance_from_center

    # Reward higher if the car stays inside the track borders
    if distance_from_border >= 0.05:
        reward = 1.0
    else:
        reward = 1e-3 # Low reward if too close to the border or goes off the track

    return float(reward)
```

## x, y
<a name="reward-function-input-x_y"></a>

**Type :** `float`

**Plage** : `0:N`

Emplacement, en mètres, du centre de l'agent le long des axes X et Y de l'environnement simulé contenant la piste. L'origine se trouve dans l'angle inférieur gauche de l'environnement simulé.

![\[\]](http://docs.aws.amazon.com/fr_fr/deepracer/latest/developerguide/images/deepracer-reward-function-input-x-y.png)


## waypoints
<a name="reward-function-input-waypoints"></a>

**Type** : `list` de `[float, float]`

**Plage** : `[[xw,0,yw,0] … [xw,Max-1, yw,Max-1]]`

Liste ordonnée des jalons `Max` dépendants des pistes le long du centre de la piste. Chaque jalon est décrit par une coordonnée de (xw,i, yw,i). Pour une piste en anneau, le premier et le dernier points de route sont identiques. Pour une piste rectiligne ou autre piste sans anneau, le premier et le dernier points de route sont différents.

![\[\]](http://docs.aws.amazon.com/fr_fr/deepracer/latest/developerguide/images/deepracer-reward-function-input-waypoints.png)


**Exemple :** *Fonction de récompense utilisant le paramètre `waypoints`*

Pour de plus amples informations, veuillez consulter [`closest_waypoints`](#reward-function-input-closest_waypoints).

# Exemples de fonctions de DeepRacer récompense AWS
<a name="deepracer-reward-function-examples"></a>

Vous trouverez ci-dessous quelques exemples de la fonction de DeepRacer récompense AWS.

**Topics**
+ [Exemple 1 : suivre la ligne centrale dans les contre-la-montre](#deepracer-reward-function-example-0)
+ [Exemple 2 : rester à l'intérieur des deux frontières pendant les contre-la-montre](#deepracer-reward-function-example-1)
+ [Exemple 3 : éviter le zig-zag dans les contre-la-montre](#deepracer-reward-function-example-2)
+ [Exemple 4 : restez sur une voie sans percuter des obstacles immobiles ou des véhicules en mouvement](#deepracer-reward-function-example-3)

## Exemple 1 : suivre la ligne centrale dans les contre-la-montre
<a name="deepracer-reward-function-example-0"></a>

 Cet exemple détermine à quelle distance l'agent se trouve de la ligne centrale et donne une récompense plus élevée si celui-ci est plus proche du centre de la piste, en encourageant l'agent à suivre de près la ligne centrale. 

```
def reward_function(params):
    '''
    Example of rewarding the agent to follow center line
    '''
    
    # Read input parameters
    track_width = params['track_width']
    distance_from_center = params['distance_from_center']

    # Calculate 3 markers that are increasingly further away from the center line
    marker_1 = 0.1 * track_width
    marker_2 = 0.25 * track_width
    marker_3 = 0.5 * track_width

    # Give higher reward if the car is closer to center line and vice versa
    if distance_from_center <= marker_1:
        reward = 1
    elif distance_from_center <= marker_2:
        reward = 0.5
    elif distance_from_center <= marker_3:
        reward = 0.1
    else:
        reward = 1e-3  # likely crashed/ close to off track

    return reward
```

## Exemple 2 : rester à l'intérieur des deux frontières pendant les contre-la-montre
<a name="deepracer-reward-function-example-1"></a>

 Cet exemple donne simplement des récompenses élevées si l'agent reste à l'intérieur des frontières, et lui permet de trouver le meilleur chemin pour terminer un tour. Il est facile à programmer et à comprendre, mais sa convergence prend probablement plus de temps. 

```
def reward_function(params):
    '''
    Example of rewarding the agent to stay inside the two borders of the track
    '''
    
    # Read input parameters
    all_wheels_on_track = params['all_wheels_on_track']
    distance_from_center = params['distance_from_center']
    track_width = params['track_width']
    
    # Give a very low reward by default
    reward = 1e-3

    # Give a high reward if no wheels go off the track and 
    # the car is somewhere in between the track borders 
    if all_wheels_on_track and (0.5*track_width - distance_from_center) >= 0.05:
        reward = 1.0

    # Always return a float value
    return reward
```

## Exemple 3 : éviter le zig-zag dans les contre-la-montre
<a name="deepracer-reward-function-example-2"></a>

 Cet exemple incite l'agent à suivre la ligne centrale, mais le pénalise avec une récompense plus faible s'il change trop souvent de direction, ce qui permet d'éviter le comportement de zigzag. L'agent apprend à conduire en douceur dans le simulateur et conserve probablement le même comportement lorsqu'il est déployé sur le véhicule physique. 

```
def reward_function(params):
    '''
    Example of penalize steering, which helps mitigate zig-zag behaviors
    '''
    
    # Read input parameters
    distance_from_center = params['distance_from_center']
    track_width = params['track_width']
    abs_steering = abs(params['steering_angle']) # Only need the absolute steering angle

    # Calculate 3 marks that are farther and father away from the center line
    marker_1 = 0.1 * track_width
    marker_2 = 0.25 * track_width
    marker_3 = 0.5 * track_width

    # Give higher reward if the car is closer to center line and vice versa
    if distance_from_center <= marker_1:
        reward = 1.0
    elif distance_from_center <= marker_2:
        reward = 0.5
    elif distance_from_center <= marker_3:
        reward = 0.1
    else:
        reward = 1e-3  # likely crashed/ close to off track

    # Steering penality threshold, change the number based on your action space setting
    ABS_STEERING_THRESHOLD = 15 

    # Penalize reward if the car is steering too much
    if abs_steering > ABS_STEERING_THRESHOLD:
        reward *= 0.8

    return float(reward)
```

## Exemple 4 : restez sur une voie sans percuter des obstacles immobiles ou des véhicules en mouvement
<a name="deepracer-reward-function-example-3"></a>

 

Cette fonction de récompense récompense l'agent qui reste à l'intérieur des limites de la piste et le pénalise s'il s'approche trop près des objets situés devant lui. L'agent peut passer d'une voie à l'autre pour éviter les accidents. La récompense totale est une somme pondérée de la récompense et de la pénalité. L'exemple donne plus de poids à la pénalité afin d'éviter les accidents. Expérimentez avec différents poids moyens pour vous entraîner en fonction de différents résultats comportementaux.

 

```
import math
def reward_function(params):
    '''
    Example of rewarding the agent to stay inside two borders
    and penalizing getting too close to the objects in front
    '''
    all_wheels_on_track = params['all_wheels_on_track']
    distance_from_center = params['distance_from_center']
    track_width = params['track_width']
    objects_location = params['objects_location']
    agent_x = params['x']
    agent_y = params['y']
    _, next_object_index = params['closest_objects']
    objects_left_of_center = params['objects_left_of_center']
    is_left_of_center = params['is_left_of_center']
    # Initialize reward with a small number but not zero
    # because zero means off-track or crashed
    reward = 1e-3
    # Reward if the agent stays inside the two borders of the track
    if all_wheels_on_track and (0.5 * track_width - distance_from_center) >= 0.05:
        reward_lane = 1.0
    else:
        reward_lane = 1e-3
    # Penalize if the agent is too close to the next object
    reward_avoid = 1.0
    # Distance to the next object
    next_object_loc = objects_location[next_object_index]
    distance_closest_object = math.sqrt((agent_x - next_object_loc[0])**2 + (agent_y - next_object_loc[1])**2)
    # Decide if the agent and the next object is on the same lane
    is_same_lane = objects_left_of_center[next_object_index] == is_left_of_center
    if is_same_lane:
        if 0.5 <= distance_closest_object < 0.8:
            reward_avoid *= 0.5
        elif 0.3 <= distance_closest_object < 0.5:
            reward_avoid *= 0.2
        elif distance_closest_object < 0.3:
            reward_avoid = 1e-3  # Likely crashed
    # Calculate reward by putting different weights on
    # the two aspects above
    reward += 1.0 * reward_lane + 4.0 * reward_avoid
    return reward
```