scml.scml2019.awi ================= .. py:module:: scml.scml2019.awi .. autoapi-nested-parse:: Implements an agent-world-interface (see `AgentWorldInterface`) for the SCM world. Classes ------- .. autoapisummary:: scml.scml2019.awi.SCMLAWI Module Contents --------------- .. py:class:: SCMLAWI(world: negmas.situated.world.World, agent: negmas.situated.agent.Agent) Bases: :py:obj:`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: 1. Attributes and methods available in this Agent-SCML2020World-Interface 2. Attributes and methods in the `FactoryManager` object itself which provide handy shortcuts to the agent-world interface **Attributes** *Simulation settings* - `current_step` : Current simulation step - `default_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 of `Product` objects giving all products defined in the world simulation - `processes` : A list of `Process` objects giving all products defined in the world simulation *Agent Related* - `state` : The current private state available to the agent. In SCML it is a `FactoryState` object. **Methods** *Production Control* - `schedule_job` : Schedules a `Job` for production sometime in the future - `schedule_production` : Schedules production using profile number instead of a `Job` object - `cancel_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 creating `Action` 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 to `hide_funds` - `unhide_inventory` : Un-hides inventory hidden earlier with a call to `hide_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 of `FactoryManager` (i.e. use self.request_negotiation instead of self.awi.request_negotiation). This makes it possible for NegMAS to keep track of existing `requested_negotiations` and `running_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 all `FactoryManager` 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 agent - `receive_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-step - `reports_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 contract - `buy_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-board - `bb_query` : Returns all records in the given section/sections of the bulletin-board that satisfy a query - `bb_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 with ``bb_``): - **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 file - `logwarning` : Logs a warning in the world simulation log file - `loginfo` : Logs information in the world simulation log file - `logdebug` : Logs debug information in the world simulation log file .. py:method:: register_cfp(cfp: scml.scml2019.common.CFP) -> None Registers a CFP .. py:method:: register_interest(products: List[int]) -> None registers interest in receiving callbacks about CFPs related to these products .. py:method:: unregister_interest(products: List[int]) -> None registers interest in receiving callbacks about CFPs related to these products .. py:method:: remove_cfp(cfp: scml.scml2019.common.CFP) -> bool Removes a CFP .. py:method:: evaluate_insurance(contract: negmas.situated.Contract, t: int = None) -> Optional[float] Can be called to evaluate the premium for insuring the given contract against breaches committed by others :param contract: hypothetical contract :param t: time at which the policy is to be bought. If None, it means current step .. py:method:: buy_insurance(contract: negmas.situated.Contract) -> bool 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. .. py:method:: _create_annotation(cfp: scml.scml2019.common.CFP, partner: str = None) Creates full annotation based on a cfp that the agent is receiving .. py:method:: request_negotiation(cfp: scml.scml2019.common.CFP, req_id: str, roles: List[str] = None, mechanism_name: str = None, mechanism_params: Dict[str, Any] = None) -> bool Requests a negotiation with the publisher of a given CFP :param cfp: The CFP to negotiate about :param req_id: A string that is passed back to the caller in all callbacks related to this negotiation :param roles: The roles of the CFP publisher and the agent (in that order). By default no roles are passed (None) :param mechanism_name: The mechanism type to use. If not given the default mechanism from the world will be used :param mechanism_params: Parameters of the mechanism :returns: Success of failure of the negotiation request Remarks: - The `SCML2019Agent` class implements another request_negotiation method that does not receive a `req_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 the `requested_negotiations` and `running_negotiations` properties of the `SCML2019Agent` class .. py:method:: request_negotiation_about(issues: List[negmas.Issue], partners: List[str], req_id: str, roles: List[str] = None, annotation: Optional[Dict[str, Any]] = None, mechanism_name: str = None, mechanism_params: Dict[str, Any] = None) Overrides the method of the same name in the base class to disable it in SCM Worlds. **Do not call this method** .. py:method:: is_bankrupt(agent_id: str) -> bool Checks whether the given agent is bankrupt :param agent_id: Agent ID :returns: The bankruptcy state of the agent .. py:method:: reports_for(agent_id: str) -> List[scml.scml2019.common.FinancialReport] Gets all financial reports of an agent (in the order of their publication) :param agent_id: Agent ID Returns: .. py:method:: reports_at(step: int = None) -> Dict[str, scml.scml2019.common.FinancialReport] Gets all financial reports of all agents at a given step :param step: Step at which the reports are required. If None, the last set of reports is returned :returns: A dictionary with agent IDs in keys and their financial reports at the given time as values .. py:method:: receive_financial_reports(receive: bool = True, agents: Optional[List[str]] = None) -> None Registers/unregisters interest in receiving financial reports :param receive: True to receive and False to stop receiving :param agents: 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. .. py:property:: state :type: scml.scml2019.common.FactoryState 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**. .. py:property:: products :type: List[scml.scml2019.common.Product] Products in the world .. py:property:: processes :type: List[scml.scml2019.common.Process] Processes in the world .. py:method:: schedule_production(profile: int, step: int, contract: Optional[negmas.situated.Contract] = None, override: bool = True) -> None Schedules production on the agent's factory :param profile: Index of the profile in the agent's `compiled_profiles` list :param step: The step to start production according to the given profile :param contract: The contract for which the production is scheduled (optional) :param override: Whether to override existing production jobs schedules at the same time. .. py:method:: stop_production(line: int, step: int, contract: Optional[negmas.situated.Contract], override: bool = True) Stops/cancels production scheduled at the given line at the given time. :param line: One of the factory lines (index) :param step: Step to stop/cancel production at :param contract: The contract for which the job is scheduled (optional) :param override: Whether to override existing production jobs schedules at the same time. .. py:attribute:: cancel_production Stops/cancels production scheduled at the given line at the given time. :param line: One of the factory lines (index) :param step: Step to stop/cancel production at .. py:method:: schedule_job(job: scml.scml2019.common.Job, contract: Optional[negmas.situated.Contract]) Schedules production using a `Job` object. This can be used to schedule any kind of job :param job: The job description :param 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. .. py:method:: hide_inventory(product: int, quantity: int) -> None Hides the given quantity of the given product so that it is not accessible by the simulator and does not appear in reports etc. :param product: product index :param quantity: 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 .. py:method:: hide_funds(amount: float) -> None Hides the given amount of money so that it is not accessible by the simulator and does not appear in reports etc. :param amount: 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 .. py:method:: unhide_inventory(product: int, quantity: int) -> None 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. :param product: product index :param quantity: 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 .. py:method:: unhide_funds(amount: float) -> None Un-hides the given amount of money so that it is not accessible by the simulator and does not appear in reports etc. :param amount: 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