timor.task.CostFunctions
========================

.. py:module:: timor.task.CostFunctions


Attributes
----------

.. autoapisummary::

   timor.task.CostFunctions.abbreviations
   timor.task.CostFunctions.abbreviations_inverse


Classes
-------

.. autoapisummary::

   timor.task.CostFunctions.ComposedCost
   timor.task.CostFunctions.CostFunctionBase
   timor.task.CostFunctions.CycleTime
   timor.task.CostFunctions.Effort
   timor.task.CostFunctions.GoalsFulfilled
   timor.task.CostFunctions.GoalsFulfilledFraction
   timor.task.CostFunctions.LinkSideMechanicalEnergy
   timor.task.CostFunctions.MechanicalEnergy
   timor.task.CostFunctions.NumJoints
   timor.task.CostFunctions.QDist
   timor.task.CostFunctions.RobotMass


Module Contents
---------------

.. py:class:: ComposedCost(*args, weight = default_weight)


   .. autoapi-inheritance-diagram:: timor.task.CostFunctions.ComposedCost
      :parts: 1
      :private-bases:


   A cost function composed of different atomic cost functions

   A composed cost is a container with multiple cost functions, providing a unified interface.


   .. py:method:: __add__(other)

      The sum of two costs



   .. py:method:: __eq__(other)

      Check if two composed cost functions are the same, i.e., have the same descriptor.



   .. py:method:: __mul__(other)

      Multiply all internal cost functions by the given number.



   .. py:method:: __neg__()

      Negate all internal cost functions.



   .. py:attribute:: __slots__
      :value: ()



   .. py:method:: __str__()

      Turn cost function into string representation.



   .. py:method:: __sub__(other)

      The difference of two costs



   .. py:method:: __truediv__(other)

      Divide all internal cost functions by the given number.



   .. py:method:: _evaluate(solution)

      The evaluation of the composed cost function is the sum of all internal cost functions



   .. py:attribute:: _internal
      :value: []



   .. py:attribute:: default_weight
      :value: 1.0



   .. py:method:: descriptor()

      Creates a string describing this cost function. Uses alphanumeric sorting to ensure deterministic name.



   .. py:method:: empty()
      :classmethod:


      Return an empty cost function



   .. py:method:: evaluate(solution)

      Calculates the cost of the solution for its internally stored task



   .. py:method:: from_descriptor(descriptor)
      :staticmethod:


      Build the cost from a string:

      Takes a description string for a cost function and returns the corresponding instance

      :param descriptor: Abbreviation for the cost function. Format <name> or <name_weight>
      :return: instance of the cost function



   .. py:attribute:: weight
      :value: 1.0



.. py:class:: CostFunctionBase(weight = default_weight)


   .. autoapi-inheritance-diagram:: timor.task.CostFunctions.CostFunctionBase
      :parts: 1
      :private-bases:


   A base class for cost functions that are evaluated on task solutions.

   By default, cost functions return positive values - if they describe something positive (e.g. number of goals
   fulfilled), the weight must be chosen negative.

   create a weighted cost

   The default weight should be chosen in a way that higher cost means worse outcome.
   In case of rewards (e.g. cost proportional to goals achieved), the weight should default to a negative value.

   :param weight: Can be any number, positive or negative.


   .. py:method:: __add__(other)

      The sum of two costs



   .. py:method:: __eq__(other)

      Check if cost functions are the same.



   .. py:method:: __mul__(other)

      Change the cost function's weight by multiplying it by a float



   .. py:method:: __neg__()

      Negate the cost function's weight (e.g. for rewards)



   .. py:attribute:: __slots__
      :value: ()



   .. py:method:: __str__()

      Turn cost function into string representation.



   .. py:method:: __sub__(other)

      The difference of two costs



   .. py:method:: __truediv__(other)

      Change the cost function's weight by dividing it by a float



   .. py:method:: _evaluate(solution)
      :abstractmethod:


      Interface to define class-level evaluate functions



   .. py:attribute:: default_weight
      :value: 1.0



   .. py:method:: descriptor(scale = 1.0)

      Creates a string describing this cost function which can be used for serialization.



   .. py:method:: empty()
      :classmethod:


      Return an empty cost function



   .. py:method:: evaluate(solution)

      Calculates the cost of the solution for its internally stored task



   .. py:method:: from_descriptor(descriptor)
      :staticmethod:


      Build the cost from a string:

      Takes a description string for a cost function and returns the corresponding instance

      :param descriptor: Abbreviation for the cost function. Format <name> or <name_weight>
      :return: instance of the cost function



   .. py:attribute:: weight
      :value: 1.0



