As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Referência da função de DeepRacer recompensa da AWS
<a name="deepracer-reward-function-reference"></a>

 A seguir está a referência técnica da função de DeepRacer recompensa da AWS. 

**Topics**
+ [Parâmetros de entrada da função de DeepRacer recompensa da AWS](deepracer-reward-function-input.md)
+ [Exemplos de funções de DeepRacer recompensa da AWS](deepracer-reward-function-examples.md)

# Parâmetros de entrada da função de DeepRacer recompensa da AWS
<a name="deepracer-reward-function-input"></a>

A função de DeepRacer recompensa da AWS usa um objeto de dicionário como entrada. 

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

    return float(reward)
```

O objeto de dicionário `params` contém os seguintes pares de chave/valor:

```
{
    "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

}
```

Uma referência técnica mais detalhada dos parâmetros de entrada é a seguinte. 

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

**Tipo: ** `Boolean`

**Intervalo: ** `(True:False)`

Um sinalizador `Boolean` para especificar se o agente está ou não fora da pista. Ele está fora da pista (`False`) se uma de suas rodas estiver fora das bordas da pista. Ele está na pista (`True`) se todas as rodas estiverem dentro das duas bordas da pista. A ilustração a seguir mostra que o agente está na pista. 

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


A ilustração a seguir mostra que o agente está fora da pista.

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


**Exemplo: ** *Uma função de recompensa usando o parâmetro `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>

**Digite**: `[int, int]`

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

