SCMLAWI¶
-
class
scml.scml2019.
SCMLAWI
(world, agent)[source]¶ Bases:
negmas.situated.AgentWorldInterface
A single contact point between SCML agents and the world simulation.
The agent can access the world simulation in one of two ways:
Attributes and methods available in this Agent-SCML2020World-Interface
Attributes and methods in the
FactoryManager
object itself which provide handy shortcuts to the agent-world interface
Attributes
Simulation settings
current_step
: Current simulation stepdefault_signing_delay
: The grace period allowed between contract conclusion and signature by default (i.e. if not agreed upon during the negotiation)n_steps
: Total number of simulation steps.relative_time
: The fraction of total simulation time elapsed (it will be a number between 0 and 1)
Production Graph
products
: A list ofProduct
objects giving all products defined in the world simulationprocesses
: A list ofProcess
objects giving all products defined in the world simulation
Agent Related
state
: The current private state available to the agent. In SCML it is aFactoryState
object.
Methods
Production Control
schedule_job
: Schedules aJob
for production sometime in the futureschedule_production
: Schedules production using profile number instead of aJob
objectcancel_production
: Cancels already scheduled production (if it did not start yet) or stop a running production.execute
: A general function to execute any command on the factory. There is no need to directly call this function as the SCMLAWI provides convenient functions (e.g.schedule_job
,hide_funds
, etc) to achieve the same goal without having to worry about creatingAction
objects
Storage and Wallet Control
hide_funds
: Hides funds from the view of the simulator. Note that when bankruptcy is considered, hidden funds are visible to the simulator.hide_inventory
: Hides inventory from the view of the simulator. Note that when bankruptcy is considered, hidden funds are visible to the simulator.unhide_funds
: Un-hides funds hidden earlier with a call tohide_funds
unhide_inventory
: Un-hides inventory hidden earlier with a call tohide_inventory
Negotiation and CFP Control
register_cfp
: Registers a Call-for-Proposals on the bulletin board.remove_cfp
: Removes a Call-for-Proposals from the bulletin board.request_negotiation
: Requests a negotiation based on the content of a CFP published on the bulletin-board. *It is recommended not to use this method directly and to request negotiations using the request_negotiation method ofFactoryManager
(i.e. use self.request_negotiation instead of self.awi.request_negotiation). This makes it possible for NegMAS to keep track of existingrequested_negotiations
andrunning_negotiations
for you.
Notification Control
receive_financial_reports
: Register/unregisters interest in receiving financial reports for an agent, a set of agents or all agents.register_interest
: registers interest in receiving CFPs about a set of products. By default allFactoryManager
objects are registered to receive all CFPs for any product they can produce or need to consumer according to their line-profiles.unregister_interest
: unregisters interest in receiving CFPs about a set of products.
Information about Other Agents
is_bankrupt
: Asks about the bankruptcy status of an agentreceive_financial_reports
: Register/unregisters interest in receiving financial reports for an agent, a set of agents or all agents.reports_at
: reads all financial reports produced at a given time-stepreports_for
: reads all financial reports of a given agent
Financial Control
evaluate_insurance
: Asks for the premium to be paid for insuring against partner breaches for a given contractbuy_insurance
: Buys an insurance against partner breaches for a given contract
Bulletin-Board
The bulletin-board is a key-value store. These methods allows the agent to interact with it. The `SCMLAWI` provides convenient functions for recording to the bulletin-board so you mostly need to use read/query functions.
bb_read
: Reads a complete section or a single value from the bulletin-boardbb_query
: Returns all records in the given section/sections of the bulletin-board that satisfy a querybb_record
: Registers a record in the bulletin-board.bb_remove
: Removes a record from the bulletin-board.
The following list of sections are available in the SCML Bulletin-Board (Use the exact string for the
section
parameter of any method starting withbb_
):cfps: All CFPs currently on the board. The key is the CFP ID
products: A list of all products. The key is the product index/ID
processes: A list of all processes. The key is the product index/ID
bankruptcy: The bankruptcy list giving names of all bankrupt agents.
reports_time: Financial reports indexed by time.
reports_agent: Financial reports indexed by agent
breaches: Breach-list indexed by breach ID giving all breaches committed in the system
settings: Static settings of the simulation.
The following settings are currently available:
breach_penalty_society: Penalty of breaches paid to society (as a fraction of contract value). This is always paid for every breach whether or not there is a negotiated breach.
breach_penalty_victim: Penalty of breaches paid to victim (as a fraction of contract value). This is always paid for every breach whether or not there is a negotiated breach.
immediate_negotiations: Whether negotiations start immediately when registered (the other possibility – which is the default – is for them to start at the next production step).
negotiation_speed_multiple: Number of negotiation steps that finish in a single production step.
negotiation_n_steps: Maximum allowed number of steps (rounds) in any negotiation
negotiation_step_time_limit: The maximum real-time allowed for each negotiation step (round)
negotiation_time_limit: The time limit for a complete negotiation.
transportation_delay: Transportation delay when products are moved between factories. Default is zero.
transfer_delay: The delay in transferring funds between factories when executing a contract. Default is zero.
n_steps: Number of simulation steps
time_limit: Time limit for the complete simulation
stats: Global statistics about the simulation. Not available for SCML 2019 league.
Logging
logerror
: Logs an error in the world simulation log filelogwarning
: Logs a warning in the world simulation log fileloginfo
: Logs information in the world simulation log filelogdebug
: Logs debug information in the world simulation log file
Attributes Summary
Current simulation step
- rtype
int
Number of steps in a simulation
Processes in the world
Products in the world
Relative time of the simulation going from 0 to 1
Returns the private state of the agent in that world.
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
buy_insurance
(contract)Buys insurance for the contract by the premium calculated by the insurance company.
cancel_production
(line, step, contract[, …])Stops/cancels production scheduled at the given line at the given time.
evaluate_insurance
(contract[, t])Can be called to evaluate the premium for insuring the given contract against breaches committed by others
execute
(action[, callback])Executes an action in the world simulation
hide_funds
(amount)Hides the given amount of money so that it is not accessible by the simulator and does not appear in reports etc.
hide_inventory
(product, quantity)Hides the given quantity of the given product so that it is not accessible by the simulator and does not appear in reports etc.
is_bankrupt
(agent_id)Checks whether the given agent is bankrupt
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
receive_financial_reports
([receive, agents])Registers/unregisters interest in receiving financial reports
register_cfp
(cfp)Registers a CFP
register_interest
(products)registers interest in receiving callbacks about CFPs related to these products
remove_cfp
(cfp)Removes a CFP
reports_at
([step])Gets all financial reports of all agents at a given step
reports_for
(agent_id)Gets all financial reports of an agent (in the order of their publication)
request_negotiation
(cfp, req_id[, roles, …])Requests a negotiation with the publisher of a given CFP
request_negotiation_about
(issues, partners, …)Overrides the method of the same name in the base class to disable it in SCM Worlds.
run_negotiation
(issues, partners, negotiator)Runs a negotiation until completion
run_negotiations
(issues, partners, negotiators)Requests to run a set of negotiations simultaneously.
schedule_job
(job, contract)Schedules production using a
Job
object.schedule_production
(profile, step[, …])Schedules production on the agent’s factory
stop_production
(line, step, contract[, override])Stops/cancels production scheduled at the given line at the given time.
unhide_funds
(amount)Un-hides the given amount of money so that it is not accessible by the simulator and does not appear in reports etc.
unhide_inventory
(product, quantity)Un-hides the given quantity of the given product so that it is not accessible by the simulator and does not appear in reports etc.
unregister_interest
(products)registers interest in receiving callbacks about CFPs related to these products
Attributes Documentation
-
current_step
¶ Current simulation step
- Return type
int
-
default_signing_delay
¶ - Return type
int
-
n_steps
¶ Number of steps in a simulation
- Return type
int
-
relative_time
¶ Relative time of the simulation going from 0 to 1
- Return type
float
-
settings
¶
-
state
¶ Returns the private state of the agent in that world.
In the SCML world, that is a reference to its factory. You are allowed to read information from the returned
Factory
but not to modify it or call ANY methods on it that modify the state.- Return type
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 (
Union
[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
- Parameters
section (
str
) – section namekey (
str
) – key
- Return type
Optional
[Any
]- Returns
Content of that key in the bulletin-board
-
bb_record
(section, value, key=None)¶ Records data in the given section of the bulletin board
- Parameters
section (
str
) – section name (can contain subsections separated by ‘/’)key (
Optional
[str
]) – The keyvalue (
Any
) – The value
- Return type
None
-
bb_remove
(section, *, query=None, key=None, query_keys=False, value=None)¶ Removes a value or a set of values from the bulletin Board
- Parameters
section (
Union
[str
,List
[str
],None
]) – The sectionquery (
Optional
[Any
]) – the query to use to select what to removekey (
Optional
[str
]) – the key to remove (no need to give a full query)query_keys (
bool
) – Whether to apply the query (if given) to keys or valuesvalue (
Optional
[Any
]) – Value to be removed
- Returns
Success of failure
- Return type
bool
-
buy_insurance
(contract)[source]¶ Buys insurance for the contract by the premium calculated by the insurance company.
- Remarks:
The agent can call
evaluate_insurance
to find the premium that will be used.
- Return type
bool
-
cancel_production
(line, step, contract, override=True)¶ Stops/cancels production scheduled at the given line at the given time.
- Parameters
line (
int
) – One of the factory lines (index)step (
int
) – Step to stop/cancel production at
-
evaluate_insurance
(contract, t=None)[source]¶ Can be called to evaluate the premium for insuring the given contract against breaches committed by others
- Parameters
contract (
Contract
) – hypothetical contractt (
Optional
[int
]) – time at which the policy is to be bought. If None, it means current step
- Return type
Optional
[float
]
-
execute
(action, callback=None)¶ Executes an action in the world simulation
- Return type
bool
-
hide_funds
(amount)[source]¶ Hides the given amount of money so that it is not accessible by the simulator and does not appear in reports etc.
- Parameters
amount (
float
) – The amount of money to hide
Remarks:
if the current cash in the agent’s wallet is less than the amount to be hidden, all the cash is hidden.
hiding is always immediate
- Return type
None
-
hide_inventory
(product, quantity)[source]¶ Hides the given quantity of the given product so that it is not accessible by the simulator and does not appear in reports etc.
- Parameters
product (
int
) – product indexquantity (
int
) – the amount of the product to hide
Remarks:
if the current quantity in storage of the product is less than the amount to be hidden, whatever quantity exists is hidden
hiding is always immediate
- Return type
None
-
is_bankrupt
(agent_id)[source]¶ Checks whether the given agent is bankrupt
- Parameters
agent_id (
str
) – Agent ID- Return type
bool
- Returns
The bankruptcy state of the agent
-
logdebug
(msg)¶ Logs a WARNING message
- Parameters
msg (
str
) – The message to log
Returns:
- Return type
None
-
logdebug_agent
(msg)¶ Logs a WARNING message to the agent’s log
- Parameters
msg (
str
) – The message to log
Returns:
- Return type
None
-
logerror
(msg)¶ Logs a WARNING message
- Parameters
msg (
str
) – The message to log
Returns:
- Return type
None
-
logerror_agent
(msg)¶ Logs a WARNING message to the agent’s log
- Parameters
msg (
str
) – The message to log
Returns:
- Return type
None
-
loginfo
(msg)¶ Logs an INFO message
- Parameters
msg (
str
) – The message to log
Returns:
- Return type
None
-
loginfo_agent
(msg)¶ Logs an INFO message to the agent’s log
- Parameters
msg (
str
) – The message to log
Returns:
- Return type
None
-
logwarning
(msg)¶ Logs a WARNING message
- Parameters
msg (
str
) – The message to log
Returns:
- Return type
None
-
logwarning_agent
(msg)¶ Logs a WARNING message to the agent’s log
- Parameters
msg (
str
) – The message to log
Returns:
- Return type
None
-
receive_financial_reports
(receive=True, agents=None)[source]¶ Registers/unregisters interest in receiving financial reports
- Parameters
receive (
bool
) – True to receive and False to stop receivingagents (
Optional
[List
[str
]]) – If given reception is enabled/disabled only for the given set of agents.
Remarks:
by default financial reports are not sent to any agents. To opt-in to receive financial reports, call this method.
- Return type
None
-
register_interest
(products)[source]¶ registers interest in receiving callbacks about CFPs related to these products
- Return type
None
-
reports_at
(step=None)[source]¶ Gets all financial reports of all agents at a given step
- Parameters
step (
Optional
[int
]) – Step at which the reports are required. If None, the last set of reports is returned- Return type
Dict
[str
,FinancialReport
]- Returns
A dictionary with agent IDs in keys and their financial reports at the given time as values
-
reports_for
(agent_id)[source]¶ Gets all financial reports of an agent (in the order of their publication)
- Parameters
agent_id (
str
) – Agent ID
Returns:
- Return type
List
[FinancialReport
]
-
request_negotiation
(cfp, req_id, roles=None, mechanism_name=None, mechanism_params=None)[source]¶ Requests a negotiation with the publisher of a given CFP
- Parameters
cfp (
CFP
) – The CFP to negotiate aboutreq_id (
str
) – A string that is passed back to the caller in all callbacks related to this negotiationroles (
Optional
[List
[str
]]) – The roles of the CFP publisher and the agent (in that order). By default no roles are passed (None)mechanism_name (
Optional
[str
]) – The mechanism type to use. If not given the default mechanism from the world will be usedmechanism_params (
Optional
[Dict
[str
,Any
]]) – Parameters of the mechanism
- Return type
bool
- Returns
Success of failure of the negotiation request
Remarks:
The
SCMLAgent
class implements another request_negotiation method that does not receive areq_id
. This helper method is recommended as it generates the required req_id and passes it keeping track of requested negotiations (and later of running negotiations). Call this method direclty only if you do not intend to use therequested_negotiations
andrunning_negotiations
properties of theSCMLAgent
class
-
request_negotiation_about
(issues, partners, req_id, roles=None, annotation=None, mechanism_name=None, mechanism_params=None)[source]¶ Overrides the method of the same name in the base class to disable it in SCM Worlds.
Do not call this method
-
run_negotiation
(issues, partners, negotiator, ufun=None, caller_role=None, roles=None, annotation=None, mechanism_name=None, mechanism_params=None)¶ Runs a negotiation until completion
- Parameters
partners (
Collection
[Agent
]) – The list of partners that the agent wants to negotiate with. Roles will be determined by these agents.negotiator (
Negotiator
) – The negotiator to be used in the negotiationufun (
Optional
[UtilityFunction
]) – The utility function. 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 theor None which means that the World should select the mechanism. If None, then roles and my_role (World) –
also be None (must) –
mechanism_params (
Optional
[Dict
[str
,Any
]]) – A dict of parameters used to initialize the mechanism object
- Return type
Optional
[Tuple
[Contract
,AgentMechanismInterface
]]- Returns
A Tuple of a contract and the ami of the mechanism used to get it in case of success. None otherwise
-
run_negotiations
(issues, partners, negotiators, ufuns=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
[Agent
]]) – The list of partners that the agent wants to negotiate with. Roles will be determined by these agents.issues (
Union
[List
[Issue
],List
[List
[Issue
]]]) – Negotiation issuesnegotiators (
List
[Negotiator
]) – The negotiator to be used in the negotiationufuns (
Optional
[List
[UtilityFunction
]]) – The utility function. Only needed if the negotiator does not already know itcaller_roles (
Optional
[List
[str
]]) – The role of the caller in the negotiationannotations (
Optional
[List
[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
[List
[Optional
[List
[str
]]]]) – 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 theor None which means that the World should select the mechanism. If None, then roles and my_role (World) –
also be None (must) –
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 ami (The mechanism info [None if the corresponding partner refused to negotiation])
- Return type
A list of tuples each with two values
-
schedule_job
(job, contract)[source]¶ Schedules production using a
Job
object. This can be used to schedule any kind of job- Parameters
job (
Job
) – The job descriptioncontract (
Optional
[Contract
]) – The contract for which the job is scheduled (optional)
Remarks:
Notice that actions that require the profile member of Job (run) never use the line member and vice versa.
-
schedule_production
(profile, step, contract=None, override=True)[source]¶ Schedules production on the agent’s factory
- Parameters
profile (
int
) – Index of the profile in the agent’scompiled_profiles
liststep (
int
) – The step to start production according to the given profilecontract (
Optional
[Contract
]) – The contract for which the production is scheduled (optional)override (
bool
) – Whether to override existing production jobs schedules at the same time.
- Return type
None
-
stop_production
(line, step, contract, override=True)[source]¶ Stops/cancels production scheduled at the given line at the given time.
- Parameters
line (
int
) – One of the factory lines (index)step (
int
) – Step to stop/cancel production atcontract (
Optional
[Contract
]) – The contract for which the job is scheduled (optional)override (
bool
) – Whether to override existing production jobs schedules at the same time.
-
unhide_funds
(amount)[source]¶ Un-hides the given amount of money so that it is not accessible by the simulator and does not appear in reports etc.
- Parameters
amount (
float
) – The amount of money to unhide
Remarks:
if the current cash in the agent’s wallet is less than the amount to be hidden, all the cash is hidden.
hiding is always immediate
- Return type
None
-
unhide_inventory
(product, quantity)[source]¶ Un-hides the given quantity of the given product so that it is not accessible by the simulator and does not appear in reports etc.
- Parameters
product (
int
) – product indexquantity (
int
) – the amount of the product to hide
Remarks:
if the current quantity in storage of the product is less than the amount to be hidden, whatever quantity exists is hidden
hiding is always immediate
- Return type
None