.. py:class:: CycleTime(weight = default_weight)


   .. autoapi-inheritance-diagram:: timor.task.CostFunctions.CycleTime
      :parts: 1
      :private-bases:


   Increases with trajectory length needed to solve a task

   create a weighted cost

   The default weight should be chosen in a way that higher cost means worse outcome.
   In case of rewards (e.g. cost proportional to goals achieved), the weight should default to a negative value.

   :param weight: Can be any number, positive or negative.


   .. py:method:: __add__(other)

      The sum of two costs



   .. py:method:: __eq__(other)

      Check if cost functions are the same.



   .. py:method:: __mul__(other)

      Change the cost function's weight by multiplying it by a float



   .. py:method:: __neg__()

      Negate the cost function's weight (e.g. for rewards)



   .. py:attribute:: __slots__
      :value: ()



   .. py:method:: __str__()

      Turn cost function into string representation.



   .. py:method:: __sub__(other)

      The difference of two costs



   .. py:method:: __truediv__(other)

      Change the cost function's weight by dividing it by a float



   .. py:method:: _evaluate(solution)

      The total time needed by the solution



   .. py:attribute:: default_weight
      :value: 1.0



   .. py:method:: descriptor(scale = 1.0)

      Creates a string describing this cost function which can be used for serialization.



   .. py:method:: empty()
      :classmethod:


      Return an empty cost function



   .. py:method:: evaluate(solution)

      Calculates the cost of the solution for its internally stored task



   .. py:method:: from_descriptor(descriptor)
      :staticmethod:


      Build the cost from a string:

      Takes a description string for a cost function and returns the corresponding instance

      :param descriptor: Abbreviation for the cost function. Format <name> or <name_weight>
      :return: instance of the cost function



   .. py:attribute:: weight
      :value: 1.0



.. py:class:: Effort(weight = default_weight)


   .. autoapi-inheritance-diagram:: timor.task.CostFunctions.Effort
      :parts: 1
      :private-bases:


   Increases with the torques used by a solution

   create a weighted cost

   The default weight should be chosen in a way that higher cost means worse outcome.
   In case of rewards (e.g. cost proportional to goals achieved), the weight should default to a negative value.

   :param weight: Can be any number, positive or negative.


   .. py:method:: __add__(other)

      The sum of two costs



   .. py:method:: __eq__(other)

      Check if cost functions are the same.



   .. py:method:: __mul__(other)

      Change the cost function's weight by multiplying it by a float



   .. py:method:: __neg__()

      Negate the cost function's weight (e.g. for rewards)



   .. py:attribute:: __slots__
      :value: ()



   .. py:method:: __str__()

      Turn cost function into string representation.



   .. py:method:: __sub__(other)

      The difference of two costs



   .. py:method:: __truediv__(other)

      Change the cost function's weight by dividing it by a float



   .. py:method:: _evaluate(solution)

      The integral of effort over time in the solution



   .. py:attribute:: default_weight
      :value: 1.0



   .. py:method:: descriptor(scale = 1.0)

      Creates a string describing this cost function which can be used for serialization.



   .. py:method:: empty()
      :classmethod:


      Return an empty cost function



   .. py:method:: evaluate(solution)

      Calculates the cost of the solution for its internally stored task



   .. py:method:: from_descriptor(descriptor)
      :staticmethod:


      Build the cost from a string:

      Takes a description string for a cost function and returns the corresponding instance

      :param descriptor: Abbreviation for the cost function. Format <name> or <name_weight>
      :return: instance of the cost function



   .. py:attribute:: weight
      :value: 1.0



