OneShotAWI¶
- class scml.oneshot.OneShotAWI(world, agent)[source]¶
Bases:
negmas.situated.awi.AgentWorldInterface
The agent world interface for the one-shot game.
This class contains all the methods needed to access the simulation to extract information which are divided into 4 groups:
- Static World Information:
Information about the world and the agent that does not change over time. These include:
Market Information:
n_products: Number of products in the production chain.
n_processes: Number of processes in the production chain.
n_competitors: Number of other factories on the same production level.
all_suppliers: A list of all suppliers by product.
all_consumers: A list of all consumers by product.
is_system: Is the given system ID corresponding to a system agent?
is_bankrupt: Is the given agent bankrupt? None asks about self
catalog_prices: A list of the catalog prices (by product).
price_multiplier: The multiplier multiplied by the trading/catalog price when the negotiation agendas are created to decide the maximum and lower quantities.
is_exogenous_forced: Are exogenous contracts always forced or can the agent decide not to sign them.
current_step: Current simulation step (inherited from
negmas.situated.AgentWorldInterface
).n_steps: Number of simulation steps (inherited from
negmas.situated.AgentWorldInterface
).relative_time: fraction of the simulation completed (inherited from
negmas.situated.AgentWorldInterface
).state: The full state of the agent (
OneShotState
).settings The system settings (inherited from
negmas.situated.AgentWorldInterface
).
Agent Information:
profile: Gives the agent profile including its production cost, number of production lines, input product index, mean of its delivery penalties, mean of its disposal costs, standard deviation of its shortfall penalties and standard deviation of its disposal costs. See
OneShotProfile
for full description. This information is private information and no other agent knows it.n_lines: the number of production lines in the factory (private information).
is_first_level: Is the agent in the first production level (i.e. it is an input agent that buys the raw material).
is_last_level: Is the agent in the last production level (i.e. it is an output agent that sells the final product).
is_middle_level: Is the agent neither a first level nor a last level agent
my_input_product: The input product to the factory controlled by the agent.
my_output_product: The output product from the factory controlled by the agent.
level: The production level which is numerically the same as the input product.
my_suppliers: A list of IDs for all suppliers to the agent (i.e. agents that can sell the input product of the agent).
my_consumers: A list of IDs for all consumers to the agent (i.e. agents that can buy the output product of the agent).
penalties_scale: The scale at which to calculate disposal cost/delivery penalties. “trading” and “catalog” mean trading and catalog prices. “unit” means the contract’s unit price while “none” means that disposal cost/shortfall penalty are absolute.
n_input_negotiations: Number of negotiations with suppliers.
n_output_negotiations: Number of negotiations with consumers.
- Dynamic World Information:
Information about the world and the agent that changes over time.
Market Information:
trading_prices: The trading prices of all products. This information is only available if
publish_trading_prices
is set in the world.exogenous_contract_summary: A list of n_products tuples each giving the total quantity and average price of exogenous contracts for a product. This information is only available if
publish_exogenous_summary
is set in the world.
Other Agents’ Information:
reports_of_agent: Gives all past financial reports of a given agent. See
FinancialReport
for details.reports_at_step: Gives all reports of all agents at a given step. See
FinancialReport
for details.
Current Negotiations Information:
current_input_issues: The current issues for all negotiations to buy the input product of the agent. If the agent is at level zero, this will be empty.
current_output_issues: The current issues for all negotiations to buy the output product of the agent. If the agent is at level n_products - 1, this will be empty.
Agent Information:
current_exogenous_input_quantity: The total quantity the agent have in its input exogenous contract.
current_exogenous_input_price: The total price of the agent’s input exogenous contract.
current_exogenous_output_quantity: The total quantity the agent have in its output exogenous contract.
current_exogenous_output_price: The total price of the agent’s output exogenous contract.
current_disposal_cost: The disposal cost per unit item in the current step.
current_shortfall_penalty: The shortfall penalty per unit item in the current step.
current_balance: The current balance of the agent
- Services (All inherited from
negmas.situated.AgentWorldInterface
): logdebug/loginfo/logwarning/logerror: Logs to the world log at the given log level.
logdebug_agent/loginf_agnet/…: Logs to the agent specific log at the given log level.
bb_query: Queries the bulletin-board.
bb_read: Read a section of the bulletin-board.
Attributes Summary
A list of negotiation requests sent to this agent that are already accepted by it.
Returns a list of agent IDs for all consumers for every product
Returns a list of agent IDs for all suppliers for every product
Returns the catalog prices of all products
Cost of storing one unit (penalizes buying too much/ selling too little)
The exogenous contracts for the input (this step)
The exogenous contracts for the input (this step)
The exogenous contracts for the input (this step)
The exogenous contracts for the input (this step)
- rtype
list
[Issue
]
- rtype
list
[Issue
]
Cost of failure to deliver one unit (penalizes buying too little / selling too much)
Current simulation step
- rtype
The exogenous contracts in the current step for all products
Was the agent initialized (i.e.
Are exogenous contracts forced in the sense that the agent cannot decide not to sign them?
Whether this agent is in the first production level
Whether this agent is in the last production level
Whether this agent is in neither in the first nor in the last level
The production level which is the index of the process for this factory (or the index of its input product)
Returns a list of IDs for all the agent's consumers (agents that can consume at least one product it may produce).
the product I need to buy
the product I need to sell
Returns a list of IDs for all of the agent's suppliers (agents that can supply the product I need).
Returns the number of factories/agents in the same production level
Number of negotiations with suppliers at every step
The number of lines in the corresponding factory.
Number of negotiations with consumers at every step
Returns the number of processes in the system
Returns the number of products in the system
Number of steps in a simulation
A list of the negotiation requests sent by this agent that are not yet accepted or rejected.
Returns the basic parameters of the world
- rtype
Controls the minimum and maximum prices in the negotiation agendas
Gets the profile (static private information) associated with the agent
Relative time of the simulation going from 0 to 1
The negotiations currently requested by the agent.
The negotiations currently requested by the agent.
Returns the current trading prices of all products
All contracts that are not yet signed.
Methods Summary
bb_query
(section, query[, query_keys])Returns all records in the given section/sections of the bulletin-board that satisfy the query
bb_read
(section, key)Reads the value associated with given key from the bulletin board
bb_record
(section, value[, key])Records data in the given section of the bulletin board
bb_remove
(section, *[, query, key, ...])Removes a value or a set of values from the bulletin Board
execute
(action[, callback])Executes an action in the world simulation
is_bankrupt
([aid])Checks whether an agent is a system agent or not
is_system
(aid)Checks whether an agent is a system agent or not
logdebug
(msg)Logs a WARNING message
logdebug_agent
(msg)Logs a WARNING message to the agent's log
logerror
(msg)Logs a WARNING message
logerror_agent
(msg)Logs a WARNING message to the agent's log
loginfo
(msg)Logs an INFO message
loginfo_agent
(msg)Logs an INFO message to the agent's log
logwarning
(msg)Logs a WARNING message
logwarning_agent
(msg)Logs a WARNING message to the agent's log
penalty_multiplier
(is_input, unit_price)Returns the penalty multiplier for a contract with the give unit price.
reports_at_step
(step)Returns a dictionary mapping agent ID to its financial report for the given time-step
reports_of_agent
(aid)Returns a dictionary mapping time-steps to financial reports of the given agent
request_negotiation_about
(issues, partners, ...)Requests to start a negotiation with some other agents
run_negotiation
(issues, partners, negotiator)Runs a negotiation until completion
run_negotiations
(issues, partners, negotiators)Requests to run a set of negotiations simultaneously.
state
()Returns the private state of the agent in that world
Attributes Documentation
- accepted_negotiation_requests¶
A list of negotiation requests sent to this agent that are already accepted by it.
- Remarks:
These negotiations did not start yet as they are still not accepted by all partners. Once that happens, they will be moved to
running_negotiations
- Return type
list
[NegotiationRequestInfo
]
- all_consumers¶
Returns a list of agent IDs for all consumers for every product
- all_suppliers¶
Returns a list of agent IDs for all suppliers for every product
- current_balance¶
- current_disposal_cost¶
Cost of storing one unit (penalizes buying too much/ selling too little)
- Return type
- current_exogenous_output_quantity¶
The exogenous contracts for the input (this step)
- Return type
- current_inventory¶
- current_shortfall_penalty¶
Cost of failure to deliver one unit (penalizes buying too little / selling too much)
- Return type
- exogenous_contract_summary¶
The exogenous contracts in the current step for all products
- is_exogenous_forced¶
Are exogenous contracts forced in the sense that the agent cannot decide not to sign them?
- Return type
- is_first_level¶
Whether this agent is in the first production level
- is_last_level¶
Whether this agent is in the last production level
- is_middle_level¶
Whether this agent is in neither in the first nor in the last level
- level¶
The production level which is the index of the process for this factory (or the index of its input product)
- my_consumers¶
Returns a list of IDs for all the agent’s consumers (agents that can consume at least one product it may produce).
- my_suppliers¶
Returns a list of IDs for all of the agent’s suppliers (agents that can supply the product I need).
- n_lines¶
The number of lines in the corresponding factory. You can read
state
to get this among other information- Return type
- negotiation_requests¶
A list of the negotiation requests sent by this agent that are not yet accepted or rejected.
- Remarks:
These negotiations did not start yet as they are still not accepted by all partners. Once that happens, they will be moved to
running_negotiations
- Return type
list
[NegotiationRequestInfo
]
- price_multiplier¶
Controls the minimum and maximum prices in the negotiation agendas
- Remarks:
The base price is either the catalog price if trading price information is not public or the trading price.
The minimum unit price in any negotiation agenda is the base price of the previous product in the chain **divided by the multiplier. If that is less than 1, the minimum unit price becomes 1.
The maximum unit price in any negotiation agenda is the base price of the previous product in the chain **multiplied by the multiplier. If that is less than 1, the minimum unit price becomes 1.
- profile¶
Gets the profile (static private information) associated with the agent
- Return type
- requested_negotiations¶
The negotiations currently requested by the agent.
- Return type
list
[NegotiationRequestInfo
]- Returns
A list of negotiation request information objects (
NegotiationRequestInfo
)
- running_negotiations¶
The negotiations currently requested by the agent.
- Return type
list
[RunningNegotiationInfo
]- Returns
A list of negotiation information objects (
RunningNegotiationInfo
)
- settings¶
Methods Documentation
- bb_query(section, query, query_keys=False)¶
Returns all records in the given section/sections of the bulletin-board that satisfy the query
- Parameters
section (
str
|list
[str
] |None
) – Either a section name, a list of sections or None specifying ALL public sections (see remarks)query (
Any
) – The query which is USUALLY a dict with conditions on it when querying values and a RegExp whenkeys (querying) –
query_keys – Whether the query is to be applied to the keys or values.
- Returns
value pairs giving all records that satisfied the given requirements.
- Return type
A dictionary with key
Remarks:
A public section is a section with a name that does not start with an underscore
If a set of sections is given, and two records in different sections had the same key, only one of them will be returned
Key queries use regular expressions and match from the beginning using the standard re.match function
- bb_read(section, key)¶
Reads the value associated with given key from the bulletin board
- bb_record(section, value, key=None)¶
Records data in the given section of the bulletin board
- bb_remove(section, *, query=None, key=None, query_keys=False, value=None)¶
Removes a value or a set of values from the bulletin Board
- logdebug(msg)¶
Logs a WARNING message
- Parameters
msg (
str
) – The message to log
Returns:
- Return type
- logdebug_agent(msg)¶
Logs a WARNING message to the agent’s log
- Parameters
msg (
str
) – The message to log
Returns:
- Return type
- logerror(msg)¶
Logs a WARNING message
- Parameters
msg (
str
) – The message to log
Returns:
- Return type
- logerror_agent(msg)¶
Logs a WARNING message to the agent’s log
- Parameters
msg (
str
) – The message to log
Returns:
- Return type
- loginfo_agent(msg)¶
Logs an INFO message to the agent’s log
- Parameters
msg (
str
) – The message to log
Returns:
- Return type
- logwarning(msg)¶
Logs a WARNING message
- Parameters
msg (
str
) – The message to log
Returns:
- Return type
- logwarning_agent(msg)¶
Logs a WARNING message to the agent’s log
- Parameters
msg (
str
) – The message to log
Returns:
- Return type
- penalty_multiplier(is_input, unit_price)[source]¶
Returns the penalty multiplier for a contract with the give unit price.
- Remarks:
The unit price is only needed if the penalties_scale is unit. For all other options (trading, catalog, none), the penalty scale does not depend on the unit price.
- Return type
- reports_at_step(step)[source]¶
Returns a dictionary mapping agent ID to its financial report for the given time-step
- Return type
- reports_of_agent(aid)[source]¶
Returns a dictionary mapping time-steps to financial reports of the given agent
- Return type
- request_negotiation_about(issues, partners, req_id, roles=None, annotation=None, mechanism_name=None, mechanism_params=None, group=None)¶
Requests to start a negotiation with some other agents
- Parameters
req_id (
str
) –issues (
list
[Issue
]) – Negotiation issuesannotation (
Optional
[dict
[str
,Any
]]) – Extra information to be passed to thepartners
when asking them to join the negotiationpartners (
list
[str
]) – A list of partners to participate in the negotiation. Note that the caller itself may not be in this list which makes it possible for an agent to request a negotaition that it does not participate in. If that is not to be allowed in some world, override this method and explicitly check for these kinds of negotiations and return False. If partners is passed as a single string/Agent
or as a list containing a single string/Agent
, then he caller will be added at the beginning of the list. This will only be done ifroles
was passed as None.roles (
Optional
[list
[str
]]) – The roles of different partners. If None then each role for each partner will be Nonemechanism_name (
Optional
[str
]) – Name of the mechanism to use. It must be one of the mechanism_names that are supported by theNone (must also be) –
my_role (then roles and) –
None –
mechanism_params (
Optional
[dict
[str
,Any
]]) – A dict of parameters used to initialize the mechanism objectgroup (
Optional
[str
]) – An opational identifier for the group to which this negotiation belongs. It is not used by the system but is logged for debugging purposes. Moreover, the agent have access to it through itsnegotiations
property.
- Return type
- Returns
List[“Agent”] the list of partners who rejected the negotiation if any. If None then the negotiation was accepted. If empty then the negotiation was not started from the world manager
Remarks:
The function will create a request ID that will be used in callbacks
on_neg_request_accepted
and
- run_negotiation(issues, partners, negotiator, preferences=None, caller_role=None, roles=None, annotation=None, mechanism_name=None, mechanism_params=None)¶
Runs a negotiation until completion
- Parameters
partners (
Collection
[str
|Agent
]) – A list of partners to participate in the negotiation. Note that the caller itself may not be in this list which makes it possible for an agent to request a negotaition that it does not participate in. If that is not to be allowed in some world, override this method and explicitly check for these kinds of negotiations and return False. If partners is passed as a single string/Agent
or as a list containing a single string/Agent
, then he caller will be added at the beginning of the list. This will only be done ifroles
was passed as None.negotiator (
Negotiator
) – The negotiator to be used in the negotiationpreferences (
Optional
[Preferences
]) – The preferences. Only needed if the negotiator does not already know itcaller_role (
Optional
[str
]) – The role of the caller in the negotiationissues (
Collection
[Issue
]) – Negotiation issuesannotation (
Optional
[dict
[str
,Any
]]) – Extra information to be passed to thepartners
when asking them to join the negotiationpartners – A list of partners to participate in the negotiation
roles (
Optional
[Collection
[str
]]) – The roles of different partners. If None then each role for each partner will be Nonemechanism_name (
Optional
[str
]) – Name of the mechanism to use. It must be one of the mechanism_names that are supported by theNone (must also be) –
my_role (then roles and) –
None –
mechanism_params (
Optional
[dict
[str
,Any
]]) – A dict of parameters used to initialize the mechanism object
- Return type
- Returns
A Tuple of a contract and the nmi of the mechanism used to get it in case of success. None otherwise
- run_negotiations(issues, partners, negotiators, preferences=None, caller_roles=None, roles=None, annotations=None, mechanism_names=None, mechanism_params=None, all_or_none=False)¶
Requests to run a set of negotiations simultaneously. Returns after all negotiations are run to completion
- Parameters
partners (
list
[list
[str
|Agent
]]) – A list of partners to participate in the negotiation. Note that the caller itself may not be in this list which makes it possible for an agent to request a negotaition that it does not participate in. If that is not to be allowed in some world, override this method and explicitly check for these kinds of negotiations and return False. If partners is passed as a single string/Agent
or as a list containing a single string/Agent
, then he caller will be added at the beginning of the list. This will only be done ifroles
was passed as None.issues (
list
[Issue
] |list
[list
[Issue
]]) – Negotiation issuesnegotiators (
list
[Negotiator
]) – The negotiator to be used in the negotiationufuns – The utility function. Only needed if the negotiator does not already know it
caller_roles (
Optional
[list
[str
]]) – The role of the caller in the negotiationannotations (
Optional
[list
[dict
[str
,Any
] |None
]]) – Extra information to be passed to thepartners
when asking them to join the negotiationpartners – A list of partners to participate in the negotiation
roles (
Optional
[list
[list
[str
] |None
]]) – The roles of different partners. If None then each role for each partner will be Nonemechanism_names (
Union
[str
,list
[str
],None
]) – Name of the mechanism to use. It must be one of the mechanism_names that are supported by theNone (must also be) –
my_role (then roles and) –
None –
mechanism_params (
Union
[dict
[str
,Any
],list
[dict
[str
,Any
]],None
]) – A dict of parameters used to initialize the mechanism objectall_or_none (
bool
) – If true, either no negotiations will be started execpt if all partners accepted
- Returns
contract (None for failure) and nmi (The mechanism info [None if the corresponding partner refused to negotiation])
- Return type
A list of tuples each with two values