jmadem

## Class MADeMAgArch

- java.lang.Object
- - AgArch
  - - jmadem.MADeMAgArch

-     public class MADeMAgArch
      extends AgArch

  Basic architecture for a Jason agent performing MADeM decisions.
  Author:
    Francisco Grimaldo

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `(package private) class` | `MADeMAgArch.BidTimeout` Handles bid timeout for a specific decision making.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private boolean` | `automaticRemoveOfMademData` Flag indicating whether to remove the data managed by MADeM after the winner determination problem.
    `private java.util.concurrent.ConcurrentMap<Atom,FilterFunctionInt>` | `filterFunctions` Filter functions repository
    `private java.util.logging.Logger` | `logger` Class logger
    `private java.util.concurrent.ConcurrentMap<java.lang.Integer,DecisionData>` | `mademData` Data managed by MADeM for every decision being performed: id_decision, agents involved, allocations, utility functions considered, bids...
    `private Multimodality` | `multimodality` Type of multimodality used in the Winner Determination Problem
    `private java.util.concurrent.ConcurrentMap<Atom,java.lang.Float>` | `personalWeights` Personal weights representing the internal attitude of the agent towards other individuals.
    `private java.util.Random` | `random` Random numbers generator
    `private java.util.concurrent.ScheduledExecutorService` | `timeoutScheduler` Pool of threads to schedule timeouts
    `private int` | `tout` Maximum waiting time for bids (in milliseconds).
    `private java.util.concurrent.ConcurrentMap<Atom,UtilityFunctionInt>` | `utilityFunctions` Utility functions repository
    `private java.util.concurrent.ConcurrentMap<ListTerm,java.util.List<Term>>` | `utilityValues` Storage devoted to hold utility values while they are calculated.
    `private java.util.concurrent.ConcurrentMap<Atom,java.lang.Float>` | `utilityWeights` Utility weights representing the importance given to each point of view in the multi-modal agent decision making.
    `private Cuf` | `welfare` Social welfare considered by the agent

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MADeMAgArch()` Constructor of the MADeMAgArch class

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `addFilterFunction(Atom fFuncName, java.lang.String fFuncClass)` Registers a new filter function in the MADeM agent.
    `boolean` | `addUtilityFunction(Atom uFuncName, java.lang.String uFuncClass)` Registers a new utility function in the MADeM agent.
    `private void` | `bid(ListTerm utilityKey)` Bids over a set of allocations coming from an auctioneer.
    `void` | `catchUtilityValue(ListTerm utilityKey, Term utilityValue)` Catches a utility value coming from an AgentSpeak plan and stores it within the utility values storage.
    `void` | `checkMail()` Filters MADeM messages out of the agent Mailbox.
    `private void` | `computeUtilities(java.lang.String auctioneer, Literal madem_auction)` Computes the utility of a set of allocations coming from an auctioneer according to the specified utility functions.
    `boolean` | `doFilter(Term allocation, ListTerm fFuncs)` Computes if an allocation should be filtered out according to the specified filter functions.
    `java.util.Set<Atom>` | `getFilterFunctionNames()` Gets the names of the filter functions previously registered in the MADeM agent.
    `java.lang.String` | `getMultimodality()` Gets the type of multimodality used in the Winner Determination Problem.
    `float` | `getPersonalWeight(Atom agName)` Gets the personal weight of the MADeM agent towards another agent.
    `java.util.concurrent.ConcurrentMap<Atom,java.lang.Float>` | `getPersonalWeights()` Gets the personal weights of the MADeM agent.
    `int` | `getTimeout()` Gets bid timeout (in milliseconds).
    `private float` | `getUtility(java.lang.String auctioneer, Term allocation, UtilityFunctionInt utilityFunction)` Obtains the utility value given by a specific utility function.
    `java.util.Set<Atom>` | `getUtilityFunctionNames()` Gets the names of the utility functions previously registered in the MADeM agent.
    `float` | `getUtilityWeight(Atom utilityName)` Gets the weight of the MADeM agent for a certain utility function.
    `java.util.concurrent.ConcurrentMap<Atom,java.lang.Float>` | `getUtilityWeights()` Gets the utility weights of the MADeM agent.
    `java.lang.String` | `getWelfare()` Gets the social welfare of the MADeM agent.
    `boolean` | `isAutomaticRemoveOfMademData()` Gets the value of the automatic remove of MADeM data flag.
    `private void` | `processBid(java.lang.String bidder, Literal madem_bid)` Process an external bid related to a certain decision.
    `boolean` | `removeFilterFunction(Atom fFuncName)` Removes a filter function previously registered in the MADeM agent.
    `boolean` | `removeUtilityFunction(Atom uFuncName)` Removes a utility function previously registered in the MADeM agent.
    `void` | `setAutomaticRemoveOfMademData(boolean automaticRemoveOfMademData)` Sets the value of the flag indicating whether to remove the data managed by MADeM after the winner determination problem.
    `void` | `setMultimodality(Multimodality new_multimodality)` Changes the type of multimodality used in the Winner Determination Problem.
    `boolean` | `setPersonalWeight(Atom agName, java.lang.Float new_pw)` Changes the personal weight of the MADeM agent towards another agent.
    `boolean` | `setPersonalWeights(java.util.concurrent.ConcurrentMap<Atom,java.lang.Float> new_pw)` Changes the personal weights of the MADeM agent towards the other agents.
    `boolean` | `setTimeout(int new_tout)` Changes bid timeout to a new positive value.
    `boolean` | `setUtilityWeight(Atom utilityName, java.lang.Float new_uw)` Changes the utility weight of the MADeM agent for a certain utility function.
    `boolean` | `setUtilityWeights(java.util.concurrent.ConcurrentMap<Atom,java.lang.Float> new_uw)` Changes the utility weights of the MADeM agent.
    `void` | `setWelfare(Cuf new_sw)` Changes social welfare of the MADeM agent.
    `int` | `startMADeMDecision(ListTerm ags, ListTerm allocs, ListTerm uFuncs, boolean multipleSolutions, boolean returnWelfare)` Starts a MADeM decision using the internal parameters of the agent.
    `int` | `startMADeMDecision(ListTerm ags, ListTerm allocs, ListTerm uFuncs, java.util.concurrent.ConcurrentMap<Atom,java.lang.Float> pW, java.util.concurrent.ConcurrentMap<Atom,java.lang.Float> uW, Cuf sw, Multimodality m, int tout, boolean multipleSolutions, boolean returnWelfare)` Starts a MADeM decision by specifying all its parameters.
    `private void` | `winnerDeterminationProblem(int id_decision, boolean timeout)` Solves the winner determination problem for a specific decision.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### logger

          private java.util.logging.Logger logger

      Class logger

    - #### random

          private java.util.Random random

      Random numbers generator

    - #### filterFunctions

          private java.util.concurrent.ConcurrentMap<Atom,FilterFunctionInt> filterFunctions

      Filter functions repository

    - #### utilityFunctions

          private java.util.concurrent.ConcurrentMap<Atom,UtilityFunctionInt> utilityFunctions

      Utility functions repository

    - #### utilityWeights

          private java.util.concurrent.ConcurrentMap<Atom,java.lang.Float> utilityWeights

      Utility weights representing the importance given to each point of view in the multi-modal agent decision making.

    - #### personalWeights

          private java.util.concurrent.ConcurrentMap<Atom,java.lang.Float> personalWeights

      Personal weights representing the internal attitude of the agent towards other individuals.

    - #### welfare

          private Cuf welfare

      Social welfare considered by the agent

    - #### multimodality

          private Multimodality multimodality

      Type of multimodality used in the Winner Determination Problem

    - #### tout

          private int tout

      Maximum waiting time for bids (in milliseconds). After timeout, the agent decides according to the bids it has collected and its own preferences.

    - #### timeoutScheduler

          private java.util.concurrent.ScheduledExecutorService timeoutScheduler

      Pool of threads to schedule timeouts

    - #### mademData

          private java.util.concurrent.ConcurrentMap<java.lang.Integer,DecisionData> mademData

      Data managed by MADeM for every decision being performed: id_decision, agents involved, allocations, utility functions considered, bids...

    - #### automaticRemoveOfMademData

          private boolean automaticRemoveOfMademData

      Flag indicating whether to remove the data managed by MADeM after the winner determination problem.

    - #### utilityValues

          private java.util.concurrent.ConcurrentMap<ListTerm,java.util.List<Term>> utilityValues

      Storage devoted to hold utility values while they are calculated. Once all the values are ready, they are sent to the agent in charge of the MADeM decision (i.e. the auctioneer)

  - ### Constructor Detail

    - #### MADeMAgArch

          public MADeMAgArch()

      Constructor of the MADeMAgArch class

  - ### Method Detail

    - #### setAutomaticRemoveOfMademData

          public void setAutomaticRemoveOfMademData(boolean automaticRemoveOfMademData)

      Sets the value of the flag indicating whether to remove the data managed by MADeM after the winner determination problem.
      Parameters:
        `automaticRemoveOfMademData` - `true` if the MADeM data has to be removed after the Winner Determination Problem, `false` otherwise

    - #### isAutomaticRemoveOfMademData

          public boolean isAutomaticRemoveOfMademData()

      Gets the value of the automatic remove of MADeM data flag.
      Returns:
        `true` the agent automatically removes all the data related to a MADeM decision after it has been made, `false` otherwise

    - #### addFilterFunction

          public boolean addFilterFunction(Atom fFuncName,
                                  java.lang.String fFuncClass)

      Registers a new filter function in the MADeM agent.
      Parameters:
        `fFuncName` - name of the filter function to be added
        `fFuncClass` - name of the class implementing the filter function
      Returns:
        `true` if the filter function was correctly added, `false` otherwise

    - #### removeFilterFunction

          public boolean removeFilterFunction(Atom fFuncName)

      Removes a filter function previously registered in the MADeM agent.
      Parameters:
        `fFuncName` - name of the filter function to be removed
      Returns:
        `true` if the filter function was correctly removed, `false` otherwise

    - #### getFilterFunctionNames

          public java.util.Set<Atom> getFilterFunctionNames()

      Gets the names of the filter functions previously registered in the MADeM agent.
      Returns:
        the filter function names in the form of a `Set`

    - #### doFilter

          public boolean doFilter(Term allocation,
                         ListTerm fFuncs)

      Computes if an allocation should be filtered out according to the specified filter functions.
      Parameters:
        `allocation` - allocation being evaluated
        `fFuncs` - names of filter functions being considered
      Returns:
        `true` if the allocation has to be filtered out, `false` otherwise

    - #### addUtilityFunction

          public boolean addUtilityFunction(Atom uFuncName,
                                   java.lang.String uFuncClass)

      Registers a new utility function in the MADeM agent.
      Parameters:
        `uFuncName` - name of the utility function to be added
        `uFuncClass` - name of the class implementing the utility function
      Returns:
        `true` if the utility function was correctly added, `false` otherwise

    - #### removeUtilityFunction

          public boolean removeUtilityFunction(Atom uFuncName)

      Removes a utility function previously registered in the MADeM agent.
      Parameters:
        `uFuncName` - name of the utility function to be removed
      Returns:
        `true` if the utility function was correctly removed, `false` otherwise

    - #### getUtilityFunctionNames

          public java.util.Set<Atom> getUtilityFunctionNames()

      Gets the names of the utility functions previously registered in the MADeM agent.
      Returns:
        the utility function names in the form of a `Set`

    - #### startMADeMDecision

          public int startMADeMDecision(ListTerm ags,
                               ListTerm allocs,
                               ListTerm uFuncs,
                               boolean multipleSolutions,
                               boolean returnWelfare)

      Starts a MADeM decision using the internal parameters of the agent.
      Parameters:
        `ags` - names of the agents involved in the decision
        `allocs` - allocations being considered as solutions for the decision problem
        `uFuncs` - names of the different utility functions to pay attention to
        `multipleSolutions` - ask for all possible winners or just one randomly chosen
        `returnWelfare` - whether to return the social welfare of winner allocations
      Returns:
        the identifier of the MADeM decision or `-1` when any error occurs

    - #### startMADeMDecision

          public int startMADeMDecision(ListTerm ags,
                               ListTerm allocs,
                               ListTerm uFuncs,
                               java.util.concurrent.ConcurrentMap<Atom,java.lang.Float> pW,
                               java.util.concurrent.ConcurrentMap<Atom,java.lang.Float> uW,
                               Cuf sw,
                               Multimodality m,
                               int tout,
                               boolean multipleSolutions,
                               boolean returnWelfare)

      Starts a MADeM decision by specifying all its parameters.
      Parameters:
        `ags` - names of the agents involved in the decision
        `allocs` - allocations being considered as solutions for the decision problem
        `uFuncs` - names of the different utility functions to pay attention to
        `pW` - personal weights to be applied over external preferences
        `uW` - utility weights in the multi-modal decision
        `sw` - type of social welfare being considered
        `m` - type of multimodality used in the Winner Determination Problem
        `tout` - timeout for getting bids (in milliseconds)
        `multipleSolutions` - ask for all possible winners or just one randomly chosen
        `returnWelfare` - whether to return the social welfare of winner allocations
      Returns:
        the identifier of the MADeM decision or `-1` when any error occurs

    - #### checkMail

          public void checkMail()

      Filters MADeM messages out of the agent Mailbox.

    - #### setTimeout

          public boolean setTimeout(int new_tout)

      Changes bid timeout to a new positive value.
      Parameters:
        `new_tout` - new timeout value (in milliseconds)
      Returns:
        `true` if Timeout was correctly changed, `false` otherwise

    - #### getTimeout

          public int getTimeout()

      Gets bid timeout (in milliseconds).
      Returns:
        the bid timeout (in milliseconds) used by the MADeM agent

    - #### setWelfare

          public void setWelfare(Cuf new_sw)

      Changes social welfare of the MADeM agent.
      Parameters:
        `new_sw` - new social welfare

    - #### getWelfare

          public java.lang.String getWelfare()

      Gets the social welfare of the MADeM agent.
      Returns:
        the name of the social welfare

    - #### setMultimodality

          public void setMultimodality(Multimodality new_multimodality)

      Changes the type of multimodality used in the Winner Determination Problem.
      Parameters:
        `new_multimodality` - new type of multimodality

    - #### getMultimodality

          public java.lang.String getMultimodality()

      Gets the type of multimodality used in the Winner Determination Problem.
      Returns:
        the name of the type of multimodality

    - #### setPersonalWeight

          public boolean setPersonalWeight(Atom agName,
                                  java.lang.Float new_pw)

      Changes the personal weight of the MADeM agent towards another agent.
      Parameters:
        `agName` - name of the agent
        `new_pw` - new personal weights
      Returns:
        `true` if the personal weight was correctly changed, `false` otherwise

    - #### getPersonalWeight

          public float getPersonalWeight(Atom agName)

      Gets the personal weight of the MADeM agent towards another agent.
      Parameters:
        `agName` - name of the agent
      Returns:
        the personal weight within [0, 1] or 1 when there is no weight explicitly defined

    - #### setPersonalWeights

          public boolean setPersonalWeights(java.util.concurrent.ConcurrentMap<Atom,java.lang.Float> new_pw)

      Changes the personal weights of the MADeM agent towards the other agents.
      Parameters:
        `new_pw` - new personal weights
      Returns:
        `true` if Personal Weights were correctly changed, `false` otherwise

    - #### getPersonalWeights

          public java.util.concurrent.ConcurrentMap<Atom,java.lang.Float> getPersonalWeights()

      Gets the personal weights of the MADeM agent.
      Returns:
        the personal weights being used by de MADeM agent in the form of a `ConcurrentMap`

    - #### getUtilityWeight

          public float getUtilityWeight(Atom utilityName)

      Gets the weight of the MADeM agent for a certain utility function.
      Parameters:
        `utilityName` - name of the utility function
      Returns:
        the utility weight within [0, 1] or 1 when there is no weight explicitly defined

    - #### setUtilityWeight

          public boolean setUtilityWeight(Atom utilityName,
                                 java.lang.Float new_uw)

      Changes the utility weight of the MADeM agent for a certain utility function.
      Parameters:
        `utilityName` - name of the utility function
        `new_uw` - new utility weights
      Returns:
        `true` if the utility weight was correctly changed, `false` otherwise

    - #### setUtilityWeights

          public boolean setUtilityWeights(java.util.concurrent.ConcurrentMap<Atom,java.lang.Float> new_uw)

      Changes the utility weights of the MADeM agent.
      Parameters:
        `new_uw` - new utility weights
      Returns:
        `true` if Utility Weights were correctly changed, `false` otherwise

    - #### getUtilityWeights

          public java.util.concurrent.ConcurrentMap<Atom,java.lang.Float> getUtilityWeights()

      Gets the utility weights of the MADeM agent.
      Returns:
        the utility weights being used by de MADeM agent in the form of a `ConcurrentMap`

    - #### computeUtilities

          private void computeUtilities(java.lang.String auctioneer,
                              Literal madem_auction)

      Computes the utility of a set of allocations coming from an auctioneer according to the specified utility functions.
      Parameters:
        `auctioneer` - agent asking for preference
        `madem_auction` - allocations and utility functions being considered

    - #### catchUtilityValue

          public void catchUtilityValue(ListTerm utilityKey,
                               Term utilityValue)

      Catches a utility value coming from an AgentSpeak plan and stores it within the utility values storage.
      Parameters:
        `utilityKey` - identifier of the utility value being caught
        `utilityValue` - utility value

    - #### bid

          private void bid(ListTerm utilityKey)

      Bids over a set of allocations coming from an auctioneer.
      Parameters:
        `utilityKey` - identifier of the utility values storage

    - #### processBid

          private void processBid(java.lang.String bidder,
                        Literal madem_bid)

      Process an external bid related to a certain decision.
      Parameters:
        `bidder` - name of the agent who sent the bid
        `madem_bid` - bid containing bidder's preferences

    - #### getUtility

          private float getUtility(java.lang.String auctioneer,
                         Term allocation,
                         UtilityFunctionInt utilityFunction)

      Obtains the utility value given by a specific utility function.
      Parameters:
        `auctioneer` - agent asking for preference
        `allocation` - allocation being evaluated
        `utilityFunction` - utility function being considered
      Returns:
        the utility value assigned to the allocation.

    - #### winnerDeterminationProblem

          private void winnerDeterminationProblem(int id_decision,
                                        boolean timeout)

      Solves the winner determination problem for a specific decision.
      Parameters:
        `id_decision` - Identifier of the decision being solved