.. py:class:: GoalsFulfilled(weight = default_weight)


   .. autoapi-inheritance-diagram:: timor.task.CostFunctions.GoalsFulfilled
      :parts: 1
      :private-bases:


   Cost of alpha for every goal fulfilled in the task. (negative weight --> reward)

   create a weighted cost

   The default weight should be chosen in a way that higher cost means worse outcome.
   In case of rewards (e.g. cost proportional to goals achieved), the weight should default to a negative value.

   :param weight: Can be any number, positive or negative.


   .. py:method:: __add__(other)

      The sum of two costs



   .. py:method:: __eq__(other)

      Check if cost functions are the same.



   .. py:method:: __mul__(other)

      Change the cost function's weight by multiplying it by a float



   .. py:method:: __neg__()

      Negate the cost function's weight (e.g. for rewards)



   .. py:attribute:: __slots__
      :value: ()



   .. py:method:: __str__()

      Turn cost function into string representation.



   .. py:method:: __sub__(other)

      The difference of two costs



   .. py:method:: __truediv__(other)

      Change the cost function's weight by dividing it by a float



   .. py:method:: _evaluate(solution)

      The number of goals fulfilled



   .. py:attribute:: default_weight
      :value: 1.0



   .. py:method:: descriptor(scale = 1.0)

      Creates a string describing this cost function which can be used for serialization.



   .. py:method:: empty()
      :classmethod:


      Return an empty cost function



   .. py:method:: evaluate(solution)

      Calculates the cost of the solution for its internally stored task



   .. py:method:: from_descriptor(descriptor)
      :staticmethod:


      Build the cost from a string:

      Takes a description string for a cost function and returns the corresponding instance

      :param descriptor: Abbreviation for the cost function. Format <name> or <name_weight>
      :return: instance of the cost function



   .. py:attribute:: weight
      :value: 1.0



.. py:class:: GoalsFulfilledFraction(weight = default_weight)


   .. autoapi-inheritance-diagram:: timor.task.CostFunctions.GoalsFulfilledFraction
      :parts: 1
      :private-bases:


   Cost proportional to the fraction of fulfilled goals.

   create a weighted cost

   The default weight should be chosen in a way that higher cost means worse outcome.
   In case of rewards (e.g. cost proportional to goals achieved), the weight should default to a negative value.

   :param weight: Can be any number, positive or negative.


   .. py:method:: __add__(other)

      The sum of two costs



   .. py:method:: __eq__(other)

      Check if cost functions are the same.



   .. py:method:: __mul__(other)

      Change the cost function's weight by multiplying it by a float



   .. py:method:: __neg__()

      Negate the cost function's weight (e.g. for rewards)



   .. py:attribute:: __slots__
      :value: ()



   .. py:method:: __str__()

      Turn cost function into string representation.



   .. py:method:: __sub__(other)

      The difference of two costs



   .. py:method:: __truediv__(other)

      Change the cost function's weight by dividing it by a float



   .. py:method:: _evaluate(solution)

      The fraction of goals fulfilled



   .. py:attribute:: default_weight
      :value: 1.0



   .. py:method:: descriptor(scale = 1.0)

      Creates a string describing this cost function which can be used for serialization.



   .. py:method:: empty()
      :classmethod:


      Return an empty cost function



   .. py:method:: evaluate(solution)

      Calculates the cost of the solution for its internally stored task



   .. py:method:: from_descriptor(descriptor)
      :staticmethod:


      Build the cost from a string:

      Takes a description string for a cost function and returns the corresponding instance

      :param descriptor: Abbreviation for the cost function. Format <name> or <name_weight>
      :return: instance of the cost function



   .. py:attribute:: weight
      :value: 1.0



