scml.scml2019.factory_managers ============================== .. py:module:: scml.scml2019.factory_managers Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/scml/scml2019/factory_managers/builtins/index Attributes ---------- .. autoapisummary:: scml.scml2019.factory_managers.__all__ Classes ------- .. autoapisummary:: scml.scml2019.factory_managers.FactoryManager scml.scml2019.factory_managers.DoNothingFactoryManager scml.scml2019.factory_managers.GreedyFactoryManager Package Contents ---------------- .. py:class:: FactoryManager(name=None, simulator_type: Union[str, Type[scml.scml2019.simulators.FactorySimulator]] = FastFactorySimulator) Bases: :py:obj:`scml.scml2019.agent.SCML2019Agent`, :py:obj:`abc.ABC` Base factory manager class that will be inherited by participant negmas in ANAC 2019. The agent can access the world simulation in one of two ways: 1. Attributes and methods available in the Agent-SCML2020World-Interface (See `SCMLAWI` documentation for those). 2. Attributes and methods in the `FactoryManager` object itself. All factory managers will have the following attributes and methods that simplify the interaction with the world simulation. Some of these attributes/methods are convenient ways to access functionality already available in the agent's internal `SCMLAWI`. **Attributes** *Agent information* - `id` : The unique ID assigned to this agent. This is unique system-wide and is what is used in contracts, CFPs, etc. - `name`: A name of the agent used for display purposes only. The simulator never accesses or uses this name except in printing and logging. - `uuid` : Another name of the `id` . - `type_name` : A string giving the type of the agent (as a fully qualified python class name). *Capabilities/Profiles* - `line_profiles` : A mapping specifying for each line index, all the profiles that can be run on it - `process_profiles` : A mapping specifying for each `Process` index, all the profiles used to run it in the factory - `producing` : Mapping from a product index to all manufacturing processes that can generate it - `consuming` : Mapping from a product index to all manufacturing processes that can consume it - `compiled_profiles` : All the profiles to be used by the factory belonging to this agent compiled to use process indices - `max_storage` : Maximum storage available to the agent. Zero, None or float('inf') all indicate unlimited storage. *Production Graph* (also accessible through *awi*) - `products` : List of products in the system - `processes` : List of processes in the system *Helper Objects* - `awi` : The `SCMLAWI` instance assigned to this agent. It can be used to interact with the simulation (See `SCMLAWI` documentation). - `simulator` : A `FactorySimulator` object that can be used to simulate what happens in the `Factory` assigned to this agent when given operations are conducted (e.g. production, paying money, etc). *Negotiations/Contracts* - `requested_negotiations` : A dynamic list of negotiations currently requested by the agent but not started. *Correct management of this list is only possible if the agent **always** uses `request_negotiation` method of this class (see methods later) rather than directly calling request_method on the `SCMLAWI` ( `awi` ) member. - `running_negotiations` : A dynamic list of negotiations currently running involving this agent. *Correct management of this list is only possible if the agent **always** uses `request_negotiation` method of this class (see methods later) rather than directly calling request_method on the `SCMLAWI` ( `awi` ) member. - `unsigned_contracts` : A dynamic list of negotiations contracts concluded involving this agent but not yet signed. *Correct management of this list is only possible if the agent **always** uses `request_negotiation` method of this class (see methods later) rather than directly calling request_method on the `SCMLAWI` ( `awi` ) member. *Simulation attributes* (also accessible through *awi*) - `transportation_delay` : The transportation delay in the system. - `current_step` : Current simulation step. - `immediate_negotiations` : Whether or not negotiations start immediately upon registration (default is to start on the next production step) - `negotiation_speed_multiple` : The number of negotiation rounds (steps) conducted in a single production step - `transportation_delay` : Transportation delay in the system. Default is zero **Methods** (Callable by the agent) *Actions on the world* - `request_negotiation` : Called to request a negotiation based on a `CFP` . *Scheduling and simulation helpers* - `can_expect_agreement` : Checks if it is possible in principle to get an agreement on this CFP by the time it becomes executable. **Callbacks** (Callable by the simulation) *Decision callbacks* (Called to make decisions) - Negotiation and Contracts - `respond_to_negotiation_request` : Decide whether or not to engage in a negotiation on a `CFP` that was published earlier by this factory manager. If accepted, the agent should return a `SAONegotiator` object. - `sign_contract` : Decide whether or not to sign the contract. If accepted, the agent should return its own ID. - `confirm_contract_execution` : Decide whether or not to go on with executing a contract that the agent already signed. If rejected (by returning `False` ), a refusal-to-execute breach will be recorded. - Breach related - `confirm_partial_execution` : Decide whether the agent agrees to partial execution. Called only when the the partner of this agent commits a partial breach (of level < 1) and this agent commits no breaches. - `set_renegotiation_agenda` : Decide what are the issues and ranges of acceptable values to re-negotiate about. Called only in case of breaches. - `respond_to_renegotiation_request` : Decide whether or not to engage in a re-negotiation. - Financial - `confirm_loan` : Decide whether or not to accept an offered loan. *In ANAC 2019 league, loans are not allowed and this callback will never be called by the simulator. *Time-dependent callbacks* (Information callback called at predefined times) - `init` : Called once before any production or negotiations to initiate the agent. - `step` : Called at every production step. *Information callbacks* (Called to inform the agent about events) - CFP related - `on_new_cfp` : Called whenever a `CFP` on a `Product` for which the agent has already registered interest (using `register_interest` method of its `awi`) is published. By default all agents register interest in the products they can consume or produce according to their profiles. - `on_remove_cfp` : Called whenever a `CFP` on a `Product` for which the agent has already registered interest (using `register_interest` method of its `awi`) is removed from the bulletin-board. - Negotiation related - `on_neg_request_accepted` : Called when a negotiation request of the agent is accepted - `on_neg_request_rejected` : Called when a negotiation request of the agent is rejected - `on_negotiation_success` : Called when a negotiation of which the agent is a party succeeds with an agreement. - `on_negotiation_failure` : Called when a negotiation of which the agent is a party ends without agreement. - Contract related - `on_contract_cancelled` : Called whenever a `Contract` of which the agent is a party is cancelled because the other party refused to sign it. - `on_contract_signed` : Called whenever a `Contract` of which the agent is a party is signed by both patners. - `on_contract_nullified` : Called whenever a `Contract` of which the agent is a party is nullified by the simulator as a part of bankruptcy processing. - `on_contract_executed` : Called when a contract executes completely and successfully. - `on_contract_breached` : Called when a contract is breached after complete contract processing. - Production and factory related - `on_production_failure` : Called whenever a scheduled production (see `SCMLAWI` for production commands) fails - `on_inventory_change` : Called whenever there is a change in the inventory (something is moved in or out or out of storage due to an event other than production (e.g. contract execution). - `on_cash_transfer` : Called whenever cash is transferred to or from the factory's wallet. - About other agents - `on_agent_bankrupt` : Called whenever another agent goes bankrupt - `on_new_report` : Called whenever a new report of another agent for which this agent has registered interest is published. Interest is registered using the agent's `awi` 's `receive_financial_reports` method. .. py:attribute:: transportation_delay :value: 0 Transportation delay in the world .. py:attribute:: simulator :type: Optional[scml.scml2019.simulators.FactorySimulator] :value: None The simulator used by this agent .. py:attribute:: simulator_type :type: Type[scml.scml2019.simulators.FactorySimulator] Simulator type (as a class) .. py:attribute:: current_step :value: 0 Current simulation step .. py:attribute:: max_storage :type: int :value: 0 Maximum storage available to the agent .. py:method:: init_() The initialization function called by the world directly. It does the following actions by default: 1. copies some of the static world settings to the agent to make them available without calling the AWI. 2. prepares production related properties like producing, consuming, line_profiles, compiled_profiles, etc. 3. registers interest in all products that the agent can produce or consume in its factory. 4. finally it calls any custom initialization logic implemented in `init`() .. seealso:: `init`, `step` .. py:method:: step_() Called at every time-step. This function is called directly by the world. .. py:method:: on_production_failure(failures: List[scml.scml2019.common.ProductionFailure]) -> None :abstractmethod: Called with a list of `ProductionFailure` records on production failure. .. py:method:: on_production_success(reports: List[scml.scml2019.common.ProductionReport]) -> None :abstractmethod: Called with a list of `ProductionReport` records on production success .. py:class:: DoNothingFactoryManager(name=None, simulator_type: Union[str, Type[scml.scml2019.simulators.FactorySimulator]] = FastFactorySimulator) Bases: :py:obj:`FactoryManager` The default factory manager that will be implemented by the committee of ANAC-SCML 2019 .. py:method:: init() Called to initialize the agent **after** the world is initialized. the AWI is accessible at this point. .. py:method:: step() Called by the simulator at every simulation step .. 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.Contract, mechanism: negmas.NegotiatorMechanismInterface) -> None Called whenever a negotiation ends with agreement .. py:method:: on_contract_signed(contract: negmas.Contract) -> None Called whenever a contract is signed by all partners .. py:method:: on_contract_cancelled(contract: negmas.Contract, rejectors: List[str]) -> None Called whenever at least a partner did not sign the contract .. py:method:: on_contract_executed(contract: negmas.Contract) -> None Called after successful contract execution for which the agent is one of the partners. .. py:method:: on_contract_breached(contract: negmas.Contract, breaches: List[negmas.Breach], resolution: Optional[negmas.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:: sign_contract(contract: negmas.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_nullified(contract: negmas.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.Contract, breaches: List[negmas.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) -> None Called when a new CFP for a product for which the agent registered interest is removed .. py:method:: on_production_failure(failures: List[scml.scml2019.common.ProductionFailure]) -> None Called with a list of `ProductionFailure` records on production failure. .. py:method:: respond_to_negotiation_request(cfp: scml.scml2019.common.CFP, partner: str) -> Optional[negmas.Negotiator] Called when a prospective partner requests a negotiation to start .. py:method:: confirm_contract_execution(contract: negmas.Contract) -> bool Called before executing any agreement .. py:method:: set_renegotiation_agenda(contract: negmas.Contract, breaches: List[negmas.Breach]) -> Optional[negmas.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 being breached :param breaches: All breaches on `contract` :returns: Renegotiation agenda (issues to negotiate about to avoid reporting the breaches). .. py:method:: respond_to_renegotiation_request(contract: negmas.Contract, breaches: List[negmas.Breach], agenda: negmas.RenegotiationRequest) -> Optional[negmas.Negotiator] Called to respond to a renegotiation request :param agenda: :param contract: :param breaches: Returns: .. 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:: 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:: 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_production_success(reports: List[scml.scml2019.common.ProductionReport]) -> None Called with a list of `ProductionReport` records on production success .. 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:class:: GreedyFactoryManager(name=None, simulator_type: Union[str, Type[scml.scml2019.simulators.FactorySimulator]] = FastFactorySimulator, scheduler_type: Union[str, Type[scml.scml2019.schedulers.Scheduler]] = GreedyScheduler, scheduler_params: Optional[Dict[str, Any]] = None, optimism: float = 0.0, negotiator_type: Union[str, Type[negmas.Negotiator]] = DEFAULT_NEGOTIATOR, negotiator_params: Optional[Dict[str, Any]] = None, n_retrials=5, use_consumer=True, reactive=True, sign_only_guaranteed_contracts=False, riskiness=0.0, max_insurance_premium: float = 0.1, reserved_value: float = -float('inf')) Bases: :py:obj:`DoNothingFactoryManager` The default factory manager that will be implemented by the committee of ANAC-SCML 2019 .. py:method:: on_production_failure(failures: List[scml.scml2019.common.ProductionFailure]) -> None Called with a list of `ProductionFailure` records on production failure. .. py:method:: on_production_success(reports: List[scml.scml2019.common.ProductionReport]) -> None Called with a list of `ProductionReport` records on production success .. 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:: confirm_contract_execution(contract: negmas.Contract) -> bool Called before executing any agreement .. py:method:: set_renegotiation_agenda(contract: negmas.Contract, breaches: List[negmas.Breach]) -> Optional[negmas.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 being breached :param breaches: All breaches on `contract` :returns: Renegotiation agenda (issues to negotiate about to avoid reporting the breaches). .. py:method:: respond_to_renegotiation_request(contract: negmas.Contract, breaches: List[negmas.Breach], agenda: negmas.RenegotiationRequest) -> Optional[negmas.Negotiator] Called to respond to a renegotiation request :param agenda: :param contract: :param breaches: Returns: .. py:attribute:: negotiator_type :value: 'negmas.sao.AspirationNegotiator' .. py:attribute:: negotiator_params :value: None .. py:attribute:: optimism :value: 0.0 .. py:attribute:: ufun_factory :type: Union[Type[NegotiatorUtility], Callable[[Any, Any], NegotiatorUtility]] .. py:attribute:: __reserved_value .. py:attribute:: max_insurance_premium :value: 0.1 .. py:attribute:: n_retrials :value: 5 .. py:attribute:: n_neg_trials :type: Dict[str, int] .. py:attribute:: consumer :value: None .. py:attribute:: use_consumer :value: True .. py:attribute:: reactive :value: True .. py:attribute:: sign_only_guaranteed_contracts :value: False .. py:attribute:: contract_schedules :type: Dict[str, scml.scml2019.schedulers.ScheduleInfo] .. py:attribute:: riskiness :value: 0.0 .. py:attribute:: negotiation_margin .. py:attribute:: scheduler_type :type: Type[scml.scml2019.schedulers.Scheduler] .. py:attribute:: scheduler :type: scml.scml2019.schedulers.Scheduler :value: None .. py:attribute:: scheduler_params :type: Dict[str, Any] :value: None .. py:method:: total_utility(contracts: Collection[negmas.Contract] = ()) -> float Calculates the total utility for the agent of a collection of contracts .. py:method:: init() Called to initialize the agent **after** the world is initialized. the AWI is accessible at this point. .. py:method:: respond_to_negotiation_request(cfp: scml.scml2019.common.CFP, partner: str) -> Optional[negmas.Negotiator] Called when a prospective partner requests a negotiation to start .. py:method:: on_negotiation_success(contract: negmas.Contract, mechanism: negmas.NegotiatorMechanismInterface) Called whenever a negotiation ends with agreement .. 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:: _execute_schedule(schedule: scml.scml2019.schedulers.ScheduleInfo, contract: negmas.Contract) -> None .. py:method:: sign_contract(contract: negmas.Contract) 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.Contract) Called whenever a contract is signed by all partners .. py:method:: _process_buy_cfp(cfp: scml.scml2019.common.CFP) -> None .. py:method:: _process_sell_cfp(cfp: scml.scml2019.common.CFP) .. 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:: step() Called by the simulator at every simulation step .. py:method:: can_produce(cfp: scml.scml2019.common.CFP, assume_no_further_negotiations=False) -> bool Whether or not we can produce the required item in time .. py:method:: can_secure_needs(schedule: scml.scml2019.schedulers.ScheduleInfo, step: int) Finds if it is possible in principle to arrange these needs at the given time. :param schedule: :param step: Returns: .. py:data:: __all__