scml.scml2019.consumers

Module Contents

Classes

ConsumptionProfile
Consumer	Base class of all consumer classes
JustInTimeConsumer	Consumer class

class scml.scml2019.consumers.ConsumptionProfile

schedule: int | List[int] = 0

underconsumption: float = 0.1

overconsumption: float = 0.01

dynamicity: float = 0.0

cv: float = 0.1

alpha_q: float = 0.5

alpha_u: float = 1.0

beta_q: float = 10.0

beta_u: float = 10.0

tau_q: float = 2

tau_u: float = 0.25

classmethod random()

schedule_at(time: int) → int

schedule_within(time: int | List[int] | Tuple[int, int]) → int

set_schedule_at(time: int, value: int, n_steps: int) → None

class scml.scml2019.consumers.Consumer(name: str | None = None, ufun: negmas.UtilityFunction | None = None)

Bases: scml.scml2019.agent.SCML2019Agent, abc.ABC

Base class of all consumer classes

class scml.scml2019.consumers.JustInTimeConsumer(profiles: Dict[int, ConsumptionProfile] = None, negotiator_type=DEFAULT_NEGOTIATOR, consumption_horizon: int | None = 20, immediate_cfp_update: bool = True, name=None)

Bases: Consumer

Consumer class

MAX_UNIT_PRICE = 100.0

RELATIVE_MAX_PRICE = 1.5

on_contract_executed(contract: negmas.situated.Contract) → None

Called after successful contract execution for which the agent is one of the partners.

on_contract_breached(contract: negmas.situated.Contract, breaches: List[negmas.situated.Breach], resolution: negmas.situated.Contract | None) → None

Called after complete processing of a contract that involved a breach.

Parameters:

• contract – The contract

• breaches – All breaches committed (even if they were resolved)

• resolution – The resolution contract if re-negotiation was successful. None if not.

on_inventory_change(product: int, quantity: int, cause: str) → None

Received whenever something moves in or out of the factory’s storage

Parameters:

• product – Product index.

• quantity – Negative value for products moving out and positive value for products moving in

• cause –

  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).

on_cash_transfer(amount: float, cause: str) → None

Received whenever money is transferred to the factory or from it.

Parameters:

• amount – Amount of money (negative for transfers out of the factory, positive for transfers to it).

• cause –

  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).

on_new_report(report: scml.scml2019.common.FinancialReport)

Called whenever a financial report is published.

Parameters:

report – The financial report giving details of the standing of an agent at some time (see FinancialReport)

Remarks:

• Agents must opt-in to receive these calls by calling receive_financial_reports on their AWI

on_neg_request_rejected(req_id: str, by: List[str] | None)

Called when a requested negotiation is rejected

Parameters:

• req_id – The request ID passed to _request_negotiation

• by – A list of agents that refused to participate or None if the failure was for another reason

on_neg_request_accepted(req_id: str, mechanism: negmas.NegotiatorMechanismInterface)

Called when a requested negotiation is accepted

on_negotiation_failure(partners: List[str], annotation: Dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface, state: negmas.MechanismState) → None

Called whenever a negotiation ends without agreement

on_negotiation_success(contract: negmas.situated.Contract, mechanism: negmas.NegotiatorMechanismInterface) → None

Called whenever a negotiation ends with agreement

on_contract_cancelled(contract: negmas.situated.Contract, rejectors: List[str]) → None

Called whenever at least a partner did not sign the contract

on_contract_nullified(contract: negmas.situated.Contract, bankrupt_partner: str, compensation: float) → None

Will be called whenever a contract the agent is involved in is nullified because another partner went bankrupt

on_agent_bankrupt(agent_id: str) → None

Will be called whenever any agent goes bankrupt

Parameters:

agent_id – The ID of the agent that went bankrupt

Remarks:

• Agents can go bankrupt in two cases:

  1. Failing to pay one installments of a loan they bought and refusing (or being unable to) get another loan to pay it.

  2. 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 and respond_to_negotiation_request callbacks by pulling the bulletin-board using the helper function is_bankrupt of their AWI.

confirm_partial_execution(contract: negmas.situated.Contract, breaches: List[negmas.situated.Breach]) → bool

Will be called whenever a contract cannot be fully executed due to breaches by the other partner.

Parameters:

• contract – The contract that was breached

• breaches – A list of all the breaches committed.

Remarks:

• Will not be called if both partners committed breaches.

on_remove_cfp(cfp: scml.scml2019.common.CFP)

Called when a new CFP for a product for which the agent registered interest is removed

on_new_cfp(cfp: scml.scml2019.common.CFP) → None

Called when a new CFP for a product for which the agent registered interest is published

init()

Called to initialize the agent after the world is initialized. the AWI is accessible at this point.

set_profiles(profiles: Dict[int, ConsumptionProfile])

register_product_cfps(p: int, t: int, profile: ConsumptionProfile)

step()

Called by the simulator at every simulation step

confirm_contract_execution(contract: negmas.situated.Contract) → bool

Called before executing any agreement

static _qufun(outcome: Dict[str, Any], tau: float, profile: ConsumptionProfile)

The ufun value for quantity

respond_to_negotiation_request(cfp: scml.scml2019.common.CFP, partner: str) → negmas.negotiators.Negotiator | None

Called when a prospective partner requests a negotiation to start

set_renegotiation_agenda(contract: negmas.situated.Contract, breaches: List[negmas.situated.Breach]) → negmas.situated.RenegotiationRequest | None

Received by partners in ascending order of their total breach levels in order to set the renegotiation agenda when contract execution fails

Parameters:

• contract – The contract that was breached about which re-negotiation is offered

• breaches – The list of breaches by all parties for the breached contract.

Returns:

None if renegotiation is not to be started, otherwise a re-negotiation agenda.

respond_to_renegotiation_request(contract: negmas.situated.Contract, breaches: List[negmas.situated.Breach], agenda: negmas.situated.RenegotiationRequest) → negmas.negotiators.Negotiator | None

Called to respond to a renegotiation request

Parameters:

• agenda – Renegotiation agenda (issues to renegotiate about).

• contract – The contract that was breached

• breaches – All breaches on that contract

Returns:

None to refuse to enter the negotiation, otherwise, a negotiator to use for this negotiation.

confirm_loan(loan: scml.scml2019.common.Loan, bankrupt_if_rejected: bool) → bool

called by the world manager to confirm a loan if needed by the buyer of a contract that is about to be breached

sign_contract(contract: negmas.situated.Contract) → str | None

Called after the signing delay from contract conclusion to sign the contract. Contracts become binding only after they are signed.

on_contract_signed(contract: negmas.situated.Contract)

Called whenever a contract is signed by all partners