.. py:class:: LinkSideMechanicalEnergy(weight = default_weight)


   .. autoapi-inheritance-diagram:: timor.task.CostFunctions.LinkSideMechanicalEnergy
      :parts: 1
      :private-bases:


   Calculate the energy used in the link side movement EXCLUDING joint friction and rotor inertia.

   create a weighted cost

   The default weight should be chosen in a way that higher cost means worse outcome.
   In case of rewards (e.g. cost proportional to goals achieved), the weight should default to a negative value.

   :param weight: Can be any number, positive or negative.


   .. py:method:: __add__(other)

      The sum of two costs



   .. py:method:: __eq__(other)

      Check if cost functions are the same.



   .. py:method:: __mul__(other)

      Change the cost function's weight by multiplying it by a float



   .. py:method:: __neg__()

      Negate the cost function's weight (e.g. for rewards)



   .. py:attribute:: __slots__
      :value: ()



   .. py:method:: __str__()

      Turn cost function into string representation.



   .. py:method:: __sub__(other)

      The difference of two costs



   .. py:method:: __truediv__(other)

      Change the cost function's weight by dividing it by a float



   .. py:method:: _evaluate(solution)

      The integral of mechanical power (excl. joint friction and inertia) over the solution times.



   .. py:attribute:: default_weight
      :value: 1.0



   .. py:method:: descriptor(scale = 1.0)

      Creates a string describing this cost function which can be used for serialization.



   .. py:method:: empty()
      :classmethod:


      Return an empty cost function



   .. py:method:: evaluate(solution)

      Calculates the cost of the solution for its internally stored task



   .. py:method:: from_descriptor(descriptor)
      :staticmethod:


      Build the cost from a string:

      Takes a description string for a cost function and returns the corresponding instance

      :param descriptor: Abbreviation for the cost function. Format <name> or <name_weight>
      :return: instance of the cost function



   .. py:attribute:: weight
      :value: 1.0



.. py:class:: MechanicalEnergy(weight = default_weight)


   .. autoapi-inheritance-diagram:: timor.task.CostFunctions.MechanicalEnergy
      :parts: 1
      :private-bases:


   Calculate the energy provided by the motors to move the robot along the solution trajectory.

   Includes the energy to overcome joint friction, rotor inertia and all link inertias.

   create a weighted cost

   The default weight should be chosen in a way that higher cost means worse outcome.
   In case of rewards (e.g. cost proportional to goals achieved), the weight should default to a negative value.

   :param weight: Can be any number, positive or negative.


   .. py:method:: __add__(other)

      The sum of two costs



   .. py:method:: __eq__(other)

      Check if cost functions are the same.



   .. py:method:: __mul__(other)

      Change the cost function's weight by multiplying it by a float



   .. py:method:: __neg__()

      Negate the cost function's weight (e.g. for rewards)



   .. py:attribute:: __slots__
      :value: ()



   .. py:method:: __str__()

      Turn cost function into string representation.



   .. py:method:: __sub__(other)

      The difference of two costs



   .. py:method:: __truediv__(other)

      Change the cost function's weight by dividing it by a float



   .. py:method:: _evaluate(solution)

      The integral of mechanical power over time in the solution.



   .. py:attribute:: default_weight
      :value: 1.0



   .. py:method:: descriptor(scale = 1.0)

      Creates a string describing this cost function which can be used for serialization.



   .. py:method:: empty()
      :classmethod:


      Return an empty cost function



   .. py:method:: evaluate(solution)

      Calculates the cost of the solution for its internally stored task



   .. py:method:: from_descriptor(descriptor)
      :staticmethod:


      Build the cost from a string:

      Takes a description string for a cost function and returns the corresponding instance

      :param descriptor: Abbreviation for the cost function. Format <name> or <name_weight>
      :return: instance of the cost function



   .. py:attribute:: weight
      :value: 1.0



.. py:class:: NumJoints(weight = default_weight)


   .. autoapi-inheritance-diagram:: timor.task.CostFunctions.NumJoints
      :parts: 1
      :private-bases:


   Punishes a higher number of actuated joints

   create a weighted cost

   The default weight should be chosen in a way that higher cost means worse outcome.
   In case of rewards (e.g. cost proportional to goals achieved), the weight should default to a negative value.

   :param weight: Can be any number, positive or negative.


   .. py:method:: __add__(other)

      The sum of two costs



   .. py:method:: __eq__(other)

      Check if cost functions are the same.



   .. py:method:: __mul__(other)

      Change the cost function's weight by multiplying it by a float



   .. py:method:: __neg__()

      Negate the cost function's weight (e.g. for rewards)



   .. py:attribute:: __slots__
      :value: ()



   .. py:method:: __str__()

      Turn cost function into string representation.



   .. py:method:: __sub__(other)

      The difference of two costs



   .. py:method:: __truediv__(other)

      Change the cost function's weight by dividing it by a float



   .. py:method:: _evaluate(solution)

      The number of actuated joints in the solution robot



   .. py:attribute:: default_weight
      :value: 1.0



   .. py:method:: descriptor(scale = 1.0)

      Creates a string describing this cost function which can be used for serialization.



   .. py:method:: empty()
      :classmethod:


      Return an empty cost function



   .. py:method:: evaluate(solution)

      Calculates the cost of the solution for its internally stored task



   .. py:method:: from_descriptor(descriptor)
      :staticmethod:


      Build the cost from a string:

      Takes a description string for a cost function and returns the corresponding instance

      :param descriptor: Abbreviation for the cost function. Format <name> or <name_weight>
      :return: instance of the cost function



   .. py:attribute:: weight
      :value: 1.0



