Consumer¶
- class scml.scml2019.Consumer(name=None, ufun=None)[source]¶
Bases:
scml.scml2019.agent.SCML2019Agent
,abc.ABC
Base class of all consumer classes
Attributes Summary
A list of negotiation requests sent to this agent that are already accepted by it.
Returns the Agent-SCML2020World-Interface through which the agent does all of its actions in the world.
Returns the preferences if it is a CrispUtilityFunction else None
Does the entity has an associated ufun?
Does the entity has an associated ufun?
The unique ID of this entity
Was the agent initialized (i.e.
A convenient name of the entity (intended primarily for printing/logging/debugging).
A list of the negotiation requests sent by this agent that are not yet accepted or rejected.
The utility function attached to that object
Returns the preferences if it is a ProbUtilityFunction else None
The negotiations currently requested by the agent.
Reserved outcome is the outcome that will be realized by default for this agent.
Reserved value is what the entity gets if no agreement is reached in the negotiation.
The negotiations currently requested by the agent.
Returns a short name of the type of this entity
Returns the name of the type of this entity
Returns the preferences if it is a UtilityFunction else None
All contracts that are not yet signed.
The unique ID of this entity
Methods Summary
can_expect_agreement
(cfp, margin)Checks if it is possible in principle to get an agreement on this CFP by the time it becomes executable
checkpoint
(path[, file_name, info, ...])Saves a checkpoint of the current object at the given path.
checkpoint_info
(file_name)Returns the information associated with a dump of the object saved in the given file
confirm_contract_execution
(contract)Called before executing any agreement
confirm_loan
(loan, bankrupt_if_rejected)called by the world manager to confirm a loan if needed by the buyer of a contract that is about to be breached
confirm_partial_execution
(contract, breaches)Will be called whenever a contract cannot be fully executed due to breaches by the other partner.
create
(*args, **kwargs)Creates an object and returns a proxy to it.
create_negotiation_request
(issues, partners, ...)Creates a new
NegotiationRequestInfo
record and returns itS IDfrom_checkpoint
(file_name[, return_info])Creates an object from a saved checkpoint
from_config
(config[, section, ...])Creates an object of this class given the configuration info
init
()Called to initialize the agent after the world is initialized.
init_
()The initialization function called by the world directly.
notify
(notifiable, notification)on_agent_bankrupt
(agent_id)Will be called whenever any agent goes bankrupt
on_cash_transfer
(amount, cause)Received whenever money is transferred to the factory or from it.
on_contract_breached
(contract, breaches, ...)Called after complete processing of a contract that involved a breach.
on_contract_cancelled
(contract, rejectors)Called whenever at least a partner did not sign the contract
on_contract_cancelled_
(contract, rejectors)Called whenever at least a partner did not sign the contract
on_contract_executed
(contract)Called after successful contract execution for which the agent is one of the partners.
on_contract_nullified
(contract, ...)Will be called whenever a contract the agent is involved in is nullified because another partner went bankrupt
on_contract_signed
(contract)Called whenever a contract is signed by all partners
on_contract_signed_
(contract)Called whenever a contract is signed by all partners
on_contracts_finalized
(signed, cancelled, ...)Called for all contracts in a single step to inform the agent about which were finally signed and which were rejected by any agents (including itself)
on_event
(event, sender)on_inventory_change
(product, quantity, cause)Received whenever something moves in or out of the factory's storage
on_neg_request_accepted
(req_id, mechanism)Called when a requested negotiation is accepted
on_neg_request_accepted_
(req_id, mechanism)Called when a requested negotiation is accepted
on_neg_request_rejected
(req_id, by)Called when a requested negotiation is rejected
on_neg_request_rejected_
(req_id, by)Called when a requested negotiation is rejected
on_negotiation_failure
(partners, annotation, ...)Called whenever a negotiation ends without agreement
on_negotiation_failure_
(partners, ...)Called whenever a negotiation ends without agreement
on_negotiation_success
(contract, mechanism)Called whenever a negotiation ends with agreement
on_negotiation_success_
(contract, mechanism)Called whenever a negotiation ends with agreement
on_new_cfp
(cfp)Called when a new CFP for a product for which the agent registered interest is published
on_new_report
(report)Called whenever a financial report is published.
on_preferences_changed
(changes)Called to inform the entity that its ufun has changed.
on_remove_cfp
(cfp)Called when a new CFP for a product for which the agent registered interest is removed
Will be called at the end of the simulation step after everything else
Will be called at the beginning of the simulation step before everything else (except init)
read_config
(config[, section])Reads the configuration from a file or a dict and prepares it for parsing
request_negotiation
(cfp[, negotiator, ufun])Requests a negotiation from the AWI while keeping track of available negotiation requests
respond_to_negotiation_request
(cfp, partner)Called when a prospective partner requests a negotiation to start
respond_to_negotiation_request_
(initiator, ...)Called when a negotiation request is received
respond_to_renegotiation_request
(contract, ...)Called to respond to a renegotiation request
set_preferences
(value[, force])Sets tha utility function/Preferences.
set_renegotiation_agenda
(contract, breaches)Received by partners in ascending order of their total breach levels in order to set the renegotiation agenda when contract execution fails
sign_all_contracts
(contracts)Called to sign all contracts concluded in a single step by this agent
sign_contract
(contract)Called after the signing delay from contract conclusion to sign the contract.
spawn
([spawn_as, spawn_params])spawn_object
(*args, **kwargs)step
()Called by the simulator at every simulation step
step_
()Called at every time-step.
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
]
- awi¶
Returns the Agent-SCML2020World-Interface through which the agent does all of its actions in the world.
A single excption is request_negotiation for which it is recommended to actually call the helper method on the agent itself instead of directly calling the AWI version.
- Return type
- crisp_ufun¶
Returns the preferences if it is a CrispUtilityFunction else None
- Return type
UtilityFunction
|None
- id¶
The unique ID of this entity
- name¶
A convenient name of the entity (intended primarily for printing/logging/debugging).
- 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
]
- prob_ufun¶
Returns the preferences if it is a ProbUtilityFunction else None
- Return type
ProbUtilityFunction
|None
- requested_negotiations¶
The negotiations currently requested by the agent.
- Return type
list
[NegotiationRequestInfo
]- Returns
A list of negotiation request information objects (
NegotiationRequestInfo
)
- reserved_outcome¶
Reserved outcome is the outcome that will be realized by default for this agent.
Remarks:
Reserved outcomes are defined for
OrdinalPreferences
.
See also
- reserved_value¶
Reserved value is what the entity gets if no agreement is reached in the negotiation.
The reserved value can either be explicity defined for the ufun or it can be the output of the ufun for
None
outcome.- Return type
- running_negotiations¶
The negotiations currently requested by the agent.
- Return type
list
[RunningNegotiationInfo
]- Returns
A list of negotiation information objects (
RunningNegotiationInfo
)
- short_type_name¶
Returns a short name of the type of this entity
- type_name¶
Returns the name of the type of this entity
- type_postfix¶
- ufun¶
Returns the preferences if it is a UtilityFunction else None
- Return type
BaseUtilityFunction
|None
- uuid¶
The unique ID of this entity
Methods Documentation
- can_expect_agreement(cfp, margin)¶
Checks if it is possible in principle to get an agreement on this CFP by the time it becomes executable
Returns:
- checkpoint(path, file_name=None, info=None, exist_ok=False, single_checkpoint=True, step_attribs=('current_step', '_current_step', '_Entity__current_step', '_step'))¶
Saves a checkpoint of the current object at the given path.
- Parameters
path (
PathLike
) – Full path to a directory to store the checkpointfile_name (
Optional
[str
]) – Name of the file to dump into. If not given, a unique name is createdinfo (
Optional
[dict
[str
,Any
]]) – Information to save with the checkpoint (must be json serializable)exist_ok (
bool
) – If true, override existing dumpsingle_checkpoint (
bool
) – If true, keep a single checkpoint for the last stepstep_attribs (
tuple
[str
,...
]) – Attributes to represent the time-step of the object. Any of the given attributes will be used in the file name generated if single_checkpoint is False. If single_checkpoint is True, the filename will not contain time-step information
- Return type
- Returns
full path to the file used to save the checkpoint
- classmethod checkpoint_info(file_name)¶
Returns the information associated with a dump of the object saved in the given file
Returns:
- abstract confirm_contract_execution(contract)¶
Called before executing any agreement
- Return type
- abstract confirm_loan(loan, bankrupt_if_rejected)¶
called by the world manager to confirm a loan if needed by the buyer of a contract that is about to be breached
- Return type
- abstract confirm_partial_execution(contract, breaches)¶
Will be called whenever a contract cannot be fully executed due to breaches by the other partner.
- Parameters
contract (
Contract
) – The contract that was breachedbreaches (
List
[Breach
]) – A list of all the breaches committed.
Remarks:
Will not be called if both partners committed breaches.
- Return type
- classmethod create(*args, **kwargs)¶
Creates an object and returns a proxy to it.
- create_negotiation_request(issues, partners, annotation, negotiator, extra)¶
Creates a new
NegotiationRequestInfo
record and returns itS ID- Parameters
- Return type
- Returns
A unique identifier for this negotiation info structure
- classmethod from_checkpoint(file_name, return_info=False)¶
Creates an object from a saved checkpoint
- Parameters
- Return type
- Returns
Either the object or the object and dump-info as a dict (if return_info was true)
Remarks:
- If info is returned, it is guaranteed to have the following members:
time: Dump time
type: Type of the dumped object
id: ID
name: name
- classmethod from_config(config, section=None, ignore_children=True, try_parsing_children=True, scope=None)¶
Creates an object of this class given the configuration info
- Parameters
section (
Optional
[str
]) – A section in the file or a key in the dictionary to use for loading paramsignore_children (
bool
) – If true then children will be ignored and there will be a single returntry_parsing_children (
bool
) – If true the children will first be parsed asConfigReader
classes if they are notint (simple types (e.g.) –
str –
float –
Iterable[int|str|float] –
scope – The scope at which to evaluate any child classes. This MUST be passed as scope=globals() if you are
parsed. (having any children that are to be) –
- Returns
An object of cls if ignore_children is True or a tuple with an object of cls and a dictionary with children that were not parsed.
Remarks:
This function will return an object of its class after passing the key-value pairs found in the config to the init function.
Requiring passing scope=globals() to this function is to get around the fact that in python eval() will be called with a globals dictionary based on the module in which the function is defined not called. This means that in general when eval() is called to create the children, it will not have access to the class definitions of these children (except if they happen to be imported in this file). To avoid this problem causing an undefined_name exception, the caller must pass her globals() as the scope.
- abstract init()¶
Called to initialize the agent after the world is initialized. the AWI is accessible at this point.
- init_()¶
The initialization function called by the world directly.
It does the following actions by default:
copies some of the static world settings to the agent to make them available without calling the AWI.
prepares production related properties like producing, consuming, line_profiles, compiled_profiles, etc.
registers interest in all products that the agent can produce or consume in its factory.
finally it calls any custom initialization logic implemented in `init`()
- notify(notifiable, notification)¶
- abstract on_agent_bankrupt(agent_id)¶
Will be called whenever any agent goes bankrupt
- Parameters
agent_id (
str
) – The ID of the agent that went bankrupt
Remarks:
Agents can go bankrupt in two cases:
Failing to pay one installments of a loan they bought and refusing (or being unable to) get another loan to pay it.
Failing to pay a penalty on a sell contract they failed to honor (and refusing or being unable to get a loan to pay for it).
All built-in agents ignore this call and they use the bankruptcy list ONLY to decide whether or not to negotiate in their
on_new_cfp
andrespond_to_negotiation_request
callbacks by pulling the bulletin-board using the helper functionis_bankrupt
of their AWI.
- Return type
- abstract on_cash_transfer(amount, cause)¶
Received whenever money is transferred to the factory or from it.
- Parameters
amount (
float
) – Amount of money (negative for transfers out of the factory, positive for transfers to it).cause (
str
) –The cause of the change. Possibilities include:
contract: Contract execution
insurance: Received from insurance company
bankruptcy: Liquidated due to bankruptcy
transfer: Arrival of transferred money (when transfer delay in the system is > 0).
- Return type
- abstract on_contract_breached(contract, breaches, resolution)¶
Called after complete processing of a contract that involved a breach.
- on_contract_cancelled(contract, rejectors)¶
Called whenever at least a partner did not sign the contract
- Return type
- on_contract_cancelled_(contract, rejectors)¶
Called whenever at least a partner did not sign the contract
- Return type
- abstract on_contract_executed(contract)¶
Called after successful contract execution for which the agent is one of the partners.
- Return type
- abstract on_contract_nullified(contract, bankrupt_partner, compensation)¶
Will be called whenever a contract the agent is involved in is nullified because another partner went bankrupt
- Return type
- on_contract_signed_(contract)¶
Called whenever a contract is signed by all partners
- Return type
- on_contracts_finalized(signed, cancelled, rejectors)¶
Called for all contracts in a single step to inform the agent about which were finally signed and which were rejected by any agents (including itself)
- Parameters
signed (
list
[Contract
]) – A list of signed contracts. These are bindingcancelled (
list
[Contract
]) – A list of cancelled contracts. These are not bindingrejectors (
list
[list
[str
]]) – A list of lists where each of the internal lists gives the rejectors of one of the cancelled contracts. Notice that it is possible that this list is empty which means that the contract other than being rejected by any agents (if that was possible in the specific world).
Remarks:
The default implementation is to call
on_contract_signed
for singed contracts andon_contract_cancelled
for cancelled contracts- Return type
- on_event(event, sender)¶
- abstract on_inventory_change(product, quantity, cause)¶
Received whenever something moves in or out of the factory’s storage
- Parameters
product (
int
) – Product index.quantity (
int
) – Negative value for products moving out and positive value for products moving incause (
str
) –The cause of the change. Possibilities include:
contract: Contract execution
insurance: Received from insurance company
bankruptcy: Liquidated due to bankruptcy
transport: Arrival of goods (when transportation delay in the system is > 0).
- Return type
- abstract on_neg_request_accepted(req_id, mechanism)¶
Called when a requested negotiation is accepted
- on_neg_request_accepted_(req_id, mechanism)¶
Called when a requested negotiation is accepted
- abstract on_neg_request_rejected(req_id, by)¶
Called when a requested negotiation is rejected
- on_neg_request_rejected_(req_id, by)¶
Called when a requested negotiation is rejected
- abstract on_negotiation_failure(partners, annotation, mechanism, state)¶
Called whenever a negotiation ends without agreement
- Return type
- on_negotiation_failure_(partners, annotation, mechanism, state)¶
Called whenever a negotiation ends without agreement
- Return type
- abstract on_negotiation_success(contract, mechanism)¶
Called whenever a negotiation ends with agreement
- Return type
- on_negotiation_success_(contract, mechanism)¶
Called whenever a negotiation ends with agreement
- Return type
- abstract on_new_cfp(cfp)¶
Called when a new CFP for a product for which the agent registered interest is published
- abstract on_new_report(report)¶
Called whenever a financial report is published.
- Parameters
report (
FinancialReport
) – The financial report giving details of the standing of an agent at some time (seeFinancialReport
)
Remarks:
Agents must opt-in to receive these calls by calling
receive_financial_reports
on their AWI
- on_preferences_changed(changes)¶
Called to inform the entity that its ufun has changed.
- Parameters
changes (
list
[PreferencesChange
]) – An ordered list of changes that happened.
Remarks:
You MUST call the super() version of this function either before or after your code when you are overriding it.
The most general form of change is
PreferencesChange.General
which indicates that you cannot trust anything you knew about the ufun anymore
- abstract on_remove_cfp(cfp)¶
Called when a new CFP for a product for which the agent registered interest is removed
- on_simulation_step_ended()¶
Will be called at the end of the simulation step after everything else
- on_simulation_step_started()¶
Will be called at the beginning of the simulation step before everything else (except init)
- classmethod read_config(config, section=None)¶
Reads the configuration from a file or a dict and prepares it for parsing
- Parameters
- Return type
- Returns
A dict ready to be parsed by from_config
Remarks:
- request_negotiation(cfp, negotiator=None, ufun=None)¶
Requests a negotiation from the AWI while keeping track of available negotiation requests
- abstract respond_to_negotiation_request(cfp, partner)¶
Called when a prospective partner requests a negotiation to start
- Return type
Optional
[Negotiator
]
- respond_to_negotiation_request_(initiator, partners, issues, annotation, mechanism, role, req_id)¶
Called when a negotiation request is received
- Return type
Negotiator
|None
- abstract respond_to_renegotiation_request(contract, breaches, agenda)¶
Called to respond to a renegotiation request
- Parameters
agenda (
RenegotiationRequest
) –contract (
Contract
) –breaches (
list
[Breach
]) –
Returns:
- Return type
Negotiator
|None
- set_preferences(value, force=False)¶
Sets tha utility function/Preferences.
- abstract set_renegotiation_agenda(contract, breaches)¶
Received by partners in ascending order of their total breach levels in order to set the renegotiation agenda when contract execution fails
- sign_all_contracts(contracts)¶
Called to sign all contracts concluded in a single step by this agent
- Parameters
contracts (
list
[Contract
]) – A list of contracts to sign/ refuse to sign- Returns
None
to indicate refusing to sign all contracts.str
(specifically, the agent ID) to indicate signing ALL contracts.List[Optional[str]]
A list with a value for each input contract whereNone
means refusal to sign that contract and a string (agent ID) indicates acceptance to sign it. Note that in this case, the number of values in the returned list must match that of the contacts (and they should obviously correspond to the contracts).Dict[str, Optional[str]]
A mapping from contract ID to either aNone
for rejection to sign or a string (for acceptance to sign). Contracts with IDs not in the keys will assumed not to be signed.
- Return type
You can return any of the following
Remarks:
default implementation calls
sign_contract
for each contract returning the results
- sign_contract(contract)¶
Called after the signing delay from contract conclusion to sign the contract. Contracts become binding only after they are signed.
- classmethod spawn(spawn_as='object', spawn_params=None, *args, **kwargs)¶
- classmethod spawn_object(*args, **kwargs)¶
- abstract step()¶
Called by the simulator at every simulation step
- step_()¶
Called at every time-step. This function is called directly by the world.