Os índices baseados em zero dos dois `waypoint` vizinhos mais próximos da posição atual do atendente de `(x, y)`. A distância é medida pela distância euclidiana do centro do atendente. O primeiro elemento refere-se ao ponto de referência mais próximo atrás do atendente, e o segundo elemento refere-se ao ponto de referência mais próximo na frente do atendente. `Max` é o tamanho da lista de pontos de referência. Na ilustração mostrada em [pontos de referência](#reward-function-input-waypoints), os `closest_waypoints` seriam `[16, 17]`. 

**Example (Exemplo)**: uma função de recompensa usando o parâmetro `closest_waypoints`.

A seguinte função de recompensa de exemplo demonstra como usar `waypoints` e `closest_waypoints` bem como `heading` para calcular recompensas imediatas.

A AWS DeepRacer oferece suporte às seguintes bibliotecas: math NumPy SciPy, random e Shapely. Para usar uma delas, adicione uma declaração de importação, `import supported library`, acima da definição da função, `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>

**Digite**: `[int, int]`

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

 Os índices baseados em zero dos dois objetos mais próximos da posição atual do atendente de (x, y). O primeiro índice refere-se ao objeto mais próximo atrás do veículo, e o segundo índice refere-se ao objeto mais próximo na frente do atendente. Se houver apenas um objeto, os dois índices serão 0. 

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

**Digite**: `float`

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

Deslocamento, em metros, entre o centro do agente e o centro da pista. O deslocamento máximo observável ocorre quando qualquer uma das rodas do atendente está fora de uma borda da pista e, dependendo da largura da borda da pista, pode ser ligeiramente menor ou maior que a metade da `track_width`.

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


**Exemplo: ** *Uma função de recompensa usando o parâmetro `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>

**Digite**: `float`

**Intervalo**: `-180:+180`

A condução da direção, em graus, do agente em relação ao eixo x do sistema de coordenadas.

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


**Exemplo: ** *Uma função de recompensa usando o parâmetro `heading`*

Para obter mais informações, consulte [`closest_waypoints`](#reward-function-input-closest_waypoints).

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

**Digite**: `Boolean`

**Intervalo**: `(True:False)`

Um sinalizador booliano para indicar se o agente bateu em outro objeto (`True`) ou não (`False`), como um status de encerramento. 

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

**Digite**: `Boolean`

**Intervalo**: `[True : False]`

Um sinalizador `Boolean` para indicar se o agente está no lado esquerdo em relação ao centro da pista (`True`) ou no lado direito (`False`). 

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

**Digite**: `Boolean`

**Intervalo**: `(True:False)`

Um sinalizador booliano para indicar se o agente tem o status fora da pista (Verdadeiro) ou não (Falso) como um status de encerramento. 

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

**Digite**: `Boolean`

**Intervalo**: `[True:False]`

Um sinalizador booliano para indicar se o agente está dirigindo no sentido horário (Verdadeiro) ou no sentido anti-horário (Falso). 

Ela é usada quando você habilita a mudança de condução para cada episódio. 

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

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

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

Uma lista das distâncias entre objetos no ambiente em relação à linha de largada. O io elemento mede a distância em metros entre o io objeto e a linha de largada ao longo da linha central da pista. 

**nota**  
abs \$1 (var1) - (var2) \$1 = a proximidade do carro em relação a um objeto, WHEN var1 = ["objects\$1distance"][index] e var2 = params["progress"]\$1params["track\$1length"]  
Para obter um índice do objeto mais próximo na frente do veículo e o objeto mais próximo atrás do veículo, use o parâmetro “closest\$1objects”.

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

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

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

Lista das direções dos objetos em graus. O io elemento mede a direção do io objeto. Para objetos estacionários, ad direções são iguais a 0. Para um veículo bot, o valor do elemento correspondente é o ângulo da direção do veículo.

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

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

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

Lista de sinalizadores boolianos. O primeiro valor do elemento indica se o primeiro objeto está no lado esquerdo (Verdadeiro) ou direito (Falso) do centro da pista. 

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

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

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

Lista de todos os locais de objetos, cada local é uma tupla de ([x, y](#reward-function-input-x_y)). 

O tamanho da lista é igual ao número de objetos na pista. Observe que os objetos podem ser os obstáculos estacionários, veículos bot em movimento. 

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

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

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

Lista de velocidades (metros por segundo) dos objetos na pista. Para objetos estacionários, suas velocidades são 0. Para um veículo bot, o valor é a velocidade definida no treinamento. 

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

**Digite**: `float`

**Intervalo**: `0:100`

Porcentagem da pista concluída.

**Exemplo: ** *Uma função de recompensa usando o parâmetro `progress`*

Para mais informações, consulte [etapas](#reward-function-input-steps).

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

**Digite**: `float`

**Intervalo**: `0.0:5.0`

A velocidade observada do atendente, em metros por segundo (m/s).

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


**Exemplo: ** *Uma função de recompensa usando o parâmetro `speed`*

Para mais informações, consulte [all\$1wheels\$1on\$1track](#reward-function-input-all_wheels_on_track).

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

**Digite**: `float`

**Intervalo**: `-30:30`

Ângulo da direção, em graus, das rodas dianteiras a partir da linha central do atendente. O sinal negativo (-) significa curva para a direita e o sinal positivo (\$1) significa curva para a esquerda. A linha central do agente não é necessariamente paralela à linha central da pista, conforme mostrado na ilustração a seguir.

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


**Exemplo: ** *Uma função de recompensa usando o parâmetro `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>

**Digite**: `int`

**Intervalo**: `0:Nstep`

Número de etapas concluídas. Uma etapa corresponde a uma ação executada pelo agente seguindo a política atual.

**Exemplo: ** *Uma função de recompensa usando o parâmetro `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>

**Digite**: `float`

**Intervalo**: `[0:Lmax]`

O comprimento da pista em metros. `Lmax is track-dependent.`

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

**Digite**: `float`

**Intervalo**: `0:Dtrack`

Largura da pista em metros.

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


**Exemplo:** *Uma função de recompensa usando o parâmetro `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>

**Digite**: `float`

**Intervalo**: `0:N`

Localização, em metros, do centro do agente ao longo dos eixos x e y do ambiente simulado da pista. A origem está no canto inferior esquerdo do ambiente simulado.

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


## pontos de referência
<a name="reward-function-input-waypoints"></a>

**Type (Tipo)**: `list` de `[float, float]`

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

Uma lista ordenada dos marcos `Max` dependentes da pista ao longo do centro da pista. Cada marco é descrito por uma coordenada de (xw,i, yw,i). Para um circuito, o primeiro e o último ponto de referência são os mesmos. Para uma pista reta ou que não seja um circuito, o primeiro e o último ponto de referência são diferentes.

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


**Example (Exemplo)** *Uma função de recompensa usando o parâmetro `waypoints`*

Para obter mais informações, consulte [`closest_waypoints`](#reward-function-input-closest_waypoints).

# Exemplos de funções de DeepRacer recompensa da AWS
<a name="deepracer-reward-function-examples"></a>

Veja a seguir alguns exemplos da função de DeepRacer recompensa da AWS.

**Topics**
+ [Exemplo 1: Seguir a linha central em contrarrelógio](#deepracer-reward-function-example-0)
+ [Exemplo 2: Permanecer dentro das duas margens em contrarrelógio](#deepracer-reward-function-example-1)
+ [Exemplo 3: Impedir zig-zag em contrarrelógio](#deepracer-reward-function-example-2)
+ [Exemplo 4: Permanecer em uma faixa sem colidir com obstáculos imóveis ou veículos em movimento](#deepracer-reward-function-example-3)

## Exemplo 1: Seguir a linha central em contrarrelógio
<a name="deepracer-reward-function-example-0"></a>

 Este exemplo determina a distância entre o agente e a linha central e dará maior recompensa se ele estiver mais perto da pista central, incentivando o agente a seguir de perto a linha central. 

```
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
```

## Exemplo 2: Permanecer dentro das duas margens em contrarrelógio
<a name="deepracer-reward-function-example-1"></a>

 Este exemplo simplesmente dará altas recompensas se o agente permanecer dentro das margens, e deixa o agente descobrir qual é o melhor caminho para terminar uma volta. Isso é fácil de programar e de entender, mas provavelmente leva mais tempo para convergir. 

```
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
```

## Exemplo 3: Impedir zig-zag em contrarrelógio
<a name="deepracer-reward-function-example-2"></a>

 Este exemplo incentiva o agente a seguir a linha central, mas penaliza com menor recompensa se ele se desviar muito, o que ajuda a evitar o comportamento em ziguezague. O agente aprende a dirigir com suavidade no simulador e possivelmente manter o mesmo comportamento quando implantado no veículo físico. 

```
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)
```

## Exemplo 4: Permanecer em uma faixa sem colidir com obstáculos imóveis ou veículos em movimento
<a name="deepracer-reward-function-example-3"></a>

 

Essa função de recompensa premia o agente por permanecer entre as margens da pista e o penaliza por se aproximar muito dos objetos à frente. O agente pode mudar de faixa para faixa para evitar colisões. A recompensa total é uma soma ponderada das recompensas e das penalidades. O exemplo dá mais peso à penalidade para evitar colisões. Experimente com diferentes pesos médios para treinar para diferentes resultados de comportamento.

 

```
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
```