.. py:class:: QDist(weight = default_weight)


   .. autoapi-inheritance-diagram:: timor.task.CostFunctions.QDist
      :parts: 1
      :private-bases:


   Increases with the joint space distance traversed by the solution

   create a weighted cost

   The default weight should be chosen in a way that higher cost means worse outcome.
   In case of rewards (e.g. cost proportional to goals achieved), the weight should default to a negative value.

   :param weight: Can be any number, positive or negative.


   .. py:method:: __add__(other)

      The sum of two costs



   .. py:method:: __eq__(other)

      Check if cost functions are the same.



   .. py:method:: __mul__(other)

      Change the cost function's weight by multiplying it by a float



   .. py:method:: __neg__()

      Negate the cost function's weight (e.g. for rewards)



   .. py:attribute:: __slots__
      :value: ()



   .. py:method:: __str__()

      Turn cost function into string representation.



   .. py:method:: __sub__(other)

      The difference of two costs



   .. py:method:: __truediv__(other)

      Change the cost function's weight by dividing it by a float



   .. py:method:: _evaluate(solution)

      The integral over time for all joint parameters (mixes up radian and meters!)



   .. py:attribute:: default_weight
      :value: 1.0



   .. py:method:: descriptor(scale = 1.0)

      Creates a string describing this cost function which can be used for serialization.



   .. py:method:: empty()
      :classmethod:


      Return an empty cost function



   .. py:method:: evaluate(solution)

      Calculates the cost of the solution for its internally stored task



   .. py:method:: from_descriptor(descriptor)
      :staticmethod:


      Build the cost from a string:

      Takes a description string for a cost function and returns the corresponding instance

      :param descriptor: Abbreviation for the cost function. Format <name> or <name_weight>
      :return: instance of the cost function



   .. py:attribute:: weight
      :value: 1.0



.. py:class:: RobotMass(weight = default_weight)


   .. autoapi-inheritance-diagram:: timor.task.CostFunctions.RobotMass
      :parts: 1
      :private-bases:


   Punishes higher weight of the robot

   create a weighted cost

   The default weight should be chosen in a way that higher cost means worse outcome.
   In case of rewards (e.g. cost proportional to goals achieved), the weight should default to a negative value.

   :param weight: Can be any number, positive or negative.


   .. py:method:: __add__(other)

      The sum of two costs



   .. py:method:: __eq__(other)

      Check if cost functions are the same.



   .. py:method:: __mul__(other)

      Change the cost function's weight by multiplying it by a float



   .. py:method:: __neg__()

      Negate the cost function's weight (e.g. for rewards)



   .. py:attribute:: __slots__
      :value: ()



   .. py:method:: __str__()

      Turn cost function into string representation.



   .. py:method:: __sub__(other)

      The difference of two costs



   .. py:method:: __truediv__(other)

      Change the cost function's weight by dividing it by a float



   .. py:method:: _evaluate(solution)

      The total mass of the solution robot



   .. py:attribute:: default_weight
      :value: 1.0



   .. py:method:: descriptor(scale = 1.0)

      Creates a string describing this cost function which can be used for serialization.



   .. py:method:: empty()
      :classmethod:


      Return an empty cost function



   .. py:method:: evaluate(solution)

      Calculates the cost of the solution for its internally stored task



   .. py:method:: from_descriptor(descriptor)
      :staticmethod:


      Build the cost from a string:

      Takes a description string for a cost function and returns the corresponding instance

      :param descriptor: Abbreviation for the cost function. Format <name> or <name_weight>
      :return: instance of the cost function



   .. py:attribute:: weight
      :value: 1.0



.. py:data:: abbreviations

.. py:data:: abbreviations_inverse