scml.scml2020 ============= .. py:module:: scml.scml2020 .. autoapi-nested-parse:: Implements the SCML 2020 world design. The detailed description of this world simulation can be found here_ . .. _here: http://www.yasserm.com/scml/scml2020.pdf Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/scml/scml2020/agent/index /autoapi/scml/scml2020/agents/index /autoapi/scml/scml2020/awi/index /autoapi/scml/scml2020/common/index /autoapi/scml/scml2020/components/index /autoapi/scml/scml2020/factory/index /autoapi/scml/scml2020/services/index /autoapi/scml/scml2020/world/index Attributes ---------- .. autoapisummary:: scml.scml2020.__all__ scml.scml2020.SYSTEM_BUYER_ID scml.scml2020.SYSTEM_SELLER_ID scml.scml2020.COMPENSATION_ID scml.scml2020.ANY_STEP scml.scml2020.NO_COMMAND scml.scml2020.ANY_LINE scml.scml2020.INFINITE_COST scml.scml2020.QUANTITY scml.scml2020.TIME scml.scml2020.UNIT_PRICE scml.scml2020.__all__ scml.scml2020.__all__ Classes ------- .. autoapisummary:: scml.scml2020.SCML2020Agent scml.scml2020.OneShotAdapter scml.scml2020.RandomAgent scml.scml2020.DoNothingAgent scml.scml2020.IndependentNegotiationsAgent scml.scml2020.MarketAwareIndependentNegotiationsAgent scml.scml2020.BuyCheapSellExpensiveAgent scml.scml2020.MarketAwareBuyCheapSellExpensiveAgent scml.scml2020.DecentralizingAgent scml.scml2020.IndDecentralizingAgent scml.scml2020.DecentralizingAgentWithLogging scml.scml2020.MarketAwareDecentralizingAgent scml.scml2020.MarketAwareIndDecentralizingAgent scml.scml2020.ReactiveAgent scml.scml2020.MarketAwareReactiveAgent scml.scml2020.MovingRangeAgent scml.scml2020.MarketAwareMovingRangeAgent scml.scml2020.SatisficerAgent scml.scml2020.AWI scml.scml2020.FactoryState scml.scml2020.FinancialReport scml.scml2020.FactoryProfile scml.scml2020.Failure scml.scml2020.ExogenousContract scml.scml2020.ProductionStrategy scml.scml2020.SupplyDrivenProductionStrategy scml.scml2020.DemandDrivenProductionStrategy scml.scml2020.TradeDrivenProductionStrategy scml.scml2020.TradePredictionStrategy scml.scml2020.FixedTradePredictionStrategy scml.scml2020.ExecutionRatePredictionStrategy scml.scml2020.FixedERPStrategy scml.scml2020.MeanERPStrategy scml.scml2020.MarketAwareTradePredictionStrategy scml.scml2020.SignAll scml.scml2020.SignAllPossible scml.scml2020.KeepOnlyGoodPrices scml.scml2020.NegotiationManager scml.scml2020.StepNegotiationManager scml.scml2020.IndependentNegotiationsManager scml.scml2020.MovingRangeNegotiationManager scml.scml2020.Simulation scml.scml2020.Factory scml.scml2020.SCML2020World scml.scml2020.SCML2021World scml.scml2020.SCML2022World scml.scml2020.SCML2023World scml.scml2020.SCML2024World scml.scml2020.Failure scml.scml2020.AWI Functions --------- .. autoapisummary:: scml.scml2020.is_system_agent scml.scml2020.builtin_agent_types Package Contents ---------------- .. py:class:: SCML2020Agent(name: str | None = None, type_postfix: str = '', preferences: negmas.preferences.Preferences | None = None, ufun: negmas.preferences.UtilityFunction | None = None) Bases: :py:obj:`negmas.Agent` Base class for all SCML2020 agents (factory managers) .. py:method:: reset() .. py:method:: is_clean() -> bool .. py:method:: init() Called to initialize the agent **after** the world is initialized. the AWI is accessible at this point. .. py:method:: before_step() .. py:method:: step_() Called at every time-step. This function is called directly by the world. .. py:method:: step() Called by the simulator at every simulation step .. py:method:: to_dict() .. py:method:: _respond_to_negotiation_request(initiator: str, partners: List[str], issues: List[negmas.Issue], annotation: Dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface, role: Optional[str], req_id: Optional[str]) -> Optional[negmas.Negotiator] Called by the mechanism to ask for joining a negotiation. The agent can refuse by returning a None :param initiator: The ID of the agent that initiated the negotiation request :param partners: The partner list (will include this agent) :param issues: The list of issues :param annotation: Any annotation specific to this negotiation. :param mechanism: The mechanism that started the negotiation :param role: The role of this agent in the negotiation :param req_id: The req_id passed to the AWI when starting the negotiation (only to the initiator). :returns: None to refuse the negotiation or a `Negotiator` object appropriate to the given mechanism to accept it. Remarks: - It is expected that world designers will introduce a better way to respond and override this function to call it .. 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:: on_contract_executed(contract: negmas.Contract) -> None Called after successful contract execution for which the agent is one of the partners. .. 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:: 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:property:: internal_state :type: Dict[str, Any] Returns the internal state of the agent for debugging purposes .. 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_agent_bankrupt(agent: str, contracts: List[negmas.Contract], quantities: List[int], compensation_money: int) -> None Called whenever a contract is nullified (because the partner is bankrupt) :param agent: The ID of the agent that went bankrupt. :param contracts: All future contracts between this agent and the bankrupt agent. :param quantities: The actual quantities that these contracts will be executed at. :param compensation_money: The compensation money that is already added to the agent's wallet (if ANY). Remarks: - compensation_money will be nonzero iff immediate_compensation is enabled for this world .. py:method:: on_failures(failures: List[scml.scml2020.common.Failure]) -> None Called whenever there are failures either in production or in execution of guaranteed transactions :param failures: A list of `Failure` s. .. py:method:: respond_to_negotiation_request(initiator: str, issues: List[negmas.Issue], annotation: Dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface) -> Optional[negmas.Negotiator] Called whenever another agent requests a negotiation with this agent. :param initiator: The ID of the agent that requested this negotiation :param issues: Negotiation issues :param annotation: Annotation attached with this negotiation :param mechanism: The `NegotiatorMechanismInterface` interface to the mechanism to be used for this negotiation. :returns: None to reject the negotiation, otherwise a negotiator .. py:method:: confirm_production(commands: numpy.ndarray, balance: int, inventory) -> numpy.ndarray Called just before production starts at every time-step allowing the agent to change what is to be produced in its factory :param commands: an n_lines vector giving the process to be run at every line (NO_COMMAND indicates nothing to be processed :param balance: The current balance of the factory :param inventory: an n_products vector giving the number of items available in the inventory of every product type. :returns: an n_lines vector giving the process to be run at every line (NO_COMMAND indicates nothing to be processed Remarks: - Not called in SCML2020 competition. - The inventory will contain zero items of all products that the factory does not buy or sell - The default behavior is to just retrun commands confirming production of everything. .. py:method:: sign_all_contracts(contracts: List[negmas.Contract]) -> List[Optional[str]] Signs all contracts .. py:class:: OneShotAdapter(oneshot_type: Union[str, scml.oneshot.agent.OneShotAgent], oneshot_params: Dict[str, Any], obj: Optional[scml.oneshot.agent.OneShotAgent] = None, name=None, type_postfix='', ufun=None) Bases: :py:obj:`scml.scml2020.components.signing.SignAll`, :py:obj:`scml.scml2020.components.production.DemandDrivenProductionStrategy`, :py:obj:`scml.scml2020.components.trading.MarketAwareTradePredictionStrategy`, :py:obj:`SCML2020Agent`, :py:obj:`negmas.situated.Adapter`, :py:obj:`scml.oneshot.mixins.OneShotUFunCreatorMixin` An adapter allowing agents developed for SCML-OneShot to run in `SCML2020World` simulations. .. py:attribute:: _obj :type: SCML2020Agent .. py:method:: init() Called to initialize the agent **after** the world is initialized. the AWI is accessible at this point. .. py:property:: price_multiplier .. py:method:: _make_issues(product) .. py:method:: before_step() .. py:method:: step() Called by the simulator at every simulation step .. py:method:: make_ufun(add_exogenous: bool) .. py:method:: to_dict() .. py:method:: respond_to_negotiation_request(initiator, issues, annotation, mechanism) Called whenever another agent requests a negotiation with this agent. :param initiator: The ID of the agent that requested this negotiation :param issues: Negotiation issues :param annotation: Annotation attached with this negotiation :param mechanism: The `NegotiatorMechanismInterface` interface to the mechanism to be used for this negotiation. :returns: None to reject the negotiation, otherwise a negotiator .. py:method:: get_disposal_cost() -> float .. py:method:: get_shortfall_penalty_mean() .. py:method:: get_disposal_cost_mean() .. py:method:: get_shortfall_penalty_dev() .. py:method:: get_disposal_cost_dev() .. py:method:: get_storage_cost_mean() .. py:method:: get_storage_cost_dev() .. py:method:: get_profile() .. py:method:: get_shortfall_penalty() .. py:method:: get_current_balance() .. py:method:: get_exogenous_output() -> Tuple[int, int] .. py:method:: get_exogenous_input() -> Tuple[int, int] .. py:property:: is_perishable :type: bool Are all products perishable (original design of OneShot) .. py:property:: current_disposal_cost :type: float Cost of storing one unit (penalizes buying too much/ selling too little) .. py:property:: current_storage_cost :type: float Cost of storing one unit (penalizes buying too much/ selling too little) .. py:property:: current_shortfall_penalty :type: float Cost of failure to deliver one unit (penalizes buying too little / selling too much) .. py:property:: allow_zero_quantity :type: bool Does negotiations allow zero quantity? .. py:data:: __all__ .. py:class:: RandomAgent(*args, **kwargs) Bases: :py:obj:`scml.scml2020.agents.indneg.IndependentNegotiationsAgent` An agent that negotiates randomly. .. py:method:: create_ufun(is_seller: bool, issues=None, outcomes=None) Creates a utility function .. py:class:: DoNothingAgent(name: str | None = None, type_postfix: str = '', preferences: negmas.preferences.Preferences | None = None, ufun: negmas.preferences.UtilityFunction | None = None) Bases: :py:obj:`scml.scml2020.agent.SCML2020Agent` An agent that does nothing for the whole length of the simulation .. py:method:: respond_to_negotiation_request(initiator: str, issues: List[negmas.Issue], annotation: Dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface) -> Optional[negmas.Negotiator] Called whenever another agent requests a negotiation with this agent. :param initiator: The ID of the agent that requested this negotiation :param issues: Negotiation issues :param annotation: Annotation attached with this negotiation :param mechanism: The `NegotiatorMechanismInterface` interface to the mechanism to be used for this negotiation. :returns: None to reject the negotiation, otherwise a negotiator .. py:method:: sign_all_contracts(contracts: List[negmas.Contract]) -> List[Optional[str]] Signs all contracts .. py:method:: on_contracts_finalized(signed: List[negmas.Contract], cancelled: List[negmas.Contract], rejectors: List[List[str]]) -> None 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) :param signed: A list of signed contracts. These are binding :param cancelled: A list of cancelled contracts. These are not binding :param rejectors: 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 and `on_contract_cancelled` for cancelled contracts .. py:method:: step() Called by the simulator at every simulation step .. py:method:: init() Called to initialize the agent **after** the world is initialized. the AWI is accessible at this point. .. py:method:: on_agent_bankrupt(agent: str, contracts: List[negmas.Contract], quantities: List[int], compensation_money: int) -> None Called whenever a contract is nullified (because the partner is bankrupt) :param agent: The ID of the agent that went bankrupt. :param contracts: All future contracts between this agent and the bankrupt agent. :param quantities: The actual quantities that these contracts will be executed at. :param compensation_money: The compensation money that is already added to the agent's wallet (if ANY). Remarks: - compensation_money will be nonzero iff immediate_compensation is enabled for this world .. py:method:: on_failures(failures: List[scml.scml2020.common.Failure]) -> None Called whenever there are failures either in production or in execution of guaranteed transactions :param failures: A list of `Failure` s. .. 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_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:class:: IndependentNegotiationsAgent(*args, **kwargs) Bases: :py:obj:`scml.scml2020.components.negotiation.IndependentNegotiationsManager`, :py:obj:`scml.scml2020.components.prediction.FixedTradePredictionStrategy`, :py:obj:`scml.scml2020.components.trading.ReactiveTradingStrategy`, :py:obj:`scml.scml2020.world.SCML2020Agent` Implements the base class for agents that negotiate independently with different partners. These agents do not take production capacity, availability of materials or any other aspects of the simulation into account. They are to serve only as baselines. Remarks: - `IndependentNegotiationsAgent` agents assume that each production process has one input type with the same index as itself and one output type with one added to the index (i.e. process $i$ takes product $i$ as input and creates product $i+1$ as output. - It does not assume that all lines have the same production cost (it uses the average cost though). - It does not assume that the agent has a single production process. .. py:method:: acceptable_unit_price(step: int, sell: bool) -> int Returns the maximum/minimum acceptable unit price for buying/selling at the given time-step :param step: Simulation step :param sell: Sell or buy .. py:method:: target_quantity(step: int, sell: bool) -> int Returns the target quantity to sell/buy at a given time-step :param step: Simulation step :param sell: Sell or buy .. py:class:: MarketAwareIndependentNegotiationsAgent(*args, buying_margin=None, selling_margin=None, min_price_margin=0.5, max_price_margin=0.5, **kwargs) Bases: :py:obj:`scml.scml2020.components.signing.KeepOnlyGoodPrices`, :py:obj:`IndependentNegotiationsAgent` Implements the base class for agents that negotiate independently with different partners using trading/catalog prices to control signing These agents do not take production capacity, availability of materials or any other aspects of the simulation into account. They are to serve only as baselines. Remarks: - `IndependentNegotiationsAgent` agents assume that each production process has one input type with the same index as itself and one output type with one added to the index (i.e. process $i$ takes product $i$ as input and creates product $i+1$ as output. - It does not assume that all lines have the same production cost (it uses the average cost though). - It does not assume that the agent has a single production process. .. py:class:: BuyCheapSellExpensiveAgent(*args, **kwargs) Bases: :py:obj:`scml.scml2020.agents.indneg.IndependentNegotiationsAgent` An agent that tries to buy cheap and sell expensive but does not care about production scheduling. .. py:method:: create_ufun(is_seller: bool, issues=None, outcomes=None) Creates a utility function .. py:class:: MarketAwareBuyCheapSellExpensiveAgent(*args, buying_margin=None, selling_margin=None, min_price_margin=0.5, max_price_margin=0.5, **kwargs) Bases: :py:obj:`scml.scml2020.agents.indneg.MarketAwareIndependentNegotiationsAgent`, :py:obj:`BuyCheapSellExpensiveAgent` An agent that tries to buy cheap and sell expensive but does not care about production scheduling. .. py:class:: DecentralizingAgent(*args, negotiator_type: Union[negmas.SAONegotiator, str] = AspirationNegotiator, negotiator_params: Optional[Dict[str, Any]] = None, **kwargs) Bases: :py:obj:`_NegotiationCallbacks`, :py:obj:`scml.scml2020.components.StepNegotiationManager`, :py:obj:`scml.scml2020.components.trading.PredictionBasedTradingStrategy`, :py:obj:`scml.scml2020.components.SupplyDrivenProductionStrategy`, :py:obj:`scml.scml2020.world.SCML2020Agent` A negotiation manager that controls a controller and another for selling for every timestep :param negotiator_type: The negotiator type to use to manage all negotiations :param negotiator_params: Paramters of the negotiator Provides: - `all_negotiations_concluded` Requires: - `acceptable_unit_price` - `target_quantity` - OPTIONALLY `target_quantities` Hooks Into: - `init` - `respond_to_negotiation_request` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:class:: IndDecentralizingAgent(*args, negotiator_type: Union[negmas.SAONegotiator, str] = AspirationNegotiator, negotiator_params: Optional[Dict[str, Any]] = None, **kwargs) Bases: :py:obj:`_NegotiationCallbacks`, :py:obj:`scml.scml2020.components.IndependentNegotiationsManager`, :py:obj:`scml.scml2020.components.trading.PredictionBasedTradingStrategy`, :py:obj:`scml.scml2020.components.SupplyDrivenProductionStrategy`, :py:obj:`scml.scml2020.world.SCML2020Agent` A negotiation manager that manages independent negotiators that do not share any information once created :param negotiator_type: The negotiator type to use to manage all negotiations :param negotiator_params: Parameters of the negotiator Requires: - `create_ufun` - `acceptable_unit_price` - `target_quantity` - OPTIONALLY `target_quantities` Hooks Into: - `respond_to_negotiation_request` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:method:: create_ufun(is_seller: bool, issues=None, outcomes=None) Creates a utility function .. py:class:: DecentralizingAgentWithLogging(*args, **kwargs) Bases: :py:obj:`_NegotiationCallbacks`, :py:obj:`scml.scml2020.components.StepNegotiationManager`, :py:obj:`scml.scml2020.components.trading.PredictionBasedTradingStrategy`, :py:obj:`scml.scml2020.components.SupplyDrivenProductionStrategy`, :py:obj:`scml.scml2020.world.SCML2020Agent` A negotiation manager that controls a controller and another for selling for every timestep :param negotiator_type: The negotiator type to use to manage all negotiations :param negotiator_params: Paramters of the negotiator Provides: - `all_negotiations_concluded` Requires: - `acceptable_unit_price` - `target_quantity` - OPTIONALLY `target_quantities` Hooks Into: - `init` - `respond_to_negotiation_request` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:class:: MarketAwareDecentralizingAgent(*args, buying_margin=None, selling_margin=None, min_price_margin=0.5, max_price_margin=0.5, **kwargs) Bases: :py:obj:`scml.scml2020.components.prediction.MarketAwareTradePredictionStrategy`, :py:obj:`_NegotiationCallbacks`, :py:obj:`scml.scml2020.components.MovingRangeNegotiationManager`, :py:obj:`scml.scml2020.components.trading.PredictionBasedTradingStrategy`, :py:obj:`scml.scml2020.components.signing.KeepOnlyGoodPrices`, :py:obj:`scml.scml2020.components.SupplyDrivenProductionStrategy`, :py:obj:`scml.scml2020.world.SCML2020Agent` Predicts an amount based on publicly available market information. Falls back to fixed prediction if no information is available Hooks Into: - `internal_state` - `on_contracts_finalized` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:class:: MarketAwareIndDecentralizingAgent(*args, buying_margin=None, selling_margin=None, min_price_margin=0.5, max_price_margin=0.5, **kwargs) Bases: :py:obj:`scml.scml2020.components.signing.KeepOnlyGoodPrices`, :py:obj:`scml.scml2020.components.prediction.MarketAwareTradePredictionStrategy`, :py:obj:`IndDecentralizingAgent` Signs all contracts that have good prices Overrides: - `sign_all_contracts` .. attribute:: - buying_margin The margin from the catalog price to allow for buying. The agent will never buy at a price higher than the catalog price by more than this margin (relative to catalog price). .. attribute:: - selling_margin The margin from the catalog price to allow for selling. The agent will never sell at a price lower than the catalog price by more than this margin (relative to catalog price). Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:class:: ReactiveAgent(*args, negotiator_type: Union[negmas.SAONegotiator, str] = AspirationNegotiator, negotiator_params: Optional[Dict[str, Any]] = None, **kwargs) Bases: :py:obj:`scml.scml2020.components.StepNegotiationManager`, :py:obj:`scml.scml2020.components.trading.ReactiveTradingStrategy`, :py:obj:`scml.scml2020.components.production.TradeDrivenProductionStrategy`, :py:obj:`scml.scml2020.components.FixedTradePredictionStrategy`, :py:obj:`scml.scml2020.world.SCML2020Agent` A negotiation manager that controls a controller and another for selling for every timestep :param negotiator_type: The negotiator type to use to manage all negotiations :param negotiator_params: Paramters of the negotiator Provides: - `all_negotiations_concluded` Requires: - `acceptable_unit_price` - `target_quantity` - OPTIONALLY `target_quantities` Hooks Into: - `init` - `respond_to_negotiation_request` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:method:: acceptable_unit_price(step: int, sell: bool) -> int Returns the maximum/minimum acceptable unit price for buying/selling at the given time-step :param step: Simulation step :param sell: Sell or buy .. py:method:: target_quantity(step: int, sell: bool) -> int Returns the target quantity to sell/buy at a given time-step :param step: Simulation step :param sell: Sell or buy .. py:method:: target_quantities(steps: Tuple[int, int], sell: bool) -> numpy.ndarray Implemented for speed but not really required .. py:class:: MarketAwareReactiveAgent(*args, buying_margin=None, selling_margin=None, min_price_margin=0.5, max_price_margin=0.5, **kwargs) Bases: :py:obj:`scml.scml2020.components.signing.KeepOnlyGoodPrices`, :py:obj:`ReactiveAgent` Signs all contracts that have good prices Overrides: - `sign_all_contracts` .. attribute:: - buying_margin The margin from the catalog price to allow for buying. The agent will never buy at a price higher than the catalog price by more than this margin (relative to catalog price). .. attribute:: - selling_margin The margin from the catalog price to allow for selling. The agent will never sell at a price lower than the catalog price by more than this margin (relative to catalog price). Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:class:: MovingRangeAgent(*args, price_weight=0.7, utility_threshold=0.9, time_threshold=0.9, time_horizon=0.1, min_price_margin=0.5, max_price_margin=0.5, **kwargs) Bases: :py:obj:`scml.scml2020.components.MovingRangeNegotiationManager`, :py:obj:`scml.scml2020.components.trading.PredictionBasedTradingStrategy`, :py:obj:`scml.scml2020.components.SupplyDrivenProductionStrategy`, :py:obj:`scml.scml2020.world.SCML2020Agent` My negotiation strategy :param price_weight: The relative importance of price in the utility calculation. :param utility_threshold: The fraction of maximum utility above which all offers will be accepted. :param time_threshold: The fraction of the negotiation time after which any valid offers will be accepted. :param time_range: The time-range for each controller as a fraction of the number of simulation steps Hooks Into: - `init` - `step` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:class:: MarketAwareMovingRangeAgent(*args, min_price_margin=0.5, max_price_margin=0.5, **kwargs) Bases: :py:obj:`scml.scml2020.components.prediction.MarketAwareTradePredictionStrategy`, :py:obj:`MovingRangeAgent` Predicts an amount based on publicly available market information. Falls back to fixed prediction if no information is available Hooks Into: - `internal_state` - `on_contracts_finalized` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:class:: SatisficerAgent(*args, target_productivity=1.0, satisfying_profit=0.15, acceptable_loss=0.02, price_range=0.4, concession_rate_price=1.0, concession_rate_quantity=1.0, concession_rate_time=1.0, market_share=1, horizon=5, **kwargs) Bases: :py:obj:`scml.scml2020.agent.SCML2020Agent` A simple monolithic agent that tries to *carefully* make small profit every step. :param target_productivity: The productivity level targeted by the agent defined as the fraction of its lines to be active per step. :param satisfying_profit: A profit amount considered satisfactory. Used when deciding negotiation agenda and signing to decide if a price is a good price (see `_good_price()`). A fraction of the trading price. :param acceptable_loss: A fraction of trading price that the seller/buyer is willing to go under/over the current trading price during negotiation. :param price_range: The total range around the trading price for negotiation agendas. :param concession_rate_price: The exponent of the consession curve for price. :param concession_rate_quantity: The exponent of the consession curve for quantity. :param concession_rate_time: The exponent of the consession curve for time. :param market_share: An integer specifying the expected share of the agent in the market. The agent will assume that it can get up to (market_share / (n_competitors + market_share -1)) of all sales and supplies where `n_competitors` is the number of agents at the same production level. Setting it to 1 means that the agent assumes it will get the same amount of trade as all other agents. Setting it to infinity means that the agent will assume it will take all the trade in the market :param horizon: Time horizon for negotiations. If None, the exogenous_contracts_revelation horizon will be used .. py:attribute:: horizon :value: 5 .. py:attribute:: satisfying_profit :value: 0.15 .. py:attribute:: target_productivity :value: 1.0 .. py:attribute:: price_range :value: 0.4 .. py:attribute:: ep :value: 1.0 .. py:attribute:: eq :value: 1.0 .. py:attribute:: et :value: 1.0 .. py:attribute:: acceptable_loss :value: 0.02 .. py:attribute:: last_q .. py:attribute:: last_t .. py:attribute:: market_share :value: 1 .. py:method:: init() Called once .. py:method:: before_step() Called at at the BEGINNING of every production step (day) .. py:method:: step() Called at the end of the day. Will request all negotiations .. py:method:: respond_to_negotiation_request(initiator, issues, annotation, mechanism) Called whenever another agent requests a negotiation with this agent. :param initiator: The ID of the agent that requested this negotiation :param issues: Negotiation issues :param annotation: Annotation attached with this negotiation :param mechanism: The `NegotiatorMechanismInterface` interface to the mechanism to be used for this negotiation. :returns: None to reject the negotiation, otherwise a negotiator .. py:method:: sign_all_contracts(contracts) Signs all contracts .. py:method:: 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) :param signed: A list of signed contracts. These are binding :param cancelled: A list of cancelled contracts. These are not binding :param rejectors: 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 and `on_contract_cancelled` for cancelled contracts .. py:method:: do_production() -> int .. py:method:: propose(state: negmas.sao.SAOState, ami: negmas.sao.SAONMI, is_selling: bool, is_requested: bool) Used to propose to the opponent :param state: mechanism state including current round :param ami: Agent-mechanism-interface for accessing the negotiation mechanism :param offer: The offer proposed by the partner :param is_selling: Whether the agent is selling to this partner :param is_requested: Whether the agent requested this negotiation .. py:method:: respond(state, ami, is_selling, is_requested) Responds to an offer from one partner. :param state: mechanism state including current round :param ami: Agent-mechanism-interface for accessing the negotiation mechanism :param offer: The offer proposed by the partner :param is_selling: Whether the agent is selling to this partner :param is_requested: Whether the agent requested this negotiation Remarks: - The main idea is to accept offers that are within the quantity limits for the delivery day if its price is good enough for the current stage of the negotiation. - During negotiation, the agent starts accepting highest/lowest prices for selling/buying and gradually conceeds to the minimally acceptable price (`good_price`) defined as being `acceptable_loss` above/below the trading price for buying/selling. .. py:method:: on_negotiation_failure(partners, annotation, mechanism, state) Called when a negotiation fails .. py:method:: on_negotiation_success(contract, mechanism) Called when a negotiation fails .. py:method:: _remove_tentative_offer(selling, partner) Removes my last offer from the tentative offers .. py:method:: _is_good_price(is_selling: bool, u: float, slack: float = 0.0) Checks whether a price is good relative to current trading prices, and satisfying profit (with possible slack). .. py:class:: AWI(world: negmas.situated.world.World, agent: negmas.situated.agent.Agent) Bases: :py:obj:`negmas.AgentWorldInterface` The Agent SCML2020World Interface for SCML2020 world. This class contains all the methods needed to access the simulation to extract information which are divided into 5 groups: Static World Information: Information about the world and the agent that does not change over time. These include: A. Market Information: - *n_products*: Number of products in the production chain. - *n_processes*: Number of processes in the production chain. - *n_competitors*: Number of other factories on the same production level. - *all_suppliers*: A list of all suppliers by product. - *all_consumers*: A list of all consumers by product. - *catalog_prices*: A list of the catalog prices (by product). - *inputs*: Inputs to every manufacturing process. - *outputs*: Outputs to every manufacturing process. - *is_system*: Is the given system ID corresponding to a system agent? - *is_bankrupt*: Is the given agent bankrupt (None asks about self)? - *current_step*: Current simulation step (inherited from `negmas.situated.AgentWorldInterface` ). - *n_steps*: Number of simulation steps (inherited from `negmas.situated.AgentWorldInterface` ). - *relative_time*: fraction of the simulation completed (inherited from `negmas.situated.AgentWorldInterface`). - *settings*: The system settings (inherited from `negmas.situated.AgentWorldInterface` ). B. Agent Information: - *profile*: Gives the agent profile including its production cost, number of production lines, input product index, mean of its delivery penalties, mean of its disposal costs, standard deviation of its shortfall penalties and standard deviation of its disposal costs. See `OneShotProfile` for full description. This information is private information and no other agent knows it. - *n_lines*: the number of production lines in the factory (private information). - *is_first_level*: Is the agent in the first production level (i.e. it is an input agent that buys the raw material). - *is_last_level*: Is the agent in the last production level (i.e. it is an output agent that sells the final product). - *is_middle_level*: Is the agent neither a first level nor a last level agent - *my_input_product*: The input product to the factory controlled by the agent. - *my_output_product*: The output product from the factory controlled by the agent. - *my_input_products*: All input products of a factory controlled by the agent. Currently, it is always a list of one item. For future compatibility. - *my_output_products*: All output products of a factory controlled by the agent. Currently, it is always a list of one item. For future compatibility. - *available_for_production*: Returns the line-step slots available for production. - *level*: The production level which is numerically the same as the input product. - *my_suppliers*: A list of IDs for all suppliers to the agent (i.e. agents that can sell the input product of the agent). - *my_consumers*: A list of IDs for all consumers to the agent (i.e. agents that can buy the output product of the agent). - *penalties_scale*: The scale at which to calculate disposal cost/delivery penalties. "trading" and "catalog" mean trading and catalog prices. "unit" means the contract's unit price while "none" means that disposal cost/shortfall penalty are absolute. - *n_input_negotiations*: Number of negotiations with suppliers. - *n_output_negotiations*: Number of negotiations with consumers. - *state*: The full state of the agent ( `FactoryState` ). - *current_balance*: The current balance of the agent - *current_inventory*: The current inventory of the agent (quantity per product) Dynamic World Information: Information about the world and the agent that changes over time. A. Market Information: - *trading_prices*: The trading prices of all products. This information is only available if `publish_trading_prices` is set in the world. - *exogenous_contract_summary*: A list of n_products tuples each giving the total quantity and average price of exogenous contracts for a product. This information is only available if `publish_exogenous_summary` is set in the world. B. Other Agents' Information: - *reports_of_agent*: Gives all past financial reports of a given agent. See `FinancialReport` for details. - *reports_at_step*: Gives all reports of all agents at a given step. See `FinancialReport` for details. C. Current Negotiations Information: - *current_input_issues*: The current issues for all negotiations to buy the input product of the agent. If the agent is at level zero, this will be empty. - *current_output_issues*: The current issues for all negotiations to buy the output product of the agent. If the agent is at level n_products - 1, this will be empty. D. Agent Information: - *spot_market_quantity*: The quantity the agent bought from the spot market at a given step - *spot_market_loss*: The spot market loss for the agent. Actions: A. Negotiation Control: - *request_negotiations*: Requests a set of negotiations controlled by a single controller. - *request_negotiation*: Requests a negotiation controlled by a single negotiator. B. Production Control: - *schedule_production*: Schedules production using one of the predefined scheduling strategies. - *order_production*: Orders production directly for the current step. - *set_commands*: Sets production commands directly on the factory. - *cancel_production*: Cancels a scheduled production command. Services (All inherited from `negmas.situated.AgentWorldInterface`): - *logdebug/loginfo/logwarning/logerror*: Logs to the world log at the given log level. - *logdebug_agent/loginf_agnet/...*: Logs to the agent specific log at the given log level. - *bb_query*: Queries the bulletin-board. - *bb_read*: Read a section of the bulletin-board. .. py:method:: request_negotiations(is_buy: bool, product: int, quantity: Union[int, Tuple[int, int]], unit_price: Union[int, Tuple[int, int]], time: Union[int, Tuple[int, int]], controller: Optional[negmas.SAOController] = None, negotiators: List[negmas.Negotiator] = None, partners: List[str] = None, extra: Dict[str, Any] = None, copy_partner_id=True) -> bool Requests a negotiation :param is_buy: If True the negotiation is about buying otherwise selling. :param product: The product to negotiate about :param quantity: The minimum and maximum quantities. Passing a single value q is equivalent to passing (q,q) :param unit_price: The minimum and maximum unit prices. Passing a single value u is equivalent to passing (u,u) :param time: The minimum and maximum delivery step. Passing a single value t is equivalent to passing (t,t) :param controller: The controller to manage the complete set of negotiations :param negotiators: An optional list of negotiators to use for negotiating with the given partners (in the same order). :param partners: ID of all the partners to negotiate with. :param extra: Extra information accessible through the negotiation annotation to the caller :param copy_partner_id: If true, the partner ID will be copied to the negotiator ID :returns: `True` if the partner accepted and the negotiation is ready to start Remarks: - You can either use controller or negotiators. One of them must be None. - All negotiations will use the following issues **in order**: quantity, time, unit_price - Negotiations with bankrupt agents or on invalid products (see next point) will be automatically rejected - Valid products for a factory are the following (any other products are not valid): 1. Buying an input product (i.e. product $\in$ `my_input_products` ) and an output product if the world settings allows it (see `allow_buying_output`) 1. Selling an output product (i.e. product $\in$ `my_output_products` ) and an input product if the world settings allows it (see `allow_selling_input`) .. py:method:: request_negotiation(is_buy: bool, product: int, quantity: Union[int, Tuple[int, int]], unit_price: Union[int, Tuple[int, int]], time: Union[int, Tuple[int, int]], partner: str, negotiator: negmas.SAONegotiator, extra: Dict[str, Any] = None) -> bool Requests a negotiation :param is_buy: If True the negotiation is about buying otherwise selling. :param product: The product to negotiate about :param quantity: The minimum and maximum quantities. Passing a single value q is equivalent to passing (q,q) :param unit_price: The minimum and maximum unit prices. Passing a single value u is equivalent to passing (u,u) :param time: The minimum and maximum delivery step. Passing a single value t is equivalent to passing (t,t) :param partner: ID of the partner to negotiate with. :param negotiator: The negotiator to use for this negotiation (if the partner accepted to negotiate) :param extra: Extra information accessible through the negotiation annotation to the caller :returns: `True` if the partner accepted and the negotiation is ready to start Remarks: - All negotiations will use the following issues **in order**: quantity, time, unit_price - Negotiations with bankrupt agents or on invalid products (see next point) will be automatically rejected - Valid products for a factory are the following (any other products are not valid): 1. Buying an input product (i.e. product $\in$ `my_input_products` ) and an output product if the world settings allows it (see `allow_buying_output`) 1. Selling an output product (i.e. product $\in$ `my_output_products` ) and an input product if the world settings allows it (see `allow_selling_input`) .. py:method:: schedule_production(process: int, repeats: int, step: Union[int, Tuple[int, int]] = ANY_STEP, line: int = ANY_LINE, override: bool = True, method: str = 'latest', partial_ok: bool = False) -> Tuple[numpy.ndarray, numpy.ndarray] Orders the factory to run the given process at the given line at the given step :param process: The process to run :param repeats: How many times to repeat the process :param step: The simulation step or a range of steps. The special value ANY_STEP gives the factory the freedom to schedule production at any step in the present or future. :param line: The production line. The special value ANY_LINE gives the factory the freedom to use any line :param override: Whether to override existing production commands or not :param method: When to schedule the command if step was set to a range. Options are latest, earliest :param partial_ok: If true, allows partial scheduling :returns: Tuple[int, int] giving the steps and lines at which production is scheduled. Remarks: - The step cannot be in the past. Production can only be ordered for current and future steps - ordering production of process -1 is equivalent of `cancel_production` only if both step and line are given .. py:method:: order_production(process: int, steps: numpy.ndarray, lines: numpy.ndarray) -> None Orders production of the given process :param process: The process to run :param steps: The time steps to run the process at as an np.ndarray :param lines: The corresponding lines to run the process at Remarks: - len(steps) must equal len(lines) - No checks are done in this function. It is expected to be used after calling `available_for_production` .. py:method:: available_for_production(repeats: int, step: Union[int, Tuple[int, int]] = ANY_STEP, line: int = ANY_LINE, override: bool = True, method: str = 'latest') -> Tuple[numpy.ndarray, numpy.ndarray] Finds available times and lines for scheduling production. :param repeats: How many times to repeat the process :param step: The simulation step or a range of steps. The special value ANY_STEP gives the factory the freedom to schedule production at any step in the present or future. :param line: The production line. The special value ANY_LINE gives the factory the freedom to use any line :param override: Whether to override any existing commands at that line at that time. :param method: When to schedule the command if step was set to a range. Options are latest, earliest, all :returns: Tuple[np.ndarray, np.ndarray] The steps and lines at which production is scheduled. Remarks: - You cannot order production in the past or in the current step - Ordering production, will automatically update inventory and balance for all simulation steps assuming that this production will be carried out. At the indicated `step` if production was not possible (due to insufficient funds or insufficient inventory of the input product), the predictions for the future will be corrected. .. py:method:: set_commands(commands: numpy.ndarray, step: int = -1) -> None Sets the production commands for all lines in the given step :param commands: n_lines vector of commands. A command is either a process number to run or `NO_COMMAND` to keep the line idle :param step: The step to set the commands at. If < 0, it means current step .. py:method:: cancel_production(step: int, line: int) -> bool Cancels any production commands on that line at this step :param step: The step to cancel production at (must be in the future). :param line: The production line :returns: success/failure Remarks: - The step cannot be in the past or the current step. Cancellation can only be ordered for future steps .. py:property:: trading_prices :type: numpy.ndarray Returns the current trading prices of all products .. py:property:: exogenous_contract_summary :type: List[Tuple[int, int]] The exogenous contracts in the current step for all products :returns: A list of tuples giving the total quantity and total price of all revealed exogenous contracts of all products at the current step. .. py:property:: allow_zero_quantity :type: bool Does negotiations allow zero quantity? .. py:property:: state :type: scml.scml2020.common.FactoryState Receives the factory state .. py:property:: current_balance Current balance of the agent .. py:property:: current_inventory Current inventory of the agent .. py:method:: reports_of_agent(aid: str) -> Dict[int, scml.scml2020.common.FinancialReport] Returns a dictionary mapping time-steps to financial reports of the given agent .. py:method:: reports_at_step(step: int) -> Dict[str, scml.scml2020.common.FinancialReport] Returns a dictionary mapping agent ID to its financial report for the given time-step .. py:property:: profile :type: scml.scml2020.common.FactoryProfile Gets the profile (static private information) associated with the agent .. py:property:: all_suppliers :type: List[List[str]] Returns a list of agent IDs for all suppliers for every product .. py:property:: all_consumers :type: List[List[str]] Returns a list of agent IDs for all consumers for every product .. py:property:: inputs :type: numpy.ndarray Returns the number of inputs to every production process .. py:property:: outputs :type: numpy.ndarray Returns the number of outputs to every production process .. py:property:: n_competitors :type: int Returns the number of factories/agents in the same production level .. py:property:: my_input_product :type: int Returns a list of products that are inputs to at least one process the agent can run .. py:property:: my_output_product :type: int Returns a list of products that are outputs to at least one process the agent can run .. py:property:: my_input_products :type: numpy.ndarray Returns a list of products that are inputs to at least one process the agent can run .. py:property:: my_output_products :type: numpy.ndarray Returns a list of products that are outputs to at least one process the agent can run .. py:property:: my_suppliers :type: List[str] Returns a list of IDs for all of the agent's suppliers (agents that can supply at least one product it may need). Remarks: - If the agent have multiple input products, suppliers of a specific product $p$ can be found using: **self.all_suppliers[p]**. .. py:property:: my_consumers :type: List[str] Returns a list of IDs for all the agent's consumers (agents that can consume at least one product it may produce). Remarks: - If the agent have multiple output products, consumers of a specific product $p$ can be found using: **self.all_consumers[p]**. .. py:property:: n_lines :type: int The number of lines in the corresponding factory. You can read `state` to get this among other information .. py:property:: catalog_prices :type: numpy.ndarray Returns the catalog prices of all products .. py:property:: n_products :type: int Number of products in the world .. py:property:: n_processes :type: int Returns the number of processes in the system .. py:property:: is_first_level Whether this agent is in the first production level .. py:property:: is_last_level Whether this agent is in the last production level .. py:property:: level The production level which is the index of the process for this factory (or the index of its input product) .. py:property:: is_middle_level Whether this agent is in neither in the first nor in the last level .. py:method:: is_system(aid: str) -> bool Checks whether an agent is a system agent or not :param aid: Agent ID .. py:method:: is_bankrupt(aid: Optional[str] = None) -> bool Checks whether the agent is bankrupt :param aid: Agent ID (None means self) .. py:method:: spot_market_quantity(step: Optional[int]) -> int The quantity bought by the agent from the spot market at the given step. :param step: The simulation step (day) Remarks: If step is `None`, the current step will be used .. py:method:: spot_market_loss(step: Optional[int]) -> int The spot market loss of the agent at the given step. :param step: The simulation step (day) Remarks: If step is `None`, the current step will be used .. py:data:: SYSTEM_BUYER_ID :value: 'BUYER' ID of the system buyer agent .. py:data:: SYSTEM_SELLER_ID :value: 'SELLER' ID of the system seller agent .. py:data:: COMPENSATION_ID :value: 'COMPENSATOR' ID of the takeover agent .. py:data:: ANY_STEP :value: -1 Used to indicate any time-step .. py:data:: NO_COMMAND :value: -1 A constant indicating no command is scheduled on a factory line .. py:data:: ANY_LINE :value: -1 Used to indicate any line .. py:data:: INFINITE_COST :value: 4611686018427387903 A constant indicating an invalid cost for lines incapable of running some process .. py:data:: QUANTITY :value: 0 Index of quantity in negotiation issues .. py:data:: TIME :value: 1 Index of time in negotiation issues .. py:data:: UNIT_PRICE :value: 2 Index of unit price in negotiation issues .. py:function:: is_system_agent(aid: str) -> bool Checks whether an agent is a system agent or not :param aid: Agent ID :returns: True if the ID is for a system agent. .. py:class:: FactoryState .. py:attribute:: inventory :type: numpy.ndarray An n_products vector giving current quantity of every product in storage .. py:attribute:: balance :type: int Current balance in the wallet .. py:attribute:: commands :type: numpy.ndarray n_steps * n_lines array giving the process scheduled on each line at every step for the whole simulation .. py:attribute:: inventory_changes :type: numpy.ndarray Changes in the inventory in the last step .. py:attribute:: balance_change :type: int Change in the balance in the last step .. py:attribute:: contracts :type: list[list[ContractInfo]] The An n_steps list of lists containing the contracts of this agent by time-step .. py:property:: n_lines :type: int .. py:property:: n_steps :type: int .. py:property:: n_products :type: int .. py:property:: n_processes :type: int .. py:class:: FinancialReport A report published periodically by the system showing the financial standing of an agent .. py:attribute:: __slots__ :value: ['agent_id', 'step', 'cash', 'assets', 'breach_prob', 'breach_level', 'is_bankrupt', 'agent_name'] .. py:attribute:: agent_id :type: str Agent ID .. py:attribute:: step :type: int Simulation step at the beginning of which the report was published. .. py:attribute:: cash :type: int Cash in the agent's wallet. Negative numbers indicate liabilities. .. py:attribute:: assets :type: int Value of the products in the agent's inventory @ catalog prices. .. py:attribute:: breach_prob :type: float Number of times the agent breached a contract over the total number of contracts it signed. .. py:attribute:: breach_level :type: float Sum of the agent's breach levels so far divided by the number of contracts it signed. .. py:attribute:: is_bankrupt :type: bool Whether the agent is already bankrupt (i.e. incapable of doing any more transactions). .. py:attribute:: agent_name :type: str Agent name for printing purposes .. py:method:: __str__() .. py:class:: FactoryProfile Defines all private information of a factory .. py:attribute:: __slots__ :value: ['costs'] .. py:attribute:: costs :type: numpy.ndarray An n_lines * n_processes array giving the cost of executing any process (INVALID_COST indicates infinity) .. py:property:: n_lines .. py:property:: n_products .. py:property:: n_processes .. py:property:: processes :type: numpy.ndarray The processes that have valid costs .. py:property:: input_products :type: numpy.ndarray The input products to all processes runnable (See `processes` ) .. py:property:: output_products :type: numpy.ndarray The output products to all processes runnable (See `processes` ) .. py:class:: Failure A production failure .. py:attribute:: __slots__ :value: ['is_inventory', 'line', 'step', 'process'] .. py:attribute:: is_inventory :type: bool True if the cause of failure was insufficient inventory. If False, the cause was insufficient funds. Note that if both conditions were true, only insufficient funds (is_inventory=False) will be reported. .. py:attribute:: line :type: int The line at which the failure happened .. py:attribute:: step :type: int The step at which the failure happened .. py:attribute:: process :type: int The process that failed to execute .. py:class:: ExogenousContract Represents a contract to be revealed at revelation_time to buyer and seller between them that is not agreed upon through negotiation but is endogenously given .. py:attribute:: product :type: int Product .. py:attribute:: quantity :type: int Quantity .. py:attribute:: unit_price :type: int Unit price .. py:attribute:: time :type: int Delivery time .. py:attribute:: revelation_time :type: int Time at which to reveal the contract to both buyer and seller .. py:attribute:: seller :type: int :value: -1 Seller index in the agents array (-1 means "system") .. py:attribute:: buyer :type: int :value: -1 Buyer index in the agents array (-1 means "system") .. py:data:: __all__ .. py:class:: ProductionStrategy(*args, **kwargs) Represents a strategy for controlling production. Provides: - `schedule_range` : A mapping from contract ID to a tuple of the first and last steps at which some lines are occupied to produce the quantity specified by the contract and whether it is a sell contract - `can_be_produced` : Given a contract, it returns whether or not it is possible to produce the quantity entailed by it (which means that there is enough vacant production line slots before/after the contracts delivery time for sell/buy contracts). Hooks Into: - `on_contract_breached` - `on_contract_executed` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:attribute:: schedule_range :type: dict[str, tuple[int, int, bool]] Gives the range of steps at which the production needed for a given contract are scheduled .. py:method:: can_be_produced(contract_id: str) Returns True if the SELL contract given can be honored in principle given the production capacity of the agent (n. lines). It does not check for the availability of inputs or enough money to run the production process. Remarks: - Cannot be called before calling on_contracts_finalized .. py:method:: on_contract_executed(contract: negmas.Contract) -> None .. py:method:: on_contract_breached(contract: negmas.Contract, breaches, resolution) -> None .. py:class:: SupplyDrivenProductionStrategy(*args, **kwargs) Bases: :py:obj:`ProductionStrategy` A production strategy that converts all inputs to outputs Hooks Into: - `step` - `on_contracts_finalized` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:method:: step() .. py:method:: on_contracts_finalized(signed: list[negmas.Contract], cancelled: list[negmas.Contract], rejectors: list[list[str]]) -> None .. py:class:: DemandDrivenProductionStrategy(*args, **kwargs) Bases: :py:obj:`ProductionStrategy` A production strategy that produces ONLY when a contract is secured Hooks Into: - `on_contract_finalized` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:method:: on_contracts_finalized(signed: list[negmas.Contract], cancelled: list[negmas.Contract], rejectors: list[list[str]]) -> None .. py:class:: TradeDrivenProductionStrategy(*args, **kwargs) Bases: :py:obj:`ProductionStrategy` A production strategy that produces ONLY for contracts that the agent did not initiate. Hooks Into: - `on_contract_finalized` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:method:: on_contracts_finalized(signed: list[negmas.Contract], cancelled: list[negmas.Contract], rejectors: list[list[str]]) -> None .. py:class:: TradePredictionStrategy(*args, predicted_outputs: Union[int, numpy.ndarray] = None, predicted_inputs: Union[int, numpy.ndarray] = None, add_trade=False, **kwargs) A prediction strategy for expected inputs and outputs at every step :param - `predicted_inputs`: None for default, a number of an n_steps numbers giving predicted inputs :param - `predicted_outputs`: None for default, a number of an n_steps numbers giving predicted outputs Provides: - `expected_inputs` : n_steps vector giving the predicted inputs at every time-step. It defaults to the number of lines. - `expected_outputs` : n_steps vector giving the predicted outputs at every time-step. It defaults to the number of lines. - `input_cost` : n_steps vector giving the predicted input cost at every time-step. It defaults to catalog price. - `output_price` : n_steps vector giving the predicted output price at every time-step. It defaults to catalog price. Hooks Into: - `init` - `before_step` - `step` Abstract: - `trade_prediction_init`: Called during init() to initialize the trade prediction. - `trade_prediction_step`: Called during step() to update the trade prediction. Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:attribute:: expected_outputs :value: None Expected output quantity every step .. py:attribute:: expected_inputs :value: None Expected input quantity every step .. py:attribute:: input_cost :type: numpy.ndarray :value: None Expected unit price of the input .. py:attribute:: output_price :type: numpy.ndarray :value: None Expected unit price of the output .. py:attribute:: _add_trade :value: False .. py:method:: trade_prediction_init() -> None :abstractmethod: Will be called to update expected_outputs, expected_inputs, input_cost, output_cost during init() .. py:method:: trade_prediction_before_step() -> None Will be called at the beginning of every step to update the prediction .. py:method:: trade_prediction_step() -> None Will be called at the end of every step to update the prediction .. py:method:: init() .. py:method:: before_step() .. py:method:: step() .. py:class:: FixedTradePredictionStrategy(*args, add_trade=True, **kwargs) Bases: :py:obj:`TradePredictionStrategy` Predicts a fixed amount of trade both for the input and output products. Hooks Into: - `internal_state` - `on_contracts_finalized` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:attribute:: _add_trade :value: True .. py:method:: trade_prediction_init() Will be called to update expected_outputs, expected_inputs, input_cost, output_cost during init() .. py:property:: internal_state .. py:method:: on_contracts_finalized(signed: List[negmas.Contract], cancelled: List[negmas.Contract], rejectors: List[List[str]]) -> None .. py:class:: ExecutionRatePredictionStrategy A prediction strategy for expected inputs and outputs at every step Provides: - `predict_quantity` : A method for predicting the quantity that will actually be executed from a contract Abstract: - `predict_quantity` : A method for predicting the quantity that will actually be executed from a contract Hooks Into: - `internal_state` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:method:: predict_quantity(contract: negmas.Contract) :abstractmethod: .. py:class:: FixedERPStrategy(*args, execution_fraction=0.95, **kwargs) Bases: :py:obj:`ExecutionRatePredictionStrategy` Predicts that the there is a fixed execution rate that does not change for all partners :param execution_fraction: The expected fraction of any contract's quantity to be executed Provides: - `predict_quantity` : A method for predicting the quantity that will actually be executed from a contract Hooks Into: - `internal_state` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:attribute:: _execution_fraction :value: 0.95 .. py:method:: predict_quantity(contract: negmas.Contract) .. py:class:: MeanERPStrategy(*args, execution_fraction=0.95, **kwargs) Bases: :py:obj:`ExecutionRatePredictionStrategy` Predicts the mean execution fraction for each partner :param execution_fraction: The expected fraction of any contract's quantity to be executed Provides: - `predict_quantity` : A method for predicting the quantity that will actually be executed from a contract Hooks Into: - `internal_state` - `init` - `on_contract_executed` - `on_contract_breached` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:attribute:: _execution_fraction :value: 0.95 .. py:attribute:: _total_quantity :value: None .. py:method:: predict_quantity(contract: negmas.Contract) .. py:method:: init() .. py:property:: internal_state .. py:method:: on_contract_executed(contract: negmas.Contract) -> None .. py:method:: on_contract_breached(contract: negmas.Contract, breaches: List[negmas.Breach], resolution: Optional[negmas.Contract]) -> None .. py:class:: MarketAwareTradePredictionStrategy(*args, predicted_outputs: Union[int, numpy.ndarray] = None, predicted_inputs: Union[int, numpy.ndarray] = None, add_trade=False, **kwargs) Bases: :py:obj:`TradePredictionStrategy` Predicts an amount based on publicly available market information. Falls back to fixed prediction if no information is available Hooks Into: - `internal_state` - `on_contracts_finalized` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:method:: init() .. py:method:: trade_prediction_init() Will be called to update expected_outputs, expected_inputs, input_cost, output_cost during init() .. py:method:: __update() .. py:method:: trade_prediction_step() Will be called at the end of every step to update the prediction .. py:method:: trade_prediction_before_step() Will be called at the beginning of every step to update the prediction .. py:property:: internal_state .. py:class:: SignAll Signs all contracts no matter what. Overrides: - `sign_all_contracts` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:method:: sign_all_contracts(contracts: List[negmas.Contract]) -> List[Optional[str]] .. py:class:: SignAllPossible Signs all contracts that can in principle be honored. The only check made by this strategy is that for sell contracts there is enough production capacity Overrides: - `sign_all_contracts` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:method:: sign_all_contracts(contracts: List[negmas.Contract]) -> List[Optional[str]] .. py:class:: KeepOnlyGoodPrices(*args, buying_margin=0.5, selling_margin=0.5, **kwargs) Signs all contracts that have good prices Overrides: - `sign_all_contracts` .. attribute:: - buying_margin The margin from the catalog price to allow for buying. The agent will never buy at a price higher than the catalog price by more than this margin (relative to catalog price). .. attribute:: - selling_margin The margin from the catalog price to allow for selling. The agent will never sell at a price lower than the catalog price by more than this margin (relative to catalog price). Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:method:: sign_all_contracts(contracts: List[negmas.Contract]) -> List[Optional[str]] .. py:class:: NegotiationManager(*args, horizon=5, negotiate_on_signing=True, logdebug=False, use_trading_prices=True, min_price_margin=0.5, max_price_margin=0.5, **kwargs) A negotiation manager is a component that provides negotiation control functionality to an agent :param horizon: The number of steps in the future to consider for selling outputs. Provides: - `start_negotiations` An easy to use method to start a set of buy/sell negotiations Requires: - `acceptable_unit_price` - `target_quantity` - OPTIONALLY `target_quantities` Abstract: - `respond_to_negotiation_request` Hooks Into: - `init` - `step` - `on_contracts_finalized` - `respond_to_negotiation_request` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:attribute:: _horizon :value: 5 .. py:attribute:: _negotiate_on_signing :value: True .. py:attribute:: _log :value: False .. py:attribute:: _use_trading :value: True .. py:attribute:: _min_margin :value: 0.5 .. py:attribute:: _max_margin :value: 1.5 .. py:property:: use_trading .. py:method:: init() .. py:method:: start_negotiations(product: int, quantity: int, unit_price: int, step: int, partners: List[str] = None) -> None Starts a set of negotiations to buy/sell the product with the given limits :param product: product type. If it is an input product, negotiations to buy it will be started otherweise to sell. :param quantity: The maximum quantity to negotiate about :param unit_price: The maximum/minimum unit price for buy/sell :param step: The maximum/minimum time for buy/sell :param partners: A list of partners to negotiate with Remarks: - This method assumes that product is either my_input_product or my_output_product .. py:method:: step() Generates buy and sell negotiations as needed .. py:method:: on_contracts_finalized(signed: List[negmas.Contract], cancelled: List[negmas.Contract], rejectors: List[List[str]]) -> None .. py:method:: _generate_negotiations(step: int, sell: bool) -> None Generates all the required negotiations for selling/buying for the given step .. py:method:: _urange(step, is_seller, time_range) .. py:method:: _trange(step, is_seller) .. py:method:: target_quantities(steps: Tuple[int, int], sell: bool) -> numpy.ndarray Returns the target quantity to negotiate about for each step in the range given (beginning included and ending excluded) for buying/selling :param steps: Simulation step :param sell: Sell or buy .. py:method:: _start_negotiations(product: int, sell: bool, step: int, qvalues: Tuple[int, int], uvalues: Tuple[int, int], tvalues: Tuple[int, int], partners: List[str]) -> None :abstractmethod: Actually start negotiations with the given agenda :param product: The product to negotiate about. :param sell: If true, this is a sell negotiation :param step: The step :param qvalues: the range of quantities :param uvalues: the range of unit prices :param tvalues: the range of times :param partners: partners .. py:method:: target_quantity(step: int, sell: bool) -> int :abstractmethod: Returns the target quantity to sell/buy at a given time-step :param step: Simulation step :param sell: Sell or buy .. py:method:: acceptable_unit_price(step: int, sell: bool) -> int :abstractmethod: Returns the maximum/minimum acceptable unit price for buying/selling at the given time-step :param step: Simulation step :param sell: Sell or buy .. py:method:: respond_to_negotiation_request(initiator: str, issues: List[negmas.Issue], annotation: Dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface) -> Optional[negmas.Negotiator] :abstractmethod: .. py:class:: StepNegotiationManager(*args, negotiator_type: Union[negmas.SAONegotiator, str] = AspirationNegotiator, negotiator_params: Optional[Dict[str, Any]] = None, **kwargs) Bases: :py:obj:`scml.scml2020.components.prediction.MeanERPStrategy`, :py:obj:`NegotiationManager` A negotiation manager that controls a controller and another for selling for every timestep :param negotiator_type: The negotiator type to use to manage all negotiations :param negotiator_params: Paramters of the negotiator Provides: - `all_negotiations_concluded` Requires: - `acceptable_unit_price` - `target_quantity` - OPTIONALLY `target_quantities` Hooks Into: - `init` - `respond_to_negotiation_request` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:attribute:: negotiator_type .. py:attribute:: negotiator_params :value: None .. py:method:: init() .. py:method:: _start_negotiations(product: int, sell: bool, step: int, qvalues: Tuple[int, int], uvalues: Tuple[int, int], tvalues: Tuple[int, int], partners: List[str]) -> None Actually start negotiations with the given agenda :param product: The product to negotiate about. :param sell: If true, this is a sell negotiation :param step: The step :param qvalues: the range of quantities :param uvalues: the range of unit prices :param tvalues: the range of times :param partners: partners .. py:method:: respond_to_negotiation_request(initiator: str, issues: List[negmas.Issue], annotation: Dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface) -> Optional[negmas.Negotiator] .. py:method:: all_negotiations_concluded(controller_index: int, is_seller: bool) -> None Called by the `StepController` to affirm that it is done negotiating for some time-step .. py:method:: add_controller(is_seller: bool, target, urange: Tuple[int, int], expected_quantity: int, step: int) -> scml.scml2020.services.controllers.StepController .. py:method:: insert_controller(controller: scml.scml2020.services.controllers.StepController, is_seller: bool, target, urange: Tuple[int, int], expected_quantity: int, step: int = None) -> scml.scml2020.services.controllers.StepController .. py:method:: create_controller(is_seller: bool, target, urange: Tuple[int, int], expected_quantity: int, step: int) -> scml.scml2020.services.controllers.StepController .. py:method:: _get_controller(mechanism) -> scml.scml2020.services.controllers.StepController .. py:class:: IndependentNegotiationsManager(*args, negotiator_type: Union[negmas.SAONegotiator, str] = AspirationNegotiator, negotiator_params: Optional[Dict[str, Any]] = None, **kwargs) Bases: :py:obj:`NegotiationManager` A negotiation manager that manages independent negotiators that do not share any information once created :param negotiator_type: The negotiator type to use to manage all negotiations :param negotiator_params: Parameters of the negotiator Requires: - `create_ufun` - `acceptable_unit_price` - `target_quantity` - OPTIONALLY `target_quantities` Hooks Into: - `respond_to_negotiation_request` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:attribute:: negotiator_type .. py:attribute:: negotiator_params :value: None .. py:method:: _start_negotiations(product: int, sell: bool, step: int, qvalues: Tuple[int, int], uvalues: Tuple[int, int], tvalues: Tuple[int, int], partners: List[str]) -> None Actually start negotiations with the given agenda :param product: The product to negotiate about. :param sell: If true, this is a sell negotiation :param step: The step :param qvalues: the range of quantities :param uvalues: the range of unit prices :param tvalues: the range of times :param partners: partners .. py:method:: respond_to_negotiation_request(initiator: str, issues: List[negmas.Issue], annotation: Dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface) -> Optional[negmas.Negotiator] .. py:method:: create_ufun(is_seller: bool, issues=None, outcomes=None) -> negmas.UtilityFunction Creates a utility function .. py:method:: negotiator(is_seller: bool, issues=None, outcomes=None, partner=None) -> negmas.SAONegotiator Creates a negotiator .. py:class:: MovingRangeNegotiationManager(*args, price_weight=0.7, utility_threshold=0.9, time_threshold=0.9, time_horizon=0.1, min_price_margin=0.5, max_price_margin=0.5, **kwargs) My negotiation strategy :param price_weight: The relative importance of price in the utility calculation. :param utility_threshold: The fraction of maximum utility above which all offers will be accepted. :param time_threshold: The fraction of the negotiation time after which any valid offers will be accepted. :param time_range: The time-range for each controller as a fraction of the number of simulation steps Hooks Into: - `init` - `step` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:attribute:: index :type: List[int] :value: None .. py:attribute:: time_horizon :value: 0.1 .. py:attribute:: _time_threshold :value: 0.9 .. py:attribute:: _price_weight :value: 0.7 .. py:attribute:: _utility_threshold :value: 0.9 .. py:attribute:: _min_margin :value: 0.5 .. py:attribute:: _max_margin :value: 1.5 .. py:attribute:: controllers :type: Dict[bool, scml.scml2020.services.controllers.SyncController] .. py:attribute:: _current_end :value: -1 .. py:attribute:: _current_start :value: -1 .. py:method:: step() .. py:method:: respond_to_negotiation_request(initiator: str, issues: List[negmas.Issue], annotation: Dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface) -> Optional[negmas.Negotiator] .. py:class:: Simulation(*args, **kwargs) Provides a simulator to the agent. Provides: - `simulator` (FactorySimulator): A simulator that can be used to simulate the effect of contracts on the future of the factory Hooks Into: - `init` - `step` Remarks: - `Attributes` section describes the attributes that can be used to construct the component (passed to its `__init__` method). - `Provides` section describes the attributes (methods, properties, data-members) made available by this component directly. Note that everything provided by the bases of this components are also available to the agent (Check the `Bases` section above for all the bases of this component). - `Requires` section describes any requirements from the agent using this component. It defines a set of methods or properties/data-members that must exist in the agent that uses this component. These requirement are usually implemented as abstract methods in the component - `Abstract` section describes abstract methods that MUST be implemented by any descendant of this component. - `Hooks Into` section describes the methods this component overrides calling `super` () which allows other components to hook into the same method (by overriding it). Usually callbacks starting with `on_` are hooked into this way. - `Overrides` section describes the methods this component overrides without calling `super` effectively disallowing any other components after it in the MRO to call this method. Usually methods that do some action (i.e. not starting with `on_`) are overridden this way. .. py:attribute:: simulator :type: scml.scml2020.services.FactorySimulator :value: None .. py:method:: init() .. py:method:: step() .. py:class:: Factory(profile: scml.scml2020.common.FactoryProfile, initial_balance: int, inputs: numpy.ndarray, outputs: numpy.ndarray, catalog_prices: numpy.ndarray, world: scml.scml2020.world.SCML2020World, compensate_before_past_debt: bool, buy_missing_products: bool, production_buy_missing: bool, production_penalty: float, production_no_bankruptcy: bool, production_no_borrow: bool, agent_id: str, agent_name: Optional[str] = None, confirm_production: bool = True, initial_inventory: Optional[numpy.ndarray] = None, disallow_concurrent_negs_with_same_partners=False) A simulated factory .. py:attribute:: confirm_production :value: True .. py:attribute:: production_buy_missing .. py:attribute:: compensate_before_past_debt .. py:attribute:: buy_missing_products .. py:attribute:: production_penalty .. py:attribute:: production_no_bankruptcy .. py:attribute:: production_no_borrow .. py:attribute:: catalog_prices .. py:attribute:: initial_balance .. py:attribute:: __profile .. py:attribute:: world .. py:attribute:: profile .. py:attribute:: _disallow_concurrent_negs_with_same_partners :value: False The readonly factory profile (See `FactoryProfile` ) .. py:attribute:: commands An n_steps * n_lines array giving the process scheduled for each line at every step. -1 indicates an empty line. .. py:attribute:: _balance Current balance .. py:attribute:: _inventory Current inventory .. py:attribute:: agent_id A unique ID for the agent owning the factory .. py:attribute:: inputs An n_process array giving the number of inputs needed for each process (of the product with the same index) .. py:attribute:: outputs An n_process array giving the number of outputs produced by each process (of the product with the next index) .. py:attribute:: inventory_changes Changes in the inventory in the last step .. py:attribute:: balance_change :value: 0 Change in the balance in the last step .. py:attribute:: min_balance The minimum balance possible .. py:attribute:: is_bankrupt :value: False Will be true when the factory is bankrupt .. py:attribute:: agent_name SCML2020Agent names used for logging purposes .. py:attribute:: contracts :type: List[List[scml.scml2020.common.ContractInfo]] A list of lists of contracts per time-step (len == n_steps) .. py:property:: state :type: scml.scml2020.common.FactoryState .. py:property:: current_inventory :type: numpy.ndarray Current inventory contents .. py:property:: current_balance :type: int Current wallet balance .. py:method:: schedule_production(process: int, repeats: int, step: Union[int, Tuple[int, int]] = ANY_STEP, line: int = ANY_LINE, override: bool = True, method: str = 'latest', partial_ok: bool = False) -> Tuple[numpy.ndarray, numpy.ndarray] Orders production of the given process on the given step and line. :param process: The process index :param repeats: How many times to repeat the process :param step: The simulation step or a range of steps. The special value ANY_STEP gives the factory the freedom to schedule production at any step in the present or future. :param line: The production line. The special value ANY_LINE gives the factory the freedom to use any line :param override: Whether to override any existing commands at that line at that time. :param method: When to schedule the command if step was set to a range. Options are latest, earliest, all :param partial_ok: If true, it is OK to produce only a subset of repeats :returns: Tuple[np.ndarray, np.ndarray] The steps and lines at which production is scheduled. Remarks: - You cannot order production in the past or in the current step - Ordering production, will automatically update inventory and balance for all simulation steps assuming that this production will be carried out. At the indicated `step` if production was not possible (due to insufficient funds or insufficient inventory of the input product), the predictions for the future will be corrected. .. py:method:: order_production(process: int, steps: numpy.ndarray, lines: numpy.ndarray) -> None Orders production of the given process :param process: The process to run :param steps: The time steps to run the process at as an np.ndarray :param lines: The corresponding lines to run the process at Remarks: - len(steps) must equal len(lines) - No checks are done in this function. It is expected to be used after calling `available_for_production` .. py:method:: available_for_production(repeats: int, step: Union[int, Tuple[int, int]] = ANY_STEP, line: int = ANY_LINE, override: bool = True, method: str = 'latest') -> Tuple[numpy.ndarray, numpy.ndarray] Finds available times and lines for scheduling production. :param repeats: How many times to repeat the process :param step: The simulation step or a range of steps. The special value ANY_STEP gives the factory the freedom to schedule production at any step in the present or future. :param line: The production line. The special value ANY_LINE gives the factory the freedom to use any line :param override: Whether to override any existing commands at that line at that time. :param method: When to schedule the command if step was set to a range. Options are latest, earliest, all :returns: Tuple[np.ndarray, np.ndarray] The steps and lines at which production is scheduled. Remarks: - You cannot order production in the past or in the current step - Ordering production, will automatically update inventory and balance for all simulation steps assuming that this production will be carried out. At the indicated `step` if production was not possible (due to insufficient funds or insufficient inventory of the input product), the predictions for the future will be corrected. .. py:method:: cancel_production(step: int, line: int) -> bool Cancels pre-ordered production given that it did not start yet. :param step: Step to cancel at :param line: Line to cancel at :returns: True if step >= self.current_step Remarks: - Cannot cancel a process in the past or present. .. py:method:: step() -> List[scml.scml2020.common.Failure] Override this method to modify stepping logic. .. py:method:: spot_price(product: int, spot_loss: float) -> int Get the current spot price for buying the given product on the spot market :param product: Product :param spot_loss: Spot loss specific to that agent :returns: The unit price .. py:method:: store(product: int, quantity: int, buy_missing: bool, spot_price: float, no_bankruptcy: bool = False, no_borrowing: bool = False) -> int Stores the given amount of product (signed) to the factory. :param product: Product :param quantity: quantity to store/take out (-ve means take out) :param buy_missing: If the quantity is negative and not enough product exists in the market, it buys the product from the spot-market at an increased price of penalty :param spot_price: The fraction of unit_price added because we are buying from the spot market. Only effective if quantity is negative and not enough of the product exists in the inventory :param no_bankruptcy: Never bankrupt the agent on this transaction :param no_borrowing: Never borrow for this transaction :returns: The quantity actually stored or taken out (always positive) .. py:method:: buy(product: int, quantity: int, unit_price: int, buy_missing: bool, penalty: float, no_bankruptcy: bool = False, no_borrowing: bool = False) -> Tuple[int, int] Executes a transaction to buy/sell involving adding quantity and paying price (both are signed) :param product: The product transacted on :param quantity: The quantity (added) :param unit_price: The unit price (paid) :param buy_missing: If true, attempt buying missing products from the spot market :param penalty: The penalty as a fraction to be paid for breaches :param no_bankruptcy: If true, this transaction can never lead to bankruptcy :param no_borrowing: If true, this transaction can never lead to borrowing :returns: Tuple[int, int] The actual quantities bought and the total cost .. py:method:: pay(money: int, no_bankruptcy: bool = False, no_borrowing: bool = False, unit: int = 0) -> int Pays money :param money: amount to pay :param no_bankruptcy: If true, this transaction can never lead to bankruptcy :param no_borrowing: If true, this transaction can never lead to borrowing :param unit: If nonzero then an integer multiple of unit will be paid :returns: The amount actually paid .. py:method:: bankrupt(required: int) -> int Bankruptcy processing for the given agent :param required: The money required after the bankruptcy is processed :returns: The amount of money to pay back to the entity that should have been paid `money` .. py:class:: SCML2020World(process_inputs: numpy.ndarray, process_outputs: numpy.ndarray, catalog_prices: numpy.ndarray, profiles: list[scml.scml2020.common.FactoryProfile], agent_types: list[type[scml.scml2020.agent.SCML2020Agent]], agent_params: list[dict[str, Any]] | None = None, exogenous_contracts: Collection[scml.scml2020.common.ExogenousContract] = (), initial_balance: numpy.ndarray | tuple[int, int] | int = 1000, allow_buying_output=False, allow_selling_input=False, catalog_quantities: int | numpy.ndarray = 50, buy_missing_products=True, borrow_on_breach=True, bankruptcy_limit=0.0, liquidation_rate=1.0, spot_market_global_loss=0.3, interest_rate=0.05, financial_report_period: int = 5, compensation_fraction: float = 1.0, compensate_immediately=False, compensate_before_past_debt=True, exogenous_horizon: int | None = None, exogenous_force_max: bool = False, production_confirm=False, production_buy_missing=False, production_no_borrow=True, production_no_bankruptcy=False, production_penalty=0.15, compact=False, no_logs=False, n_steps=1000, time_limit=60 * 90, neg_n_steps=20, neg_time_limit=2 * 60, neg_step_time_limit=60, negotiation_speed=21, negotiation_quota_per_step=None, negotiation_quota_per_simulation=float('inf'), n_concurrent_negs_between_partners=float('inf'), shuffle_negotiations=False, end_negotiation_on_refusal_to_propose=True, trading_price_discount=0.9, spot_discount=0.9, spot_multiplier=0.05, signing_delay=0, force_signing=False, batch_signing=True, name: str = None, publish_exogenous_summary=True, publish_trading_prices=True, agent_name_reveals_position: bool = True, agent_name_reveals_type: bool = True, inventory_valuation_trading: float = 0.5, inventory_valuation_catalog: float = 0.0, **kwargs) Bases: :py:obj:`negmas.situated.TimeInAgreementMixin`, :py:obj:`negmas.situated.World` A Supply Chain SCML2020World simulation as described for the SCML league of ANAC @ IJCAI 2020. :param process_inputs: An n_processes vector specifying the number of inputs from each product needed to execute each process. :param process_outputs: An n_processes vector specifying the number of inputs from each product generated by executing each process. :param catalog_prices: An n_products vector (i.e. n_processes+1 vector) giving the catalog price of all products :param profiles: An n_agents list of `FactoryProfile` objects specifying the private profile of the factory associated with each agent. :param agent_types: An n_agents list of strings/ `SCML2020Agent` classes specifying the type of each agent :param agent_params: An n_agents dictionaries giving the parameters of each agent :param initial_balance: The initial balance in each agent's wallet. All agents will start with this same value. :param allow_selling_input: Allows agents to sell their input product(s) through negotiation :param allow_buying_output: Allows agents to buy their output product(s) through negotiation :param catalog_quantities: The quantities in the past for which catalog_prices are the average unit prices. This is used when updating the trading prices. If set to zero then the trading price will follow the market price and will not use the catalog_price (except for products that are never sold in the market for which the trading price will take the default value of the catalog price). If set to a large value (e.g. 10000), the price at which a product is sold will not affect the trading price :param spot_market_global_loss: Buying from the spot market will cost trading-price * (1+`spot_market_global_loss) and selling to it will cost trading-price / (1+ spot_market_global_loss) for agents with unit spot-market-loss-multiplier :param financial_report_period: The number of steps between financial reports. If < 1, it is a fraction of n_steps :param borrow_on_breach: If true, agents will be forced to borrow money on breach as much as possible to honor the contract :param interest_rate: The interest at which loans grow over time (it only affect a factory when its balance is negative) :param bankruptcy_limit: The maximum amount that be be borrowed (including interest). The balance of any factory cannot go lower than - borrow_limit or the agent will go bankrupt immediately :param liquidation_rate: The rate at which future contracts get liquidated when an agent gets bankrupt. It should be between zero and one. :param compensation_fraction: Fraction of a contract to be compensated (at most) if a partner goes bankrupt. Notice that this fraction is not guaranteed because the bankrupt agent may not have enough assets to pay all of its standing contracts to this level of compensation. In such cases, a smaller fraction will be used. :param compensate_immediately: If true, compensation will happen immediately when an agent goes bankrupt and in in money. This means that agents with contracts involving the bankrupt agent will just have these contracts be nullified and receive monetary compensation immediately . If false, compensation will not happen immediately but at the contract execution time. In this case, agents with contracts involving the bankrupt agent will be informed of the compensation fraction (instead of the compensation money) at the time of bankruptcy and will receive the compensation in kind (money if they are sellers and products if they are buyers) at the normal execution time of the contract. In the special case of no-compensation (i.e. `compensation_fraction` is zero or the bankrupt agent has no assets), the two options will behave similarity. :param compensate_before_past_debt: If true, then compensations will be paid before past debt is considered, otherwise, the money from liquidating bankrupt agents will first be used to pay past debt then whatever remains will be used for compensation. Notice that in all cases, the trigger of bankruptcy will be paid before compensation and past debts. :param exogenous_horizon: The horizon for revealing external contracts :param exogenous_force_max: If true, exogenous contracts are forced to be signed independent of the setting of `force_signing` :param production_no_borrow: If true, agents will not borrow if they fail to satisfy its production need to execute a scheduled production command :param production_no_bankruptcy: If true, agents will not go bankrupt because of an production related transaction. :param production_penalty: The penalty paid when buying from spot-market to satisfy production needs :param production_confirm: If true, the factory will confirm running processes at every time-step just before running them by calling `confirm_production` on the agent controlling it. :param compact: If True, no logs will be kept and the whole simulation will use a smaller memory footprint :param n_steps: Number of simulation steps (can be considered as days). :param time_limit: Total time allowed for the complete simulation in seconds. :param neg_n_steps: Number of negotiation steps allowed for all negotiations. :param neg_time_limit: Total time allowed for a complete negotiation in seconds. :param neg_step_time_limit: Total time allowed for a single step of a negotiation. in seconds. :param negotiation_speed: The number of negotiation steps that pass in every simulation step. If 0, negotiations will be guaranteed to finish within a single simulation step :param signing_delay: The number of simulation steps to pass between a contract is concluded and signed :param name: The name of the simulations :param \*\*kwargs: Other parameters that are passed directly to `SCML2020World` constructor. .. py:attribute:: publish_exogenous_summary :value: True .. py:attribute:: publish_trading_prices :value: True .. py:attribute:: allow_buying_output :value: False .. py:attribute:: allow_selling_input :value: False .. py:attribute:: exogenous_horizon :value: None .. py:attribute:: buy_missing_products :value: True .. py:attribute:: production_buy_missing :value: False .. py:attribute:: liquidation_rate :value: 1.0 .. py:attribute:: trading_price_discount :value: 0.9 .. py:attribute:: spot_discount :value: 0.9 .. py:attribute:: spot_multiplier :value: 0.05 .. py:attribute:: catalog_quantities :value: 50 .. py:attribute:: inventory_valuation_trading :value: 0.5 .. py:attribute:: inventory_valuation_catalog :value: 0.0 .. py:attribute:: n_concurrent_negs_between_partners .. py:attribute:: compact :value: False .. py:attribute:: spot_market_global_loss :value: 0.3 .. py:attribute:: production_no_borrow :value: True .. py:attribute:: production_no_bankruptcy :value: False .. py:attribute:: production_penalty :value: 0.15 .. py:attribute:: compensation_fraction :value: 1.0 .. py:attribute:: profiles .. py:attribute:: catalog_prices .. py:attribute:: process_inputs .. py:attribute:: process_outputs .. py:attribute:: n_products .. py:attribute:: n_processes .. py:attribute:: borrow_on_breach :value: True .. py:attribute:: interest_rate :value: 0.05 .. py:attribute:: exogenous_force_max :value: False .. py:attribute:: compensate_before_past_debt :value: True .. py:attribute:: confirm_production :value: False .. py:attribute:: financial_reports_period :value: 5 .. py:attribute:: compensate_immediately :value: False .. py:attribute:: bankruptcy_limit :value: -0.0 .. py:attribute:: agent_types .. py:attribute:: agent_params .. py:attribute:: agent_unique_types .. py:attribute:: factories .. py:attribute:: a2f .. py:attribute:: afp .. py:attribute:: i2a :value: [] .. py:attribute:: i2f .. py:attribute:: breach_prob .. py:attribute:: _breach_level .. py:attribute:: agent_n_contracts .. py:attribute:: suppliers :type: list[list[str]] .. py:attribute:: consumers :type: list[list[str]] .. py:attribute:: agent_processes :type: dict[str, list[int]] .. py:attribute:: agent_inputs :type: dict[str, list[int]] .. py:attribute:: agent_outputs :type: dict[str, list[int]] .. py:attribute:: agent_consumers :type: dict[str, list[str]] .. py:attribute:: agent_suppliers :type: dict[str, list[str]] .. py:attribute:: agent_profiles :type: dict[str, Any] .. py:attribute:: initial_balances :type: dict[str, Any] .. py:attribute:: _n_production_failures :value: 0 .. py:attribute:: __n_nullified :value: 0 .. py:attribute:: __n_bankrupt :value: 0 .. py:attribute:: penalties :value: 0 .. py:attribute:: compensation_balance :value: 0 .. py:attribute:: compensation_records :type: dict[str, list[CompensationRecord]] .. py:attribute:: exogenous_contracts :type: dict[int:list[Contract]] .. py:attribute:: compensation_factory .. py:attribute:: _agent_output .. py:attribute:: _agent_input .. py:attribute:: _traded_quantity .. py:attribute:: _real_price .. py:attribute:: _sold_quantity .. py:attribute:: _trading_price .. py:attribute:: _betas .. py:attribute:: _betas_sum .. py:attribute:: _spot_quantity .. py:attribute:: _alphas .. py:attribute:: _agent_spot_loss .. py:attribute:: _agent_spot_quantity .. py:attribute:: _registered_negs :type: dict[tuple[str], int] .. py:attribute:: exogenous_contracts_summary :value: None .. py:method:: generate(agent_types: list[type[scml.scml2020.agent.SCML2020Agent] | str], agent_params: list[dict[str, Any]] | None = None, agent_processes: list[int] | None = None, n_steps: tuple[int, int] | int = (50, 200), n_processes: tuple[int, int] | int = (2, 4), n_lines: numpy.ndarray | tuple[int, int] | int = 10, n_agents_per_process: numpy.ndarray | tuple[int, int] | int = (2, 4), process_inputs: numpy.ndarray | tuple[int, int] | int = 1, process_outputs: numpy.ndarray | tuple[int, int] | int = 1, production_costs: numpy.ndarray | tuple[int, int] | int = (1, 4), profit_means: numpy.ndarray | tuple[float, float] | float = (0.15, 0.2), profit_stddevs: numpy.ndarray | tuple[float, float] | float = 0.001, max_productivity: numpy.ndarray | tuple[float, float] | float = 1.0, initial_balance: numpy.ndarray | tuple[int, int] | int | None = None, cost_increases_with_level=True, equal_exogenous_supply=False, equal_exogenous_sales=False, exogenous_supply_predictability: tuple[float, float] | float = (0.6, 0.9), exogenous_sales_predictability: tuple[float, float] | float = (0.6, 0.9), exogenous_control: tuple[float, float] | float = (0.2, 0.8), cash_availability: tuple[float, float] | float = (1.5, 2.5), force_signing=False, profit_basis=np.max, horizon: tuple[float, float] | float = (0.2, 0.5), inventory_valuation_trading: numpy.ndarray | tuple[float, float] | float = 0.5, inventory_valuation_catalog: numpy.ndarray | tuple[float, float] | float = 0.0, random_agent_types: bool = False, cost_relativity: float = 1.0, exogenous_generation_method='profitable', exogenous_supply_surplus: tuple[float, float] | float = 0.0, exogenous_sales_surplus: tuple[float, float] | float = 0.0, run_extra_checks: bool = True, **kwargs) -> dict[str, Any] :classmethod: Generates the configuration for a world :param agent_types: All agent types :param agent_params: Agent parameters used to initialize them :param n_steps: Number of simulation steps :param n_processes: Number of processes in the production chain :param n_lines: Number of lines per factory :param process_inputs: Number of input units per process :param process_outputs: Number of output units per process :param production_costs: Production cost per factory :param profit_means: Mean profitability per production level (i.e. process). :param profit_stddevs: Std. Dev. of the profitability of every level (i.e. process). :param inventory_valuation_catalog: The fraction of catalog price to value items at the end. :param inventory_valuation_trading: The fraction of trading price to value items at the end. :param max_productivity: Maximum possible productivity per level (i.e. process). :param initial_balance: The initial balance of all agents :param n_agents_per_process: Number of agents per process :param agent_processes: The process for each agent. If not `None` , it will override `n_agents_per_process` and must be a list/tuple of the same length as `agent_types` . Morevoer, `random_agent_types` must be False in this case :param cost_increases_with_level: If true, production cost will be higher for processes nearer to the final product. :param profit_basis: The statistic used when controlling catalog prices by profit arguments. It can be np.mean, np.median, np.min, np.max or any Callable[[list[float]], float] and is used to summarize production costs at every level. :param horizon: The horizon used for revealing external supply/sales as a fraction of n_steps :param equal_exogenous_supply: If true, external supply will be distributed equally among all agents in the first layer :param equal_exogenous_sales: If true, external sales will be distributed equally among all agents in the last layer :param exogenous_supply_predictability: How predictable are exogenous supplies of each agent over time. 1.0 means that every agent will have the same quantity for all of its contracts over time. 0.0 means quantities per agent are completely random :param exogenous_sales_predictability: How predictable are exogenous supplies of each agent over time. 1.0 means that every agent will have the same quantity for all of its contracts over time. 0.0 means quantities per agent are completely random :param cash_availability: The fraction of the total money needs of the agent to work at maximum capacity that is available as `initial_balance` . This is only effective if `initial_balance` is set to `None` . :param force_signing: Whether to force contract signatures (exogenous contracts are treated in the same way). :param exogenous_control: How much control does the agent have over exogenous contract signing. Only effective if force_signing is False and use_exogenous_contracts is True :param random_agent_types: If True, the final agent types used by the generato wil always be sampled from the given types. If False, this random sampling will only happin if len(agent_types) != n_agents. :param cost_relativity: The exponent of production cost used to distribute contracts during generation :param method: The method used for world generation. Available methods are "profitable" and "guaranteed_profit" :param exogenous_supply_surplus: The surpolus exogenous supply contract quantity to add to the system as a fraction of the a fraction of the contracts generated by the given method. :param exogenous_sales_surplus: The surpolus exogenous sales contract quantity to add to the system as a fraction of the a fraction of the contracts generated by the given method. :param run_extra_checks: If given, the world generation method will check whether the genrated world "makes sense" given its internal criteria. May slow down world generation :param \*\*kwargs: :returns: world configuration as a dict[str, Any]. A world can be generated from this dict by calling SCML2020World(**d) Remarks: - There are two general ways to use this generator: 1. Pass `random_agent_types = True`, and pass `agent_types`, `agent_processes` to control placement of each agent in each level of the production graph. 2. Pass `random_agent_types = False` and pass `agent_types`, `n_agents_per_process` to make the system randomly place the specified number of agents in each production level - Most parameters (i.e. `process_inputs` , `process_outputs` , `n_agents_per_process` , `costs` ) can take a single value, a tuple of two values, or a list of values. If it has a single value, it is repeated for all processes/factories as appropriate. If it is a tuple of two numbers $(i, j)$, each process will take a number sampled from a uniform distribution supported on $[i, j]$ inclusive. If it is a list of values, of the length `n_processes` , it is used as it is otherwise, it is used to sample values for each process. .. py:method:: generate_guaranteed_profit(n_steps: int, n_lines: int, n_agents_per_process: int, process_of_agent: list[int], first_agent: list[int], last_agent: list[int], production_costs: list[int], exogenous_control: float, cash_availability: float, force_signing: bool, horizon: int, exogenous_supplies: list[int], max_productivity_process: list[float], max_productivity_agent: list[float], equal_exogenous_sales: bool, process_inputs: list[int], process_outputs: list[int], exogenous_sales_predictability: float, costs: numpy.ndarray, profit_stddevs_agent=list[float], profit_means_agent=list[float], initial_balance: numpy.ndarray | tuple[int, int] | int | None = None, cost_relativity: float = 1.0, profit_basis=np.max, inventory_valuation_trading: float = 0.5, inventory_valuation_catalog: float = 0.0, run_extra_checks=True) -> tuple[list[scml.scml2020.common.ExogenousContract], list[int], list[scml.scml2020.common.FactoryProfile], list[float], dict[str, Any]] :classmethod: Generates prices, contracts and profiles ensuring that all agents can profit and returning a set of explict contracts that can achieve this profit .. py:method:: generate_profitable(n_steps: int, n_lines: int, n_agents_per_process: int, process_of_agent: list[int], first_agent: list[int], last_agent: list[int], production_costs: list[int], exogenous_control: float, cash_availability: float, force_signing: bool, horizon: int, exogenous_supplies: list[int], max_productivity_process: list[float], max_productivity_agent: list[float], equal_exogenous_sales: bool, process_inputs: list[int], process_outputs: list[int], exogenous_sales_predictability: float, costs: numpy.ndarray, profit_stddevs_agent=list[float], profit_means_agent=list[float], initial_balance: numpy.ndarray | tuple[int, int] | int | None = None, cost_relativity: float = 1.0, profit_basis=np.max, inventory_valuation_trading: float = 0.5, inventory_valuation_catalog: float = 0.0, run_extra_checks: bool = True) -> tuple[list[scml.scml2020.common.ExogenousContract], list[int], list[scml.scml2020.common.FactoryProfile], list[float], dict[str, Any]] :classmethod: Generates the prices, contracts and profiles ensuring there is some possibility of profit in the market .. py:method:: get_private_state(agent: scml.scml2020.agent.SCML2020Agent) -> dict Reads the private state of the given agent .. py:method:: add_financial_report(agent: scml.scml2020.agent.SCML2020Agent, factory: scml.scml2020.factory.Factory, reports_agent, reports_time) -> None Records a financial report for the given agent in the agent indexed reports and time indexed reports :param agent: The agent :param factory: Its factory :param reports_agent: A dictionary of financial reports indexed by agent id :param reports_time: A dictionary of financial reports indexed by time Returns: .. py:method:: negs_between(a1, a2) .. py:method:: current_balance(agent_id: str) .. py:method:: can_negotiate(a1, a2) .. py:method:: simulation_step(stage) A single step of the simulation. :param stage: How many times so far was this method called within the current simulation step Remarks: - Using the stage parameter, it is possible to have `Operations` . `SimulationStep` several times with the list of operations while differentiating between these calls. .. py:method:: contract_size(contract: negmas.Contract) -> float Returns an estimation of the **activity level** associated with this contract. Higher is better :param contract: Returns: .. py:method:: contract_record(contract: negmas.Contract) -> dict[str, Any] Converts a contract to a record suitable for permanent storage .. py:method:: breach_record(breach: negmas.Breach) -> dict[str, Any] Converts a breach to a record suitable for storage during the simulation .. py:method:: execute_action(action: negmas.Action, agent: scml.scml2020.agent.SCML2020Agent, callback: Callable = None) -> bool Executes the given action by the given agent .. py:method:: post_step_stats() Called at the end of the simulation step to update all stats Kept for backward compatibility and will be dropped. Override `update_stats` ins .. py:method:: pre_step_stats() Called at the beginning of the simulation step to prepare stats or update them Kept for backward compatibility and will be dropped. Override `update_stats` instead .. py:property:: productivity :type: float Fraction of production lines occupied during the simulation .. py:method:: welfare(include_bankrupt: bool = False) -> float Total welfare of all agents .. py:method:: relative_welfare(include_bankrupt: bool = False) -> float | None Total welfare relative to expected value. Returns None if no expectation is found in self.info .. py:property:: relative_productivity :type: float | None Productivity relative to the expected value. Will return None if self.info does not have the expected productivity .. py:property:: bankruptcy_rate :type: float The fraction of factories that went bankrupt .. py:property:: num_bankrupt :type: float The fraction of factories that went bankrupt .. py:method:: order_contracts_for_execution(contracts: Collection[negmas.Contract]) -> Collection[negmas.Contract] Orders the contracts in a specific time-step that are about to be executed .. py:method:: _execute(product: int, q: int, p: int, u: int, buyer_factory: scml.scml2020.factory.Factory, seller_factory: scml.scml2020.factory.Factory, has_breaches: bool) Executes the contract .. py:method:: __register_contract(agent_id: str, level: float) -> None Registers execution of the contract in the agent's stats .. py:method:: record_bankrupt(factory: scml.scml2020.factory.Factory) -> None Records agent bankruptcy .. py:method:: on_contract_concluded(contract: negmas.Contract, to_be_signed_at: int) -> None Called to add a contract to the existing set of unsigned contract after it is concluded :param contract: The contract to add :param to_be_signed_at: The timestep at which the contract is to be signed Remarks: - By default this function just adds the contract to the set of contracts maintaned by the world. - You should ALWAYS call this function when overriding it. .. py:method:: is_valid_contact(contract: negmas.Contract) -> bool Checks whether a signed contract is valid .. py:method:: on_contract_signed(contract: negmas.Contract) -> bool Called to add a contract to the existing set of contract after it is signed :param contract: The contract to add :returns: True if everything went OK and False otherwise Remarks: - By default this function just adds the contract to the set of contracts maintaned by the world. - You should ALWAYS call this function when overriding it. .. py:method:: nullify_contract(contract: negmas.Contract, new_quantity: int) .. py:method:: __register_breach(agent_id: str, level: float, contract_total: float, factory: scml.scml2020.factory.Factory) -> int Registers a breach of the given level on the given agent. Assume that the contract is already added to the agent_contracts :param agent_id: The perpetrator of the breach :param level: The breach level :param contract_total: The total of the contract breached (quantity * unit_price) :param factory: The factory corresponding to the perpetrator :returns: If nonzero, the agent should go bankrupt and this amount taken from them .. py:method:: _spot_loss(aid: str) -> float .. py:method:: start_contract_execution(contract: negmas.Contract) -> set[negmas.Breach] | None Tries to execute the contract :param contract: :returns: The set of breaches committed if any. If there are no breaches return an empty set :rtype: Set[Breach] Remarks: - You must call super() implementation of this method before doing anything - It is possible to return None which indicates that the contract was nullified (i.e. not executed due to a reason other than an execution exeception). .. py:method:: complete_contract_execution(contract: negmas.Contract, breaches: list[negmas.Breach], resolution: negmas.Contract) -> None Called after breach resolution is completed for contracts for which some potential breaches occurred. :param contract: The contract considered. :param breaches: The list of potential breaches that was generated by `_execute_contract`. :param resolution: The agreed upon resolution Returns: .. py:method:: compensate(available: int, factory: scml.scml2020.factory.Factory) -> dict[str, list[tuple[negmas.Contract, int, int]]] Called by a factory when it is going bankrupt after liquidation :param available: The amount available from liquidation :param factory: The factory being bankrupted :returns: A mapping from agent ID to nullified contracts, the new quantity for them and compensation_money .. py:method:: scores(assets_multiplier_trading: float | None = None, assets_multiplier_catalog: float | None = None, assets_multiplier: float | None = None) -> dict[str, float] scores of all agents given the asset multiplier. :param assets_multiplier: a multiplier to multiply the assets with. .. py:property:: winners The winners of this world (factory managers with maximum wallet balance .. py:method:: trading_prices_for(discount: float = 1.0, condition='executed') -> numpy.ndarray Calculates the prices at which all products traded using an optional discount factor :param discount: A discount factor to treat older prices less importantly (exponential discounting). :param condition: The condition for contracts to consider. Possible values are executed, signed, concluded, nullified :returns: an n_products vector of trading prices .. py:property:: trading_prices .. py:property:: stats_df :type: pandas.DataFrame Returns a pandas data frame with the stats .. py:property:: contracts_df :type: pandas.DataFrame Returns a pandas data frame with the contracts .. py:property:: system_agents :type: list[scml.scml2020.agent.SCML2020Agent] Returns the two system agents .. py:property:: system_agent_names :type: list[str] Returns the names two system agents .. py:property:: non_system_agents :type: list[scml.scml2020.agent.SCML2020Agent] Returns all agents except system agents .. py:property:: non_system_agent_names :type: list[str] Returns names of all agents except system agents .. py:property:: agreement_fraction :type: float Fraction of negotiations ending in agreement and leading to signed contracts .. py:attribute:: system_agent_ids .. py:attribute:: non_system_agent_ids .. py:method:: draw(steps: tuple[int, int] | int | None = None, what: Collection[str] = DEFAULT_EDGE_TYPES, who: Callable[[negmas.Agent], bool] = None, where: Callable[[negmas.Agent], int | tuple[float, float]] = None, together: bool = True, axs: Collection[matplotlib.axis.Axis] = None, ncols: int = 4, figsize: tuple[int, int] = (15, 15), **kwargs) -> tuple[matplotlib.axis.Axis, networkx.Graph] | tuple[list[matplotlib.axis.Axis], list[networkx.Graph]] .. py:class:: SCML2021World(*args, **kwargs) Bases: :py:obj:`SCML2020World` A Supply Chain SCML2020World simulation as described for the SCML league of ANAC @ IJCAI 2020. :param process_inputs: An n_processes vector specifying the number of inputs from each product needed to execute each process. :param process_outputs: An n_processes vector specifying the number of inputs from each product generated by executing each process. :param catalog_prices: An n_products vector (i.e. n_processes+1 vector) giving the catalog price of all products :param profiles: An n_agents list of `FactoryProfile` objects specifying the private profile of the factory associated with each agent. :param agent_types: An n_agents list of strings/ `SCML2020Agent` classes specifying the type of each agent :param agent_params: An n_agents dictionaries giving the parameters of each agent :param initial_balance: The initial balance in each agent's wallet. All agents will start with this same value. :param allow_selling_input: Allows agents to sell their input product(s) through negotiation :param allow_buying_output: Allows agents to buy their output product(s) through negotiation :param catalog_quantities: The quantities in the past for which catalog_prices are the average unit prices. This is used when updating the trading prices. If set to zero then the trading price will follow the market price and will not use the catalog_price (except for products that are never sold in the market for which the trading price will take the default value of the catalog price). If set to a large value (e.g. 10000), the price at which a product is sold will not affect the trading price :param spot_market_global_loss: Buying from the spot market will cost trading-price * (1+`spot_market_global_loss) and selling to it will cost trading-price / (1+ spot_market_global_loss) for agents with unit spot-market-loss-multiplier :param financial_report_period: The number of steps between financial reports. If < 1, it is a fraction of n_steps :param borrow_on_breach: If true, agents will be forced to borrow money on breach as much as possible to honor the contract :param interest_rate: The interest at which loans grow over time (it only affect a factory when its balance is negative) :param bankruptcy_limit: The maximum amount that be be borrowed (including interest). The balance of any factory cannot go lower than - borrow_limit or the agent will go bankrupt immediately :param liquidation_rate: The rate at which future contracts get liquidated when an agent gets bankrupt. It should be between zero and one. :param compensation_fraction: Fraction of a contract to be compensated (at most) if a partner goes bankrupt. Notice that this fraction is not guaranteed because the bankrupt agent may not have enough assets to pay all of its standing contracts to this level of compensation. In such cases, a smaller fraction will be used. :param compensate_immediately: If true, compensation will happen immediately when an agent goes bankrupt and in in money. This means that agents with contracts involving the bankrupt agent will just have these contracts be nullified and receive monetary compensation immediately . If false, compensation will not happen immediately but at the contract execution time. In this case, agents with contracts involving the bankrupt agent will be informed of the compensation fraction (instead of the compensation money) at the time of bankruptcy and will receive the compensation in kind (money if they are sellers and products if they are buyers) at the normal execution time of the contract. In the special case of no-compensation (i.e. `compensation_fraction` is zero or the bankrupt agent has no assets), the two options will behave similarity. :param compensate_before_past_debt: If true, then compensations will be paid before past debt is considered, otherwise, the money from liquidating bankrupt agents will first be used to pay past debt then whatever remains will be used for compensation. Notice that in all cases, the trigger of bankruptcy will be paid before compensation and past debts. :param exogenous_horizon: The horizon for revealing external contracts :param exogenous_force_max: If true, exogenous contracts are forced to be signed independent of the setting of `force_signing` :param production_no_borrow: If true, agents will not borrow if they fail to satisfy its production need to execute a scheduled production command :param production_no_bankruptcy: If true, agents will not go bankrupt because of an production related transaction. :param production_penalty: The penalty paid when buying from spot-market to satisfy production needs :param production_confirm: If true, the factory will confirm running processes at every time-step just before running them by calling `confirm_production` on the agent controlling it. :param compact: If True, no logs will be kept and the whole simulation will use a smaller memory footprint :param n_steps: Number of simulation steps (can be considered as days). :param time_limit: Total time allowed for the complete simulation in seconds. :param neg_n_steps: Number of negotiation steps allowed for all negotiations. :param neg_time_limit: Total time allowed for a complete negotiation in seconds. :param neg_step_time_limit: Total time allowed for a single step of a negotiation. in seconds. :param negotiation_speed: The number of negotiation steps that pass in every simulation step. If 0, negotiations will be guaranteed to finish within a single simulation step :param signing_delay: The number of simulation steps to pass between a contract is concluded and signed :param name: The name of the simulations :param \*\*kwargs: Other parameters that are passed directly to `SCML2020World` constructor. .. py:method:: generate(*args, inventory_valuation_trading: numpy.ndarray | tuple[float, float] | float = (0.0, 0.5), horizon: tuple[float, float] | float = (0.2, 0.5), **kwargs) -> dict[str, Any] :classmethod: Generates the configuration for a world :param agent_types: All agent types :param agent_params: Agent parameters used to initialize them :param n_steps: Number of simulation steps :param n_processes: Number of processes in the production chain :param n_lines: Number of lines per factory :param process_inputs: Number of input units per process :param process_outputs: Number of output units per process :param production_costs: Production cost per factory :param profit_means: Mean profitability per production level (i.e. process). :param profit_stddevs: Std. Dev. of the profitability of every level (i.e. process). :param inventory_valuation_catalog: The fraction of catalog price to value items at the end. :param inventory_valuation_trading: The fraction of trading price to value items at the end. :param max_productivity: Maximum possible productivity per level (i.e. process). :param initial_balance: The initial balance of all agents :param n_agents_per_process: Number of agents per process :param agent_processes: The process for each agent. If not `None` , it will override `n_agents_per_process` and must be a list/tuple of the same length as `agent_types` . Morevoer, `random_agent_types` must be False in this case :param cost_increases_with_level: If true, production cost will be higher for processes nearer to the final product. :param profit_basis: The statistic used when controlling catalog prices by profit arguments. It can be np.mean, np.median, np.min, np.max or any Callable[[list[float]], float] and is used to summarize production costs at every level. :param horizon: The horizon used for revealing external supply/sales as a fraction of n_steps :param equal_exogenous_supply: If true, external supply will be distributed equally among all agents in the first layer :param equal_exogenous_sales: If true, external sales will be distributed equally among all agents in the last layer :param exogenous_supply_predictability: How predictable are exogenous supplies of each agent over time. 1.0 means that every agent will have the same quantity for all of its contracts over time. 0.0 means quantities per agent are completely random :param exogenous_sales_predictability: How predictable are exogenous supplies of each agent over time. 1.0 means that every agent will have the same quantity for all of its contracts over time. 0.0 means quantities per agent are completely random :param cash_availability: The fraction of the total money needs of the agent to work at maximum capacity that is available as `initial_balance` . This is only effective if `initial_balance` is set to `None` . :param force_signing: Whether to force contract signatures (exogenous contracts are treated in the same way). :param exogenous_control: How much control does the agent have over exogenous contract signing. Only effective if force_signing is False and use_exogenous_contracts is True :param random_agent_types: If True, the final agent types used by the generato wil always be sampled from the given types. If False, this random sampling will only happin if len(agent_types) != n_agents. :param cost_relativity: The exponent of production cost used to distribute contracts during generation :param method: The method used for world generation. Available methods are "profitable" and "guaranteed_profit" :param exogenous_supply_surplus: The surpolus exogenous supply contract quantity to add to the system as a fraction of the a fraction of the contracts generated by the given method. :param exogenous_sales_surplus: The surpolus exogenous sales contract quantity to add to the system as a fraction of the a fraction of the contracts generated by the given method. :param run_extra_checks: If given, the world generation method will check whether the genrated world "makes sense" given its internal criteria. May slow down world generation :param \*\*kwargs: :returns: world configuration as a dict[str, Any]. A world can be generated from this dict by calling SCML2020World(**d) Remarks: - There are two general ways to use this generator: 1. Pass `random_agent_types = True`, and pass `agent_types`, `agent_processes` to control placement of each agent in each level of the production graph. 2. Pass `random_agent_types = False` and pass `agent_types`, `n_agents_per_process` to make the system randomly place the specified number of agents in each production level - Most parameters (i.e. `process_inputs` , `process_outputs` , `n_agents_per_process` , `costs` ) can take a single value, a tuple of two values, or a list of values. If it has a single value, it is repeated for all processes/factories as appropriate. If it is a tuple of two numbers $(i, j)$, each process will take a number sampled from a uniform distribution supported on $[i, j]$ inclusive. If it is a list of values, of the length `n_processes` , it is used as it is otherwise, it is used to sample values for each process. .. py:class:: SCML2022World(*args, **kwargs) Bases: :py:obj:`SCML2021World` A Supply Chain SCML2020World simulation as described for the SCML league of ANAC @ IJCAI 2020. :param process_inputs: An n_processes vector specifying the number of inputs from each product needed to execute each process. :param process_outputs: An n_processes vector specifying the number of inputs from each product generated by executing each process. :param catalog_prices: An n_products vector (i.e. n_processes+1 vector) giving the catalog price of all products :param profiles: An n_agents list of `FactoryProfile` objects specifying the private profile of the factory associated with each agent. :param agent_types: An n_agents list of strings/ `SCML2020Agent` classes specifying the type of each agent :param agent_params: An n_agents dictionaries giving the parameters of each agent :param initial_balance: The initial balance in each agent's wallet. All agents will start with this same value. :param allow_selling_input: Allows agents to sell their input product(s) through negotiation :param allow_buying_output: Allows agents to buy their output product(s) through negotiation :param catalog_quantities: The quantities in the past for which catalog_prices are the average unit prices. This is used when updating the trading prices. If set to zero then the trading price will follow the market price and will not use the catalog_price (except for products that are never sold in the market for which the trading price will take the default value of the catalog price). If set to a large value (e.g. 10000), the price at which a product is sold will not affect the trading price :param spot_market_global_loss: Buying from the spot market will cost trading-price * (1+`spot_market_global_loss) and selling to it will cost trading-price / (1+ spot_market_global_loss) for agents with unit spot-market-loss-multiplier :param financial_report_period: The number of steps between financial reports. If < 1, it is a fraction of n_steps :param borrow_on_breach: If true, agents will be forced to borrow money on breach as much as possible to honor the contract :param interest_rate: The interest at which loans grow over time (it only affect a factory when its balance is negative) :param bankruptcy_limit: The maximum amount that be be borrowed (including interest). The balance of any factory cannot go lower than - borrow_limit or the agent will go bankrupt immediately :param liquidation_rate: The rate at which future contracts get liquidated when an agent gets bankrupt. It should be between zero and one. :param compensation_fraction: Fraction of a contract to be compensated (at most) if a partner goes bankrupt. Notice that this fraction is not guaranteed because the bankrupt agent may not have enough assets to pay all of its standing contracts to this level of compensation. In such cases, a smaller fraction will be used. :param compensate_immediately: If true, compensation will happen immediately when an agent goes bankrupt and in in money. This means that agents with contracts involving the bankrupt agent will just have these contracts be nullified and receive monetary compensation immediately . If false, compensation will not happen immediately but at the contract execution time. In this case, agents with contracts involving the bankrupt agent will be informed of the compensation fraction (instead of the compensation money) at the time of bankruptcy and will receive the compensation in kind (money if they are sellers and products if they are buyers) at the normal execution time of the contract. In the special case of no-compensation (i.e. `compensation_fraction` is zero or the bankrupt agent has no assets), the two options will behave similarity. :param compensate_before_past_debt: If true, then compensations will be paid before past debt is considered, otherwise, the money from liquidating bankrupt agents will first be used to pay past debt then whatever remains will be used for compensation. Notice that in all cases, the trigger of bankruptcy will be paid before compensation and past debts. :param exogenous_horizon: The horizon for revealing external contracts :param exogenous_force_max: If true, exogenous contracts are forced to be signed independent of the setting of `force_signing` :param production_no_borrow: If true, agents will not borrow if they fail to satisfy its production need to execute a scheduled production command :param production_no_bankruptcy: If true, agents will not go bankrupt because of an production related transaction. :param production_penalty: The penalty paid when buying from spot-market to satisfy production needs :param production_confirm: If true, the factory will confirm running processes at every time-step just before running them by calling `confirm_production` on the agent controlling it. :param compact: If True, no logs will be kept and the whole simulation will use a smaller memory footprint :param n_steps: Number of simulation steps (can be considered as days). :param time_limit: Total time allowed for the complete simulation in seconds. :param neg_n_steps: Number of negotiation steps allowed for all negotiations. :param neg_time_limit: Total time allowed for a complete negotiation in seconds. :param neg_step_time_limit: Total time allowed for a single step of a negotiation. in seconds. :param negotiation_speed: The number of negotiation steps that pass in every simulation step. If 0, negotiations will be guaranteed to finish within a single simulation step :param signing_delay: The number of simulation steps to pass between a contract is concluded and signed :param name: The name of the simulations :param \*\*kwargs: Other parameters that are passed directly to `SCML2020World` constructor. .. py:class:: SCML2023World(*args, **kwargs) Bases: :py:obj:`SCML2022World` A Supply Chain SCML2020World simulation as described for the SCML league of ANAC @ IJCAI 2020. :param process_inputs: An n_processes vector specifying the number of inputs from each product needed to execute each process. :param process_outputs: An n_processes vector specifying the number of inputs from each product generated by executing each process. :param catalog_prices: An n_products vector (i.e. n_processes+1 vector) giving the catalog price of all products :param profiles: An n_agents list of `FactoryProfile` objects specifying the private profile of the factory associated with each agent. :param agent_types: An n_agents list of strings/ `SCML2020Agent` classes specifying the type of each agent :param agent_params: An n_agents dictionaries giving the parameters of each agent :param initial_balance: The initial balance in each agent's wallet. All agents will start with this same value. :param allow_selling_input: Allows agents to sell their input product(s) through negotiation :param allow_buying_output: Allows agents to buy their output product(s) through negotiation :param catalog_quantities: The quantities in the past for which catalog_prices are the average unit prices. This is used when updating the trading prices. If set to zero then the trading price will follow the market price and will not use the catalog_price (except for products that are never sold in the market for which the trading price will take the default value of the catalog price). If set to a large value (e.g. 10000), the price at which a product is sold will not affect the trading price :param spot_market_global_loss: Buying from the spot market will cost trading-price * (1+`spot_market_global_loss) and selling to it will cost trading-price / (1+ spot_market_global_loss) for agents with unit spot-market-loss-multiplier :param financial_report_period: The number of steps between financial reports. If < 1, it is a fraction of n_steps :param borrow_on_breach: If true, agents will be forced to borrow money on breach as much as possible to honor the contract :param interest_rate: The interest at which loans grow over time (it only affect a factory when its balance is negative) :param bankruptcy_limit: The maximum amount that be be borrowed (including interest). The balance of any factory cannot go lower than - borrow_limit or the agent will go bankrupt immediately :param liquidation_rate: The rate at which future contracts get liquidated when an agent gets bankrupt. It should be between zero and one. :param compensation_fraction: Fraction of a contract to be compensated (at most) if a partner goes bankrupt. Notice that this fraction is not guaranteed because the bankrupt agent may not have enough assets to pay all of its standing contracts to this level of compensation. In such cases, a smaller fraction will be used. :param compensate_immediately: If true, compensation will happen immediately when an agent goes bankrupt and in in money. This means that agents with contracts involving the bankrupt agent will just have these contracts be nullified and receive monetary compensation immediately . If false, compensation will not happen immediately but at the contract execution time. In this case, agents with contracts involving the bankrupt agent will be informed of the compensation fraction (instead of the compensation money) at the time of bankruptcy and will receive the compensation in kind (money if they are sellers and products if they are buyers) at the normal execution time of the contract. In the special case of no-compensation (i.e. `compensation_fraction` is zero or the bankrupt agent has no assets), the two options will behave similarity. :param compensate_before_past_debt: If true, then compensations will be paid before past debt is considered, otherwise, the money from liquidating bankrupt agents will first be used to pay past debt then whatever remains will be used for compensation. Notice that in all cases, the trigger of bankruptcy will be paid before compensation and past debts. :param exogenous_horizon: The horizon for revealing external contracts :param exogenous_force_max: If true, exogenous contracts are forced to be signed independent of the setting of `force_signing` :param production_no_borrow: If true, agents will not borrow if they fail to satisfy its production need to execute a scheduled production command :param production_no_bankruptcy: If true, agents will not go bankrupt because of an production related transaction. :param production_penalty: The penalty paid when buying from spot-market to satisfy production needs :param production_confirm: If true, the factory will confirm running processes at every time-step just before running them by calling `confirm_production` on the agent controlling it. :param compact: If True, no logs will be kept and the whole simulation will use a smaller memory footprint :param n_steps: Number of simulation steps (can be considered as days). :param time_limit: Total time allowed for the complete simulation in seconds. :param neg_n_steps: Number of negotiation steps allowed for all negotiations. :param neg_time_limit: Total time allowed for a complete negotiation in seconds. :param neg_step_time_limit: Total time allowed for a single step of a negotiation. in seconds. :param negotiation_speed: The number of negotiation steps that pass in every simulation step. If 0, negotiations will be guaranteed to finish within a single simulation step :param signing_delay: The number of simulation steps to pass between a contract is concluded and signed :param name: The name of the simulations :param \*\*kwargs: Other parameters that are passed directly to `SCML2020World` constructor. .. py:class:: SCML2024World(*args, **kwargs) Bases: :py:obj:`SCML2022World` A Supply Chain SCML2020World simulation as described for the SCML league of ANAC @ IJCAI 2020. :param process_inputs: An n_processes vector specifying the number of inputs from each product needed to execute each process. :param process_outputs: An n_processes vector specifying the number of inputs from each product generated by executing each process. :param catalog_prices: An n_products vector (i.e. n_processes+1 vector) giving the catalog price of all products :param profiles: An n_agents list of `FactoryProfile` objects specifying the private profile of the factory associated with each agent. :param agent_types: An n_agents list of strings/ `SCML2020Agent` classes specifying the type of each agent :param agent_params: An n_agents dictionaries giving the parameters of each agent :param initial_balance: The initial balance in each agent's wallet. All agents will start with this same value. :param allow_selling_input: Allows agents to sell their input product(s) through negotiation :param allow_buying_output: Allows agents to buy their output product(s) through negotiation :param catalog_quantities: The quantities in the past for which catalog_prices are the average unit prices. This is used when updating the trading prices. If set to zero then the trading price will follow the market price and will not use the catalog_price (except for products that are never sold in the market for which the trading price will take the default value of the catalog price). If set to a large value (e.g. 10000), the price at which a product is sold will not affect the trading price :param spot_market_global_loss: Buying from the spot market will cost trading-price * (1+`spot_market_global_loss) and selling to it will cost trading-price / (1+ spot_market_global_loss) for agents with unit spot-market-loss-multiplier :param financial_report_period: The number of steps between financial reports. If < 1, it is a fraction of n_steps :param borrow_on_breach: If true, agents will be forced to borrow money on breach as much as possible to honor the contract :param interest_rate: The interest at which loans grow over time (it only affect a factory when its balance is negative) :param bankruptcy_limit: The maximum amount that be be borrowed (including interest). The balance of any factory cannot go lower than - borrow_limit or the agent will go bankrupt immediately :param liquidation_rate: The rate at which future contracts get liquidated when an agent gets bankrupt. It should be between zero and one. :param compensation_fraction: Fraction of a contract to be compensated (at most) if a partner goes bankrupt. Notice that this fraction is not guaranteed because the bankrupt agent may not have enough assets to pay all of its standing contracts to this level of compensation. In such cases, a smaller fraction will be used. :param compensate_immediately: If true, compensation will happen immediately when an agent goes bankrupt and in in money. This means that agents with contracts involving the bankrupt agent will just have these contracts be nullified and receive monetary compensation immediately . If false, compensation will not happen immediately but at the contract execution time. In this case, agents with contracts involving the bankrupt agent will be informed of the compensation fraction (instead of the compensation money) at the time of bankruptcy and will receive the compensation in kind (money if they are sellers and products if they are buyers) at the normal execution time of the contract. In the special case of no-compensation (i.e. `compensation_fraction` is zero or the bankrupt agent has no assets), the two options will behave similarity. :param compensate_before_past_debt: If true, then compensations will be paid before past debt is considered, otherwise, the money from liquidating bankrupt agents will first be used to pay past debt then whatever remains will be used for compensation. Notice that in all cases, the trigger of bankruptcy will be paid before compensation and past debts. :param exogenous_horizon: The horizon for revealing external contracts :param exogenous_force_max: If true, exogenous contracts are forced to be signed independent of the setting of `force_signing` :param production_no_borrow: If true, agents will not borrow if they fail to satisfy its production need to execute a scheduled production command :param production_no_bankruptcy: If true, agents will not go bankrupt because of an production related transaction. :param production_penalty: The penalty paid when buying from spot-market to satisfy production needs :param production_confirm: If true, the factory will confirm running processes at every time-step just before running them by calling `confirm_production` on the agent controlling it. :param compact: If True, no logs will be kept and the whole simulation will use a smaller memory footprint :param n_steps: Number of simulation steps (can be considered as days). :param time_limit: Total time allowed for the complete simulation in seconds. :param neg_n_steps: Number of negotiation steps allowed for all negotiations. :param neg_time_limit: Total time allowed for a complete negotiation in seconds. :param neg_step_time_limit: Total time allowed for a single step of a negotiation. in seconds. :param negotiation_speed: The number of negotiation steps that pass in every simulation step. If 0, negotiations will be guaranteed to finish within a single simulation step :param signing_delay: The number of simulation steps to pass between a contract is concluded and signed :param name: The name of the simulations :param \*\*kwargs: Other parameters that are passed directly to `SCML2020World` constructor. .. py:class:: Failure A production failure .. py:attribute:: __slots__ :value: ['is_inventory', 'line', 'step', 'process'] .. py:attribute:: is_inventory :type: bool True if the cause of failure was insufficient inventory. If False, the cause was insufficient funds. Note that if both conditions were true, only insufficient funds (is_inventory=False) will be reported. .. py:attribute:: line :type: int The line at which the failure happened .. py:attribute:: step :type: int The step at which the failure happened .. py:attribute:: process :type: int The process that failed to execute .. py:class:: AWI(world: negmas.situated.world.World, agent: negmas.situated.agent.Agent) Bases: :py:obj:`negmas.AgentWorldInterface` The Agent SCML2020World Interface for SCML2020 world. This class contains all the methods needed to access the simulation to extract information which are divided into 5 groups: Static World Information: Information about the world and the agent that does not change over time. These include: A. Market Information: - *n_products*: Number of products in the production chain. - *n_processes*: Number of processes in the production chain. - *n_competitors*: Number of other factories on the same production level. - *all_suppliers*: A list of all suppliers by product. - *all_consumers*: A list of all consumers by product. - *catalog_prices*: A list of the catalog prices (by product). - *inputs*: Inputs to every manufacturing process. - *outputs*: Outputs to every manufacturing process. - *is_system*: Is the given system ID corresponding to a system agent? - *is_bankrupt*: Is the given agent bankrupt (None asks about self)? - *current_step*: Current simulation step (inherited from `negmas.situated.AgentWorldInterface` ). - *n_steps*: Number of simulation steps (inherited from `negmas.situated.AgentWorldInterface` ). - *relative_time*: fraction of the simulation completed (inherited from `negmas.situated.AgentWorldInterface`). - *settings*: The system settings (inherited from `negmas.situated.AgentWorldInterface` ). B. Agent Information: - *profile*: Gives the agent profile including its production cost, number of production lines, input product index, mean of its delivery penalties, mean of its disposal costs, standard deviation of its shortfall penalties and standard deviation of its disposal costs. See `OneShotProfile` for full description. This information is private information and no other agent knows it. - *n_lines*: the number of production lines in the factory (private information). - *is_first_level*: Is the agent in the first production level (i.e. it is an input agent that buys the raw material). - *is_last_level*: Is the agent in the last production level (i.e. it is an output agent that sells the final product). - *is_middle_level*: Is the agent neither a first level nor a last level agent - *my_input_product*: The input product to the factory controlled by the agent. - *my_output_product*: The output product from the factory controlled by the agent. - *my_input_products*: All input products of a factory controlled by the agent. Currently, it is always a list of one item. For future compatibility. - *my_output_products*: All output products of a factory controlled by the agent. Currently, it is always a list of one item. For future compatibility. - *available_for_production*: Returns the line-step slots available for production. - *level*: The production level which is numerically the same as the input product. - *my_suppliers*: A list of IDs for all suppliers to the agent (i.e. agents that can sell the input product of the agent). - *my_consumers*: A list of IDs for all consumers to the agent (i.e. agents that can buy the output product of the agent). - *penalties_scale*: The scale at which to calculate disposal cost/delivery penalties. "trading" and "catalog" mean trading and catalog prices. "unit" means the contract's unit price while "none" means that disposal cost/shortfall penalty are absolute. - *n_input_negotiations*: Number of negotiations with suppliers. - *n_output_negotiations*: Number of negotiations with consumers. - *state*: The full state of the agent ( `FactoryState` ). - *current_balance*: The current balance of the agent - *current_inventory*: The current inventory of the agent (quantity per product) Dynamic World Information: Information about the world and the agent that changes over time. A. Market Information: - *trading_prices*: The trading prices of all products. This information is only available if `publish_trading_prices` is set in the world. - *exogenous_contract_summary*: A list of n_products tuples each giving the total quantity and average price of exogenous contracts for a product. This information is only available if `publish_exogenous_summary` is set in the world. B. Other Agents' Information: - *reports_of_agent*: Gives all past financial reports of a given agent. See `FinancialReport` for details. - *reports_at_step*: Gives all reports of all agents at a given step. See `FinancialReport` for details. C. Current Negotiations Information: - *current_input_issues*: The current issues for all negotiations to buy the input product of the agent. If the agent is at level zero, this will be empty. - *current_output_issues*: The current issues for all negotiations to buy the output product of the agent. If the agent is at level n_products - 1, this will be empty. D. Agent Information: - *spot_market_quantity*: The quantity the agent bought from the spot market at a given step - *spot_market_loss*: The spot market loss for the agent. Actions: A. Negotiation Control: - *request_negotiations*: Requests a set of negotiations controlled by a single controller. - *request_negotiation*: Requests a negotiation controlled by a single negotiator. B. Production Control: - *schedule_production*: Schedules production using one of the predefined scheduling strategies. - *order_production*: Orders production directly for the current step. - *set_commands*: Sets production commands directly on the factory. - *cancel_production*: Cancels a scheduled production command. Services (All inherited from `negmas.situated.AgentWorldInterface`): - *logdebug/loginfo/logwarning/logerror*: Logs to the world log at the given log level. - *logdebug_agent/loginf_agnet/...*: Logs to the agent specific log at the given log level. - *bb_query*: Queries the bulletin-board. - *bb_read*: Read a section of the bulletin-board. .. py:method:: request_negotiations(is_buy: bool, product: int, quantity: Union[int, Tuple[int, int]], unit_price: Union[int, Tuple[int, int]], time: Union[int, Tuple[int, int]], controller: Optional[negmas.SAOController] = None, negotiators: List[negmas.Negotiator] = None, partners: List[str] = None, extra: Dict[str, Any] = None, copy_partner_id=True) -> bool Requests a negotiation :param is_buy: If True the negotiation is about buying otherwise selling. :param product: The product to negotiate about :param quantity: The minimum and maximum quantities. Passing a single value q is equivalent to passing (q,q) :param unit_price: The minimum and maximum unit prices. Passing a single value u is equivalent to passing (u,u) :param time: The minimum and maximum delivery step. Passing a single value t is equivalent to passing (t,t) :param controller: The controller to manage the complete set of negotiations :param negotiators: An optional list of negotiators to use for negotiating with the given partners (in the same order). :param partners: ID of all the partners to negotiate with. :param extra: Extra information accessible through the negotiation annotation to the caller :param copy_partner_id: If true, the partner ID will be copied to the negotiator ID :returns: `True` if the partner accepted and the negotiation is ready to start Remarks: - You can either use controller or negotiators. One of them must be None. - All negotiations will use the following issues **in order**: quantity, time, unit_price - Negotiations with bankrupt agents or on invalid products (see next point) will be automatically rejected - Valid products for a factory are the following (any other products are not valid): 1. Buying an input product (i.e. product $\in$ `my_input_products` ) and an output product if the world settings allows it (see `allow_buying_output`) 1. Selling an output product (i.e. product $\in$ `my_output_products` ) and an input product if the world settings allows it (see `allow_selling_input`) .. py:method:: request_negotiation(is_buy: bool, product: int, quantity: Union[int, Tuple[int, int]], unit_price: Union[int, Tuple[int, int]], time: Union[int, Tuple[int, int]], partner: str, negotiator: negmas.SAONegotiator, extra: Dict[str, Any] = None) -> bool Requests a negotiation :param is_buy: If True the negotiation is about buying otherwise selling. :param product: The product to negotiate about :param quantity: The minimum and maximum quantities. Passing a single value q is equivalent to passing (q,q) :param unit_price: The minimum and maximum unit prices. Passing a single value u is equivalent to passing (u,u) :param time: The minimum and maximum delivery step. Passing a single value t is equivalent to passing (t,t) :param partner: ID of the partner to negotiate with. :param negotiator: The negotiator to use for this negotiation (if the partner accepted to negotiate) :param extra: Extra information accessible through the negotiation annotation to the caller :returns: `True` if the partner accepted and the negotiation is ready to start Remarks: - All negotiations will use the following issues **in order**: quantity, time, unit_price - Negotiations with bankrupt agents or on invalid products (see next point) will be automatically rejected - Valid products for a factory are the following (any other products are not valid): 1. Buying an input product (i.e. product $\in$ `my_input_products` ) and an output product if the world settings allows it (see `allow_buying_output`) 1. Selling an output product (i.e. product $\in$ `my_output_products` ) and an input product if the world settings allows it (see `allow_selling_input`) .. py:method:: schedule_production(process: int, repeats: int, step: Union[int, Tuple[int, int]] = ANY_STEP, line: int = ANY_LINE, override: bool = True, method: str = 'latest', partial_ok: bool = False) -> Tuple[numpy.ndarray, numpy.ndarray] Orders the factory to run the given process at the given line at the given step :param process: The process to run :param repeats: How many times to repeat the process :param step: The simulation step or a range of steps. The special value ANY_STEP gives the factory the freedom to schedule production at any step in the present or future. :param line: The production line. The special value ANY_LINE gives the factory the freedom to use any line :param override: Whether to override existing production commands or not :param method: When to schedule the command if step was set to a range. Options are latest, earliest :param partial_ok: If true, allows partial scheduling :returns: Tuple[int, int] giving the steps and lines at which production is scheduled. Remarks: - The step cannot be in the past. Production can only be ordered for current and future steps - ordering production of process -1 is equivalent of `cancel_production` only if both step and line are given .. py:method:: order_production(process: int, steps: numpy.ndarray, lines: numpy.ndarray) -> None Orders production of the given process :param process: The process to run :param steps: The time steps to run the process at as an np.ndarray :param lines: The corresponding lines to run the process at Remarks: - len(steps) must equal len(lines) - No checks are done in this function. It is expected to be used after calling `available_for_production` .. py:method:: available_for_production(repeats: int, step: Union[int, Tuple[int, int]] = ANY_STEP, line: int = ANY_LINE, override: bool = True, method: str = 'latest') -> Tuple[numpy.ndarray, numpy.ndarray] Finds available times and lines for scheduling production. :param repeats: How many times to repeat the process :param step: The simulation step or a range of steps. The special value ANY_STEP gives the factory the freedom to schedule production at any step in the present or future. :param line: The production line. The special value ANY_LINE gives the factory the freedom to use any line :param override: Whether to override any existing commands at that line at that time. :param method: When to schedule the command if step was set to a range. Options are latest, earliest, all :returns: Tuple[np.ndarray, np.ndarray] The steps and lines at which production is scheduled. Remarks: - You cannot order production in the past or in the current step - Ordering production, will automatically update inventory and balance for all simulation steps assuming that this production will be carried out. At the indicated `step` if production was not possible (due to insufficient funds or insufficient inventory of the input product), the predictions for the future will be corrected. .. py:method:: set_commands(commands: numpy.ndarray, step: int = -1) -> None Sets the production commands for all lines in the given step :param commands: n_lines vector of commands. A command is either a process number to run or `NO_COMMAND` to keep the line idle :param step: The step to set the commands at. If < 0, it means current step .. py:method:: cancel_production(step: int, line: int) -> bool Cancels any production commands on that line at this step :param step: The step to cancel production at (must be in the future). :param line: The production line :returns: success/failure Remarks: - The step cannot be in the past or the current step. Cancellation can only be ordered for future steps .. py:property:: trading_prices :type: numpy.ndarray Returns the current trading prices of all products .. py:property:: exogenous_contract_summary :type: List[Tuple[int, int]] The exogenous contracts in the current step for all products :returns: A list of tuples giving the total quantity and total price of all revealed exogenous contracts of all products at the current step. .. py:property:: allow_zero_quantity :type: bool Does negotiations allow zero quantity? .. py:property:: state :type: scml.scml2020.common.FactoryState Receives the factory state .. py:property:: current_balance Current balance of the agent .. py:property:: current_inventory Current inventory of the agent .. py:method:: reports_of_agent(aid: str) -> Dict[int, scml.scml2020.common.FinancialReport] Returns a dictionary mapping time-steps to financial reports of the given agent .. py:method:: reports_at_step(step: int) -> Dict[str, scml.scml2020.common.FinancialReport] Returns a dictionary mapping agent ID to its financial report for the given time-step .. py:property:: profile :type: scml.scml2020.common.FactoryProfile Gets the profile (static private information) associated with the agent .. py:property:: all_suppliers :type: List[List[str]] Returns a list of agent IDs for all suppliers for every product .. py:property:: all_consumers :type: List[List[str]] Returns a list of agent IDs for all consumers for every product .. py:property:: inputs :type: numpy.ndarray Returns the number of inputs to every production process .. py:property:: outputs :type: numpy.ndarray Returns the number of outputs to every production process .. py:property:: n_competitors :type: int Returns the number of factories/agents in the same production level .. py:property:: my_input_product :type: int Returns a list of products that are inputs to at least one process the agent can run .. py:property:: my_output_product :type: int Returns a list of products that are outputs to at least one process the agent can run .. py:property:: my_input_products :type: numpy.ndarray Returns a list of products that are inputs to at least one process the agent can run .. py:property:: my_output_products :type: numpy.ndarray Returns a list of products that are outputs to at least one process the agent can run .. py:property:: my_suppliers :type: List[str] Returns a list of IDs for all of the agent's suppliers (agents that can supply at least one product it may need). Remarks: - If the agent have multiple input products, suppliers of a specific product $p$ can be found using: **self.all_suppliers[p]**. .. py:property:: my_consumers :type: List[str] Returns a list of IDs for all the agent's consumers (agents that can consume at least one product it may produce). Remarks: - If the agent have multiple output products, consumers of a specific product $p$ can be found using: **self.all_consumers[p]**. .. py:property:: n_lines :type: int The number of lines in the corresponding factory. You can read `state` to get this among other information .. py:property:: catalog_prices :type: numpy.ndarray Returns the catalog prices of all products .. py:property:: n_products :type: int Number of products in the world .. py:property:: n_processes :type: int Returns the number of processes in the system .. py:property:: is_first_level Whether this agent is in the first production level .. py:property:: is_last_level Whether this agent is in the last production level .. py:property:: level The production level which is the index of the process for this factory (or the index of its input product) .. py:property:: is_middle_level Whether this agent is in neither in the first nor in the last level .. py:method:: is_system(aid: str) -> bool Checks whether an agent is a system agent or not :param aid: Agent ID .. py:method:: is_bankrupt(aid: Optional[str] = None) -> bool Checks whether the agent is bankrupt :param aid: Agent ID (None means self) .. py:method:: spot_market_quantity(step: Optional[int]) -> int The quantity bought by the agent from the spot market at the given step. :param step: The simulation step (day) Remarks: If step is `None`, the current step will be used .. py:method:: spot_market_loss(step: Optional[int]) -> int The spot market loss of the agent at the given step. :param step: The simulation step (day) Remarks: If step is `None`, the current step will be used .. py:function:: builtin_agent_types(as_str=False) Returns all built-in agents. :param as_str: If true, the full type name will be returned otherwise the type object itself. .. py:data:: __all__