scml.scml2019.consumers ======================= .. py:module:: scml.scml2019.consumers Classes ------- .. autoapisummary:: scml.scml2019.consumers.ConsumptionProfile scml.scml2019.consumers.Consumer scml.scml2019.consumers.JustInTimeConsumer Module Contents --------------- .. py:class:: ConsumptionProfile .. py:attribute:: schedule :type: Union[int, List[int]] :value: 0 .. py:attribute:: underconsumption :type: float :value: 0.1 .. py:attribute:: overconsumption :type: float :value: 0.01 .. py:attribute:: dynamicity :type: float :value: 0.0 .. py:attribute:: cv :type: float :value: 0.1 .. py:attribute:: alpha_q :type: float :value: 0.5 .. py:attribute:: alpha_u :type: float :value: 1.0 .. py:attribute:: beta_q :type: float :value: 10.0 .. py:attribute:: beta_u :type: float :value: 10.0 .. py:attribute:: tau_q :type: float :value: 2 .. py:attribute:: tau_u :type: float :value: 0.25 .. py:method:: random() :classmethod: .. py:method:: schedule_at(time: int) -> int .. py:method:: schedule_within(time: Union[int, List[int], Tuple[int, int]]) -> int .. py:method:: set_schedule_at(time: int, value: int, n_steps: int) -> None .. py:class:: Consumer(name: Optional[str] = None, ufun: Optional[negmas.UtilityFunction] = None) Bases: :py:obj:`scml.scml2019.agent.SCML2019Agent`, :py:obj:`abc.ABC` Base class of all consumer classes .. py:class:: JustInTimeConsumer(profiles: Dict[int, ConsumptionProfile] = None, negotiator_type=DEFAULT_NEGOTIATOR, consumption_horizon: Optional[int] = 20, immediate_cfp_update: bool = True, name=None) Bases: :py:obj:`Consumer` Consumer class .. py:method:: on_contract_executed(contract: negmas.situated.Contract) -> None Called after successful contract execution for which the agent is one of the partners. .. py:method:: on_contract_breached(contract: negmas.situated.Contract, breaches: List[negmas.situated.Breach], resolution: Optional[negmas.situated.Contract]) -> None Called after complete processing of a contract that involved a breach. :param contract: The contract :param breaches: All breaches committed (even if they were resolved) :param resolution: The resolution contract if re-negotiation was successful. None if not. .. py:method:: on_inventory_change(product: int, quantity: int, cause: str) -> None Received whenever something moves in or out of the factory's storage :param product: Product index. :param quantity: Negative value for products moving out and positive value for products moving in :param 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). .. py:method:: on_cash_transfer(amount: float, cause: str) -> None Received whenever money is transferred to the factory or from it. :param amount: Amount of money (negative for transfers out of the factory, positive for transfers to it). :param 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). .. py:method:: on_new_report(report: scml.scml2019.common.FinancialReport) Called whenever a financial report is published. :param 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 .. py:method:: on_neg_request_rejected(req_id: str, by: Optional[List[str]]) Called when a requested negotiation is rejected :param req_id: The request ID passed to _request_negotiation :param by: A list of agents that refused to participate or None if the failure was for another reason .. py:method:: on_neg_request_accepted(req_id: str, mechanism: negmas.NegotiatorMechanismInterface) Called when a requested negotiation is accepted .. py:method:: on_negotiation_failure(partners: List[str], annotation: Dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface, state: negmas.MechanismState) -> None Called whenever a negotiation ends without agreement .. py:method:: on_negotiation_success(contract: negmas.situated.Contract, mechanism: negmas.NegotiatorMechanismInterface) -> None Called whenever a negotiation ends with agreement .. py:method:: on_contract_cancelled(contract: negmas.situated.Contract, rejectors: List[str]) -> None Called whenever at least a partner did not sign the contract .. py:method:: 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 .. py:method:: on_agent_bankrupt(agent_id: str) -> None Will be called whenever any agent goes bankrupt :param 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. .. py:method:: 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. :param contract: The contract that was breached :param breaches: A list of all the breaches committed. Remarks: - Will not be called if both partners committed breaches. .. py:method:: on_remove_cfp(cfp: scml.scml2019.common.CFP) Called when a new CFP for a product for which the agent registered interest is removed .. py:attribute:: MAX_UNIT_PRICE :value: 100.0 .. py:attribute:: RELATIVE_MAX_PRICE :value: 1.5 .. py:attribute:: negotiator_type :value: 'negmas.sao.AspirationNegotiator' .. py:attribute:: profiles :type: Dict[int, ConsumptionProfile] .. py:attribute:: secured_quantities :type: Dict[int, int] .. py:attribute:: consumption_horizon :value: 20 .. py:attribute:: immediate_cfp_update :value: True .. py:method:: 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 .. py:method:: init() Called to initialize the agent **after** the world is initialized. the AWI is accessible at this point. .. py:method:: set_profiles(profiles: Dict[int, ConsumptionProfile]) .. py:method:: register_product_cfps(p: int, t: int, profile: ConsumptionProfile) .. py:method:: step() Called by the simulator at every simulation step .. py:method:: confirm_contract_execution(contract: negmas.situated.Contract) -> bool Called before executing any agreement .. py:method:: _qufun(outcome: Dict[str, Any], tau: float, profile: ConsumptionProfile) :staticmethod: The ufun value for quantity .. py:method:: respond_to_negotiation_request(cfp: scml.scml2019.common.CFP, partner: str) -> Optional[negmas.negotiators.Negotiator] Called when a prospective partner requests a negotiation to start .. py:method:: set_renegotiation_agenda(contract: negmas.situated.Contract, breaches: List[negmas.situated.Breach]) -> Optional[negmas.situated.RenegotiationRequest] Received by partners in ascending order of their total breach levels in order to set the renegotiation agenda when contract execution fails :param contract: The contract that was breached about which re-negotiation is offered :param 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. .. py:method:: respond_to_renegotiation_request(contract: negmas.situated.Contract, breaches: List[negmas.situated.Breach], agenda: negmas.situated.RenegotiationRequest) -> Optional[negmas.negotiators.Negotiator] Called to respond to a renegotiation request :param agenda: Renegotiation agenda (issues to renegotiate about). :param contract: The contract that was breached :param breaches: All breaches on that contract :returns: None to refuse to enter the negotiation, otherwise, a negotiator to use for this negotiation. .. py:method:: 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 .. py:method:: sign_contract(contract: negmas.situated.Contract) -> Optional[str] Called after the signing delay from contract conclusion to sign the contract. Contracts become binding only after they are signed. .. py:method:: on_contract_signed(contract: negmas.situated.Contract) Called whenever a contract is signed by all partners