scml.oneshot
Subpackages
Submodules
Package Contents
Classes
Base class for all agents in the One-Shot game. |
|
An agent that automatically accumulate offers from opponents and allows |
|
A synchronized agent that tries to get no more than one agreement. |
|
A one-shot agent that deligates all of its decisions to a set of independent |
|
Base class for all SAO negotiators. |
|
Uses a time-based strategy to accept a single agreement from the set |
|
A greedy agent based on OneShotAgent |
|
A greedy agent based on OneShotSyncAgent |
|
A greedy agent based on |
|
An agent that does nothing. |
|
An agent that always raises an exception if called to negotiate. It is useful as a placeholder (for example for RL and MARL exposition) |
|
An agent that randomly leaves the negotiation, accepts or counters with random outcomes |
|
An agent that distributes its needs over its partners randomly. |
|
Same as RandDistOneShotAgent but defaulting to equal distribution of needs |
|
An agent that distributes its needs over its partners randomly. |
|
A controller that agrees randomly to one offer |
|
The agent world interface for the one-shot game. |
|
State of a one-shot agent |
|
Exogenous contract information |
|
Defines all private information of a factory |
|
A report published periodically by the system showing the financial standing of an agent |
|
A context used for generating worlds satisfying predefined conditions and testing for them |
|
A context that generates oneshot worlds with agents of a given |
|
Generates a oneshot world with no constraints except compatibility with a specific ANAC competition year. |
|
Generates a world limiting the range of the agent level, production capacity |
|
Generates a world limiting the range of the agent level, production capacity |
|
Generates a oneshot world with no constraints except compatibility with a specific ANAC competition year. |
|
Generates a oneshot world limiting the range of the agent level, production capacity |
|
Generates a world limiting the range of the agent level, production capacity |
|
A world context that can generate any world compatible with the observation manager |
|
A world context that can generate any world compatible with the observation manager |
|
A supplier with almost many consumers relative to competitors |
|
A consumer with almost many suppliers relative to competitors |
|
A supplier with few consumers relative to competitors |
|
A consumer with few suppliers relative to competitors |
|
A supplier with almost same number of consumers as competitors |
|
A consumer with almost same number of suppliers as competitors |
|
Encapsulates one or more configs and switches between them when asked to generate or make something. |
|
Basic Parameters you can assume about a context. Returned by |
|
An agent that has no competitors in the same level as themselves |
|
A world in which every level has exactly one factory and the agent is a supplier |
|
An unrealistic context in which the agent is the only one in its level and all other agents are nice. |
|
An unrealistic context in which the agent is the only consumer and all suppliers are nice. |
|
An unrealistic context in which the agent is the only supplier and all consumers are nice. |
|
A oneshot agent structured in three components, state encoder, policy (action) and action decoder. |
|
Manges actions of an agent in an RL environment. |
|
An action manager that matches any context. |
|
A oneshot agent that can execute trained RL models in appropriate worlds. It falls back to the given agent type otherwise |
|
The main Gymnasium class for implementing Reinforcement Learning Agents environments. |
|
Manages the observations of an agent in an RL environment |
|
An observation manager that can be used with any SCML world. |
|
Represents a reward function. |
|
The default reward function of SCML |
|
The base class of all agents running in OneShot based on OneShotAgent. |
|
Implements an agent for handling system operations |
|
Calculates the utility function of a list of contracts or offers. |
|
Implements the a generalized form of SCML-OneShot game which supports both oneshot and standard simulations |
|
Basic oneshot simulation |
|
Oneshot simulation as used in SCML 2020 competition |
|
Oneshot simulation as used in SCML 2021 competition |
|
Oneshot simulation as used in SCML 2022 competition |
|
Oneshot simulation as used in SCML 2023 competition |
|
Oneshot simulation as used in SCML 2024 competition |
Functions
|
Checks whether an agent is a system agent or not |
|
Checks whether an agent is a system agent or not |
|
Wraps a stable_baselines3 model as an RL model |
|
Samples a random action from the action space of the |
|
Ends the negotiation or accepts with a predefined probability or samples a random response. |
|
A simple greedy policy. |
|
Returns all built-in agents. |
Attributes
Index of quantity in negotiation issues |
|
Index of unit price in negotiation issues |
|
Index of time in negotiation issues |
|
A constant indicating an invalid cost for lines incapable of running some process |
|
ID of the system buyer agent |
|
ID of the system seller agent |
|
The default action manager |
|
We assume that RL states are numpy arrays |
|
We assume that RL actions are numpy arrays |
|
A policy is a callable that receives a state and returns an action |
|
The default observation manager |
|
Information about one utility limit (either highest or lowest). See |
|
- class scml.oneshot.OneShotAgent(owner=None, ufun: scml.oneshot.OneShotUFun | None = None, name=None)[source]
Bases:
negmas.SAOController,negmas.Entity,abc.ABCBase class for all agents in the One-Shot game.
- Remarks:
You can access all of the negotiators associated with the agent using
self.negotiatorswhich is a dictionary mapping thenegotiator_idto a tuple of two values: TheSAONegotiatorobject and a key-value context dictionary. In 2021, the context will always be empty.The
negotiator_idassociated with a negotiation with some partner will be the same as the agent ID of that partner. This means that all negotiators engaged with some partner over all simulation steps will have the same ID which is useful if you are keeping information about past negotiations and partner behavior.
- property awi: scml.oneshot.OneShotAWI
Returns a
OneShotAWIobject for accessing the simulation.
- property running_negotiations: list[negmas.situated.RunningNegotiationInfo]
The negotiations currently requested by the agent.
- Returns:
A list of negotiation information objects (
RunningNegotiationInfo)
- property internal_state: dict[str, Any]
Returns the internal state of the agent for debugging purposes.
- Remarks:
In your agent, you can add any key-value pair to this dict and then use agent_log_* methods to log this information at any point.
- init()[source]
Called once after the AWI is set.
- Remarks:
Use this for any proactive initialization code.
- make_ufun(add_exogenous=False)[source]
Creates a utility function for the agent.
- Parameters:
add_exogenous – If
Truethen the exogenous contracts of the agent will be automatically added whenever the ufun is evaluated for any set of contracts, offers or otherwise.
- Remarks:
You can always as assume that self.ufun returns the ufun for your. You will not need to directly use this method in most cases.
- before_step()[source]
Called at the beginning of every step.
- Remarks:
Use this for any proactive code that needs to be done every simulation step.
- step()[source]
Called at the end of every step.
- Remarks:
Use this for any proactive code that needs to be done every simulation step.
- abstract propose(negotiator_id: str, state: negmas.SAOState) negmas.Outcome | None[source]
Proposes an offer to one of the partners.
- Parameters:
negotiator_id – ID of the negotiator (and partner)
state – Mechanism state including current step
- Returns:
an outcome to offer.
- respond(negotiator_id: str, state: negmas.SAOState, source=None) negmas.ResponseType[source]
Responds to an offer from one of the partners.
- Parameters:
negotiator_id – ID of the negotiator (and partner)
state – Mechanism state including current step
- Returns:
A response type which can either be reject, accept, or end negotiation.
- Remarks:
default behavior is to accept only if the current offer is the same or has a higher utility compared with what the agent would have proposed in the given state and reject otherwise
- on_negotiation_failure(partners: list[str], annotation: dict[str, Any], mechanism: negmas.sao.SAONMI, state: negmas.SAOState) None[source]
Called whenever a negotiation ends without agreement.
- Parameters:
partners – List of the partner IDs consisting from self and the opponent.
annotation – The annotation of the negotiation including the seller ID, buyer ID, and the product.
mechanism – The
NegotiatorMechanismInterfaceinstance containing all information about the negotiation.state – The final state of the negotiation of the type
SAOStateincluding the agreement if any.
- on_negotiation_success(contract: negmas.Contract, mechanism: negmas.sao.SAONMI) None[source]
Called whenever a negotiation ends with agreement.
- Parameters:
contract – The
Contractagreed upon.mechanism – The
NegotiatorMechanismInterfaceinstance containing all information about the negotiation that led to theContractif any.
- sign_all_contracts(contracts: list[negmas.Contract]) list[str | None][source]
Signs all contracts (used internally)
- get_negotiator(partner_id: str) negmas.sao.SAONegotiator[source]
Returns the negotiator corresponding to the given partner ID.
- Remarks:
Note that the negotiator ID and the partner ID are always the same.
- class scml.oneshot.OneShotSyncAgent(*args, **kwargs)[source]
Bases:
negmas.SAOSyncController,OneShotAgent,abc.ABCAn agent that automatically accumulate offers from opponents and allows you to control all negotiations centrally in the
counter_allmethod.- abstract counter_all(offers: dict[str, negmas.Outcome | None], states: dict[str, negmas.SAOState]) dict[str, negmas.SAOResponse][source]
Calculate a response to all offers from all negotiators (negotiator ID is the key).
- Parameters:
offers – Maps negotiator IDs to offers
states – Maps negotiator IDs to offers AT the time the offers were made.
- Returns:
A dictionary mapping negotiator ID to an
SAOResponse. The response per agent consist of a tuple. In case of acceptance or ending the negotiation the second item of the tuple should be None. In case of rejection, the second item should be the counter offer.
- Remarks:
The response type CANNOT be WAIT.
If the system determines that a loop is formed, the agent may
receive this call for a subset of negotiations not all of them.
- class scml.oneshot.OneShotSingleAgreementAgent(*args, strict: bool = False, **kwargs)[source]
Bases:
negmas.SAOSingleAgreementController,OneShotSyncAgentA synchronized agent that tries to get no more than one agreement.
This controller manages a set of negotiations from which only a single one – at most – is likely to result in an agreement. To guarantee a single agreement, pass
strict=TrueThe general algorithm for this controller is something like this:
Receive offers from all partners.
Find the best offer among them by calling the abstract
best_offermethod.Check if this best offer is acceptable using the abstract
is_acceptablemethod.If the best offer is acceptable, accept it and end all other negotiations.
If the best offer is still not acceptable, then all offers are rejected and with the partner who sent it receiving the result of
best_outcomewhile the rest of the partners receive the result ofmake_outcome.
The default behavior of
best_outcomeis to return the outcome with maximum utility.The default behavior of
make_outcomeis to return the best offer received in this round if it is valid for the respective negotiation and the result ofbest_outcomeotherwise.
- Parameters:
strict – If True the controller is guaranteed to get a single agreement but it will have to send no-response repeatedly so there is a higher chance of never getting an agreement when two of those controllers negotiate with each other
- abstract is_acceptable(offer: negmas.Outcome, source: str, state: negmas.SAOState) bool[source]
Should decide if the given offer is acceptable
- Parameters:
offer – The offer being tested
source – The ID of the negotiator that received this offer
state – The state of the negotiation handled by that negotiator
- Remarks:
If True is returned, this offer will be accepted and all other negotiations will be ended.
- abstract best_offer(offers: dict[str, negmas.Outcome]) str | None[source]
Return the ID of the negotiator with the best offer
- Parameters:
offers – A mapping from negotiator ID to the offer it received
- Returns:
The ID of the negotiator with best offer. Ties should be broken. Return None only if there is no way to calculate the best offer.
- abstract is_better(a: negmas.Outcome | None, b: negmas.Outcome | None, negotiator: str, state: negmas.SAOState) bool[source]
Compares two outcomes of the same negotiation
- Parameters:
a – “Outcome”
b – “Outcome”
negotiator – The negotiator for which the comparison is to be made
state – Current state of the negotiation
- Returns:
True if utility(a) > utility(b)
- class scml.oneshot.OneShotIndNegotiatorsAgent(*args, default_negotiator_type='negmas.sao.AspirationNegotiator', default_negotiator_params=None, normalize_ufuns=False, set_reservation=False, **kwargs)[source]
Bases:
OneShotAgentA one-shot agent that deligates all of its decisions to a set of independent negotiators (one per partner per day).
- Parameters:
default_negotiator_type – An
SAONegotiatordescendent to be used for creating all negotiators. It can be passed either as a class object or a string with the full class name (e.g. “negmas.sao.AspirationNegotiator”).default_negotiator_type – A dict specifying the paratmers used to create negotiators.
normalize_ufuns – If true, all utility functions will be normalized to have a maximum of 1.0 (the minimum value may be negative).
set_reservation – If given, the reserved value of all ufuns will be guaranteed to be between the minimum and maximum of the ufun. This is needed to avoid failures of some GeniusNegotiators.
Remarks:
To use this class, you need to override
generate_ufuns. If you want to change the negotiator type used depending on the partner, you can also overridegenerate_negotiator.- If you are using a
GeniusNegotiatoryou must guarantee the following: All ufuns are of the type
LinearAdditiveUtilityFunction.All ufuns are normalized with a maximum value of 1.0. You can use
normalize_ufuns=Trueto gruarantee that.All ufuns have a finite reserved value and at least one outcome is
above it. You can guarantee that by using
set_reservation=True.All weights of the
LinearAdditiveUtilityFunctionmust be between zero and one and the weights must sum to one.
- If you are using a
- abstract generate_ufuns() dict[str, negmas.preferences.UtilityFunction][source]
Returns a utility function for each partner. All ufuns MUST be of type
LinearAdditiveUtilityFunctionif a genius negotiator is used.
- generate_negotiator(partner_id: str) negmas.sao.SAONegotiator[source]
Returns a negotiator to be used with some partner.
- Remarks:
The default implementation will use the
default_negotiator_typeanddefault_negotiator_params.
- _get_ufuns()[source]
Internal method that makes sure the reservation value is set to a meaningful value and that the ufun is normalized if needed
- init()[source]
Called once after the AWI is set.
- Remarks:
Use this for any proactive initialization code.
- step()[source]
Called at the end of every step.
- Remarks:
Use this for any proactive code that needs to be done every simulation step.
- make_negotiator(negotiator_type=None, name: str | None = None, **kwargs) negmas.ControlledSAONegotiator[source]
Creates a negotiator but does not add it to the controller. Call
add_negotiatorto add it.- Parameters:
negotiator_type – Type of the negotiator to be created.
name – negotiator name
**kwargs – any key-value pairs to be passed to the negotiator constructor
- Returns:
The negotiator to be controlled. None for failure
- Remarks:
If you would like not to negotiate, just return
EndingNegotiator()instead of None. The value None should only be returned if an exception is to be thrown.
- class scml.oneshot.EndingNegotiator(preferences: negmas.preferences.preferences.Preferences | None = None, ufun: negmas.preferences.base_ufun.BaseUtilityFunction | None = None, name: str | None = None, parent: negmas.negotiators.Controller | None = None, owner: negmas.situated.Agent | None = None, id: str | None = None, type_name: str | None = None, can_propose: bool = True, **kwargs)[source]
Bases:
negmas.sao.SAONegotiator,negmas.ControlledNegotiatorBase class for all SAO negotiators.
- Parameters:
name – Negotiator name
parent – Parent controller if any
preferences – The preferences of the negotiator
ufun – The utility function of the negotiator (overrides preferences if given)
owner – The
Agentthat owns the negotiator.
- Remarks:
- propose(state)[source]
Propose an offer or None to refuse.
- Parameters:
state –
GBStategiving current state of the negotiation.- Returns:
The outcome being proposed or None to refuse to propose
- Remarks:
This function guarantees that no agents can propose something with a utility value
- respond(state, source=None)[source]
Called to respond to an offer. This is the method that should be overriden to provide an acceptance strategy.
- Parameters:
state – a
SAOStategiving current state of the negotiation.source – The ID of the negotiator that gave this offer
- Returns:
The response to the offer
- Return type:
ResponseType
- Remarks:
The default implementation never ends the negotiation
The default implementation asks the negotiator to
propose`() and accepts the `offerif its utility was at least as good as the offer that it would have proposed (and above the reserved value).The current offer to respond to can be accessed through
state.current_offer
- class scml.oneshot.SingleAgreementAspirationAgent(*args, **kwargs)[source]
Bases:
scml.oneshot.agent.OneShotSyncAgentUses a time-based strategy to accept a single agreement from the set it is considering.
- before_step()[source]
Called at the beginning of every step.
- Remarks:
Use this for any proactive code that needs to be done every simulation step.
- counter_all(offers, states)[source]
Calculate a response to all offers from all negotiators (negotiator ID is the key).
- Parameters:
offers – Maps negotiator IDs to offers
states – Maps negotiator IDs to offers AT the time the offers were made.
- Returns:
A dictionary mapping negotiator ID to an
SAOResponse. The response per agent consist of a tuple. In case of acceptance or ending the negotiation the second item of the tuple should be None. In case of rejection, the second item should be the counter offer.
- Remarks:
The response type CANNOT be WAIT.
If the system determines that a loop is formed, the agent may
receive this call for a subset of negotiations not all of them.
- class scml.oneshot.GreedyOneShotAgent(*args, concession_exponent=None, acc_price_slack=float('inf'), step_price_slack=None, opp_price_slack=None, opp_acc_price_slack=None, range_slack=None, **kwargs)[source]
Bases:
scml.oneshot.agent.OneShotAgentA greedy agent based on OneShotAgent
- Parameters:
concession_exponent – A real number controlling how fast does the agent concede on price.
acc_price_slack – The allowed slack in price limits compared with best prices I got so far
step_price_slack – The allowed slack in price limits compared with best prices I got this step
opp_price_slack – The allowed slack in price limits compared with best prices I got so far from a given opponent in this step
opp_acc_price_slack – The allowed slack in price limits compared with best prices I got so far from a given opponent so far
range_slack – Always consider prices above (1-
range_slack) of the best possible prices good enough.
- Remarks:
A
concession_exponentgreater than one makes the agent concede super linearly and vice versa
- propose(negotiator_id: str, state, source=None) negmas.Outcome | None[source]
Proposes an offer to one of the partners.
- Parameters:
negotiator_id – ID of the negotiator (and partner)
state – Mechanism state including current step
- Returns:
an outcome to offer.
- respond(negotiator_id, state, source=None) negmas.ResponseType[source]
Responds to an offer from one of the partners.
- Parameters:
negotiator_id – ID of the negotiator (and partner)
state – Mechanism state including current step
- Returns:
A response type which can either be reject, accept, or end negotiation.
- Remarks:
default behavior is to accept only if the current offer is the same or has a higher utility compared with what the agent would have proposed in the given state and reject otherwise
- class scml.oneshot.GreedySyncAgent(*args, threshold=None, **kwargs)[source]
Bases:
scml.oneshot.agent.OneShotSyncAgent,GreedyOneShotAgentA greedy agent based on OneShotSyncAgent
- before_step()[source]
Called at the beginning of every step.
- Remarks:
Use this for any proactive code that needs to be done every simulation step.
- first_proposals()[source]
Decide a first proposal on every negotiation. Returning None for a negotiation means ending it.
- counter_all(offers, states) dict[source]
Respond to a set of offers given the negotiation state of each.
- propose(negotiator_id, state)[source]
Proposes an offer to one of the partners.
- Parameters:
negotiator_id – ID of the negotiator (and partner)
state – Mechanism state including current step
- Returns:
an outcome to offer.
- respond(negotiator_id, state, source='')[source]
Responds to an offer from one of the partners.
- Parameters:
negotiator_id – ID of the negotiator (and partner)
state – Mechanism state including current step
- Returns:
A response type which can either be reject, accept, or end negotiation.
- Remarks:
default behavior is to accept only if the current offer is the same or has a higher utility compared with what the agent would have proposed in the given state and reject otherwise
- class scml.oneshot.GreedySingleAgreementAgent(*args, **kwargs)[source]
Bases:
scml.oneshot.agent.OneShotSingleAgreementAgentA greedy agent based on
OneShotSingleAgreementAgent- before_step()[source]
Called at the beginning of every step.
- Remarks:
Use this for any proactive code that needs to be done every simulation step.
- is_acceptable(offer, source, state) bool[source]
Should decide if the given offer is acceptable
- Parameters:
offer – The offer being tested
source – The ID of the negotiator that received this offer
state – The state of the negotiation handled by that negotiator
- Remarks:
If True is returned, this offer will be accepted and all other negotiations will be ended.
- class scml.oneshot.OneshotDoNothingAgent(owner=None, ufun: scml.oneshot.OneShotUFun | None = None, name=None)[source]
Bases:
scml.oneshot.agent.OneShotAgentAn agent that does nothing.
Remarks:
Note that this agent will lose money whenever it is at the edges (i.e. it is an input or an output agent trading in raw material or final product).
- propose(negotiator_id, state)[source]
Proposes an offer to one of the partners.
- Parameters:
negotiator_id – ID of the negotiator (and partner)
state – Mechanism state including current step
- Returns:
an outcome to offer.
- respond(negotiator_id, state, source=None)[source]
Responds to an offer from one of the partners.
- Parameters:
negotiator_id – ID of the negotiator (and partner)
state – Mechanism state including current step
- Returns:
A response type which can either be reject, accept, or end negotiation.
- Remarks:
default behavior is to accept only if the current offer is the same or has a higher utility compared with what the agent would have proposed in the given state and reject otherwise
- class scml.oneshot.Placeholder(*args, **kwargs)[source]
Bases:
scml.oneshot.policy.OneShotPolicyAn agent that always raises an exception if called to negotiate. It is useful as a placeholder (for example for RL and MARL exposition)
- class scml.oneshot.RandomOneShotAgent(*args, p_accept=PROB_ACCEPTANCE, p_end=PROB_END, **kwargs)[source]
Bases:
scml.oneshot.agent.OneShotAgentAn agent that randomly leaves the negotiation, accepts or counters with random outcomes
- propose(negotiator_id, state) negmas.outcomes.Outcome | None[source]
Proposes an offer to one of the partners.
- Parameters:
negotiator_id – ID of the negotiator (and partner)
state – Mechanism state including current step
- Returns:
an outcome to offer.
- respond(negotiator_id, state, source=None) negmas.ResponseType[source]
Responds to an offer from one of the partners.
- Parameters:
negotiator_id – ID of the negotiator (and partner)
state – Mechanism state including current step
- Returns:
A response type which can either be reject, accept, or end negotiation.
- Remarks:
default behavior is to accept only if the current offer is the same or has a higher utility compared with what the agent would have proposed in the given state and reject otherwise
- class scml.oneshot.RandDistOneShotAgent(*args, **kwargs)[source]
Bases:
SyncRandomOneShotAgentAn agent that distributes its needs over its partners randomly.
- Parameters:
equal – If given, it tries to equally distribute its needs over as many of its suppliers/consumers as possible
overordering_max – Maximum fraction of needs to over-order. For example, it the agent needs 5 items and this is 0.2, it will order 6 in the first negotiation step.
overordering_min – Minimum fraction of needs to over-order. Used in the last negotiation step.
overordering_exp – Controls how fast does the over-ordering quantity go from max to min.
concession_exp – Controls how fast does the agent concedes on matching its needs exactly.
mismatch_max – Maximum mismtach in quantity allowed between needs and accepted offers. If a fraction, it is will be this fraction of the production capacity (n_lines).
- class scml.oneshot.EqualDistOneShotAgent(*args, **kwargs)[source]
Bases:
SyncRandomOneShotAgentSame as RandDistOneShotAgent but defaulting to equal distribution of needs
- Parameters:
equal – If given, it tries to equally distribute its needs over as many of its suppliers/consumers as possible
overordering_max – Maximum fraction of needs to over-order. For example, it the agent needs 5 items and this is 0.2, it will order 6 in the first negotiation step.
overordering_min – Minimum fraction of needs to over-order. Used in the last negotiation step.
overordering_exp – Controls how fast does the over-ordering quantity go from max to min.
concession_exp – Controls how fast does the agent concedes on matching its needs exactly.
mismatch_max – Maximum mismtach in quantity allowed between needs and accepted offers. If a fraction, it is will be this fraction of the production capacity (n_lines).
- class scml.oneshot.SyncRandomOneShotAgent(*args, equal: bool = False, overordering_max: float = 0.2, overordering_min: float = 0.0, overordering_exp: float = 0.4, mismatch_exp: float = 4.0, mismatch_max: float = 0.3, **kwargs)[source]
Bases:
scml.oneshot.agent.OneShotSyncAgentAn agent that distributes its needs over its partners randomly.
- Parameters:
equal – If given, it tries to equally distribute its needs over as many of its suppliers/consumers as possible
overordering_max – Maximum fraction of needs to over-order. For example, it the agent needs 5 items and this is 0.2, it will order 6 in the first negotiation step.
overordering_min – Minimum fraction of needs to over-order. Used in the last negotiation step.
overordering_exp – Controls how fast does the over-ordering quantity go from max to min.
concession_exp – Controls how fast does the agent concedes on matching its needs exactly.
mismatch_max – Maximum mismtach in quantity allowed between needs and accepted offers. If a fraction, it is will be this fraction of the production capacity (n_lines).
- init()[source]
Called once after the AWI is set.
- Remarks:
Use this for any proactive initialization code.
- distribute_needs(t: float) dict[str, int][source]
Distributes my needs randomly over all my partners
- first_proposals()[source]
Gets a set of proposals to use for initializing the negotiation.
- Returns:
A dictionary mapping each negotiator (in self.negotiators dict) to an outcome to be used as the first proposal if the agent is to start a negotiation.
- counter_all(offers, states)[source]
Calculate a response to all offers from all negotiators (negotiator ID is the key).
- Parameters:
offers – Maps negotiator IDs to offers
states – Maps negotiator IDs to offers AT the time the offers were made.
- Returns:
A dictionary mapping negotiator ID to an
SAOResponse. The response per agent consist of a tuple. In case of acceptance or ending the negotiation the second item of the tuple should be None. In case of rejection, the second item should be the counter offer.
- Remarks:
The response type CANNOT be WAIT.
If the system determines that a loop is formed, the agent may
receive this call for a subset of negotiations not all of them.
- class scml.oneshot.SingleAgreementRandomAgent(*args, p_accept: float = PROB_ACCEPTANCE, **kwargs)[source]
Bases:
scml.oneshot.agent.OneShotSingleAgreementAgentA controller that agrees randomly to one offer
- is_acceptable(offer: negmas.outcomes.Outcome, source: str, state: negmas.sao.SAOState) bool[source]
Should decide if the given offer is acceptable
- Parameters:
offer – The offer being tested
source – The ID of the negotiator that received this offer
state – The state of the negotiation handled by that negotiator
- Remarks:
If True is returned, this offer will be accepted and all other negotiations will be ended.
- best_offer(offers: dict[str, negmas.outcomes.Outcome]) str | None[source]
Return the ID of the negotiator with the best offer
- Parameters:
offers – A mapping from negotiator ID to the offer it received
- Returns:
The ID of the negotiator with best offer. Ties should be broken. Return None only if there is no way to calculate the best offer.
- is_better(a: negmas.outcomes.Outcome | None, b: negmas.outcomes.Outcome | None, negotiator: str, state: negmas.sao.SAOState) bool[source]
Compares two outcomes of the same negotiation
- Parameters:
a – “Outcome”
b – “Outcome”
negotiator – The negotiator for which the comparison is to be made
state – Current state of the negotiation
- Returns:
True if utility(a) > utility(b)
- class scml.oneshot.OneShotAWI(world: scml.oneshot.world.SCMLBaseWorld, agent: scml.oneshot.agent.OneShotAgent)[source]
Bases:
negmas.situated.AgentWorldInterfaceThe agent world interface for the one-shot game.
This class contains all the methods needed to access the simulation to extract information which are divided into 4 groups:
- Static World Information:
Information about the world and the agent that does not change over time. These include:
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.
- proudction_capacities: The total production capacity (i.e. number of lines)
for each production level (i.e. 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
catalog_prices: A list of the catalog prices (by product).
price_multiplier: The multiplier multiplied by the trading/catalog price when the negotiation agendas are created to decide the maximum and lower quantities.
is_exogenous_forced: Are exogenous contracts always forced or can the agent decide not to sign them.
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).state: The full state of the agent (
OneShotState).**settings* The system settings (inherited from
negmas.situated.AgentWorldInterface).**quantity_range* The maximum quantity in all negotiation agendas (new in 0.6.1)
**price_range* The maximum number of different prices in any negotiation agenda (new in 0.6.1)
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
OneShotProfilefor 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.
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.
- Dynamic World Information:
Information about the world and the agent that changes over time.
Market Information:
trading_prices: The trading prices of all products. This information is only available if
publish_trading_pricesis 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_summaryis set in the world.is_perishable: Are all products perishable?
Other Agents’ Information:
reports_of_agent: Gives all past financial reports of a given agent. See
FinancialReportfor details.reports_at_step: Gives all reports of all agents at a given step. See
FinancialReportfor details.
Current Negotiations Information:
current_input_outcome_space: The current outcome-space for all negotiations to buy the input product of the agent. If the agent is at level zero, this will have no issues.
current_output_outcome_space: The current outcome-space for all negotiations to buy the output product of the agent. If the agent is at level n_products - 1, this will have no issues.
current_negotiation_details: Details on all current negotiations separated into “buy” and “sell” dictionaries.
Useful helpers about current negotiations:
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. This is exactly the same as current_input_outcome_space.issues
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. This is exactly the same as current_output_outcome_space.issues
current_buy_nmis: All NMIs for current buy negotiations.
current_sell_nmis: All NMIs for current sell negotiations.
current_nmis: All states for current negotiations.
current_buy_states: All states for current buy negotiations.
current_sell_states: All states for current sell negotiations.
current_states: All states for current negotiations.
current_buy_offers: All offers for current buy negotiations.
current_sell_offers: All offers for current sell negotiations.
current_offers: All offers for current negotiations.
running_buy_nmis: All NMIs for running buy negotiations.
running_sell_nmis: All NMIs for running sell negotiations.
running_nmis: All states for running negotiations.
running_buy_states: All states for running buy negotiations.
running_sell_states: All states for running sell negotiations.
running_states: All states for running negotiations.
Agent Information:
current_exogenous_input_quantity: The total quantity the agent have in its input exogenous contract.
current_exogenous_input_price: The total price of the agent’s input exogenous contract.
current_exogenous_output_quantity: The total quantity the agent have in its output exogenous contract.
current_exogenous_output_price: The total price of the agent’s output exogenous contract
current_disposal_cost: The disposal cost per unit item in the current step.
current_shortfall_penalty: The shortfall penalty per unit item in the current step.
current_balance: The current balance of the agent
current_score: The current score (balance / initial balance) of the agent
current_inventory_input: The total quantity remaining in the inventory of the input product
current_inventory_output: The total quantity remaining in the inventory of the output product
current_inventory: The total quantity remaining in the inventory of the input and output product
Sales and Supplies (quantities) for today:
sales: Today’s sales per customer so far.
supplies: Today’s supplies per supplier so far.
total_sales: Today’s total sales so far.
total_supplies: Today’s total supplies so far.
needed_sales: Today’s needed sales as of now (exogenous input + total supplies - exogenous output - total sales so far).
needed_supplies: Today’s needed supplies as of now (exogenous output + total sales - exogenous input - total supplies so far).
- 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.
- property all_suppliers: list[list[str]]
Returns a list of agent IDs for all suppliers for every product
- property production_capacities: list[int]
Returns the total production capacity in the market for each process
- property all_consumers: list[list[str]]
Returns a list of agent IDs for all consumers for every product
- property catalog_prices: numpy.ndarray
Returns the catalog prices of all products
- property price_multiplier: float
Controls the minimum and maximum prices in the negotiation agendas
- Remarks:
The base price is either the catalog price if trading price information is not public or the trading price.
The minimum unit price in any negotiation agenda is the base price of the previous product in the chain **divided by the multiplier. If that is less than 1, the minimum unit price becomes 1.
The maximum unit price in any negotiation agenda is the base price of the previous product in the chain **multiplied by the multiplier. If that is less than 1, the minimum unit price becomes 1.
- property is_exogenous_forced: bool
Are exogenous contracts forced in the sense that the agent cannot decide not to sign them?
- property profile: scml.oneshot.common.OneShotProfile
Gets the profile (static private information) associated with the agent
- property n_lines: int
The number of lines in the corresponding factory. You can read
stateto get this among other information
- property is_first_level
Whether this agent is in the first production level
- property is_last_level
Whether this agent is in the last production level
- property level
The production level which is the index of the process for this factory (or the index of its input product)
- property is_middle_level
Whether this agent is in neither in the first nor in the last level
- property my_suppliers: list[str]
Returns a list of IDs for all of the agent’s suppliers (agents that can supply the product I need).
- property my_consumers: list[str]
Returns a list of IDs for all the agent’s consumers (agents that can consume at least one product it may produce).
- property my_partners: list[str]
Returns a list of IDs for all of the agent’s partners starting with suppliers
- property penalties_scale: Literal[trading, catalog, unit, none]
- property state: scml.oneshot.common.OneShotState
Returns the private state of the agent in that world
- property current_balance
- property current_disposal_cost: float
Cost of storing one unit (penalizes buying too much/ selling too little)
- property current_storage_cost: float
Cost of storing one unit (penalizes buying too much/ selling too little)
- property current_shortfall_penalty: float
Cost of failure to deliver one unit (penalizes buying too little / selling too much)
- property trading_prices: numpy.ndarray
Returns the current trading prices of all products
- property exogenous_contract_summary: 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. Will be empty if the world has “publish_exogenous_summary==False”
- property current_input_outcome_space: negmas.outcomes.DiscreteCartesianOutcomeSpace
- property current_output_outcome_space: negmas.outcomes.DiscreteCartesianOutcomeSpace
- property current_negotiation_details: dict[str, dict[str, scml.oneshot.common.NegotiationDetails]]
Details of current negotiations separated as two dicts for buying and selling.
- Remarks:
current_negotiation_details[“buy”] gives details on all negotiations for buying
current_negotiation_details[“sell”] gives details on all negotiations for selling
- property current_buy_states: dict[str, negmas.sao.SAOState]
All running buy negotiations as a mapping from partner ID to current negotiation state
- property current_sell_states: dict[str, negmas.sao.SAOState]
All running sell negotiations as a mapping from partner ID to current negotiation state
- property current_states: dict[str, negmas.sao.SAOState]
All running negotiations as a mapping from partner ID to current negotiation state
- property current_buy_nmis: dict[str, negmas.sao.SAONMI]
All running buy negotiations as a mapping from partner ID to current negotiation nmi
- property current_sell_nmis: dict[str, negmas.sao.SAONMI]
All running negotiations as a mapping from partner ID to current negotiation state
- property current_nmis: dict[str, negmas.sao.SAONMI]
All running negotiations as a mapping from partner ID to current negotiation nmi
- property current_buy_offers: dict[str, negmas.outcomes.Outcome]
All current buy negotiations as a mapping from partner ID to current offer
- property current_sell_offers: dict[str, negmas.outcomes.Outcome]
All current sell negotiations as a mapping from partner ID to current offer
- property current_offers: dict[str, negmas.outcomes.Outcome]
All current negotiations as a mapping from partner ID to current offer
- property running_buy_states: dict[str, negmas.sao.SAOState]
All running buy negotiations as a mapping from partner ID to current negotiation state
- property running_sell_states: dict[str, negmas.sao.SAOState]
All running sell negotiations as a mapping from partner ID to current negotiation state
- property running_states: dict[str, negmas.sao.SAOState]
All running negotiations as a mapping from partner ID to current negotiation state
- property running_sell_nmis: dict[str, negmas.sao.SAONMI]
All running sell negotiations as a mapping from partner ID to current negotiation nmi
- property running_buy_nmis: dict[str, negmas.sao.SAONMI]
All running buy negotiations as a mapping from partner ID to current negotiation nmi
- property running_nmis: dict[str, negmas.sao.SAONMI]
All running negotiations as a mapping from partner ID to current negotiation nmi
- property future_sales: dict[int, dict[str, int]]
Future sales (quantity) per customer so far (excluding this day)
- property future_supplies: dict[int, dict[str, int]]
Future supplies (quantity) per supplier so far (excluding this day)
- property future_sales_cost: dict[int, dict[str, int]]
Future sales (total price) per customer so far (excluding this day)
- property future_supplies_cost: dict[int, dict[str, int]]
Future supplies (total price) per supplier so far (excluding this day)
- property needed_sales: int
Sales that need to be secured (exogenous input + total supplies - exogenous output - total sales so far)
- property needed_supplies: int
Supplies that need to be secured (exogenous output + total sales - exogenous input - total supplies so far)
- is_system(aid: str) bool[source]
Checks whether an agent is a system agent or not
- Parameters:
aid – Agent ID
- is_bankrupt(aid: str | None = None) bool[source]
Checks whether an agent is a system agent or not
- Parameters:
aid – Agent ID
- penalty_multiplier(is_input: bool, unit_price: float | None) float[source]
Returns the penalty multiplier for a contract with the give unit price.
- Remarks:
The unit price is only needed if the penalties_scale is unit. For all other options (trading, catalog, none), the penalty scale does not depend on the unit price.
- reports_of_agent(aid: str) dict[int, scml.oneshot.common.FinancialReport][source]
Returns a dictionary mapping time-steps to financial reports of the given agent
- reports_at_step(step: int) dict[str, scml.oneshot.common.FinancialReport][source]
Returns a dictionary mapping agent ID to its financial report for the given time-step
- total_sales_from(start: int) int[source]
Total sales starting at start and ending at end (inclusive). Past days are ignored
- total_supplies_from(start: int) int[source]
Total supplies starting at start and ending at end (inclusive). Past days are ignored
- total_sales_between(start: int, end: int) int[source]
Total sales starting at start and ending at end (inclusive). Past days are ignored
- total_supplies_between(start: int, end: int) int[source]
Total supplies starting at start and ending at end (inclusive). Past days are ignored
- total_supplies_until(step: int) int[source]
Total supplies starting today until the given step (inclusive). Past days are ignored
- class scml.oneshot.OneShotState[source]
State of a one-shot agent
- property running_buy_states: dict[str, negmas.sao.common.SAOState]
All running buy negotiations as a mapping from partner ID to current negotiation state
- property current_sell_states: dict[str, negmas.sao.common.SAOState]
All running sell negotiations as a mapping from partner ID to current negotiation state
- property current_states: dict[str, negmas.sao.common.SAOState]
All running negotiations as a mapping from partner ID to current negotiation state
- property current_buy_nmis: dict[str, negmas.sao.SAONMI]
All running buy negotiations as a mapping from partner ID to current negotiation nmi
- property current_sell_nmis: dict[str, negmas.sao.SAONMI]
All running sell negotiations as a mapping from partner ID to current negotiation nmi
- property current_nmis: dict[str, negmas.sao.SAONMI]
All running negotiations as a mapping from partner ID to current negotiation state
- property current_buy_offers: dict[str, negmas.outcomes.Outcome]
All current buy negotiations as a mapping from partner ID to current offer
- property current_sell_offers: dict[str, negmas.outcomes.Outcome]
All current sell negotiations as a mapping from partner ID to current offer
- property current_offers: dict[str, negmas.outcomes.Outcome]
All current negotiations as a mapping from partner ID to current offer
- total_future_supplies: int
Total quantity registered as supplies in the future using
awi.register_supply.
- price_multiplier: float
The multiplier multiplied by the trading/catalog price when the negotiation agendas are created to decide the maximum and lower quantities.
- is_exogenous_forced: bool
exogenous contracts always forced or can the agent decide not to sign them.
- relative_simulation_time: float
Fraction of the simulation completed (inherited from
negmas.situated.AgentWorldInterface).
- profile: OneShotProfile
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
OneShotProfilefor full description. This information is private information and no other agent knows it.
- is_first_level: bool
Is the agent in the first production level (i.e. it is an input agent that buys the raw material).
- is_last_level: bool
Is the agent in the last production level (i.e. it is an output agent that sells the final product).
- my_suppliers: list[str]
A list of IDs for all suppliers to the agent (i.e. agents that can sell the input product of the agent).
- my_consumers: list[str]
A list of IDs for all consumers to the agent (i.e. agents that can buy the output product of the agent).
- my_partners: list[str]
A list of IDs for all negotiation partners of the agent (in the order suppliers then consumers).
- penalties_scale: Literal[trading, catalog, unit, none]
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.
- trading_prices: list[float]
The trading prices of all products. This information is only available if
publish_trading_pricesis set in the world.
- exogenous_contract_summary: list[tuple[int, int]]
A list of n_products lists each giving the total quantity and average price of exogenous contracts for a product. This information is only available if
publish_exogenous_summaryis set in the world.
- reports_of_agents: dict[str, dict[int, FinancialReport]]
Gives all past financial reports of a given agent. See
FinancialReportfor details.
- current_input_outcome_space: negmas.outcomes.DiscreteCartesianOutcomeSpace
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. This is exactly the same as current_input_outcome_space.issues
- current_output_outcome_space: negmas.outcomes.DiscreteCartesianOutcomeSpace
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. This is exactly the same as current_output_outcome_space.issues
- current_negotiation_details: dict[str, dict[str, NegotiationDetails]]
Details on all current negotiations separated into “buy” and “sell” dictionaries.
- needed_sales: int
Today’s needed sales as of now (exogenous input - exogenous output - total sales so far).
- needed_supplies: int
Today needed supplies as of now (exogenous output - exogenous input - total supplies).
- storage_cost: float = 0.0
Current unit storage cost. Only used in standard worlds where products are not perishable
- classmethod random(oneshot: bool | None = None) OneShotState[source]
- class scml.oneshot.OneShotExogenousContract[source]
Exogenous contract information
- __slots__ = ['quantity', 'unit_price', 'product', 'seller', 'buyer', 'time', 'revelation_time']
- seller: str
Seller ID (when passing contrtacts to the constructor of SCML2020OneShotWorld, you can also pass an interged index referring to the agent’s index in the
agent_typeslist)
- buyer: str
Buyer ID (when passing contrtacts to the constructor of SCML2020OneShotWorld, you can also pass an interged index referring to the agent’s index in the
agent_typeslist)
- revelation_time: int
Simulation step at which the contract is revealed to its owner. Should not exceed
timeand the defaultgenerate()method sets it to time
- class scml.oneshot.OneShotProfile[source]
Defines all private information of a factory
- property level
- property output_product
- property process
- shortfall_penalty_mean: float
A positive number specifying the average penalty for selling too much.
- shortfall_penalty_dev: float
A positive number specifying the std. dev. of penalty for selling too much.
- storage_cost_mean: float
A positive number specifying the average cost for keeping inventory for one step. This is only used if the products are not
perishable.
- storage_cost_dev: float
A positive number specifying the std. dev. cost for keeping inventory for one step. This is only used if the products are not
perishable.
- classmethod random(input_product: int, oneshot: bool) OneShotProfile[source]
- class scml.oneshot.FinancialReport[source]
A report published periodically by the system showing the financial standing of an agent
- __slots__ = ['agent_id', 'step', 'cash', 'assets', 'breach_prob', 'breach_level', 'is_bankrupt', 'agent_name']
- breach_prob: float
Number of times the agent breached a contract over the total number of contracts it signed.
- breach_level: float
Sum of the agent’s breach levels so far divided by the number of contracts it signed.
- scml.oneshot.is_system_agent(aid: str) bool[source]
Checks whether an agent is a system agent or not
- Parameters:
aid – Agent ID
- Returns:
True if the ID is for a system agent.
- scml.oneshot.INFINITE_COST[source]
A constant indicating an invalid cost for lines incapable of running some process
- scml.oneshot.is_system_agent(aid: str) bool[source]
Checks whether an agent is a system agent or not
- Parameters:
aid – Agent ID
- Returns:
True if the ID is for a system agent.
- class scml.oneshot.Context[source]
Bases:
abc.ABCA context used for generating worlds satisfying predefined conditions and testing for them
- abstract generate(types: tuple[type[scml.oneshot.agent.OneShotAgent], Ellipsis] | None = None, params: tuple[dict[str, Any], Ellipsis] | None = None, name: str | None = None) tuple[scml.oneshot.world.SCMLBaseWorld, tuple[scml.oneshot.agent.OneShotAgent]][source]
Generates a world with one or more agents to be controlled externally and returns both
- Parameters:
agent_types – The types of a list of agents to be guaranteed to exist in the world
agent_params – The parameters to pass to the constructors of these agents. None means no parameters for any agents
name – The name of the worlds to generate. Uses a random name if not given
- Returns:
The constructed world and a tuple of the agents created corresponding (in order) to the given agent types/params
- abstract is_valid_world(world: scml.oneshot.world.SCMLBaseWorld) bool[source]
Checks that the given world could have been generated from this context
- abstract is_valid_awi(awi: scml.oneshot.awi.OneShotAWI) bool[source]
Checks that the given AWI is connected to a world that could have been generated from this context
- abstract contains_context(context: Context) bool[source]
Checks that the any world generated from the given
contextcould have been generated from this context
- __contains__(other: SCMLBaseWorld | OneShotAWI | Context) bool[source]
- class scml.oneshot.GeneralContext[source]
Bases:
BaseContextA context that generates oneshot worlds with agents of a given
typeswith predetermined structure and settings- force_signing = True
- cost_increases_with_level = True
- exogenous_generation_method = 'profitable'
- equal_exogenous_supply = False
- equal_exogenous_sales = False
- make_predefined_config(agent_types: list[type[scml.oneshot.agent.OneShotAgent]], agent_processes: list[int], agent_params: list[dict[str, Any]], n_agents_per_process: list[int]) dict[str, Any][source]
Generates a config for a world
- contains_context(context: Context, raise_on_failure: bool = False, warn_on_failure: bool = False, n_tests: int = NTESTS) bool[source]
Checks that the any world generated from the given
contextcould have been generated from this context
- is_valid_world(world: scml.oneshot.world.SCMLBaseWorld, raise_on_failure: bool = False, warn_on_failure: bool = False, types: tuple[str | type[scml.oneshot.agent.OneShotAgent], Ellipsis] | None = None) bool[source]
Checks that the given world could have been generated from this context
- contains_general_context(context: GeneralContext) bool[source]
Checks that the any world generated from the given
contextcould have been generated from this context
- class scml.oneshot.ANACContext[source]
Bases:
GeneralContextGenerates a oneshot world with no constraints except compatibility with a specific ANAC competition year.
- class scml.oneshot.LimitedPartnerNumbersContext[source]
Bases:
GeneralContextGenerates a world limiting the range of the agent level, production capacity and the number of suppliers, consumers, and optionally same-level competitors.
- find_test_agents(world: scml.oneshot.world.SCMLBaseWorld, types: tuple[type[scml.oneshot.agent.OneShotAgent], Ellipsis] | None = None) list[str][source]
- is_valid_world(world: scml.oneshot.world.SCMLBaseWorld, types: tuple[type[scml.oneshot.agent.OneShotAgent], Ellipsis] | None = None, raise_on_failure: bool = False, warn_on_failure: bool = False) bool[source]
Checks that the given world could have been generated from this context
- class scml.oneshot.FixedPartnerNumbersContext[source]
Bases:
LimitedPartnerNumbersContextGenerates a world limiting the range of the agent level, production capacity and the number of suppliers, consumers, and optionally same-level competitors.
- class scml.oneshot.ANACOneShotContext[source]
Bases:
ANACContextGenerates a oneshot world with no constraints except compatibility with a specific ANAC competition year.
- class scml.oneshot.LimitedPartnerNumbersOneShotContext[source]
Bases:
LimitedPartnerNumbersContextGenerates a oneshot world limiting the range of the agent level, production capacity and the number of suppliers, consumers, and optionally same-level competitors.
- class scml.oneshot.FixedPartnerNumbersOneShotContext[source]
Bases:
FixedPartnerNumbersContextGenerates a world limiting the range of the agent level, production capacity and the number of suppliers, consumers, and optionally same-level competitors.
- class scml.oneshot.SupplierContext(*args, **kwargs)[source]
Bases:
LimitedPartnerNumbersOneShotContextA world context that can generate any world compatible with the observation manager
- class scml.oneshot.ConsumerContext(*args, **kwargs)[source]
Bases:
LimitedPartnerNumbersOneShotContextA world context that can generate any world compatible with the observation manager
- class scml.oneshot.StrongSupplierContext(*args, **kwargs)[source]
Bases:
SupplierContextA supplier with almost many consumers relative to competitors
- class scml.oneshot.StrongConsumerContext(*args, **kwargs)[source]
Bases:
ConsumerContextA consumer with almost many suppliers relative to competitors
- class scml.oneshot.WeakSupplierContext(*args, **kwargs)[source]
Bases:
SupplierContextA supplier with few consumers relative to competitors
- class scml.oneshot.WeakConsumerContext(*args, **kwargs)[source]
Bases:
ConsumerContextA consumer with few suppliers relative to competitors
- class scml.oneshot.BalancedSupplierContext(*args, **kwargs)[source]
Bases:
SupplierContextA supplier with almost same number of consumers as competitors
- class scml.oneshot.BalancedConsumerContext(*args, **kwargs)[source]
Bases:
ConsumerContextA consumer with almost same number of suppliers as competitors
- class scml.oneshot.RepeatingContext[source]
Bases:
BaseContextEncapsulates one or more configs and switches between them when asked to generate or make something.
- make_config(types: tuple[type[scml.oneshot.agent.OneShotAgent], Ellipsis] = DEFAULT_PLACEHOLDER_AGENT_TYPES, params: tuple[dict[str, Any], Ellipsis] | None = None) dict[str, Any][source]
Generates a config for a world
- classmethod from_context(context: BaseContext, n: int = 1, types: tuple[type[scml.oneshot.agent.OneShotAgent]] = DEFAULT_PLACEHOLDER_AGENT_TYPES, rename: bool = False, randomize: bool = False)[source]
- contains_repeating_context(context: RepeatingContext, raise_on_failure: bool = False, warn_on_failure: bool = False)[source]
- is_valid_world(world: scml.oneshot.world.SCMLBaseWorld, raise_on_failure=RAISE_ON_FAILURE, warn_on_failure=WARN_ON_FAILURE, types: tuple[str | type[scml.oneshot.agent.OneShotAgent], Ellipsis] | None = None) bool[source]
Checks that the given world could have been generated from this context
- class scml.oneshot.ContextParams[source]
Basic Parameters you can assume about a context. Returned by
extract_context_params
- class scml.oneshot.MonopolicContext[source]
Bases:
LimitedPartnerNumbersContextAn agent that has no competitors in the same level as themselves
- class scml.oneshot.SingleAgentPerLevelSupplierContext[source]
Bases:
MonopolicContextA world in which every level has exactly one factory and the agent is a supplier
- class scml.oneshot.EutopiaContext[source]
Bases:
MonopolicContextAn unrealistic context in which the agent is the only one in its level and all other agents are nice.
- non_competitors: tuple[str | type[scml.oneshot.agent.OneShotAgent], Ellipsis]
- class scml.oneshot.EutopiaConsumerContext[source]
Bases:
EutopiaContextAn unrealistic context in which the agent is the only consumer and all suppliers are nice.
- class scml.oneshot.EutopiaSupplierContext[source]
Bases:
EutopiaContextAn unrealistic context in which the agent is the only supplier and all consumers are nice.
- class scml.oneshot.OneShotPolicy(*args, **kwargs)[source]
Bases:
scml.oneshot.agent.OneShotSyncAgent,abc.ABCA oneshot agent structured in three components, state encoder, policy (action) and action decoder.
The agent is divided into three components:
State encoder (encode_state()) which takes the current state of all negotiation mechanisms, access the awi as needed, and generates a state which can be of any type to be passed to the next component.
Policy (act()) which takes the state generated from the state encoder and returns an action which may be encoded as any type to be passed to the next component. The policy (i.e. `act` () method) is not supposed to access the AWI or any other members of the class. It is preferred to be a pure function. This makes it easy to test the policy at predefined conditions (i.e. states) without having to construct a simulation.
Action decoder (decode_action()) which takes the action generated from the policy and generates the appropriate set of responses to all partners.
- Remarks:
The simplest form of state encoder which is implemented by default is to return the
statemember of the AWI.The simplest form of action encoding is to simply return the responses as a
dict[str, SAOResponse]fromactwhich is then passed as it is bydecode_action. This is the default implementation ofdecode_action
- encode_state(mechanism_states: dict[str, negmas.sao.common.SAOState]) Any[source]
Called to generate a state to be passed to the act() method. The default is all of
awiof typeOneShotState
- decode_action(action: Any) dict[str, negmas.sao.common.SAOResponse][source]
Generates offers to all partners from an encoded action. Default is to return the action as it is assuming it is a
dict[str, SAOResponse]
- encode_action(responses: dict[str, negmas.sao.common.SAOResponse]) dict[str, negmas.sao.common.SAOResponse][source]
Receives offers for all partners and generates the corresponding action. Used mostly for debugging and testing.
- counter_all(offers: dict[str, negmas.outcomes.Outcome | None], states: dict[str, negmas.sao.common.SAOState]) dict[str, negmas.sao.common.SAOResponse][source]
Calculate a response to all offers from all negotiators (negotiator ID is the key).
- Parameters:
offers – Maps negotiator IDs to offers
states – Maps negotiator IDs to offers AT the time the offers were made.
- Returns:
A dictionary mapping negotiator ID to an
SAOResponse. The response per agent consist of a tuple. In case of acceptance or ending the negotiation the second item of the tuple should be None. In case of rejection, the second item should be the counter offer.
- Remarks:
The response type CANNOT be WAIT.
If the system determines that a loop is formed, the agent may
receive this call for a subset of negotiations not all of them.
- class scml.oneshot.ActionManager[source]
Bases:
abc.ABCManges actions of an agent in an RL environment.
- context: scml.oneshot.context.BaseContext
- abstract decode(awi: scml.oneshot.awi.OneShotAWI, action: numpy.ndarray) dict[str, negmas.sao.common.SAOResponse][source]
Decodes an action from an array to a
PurchaseOrderand aCounterMessage.
- encode(awi: scml.oneshot.awi.OneShotAWI, responses: dict[str, negmas.sao.common.SAOResponse]) numpy.ndarray[source]
Encodes an action as an array. This is only used for testing so it is optional
- class scml.oneshot.FlexibleActionManager[source]
Bases:
ActionManagerAn action manager that matches any context.
- Parameters:
n_prices – Number of distinct prices allowed in the action.
max_quantity – Maximum allowed quantity to offer in any negotiation. The number of quantities is one plus that because zero is allowed to model ending negotiation.
n_partners – Maximum of partners allowed in the action.
- Remarks:
This action manager will always generate offers that are within the price and quantity limits given in its parameters. Wen decoding them, it will scale them up so that the maximum corresponds to the actual value in the world it finds itself. For example, if
n_pricesis 10 and the world has only two prices currently in the price issue, it will use any value less than 5 as the minimum price and any value above 5 as the maximum price. If on the other hand the current price issue has 20 values, then it will scale by multiplying the number given in the encoded action (ranging from 0 to 9) by 19/9 which makes it range from 0 to 19 which is what is expected by the world.This action manager will adjust offers for different number of partners as follows: - If the true number of partners is larger than
n_partnersused by this action manager,it will simply use
n_partnersof them and always end negotiations with the rest of them.If the true number of partners is smaller than
n_partners, it will use the firstn_partnersvalues in the encoded action and increase the quantities of any counter offers (i.e. ones in which the response is REJECT_OFFER) by the amount missing from the ignored partners in the encoded action up to the maximum quantities allowed by the current negotiation context. For example, ifn_partneersis 4 and we have only 2 partners in reality, and the received quantities from partners were [4, 3] while the maximum quantity allowed is 10 and the encoded action was [2, *, 3, *, 2, *, 1, *] (where we ignored prices), then the encoded action will be converted to [(Reject, 5, *), (Accept, 3, *)] where the 3 extra units that were supposed to be offered to the last two partners are moved to the first partner. If the maximum quantity allowed was 4 in that example, the result will be [(Reject, 4, *), (Accept, 3, *)].
- make_space() gymnasium.spaces.MultiDiscrete | gymnasium.spaces.Box[source]
Creates the action space
- decode(awi: scml.oneshot.awi.OneShotAWI, action: numpy.ndarray) dict[str, negmas.sao.common.SAOResponse][source]
Generates offers to all partners from an encoded action. Default is to return the action as it is assuming it is a
dict[str, SAOResponse]
- encode(awi: scml.oneshot.awi.OneShotAWI, responses: dict[str, negmas.sao.common.SAOResponse]) numpy.ndarray[source]
Receives offers for all partners and generates the corresponding action. Used mostly for debugging and testing.
- class scml.oneshot.OneShotRLAgent(*args, models: list[scml.oneshot.rl.common.RLModel] | tuple[scml.oneshot.rl.common.RLModel, Ellipsis] = tuple(), observation_managers: list[scml.oneshot.rl.observation.ObservationManager] | tuple[scml.oneshot.rl.observation.ObservationManager, Ellipsis] = tuple(), action_managers: list[scml.oneshot.rl.action.ActionManager] | tuple[scml.oneshot.rl.action.ActionManager, Ellipsis] | None = None, fallback_type: type[scml.oneshot.agent.OneShotAgent] | None = GreedyOneShotAgent, fallback_params: dict[str, Any] | None = None, dynamic_context_switching: bool = False, randomize_test_order: bool = False, **kwargs)[source]
Bases:
scml.oneshot.policy.OneShotPolicyA oneshot agent that can execute trained RL models in appropriate worlds. It falls back to the given agent type otherwise
- Parameters:
models – List of models to choose from.
observation_managers – List of observation managers. Must be the same length as
modelsaction_managers – List of action managers of the same length as
modelsorNoneto use the default action manager.fallback_type – A
OneShotAgenttype to use as a fall-back if the current world is not compatible with any observation/action managersfallback_params – Parameters of the
fallback_typedynamic_context_switching – If
True, the world is tested each step (instead of only at init) to find the appropriate modelrandomize_test_order – If
True, the order at which the observation/action managers are checked for compatibility with the current world is randomized.**kwargs – Any other OneShotPolicy parameters
- init()[source]
Called once after the AWI is set.
- Remarks:
Use this for any proactive initialization code.
- encode_state(mechanism_states: dict[str, negmas.sao.common.SAOState]) scml.oneshot.rl.common.RLState[source]
Called to generate a state to be passed to the act() method. The default is all of
awiof typeOneShotState
- decode_action(action: scml.oneshot.rl.common.RLAction) dict[str, negmas.sao.common.SAOResponse][source]
Generates offers to all partners from an encoded action. Default is to return the action as it is assuming it is a
dict[str, SAOResponse]
- act(state: scml.oneshot.rl.common.RLState) scml.oneshot.rl.common.RLAction[source]
The main policy. Generates an action given a state
- propose(*args, **kwargs) negmas.outcomes.Outcome | None[source]
Called when the agent is asking to propose in one negotiation
- respond(*args, **kwargs) negmas.gb.common.ResponseType[source]
Called when the agent is asked to respond to an offer
- scml.oneshot.model_wrapper(model, deterministic: bool = False) RLModel[source]
Wraps a stable_baselines3 model as an RL model
- class scml.oneshot.OneShotEnv(action_manager: scml.oneshot.rl.action.ActionManager, observation_manager: scml.oneshot.rl.observation.ObservationManager, reward_function: scml.oneshot.rl.reward.RewardFunction = DefaultRewardFunction(), context: scml.oneshot.context.BaseContext = FixedPartnerNumbersOneShotContext(), agent_type: type[scml.oneshot.agent.OneShotAgent] = Placeholder, agent_params: dict[str, Any] | None = None, extra_checks: bool = True, skip_after_negotiations: bool = True, render_mode=None, debug=False)[source]
Bases:
gymnasium.EnvThe main Gymnasium class for implementing Reinforcement Learning Agents environments.
The class encapsulates an environment with arbitrary behind-the-scenes dynamics through the
step()andreset()functions. An environment can be partially or fully observed by single agents. For multi-agent environments, see PettingZoo.The main API methods that users of this class need to know are:
step()- Updates an environment with actions returning the next agent observation, the reward for taking that actions, if the environment has terminated or truncated due to the latest action and information from the environment about the step, i.e. metrics, debug info.reset()- Resets the environment to an initial state, required before calling step. Returns the first agent observation for an episode and information, i.e. metrics, debug info.render()- Renders the environments to help visualise what the agent see, examples modes are “human”, “rgb_array”, “ansi” for text.close()- Closes the environment, important when external software is used, i.e. pygame for rendering, databases
Environments have additional attributes for users to understand the implementation
action_space- The Space object corresponding to valid actions, all valid actions should be contained within the space.observation_space- The Space object corresponding to valid observations, all valid observations should be contained within the space.reward_range- A tuple corresponding to the minimum and maximum possible rewards for an agent over an episode. The default reward range is set to \((-\infty,+\infty)\).spec- An environment spec that contains the information used to initialize the environment fromgymnasium.make()metadata- The metadata of the environment, i.e. render modes, render fpsnp_random- The random number generator for the environment. This is automatically assigned duringsuper().reset(seed=seed)and when assessingself.np_random.
See also
For modifying or extending environments use the
gymnasium.WrapperclassNote
To get reproducible sampling of actions, a seed can be set with
env.action_space.seed(123).- close()[source]
After the user has finished using the environment, close contains the code necessary to “clean up” the environment.
This is critical for closing rendering windows, database or HTTP connections. Calling
closeon an already closed environment has no effect and won’t raise an error.
- render()[source]
Compute the render frames as specified by
render_modeduring the initialization of the environment.The environment’s
metadatarender modes (env.metadata["render_modes"]) should contain the possible ways to implement the render modes. In addition, list versions for most render modes is achieved throughgymnasium.makewhich automatically applies a wrapper to collect rendered frames.Note
As the
render_modeis known during__init__, the objects used to render the environment state should be initialised in__init__.By convention, if the
render_modeis:None (default): no render is computed.
“human”: The environment is continuously rendered in the current display or terminal, usually for human consumption. This rendering should occur during
step()andrender()doesn’t need to be called. ReturnsNone.“rgb_array”: Return a single frame representing the current state of the environment. A frame is a
np.ndarraywith shape(x, y, 3)representing RGB values for an x-by-y pixel image.“ansi”: Return a strings (
str) orStringIO.StringIOcontaining a terminal-style text representation for each time step. The text can include newlines and ANSI escape sequences (e.g. for colors).“rgb_array_list” and “ansi_list”: List based version of render modes are possible (except Human) through the wrapper,
gymnasium.wrappers.RenderCollectionthat is automatically applied duringgymnasium.make(..., render_mode="rgb_array_list"). The frames collected are popped afterrender()is called orreset().
Note
Make sure that your class’s
metadata"render_modes"key includes the list of supported modes.Changed in version 0.25.0: The render function was changed to no longer accept parameters, rather these parameters should be specified in the environment initialised, i.e.,
gymnasium.make("CartPole-v1", render_mode="human")
- reset(*, seed: int | None = None, options: dict[str, Any] | None = None) tuple[Any, dict[str, Any]][source]
Resets the environment to an initial internal state, returning an initial observation and info.
This method generates a new starting state often with some randomness to ensure that the agent explores the state space and learns a generalised policy about the environment. This randomness can be controlled with the
seedparameter otherwise if the environment already has a random number generator andreset()is called withseed=None, the RNG is not reset.Therefore,
reset()should (in the typical use case) be called with a seed right after initialization and then never again.For Custom environments, the first line of
reset()should besuper().reset(seed=seed)which implements the seeding correctly.Changed in version v0.25: The
return_infoparameter was removed and now info is expected to be returned.- Parameters:
seed (optional int) – The seed that is used to initialize the environment’s PRNG (
np_random). If the environment does not already have a PRNG andseed=None(the default option) is passed, a seed will be chosen from some source of entropy (e.g. timestamp or /dev/urandom). However, if the environment already has a PRNG andseed=Noneis passed, the PRNG will not be reset. If you pass an integer, the PRNG will be reset even if it already exists. Usually, you want to pass an integer right after the environment has been initialized and then never again. Please refer to the minimal example above to see this paradigm in action.options (optional dict) – Additional information to specify how the environment is reset (optional, depending on the specific environment)
- Returns:
- Observation of the initial state. This will be an element of
observation_space (typically a numpy array) and is analogous to the observation returned by
step().- info (dictionary): This dictionary contains auxiliary information complementing
observation. It should be analogous to the
inforeturned bystep().
- Observation of the initial state. This will be an element of
- Return type:
observation (ObsType)
- step(action)[source]
Run one timestep of the environment’s dynamics using the agent actions.
When the end of an episode is reached (
terminated or truncated), it is necessary to callreset()to reset this environment’s state for the next episode.Changed in version 0.26: The Step API was changed removing
donein favor ofterminatedandtruncatedto make it clearer to users when the environment had terminated or truncated which is critical for reinforcement learning bootstrapping algorithms.- Parameters:
action (ActType) – an action provided by the agent to update the environment state.
- Returns:
- An element of the environment’s
observation_spaceas the next observation due to the agent actions. An example is a numpy array containing the positions and velocities of the pole in CartPole.
reward (SupportsFloat): The reward as a result of taking the action. terminated (bool): Whether the agent reaches the terminal state (as defined under the MDP of the task)
which can be positive or negative. An example is reaching the goal state or moving into the lava from the Sutton and Barton, Gridworld. If true, the user needs to call
reset().- truncated (bool): Whether the truncation condition outside the scope of the MDP is satisfied.
Typically, this is a timelimit, but could also be used to indicate an agent physically going out of bounds. Can be used to end the episode prematurely before a terminal state is reached. If true, the user needs to call
reset().- info (dict): Contains auxiliary diagnostic information (helpful for debugging, learning, and logging).
This might, for instance, contain: metrics that describe the agent’s performance state, variables that are hidden from observations, or individual reward terms that are combined to produce the total reward. In OpenAI Gym <v26, it contains “TimeLimit.truncated” to distinguish truncation and termination, however this is deprecated in favour of returning terminated and truncated variables.
- done (bool): (Deprecated) A boolean value for if the episode has ended, in which case further
step()calls will return undefined results. This was removed in OpenAI Gym v26 in favor of terminated and truncated attributes. A done signal may be emitted for different reasons: Maybe the task underlying the environment was solved successfully, a certain timelimit was exceeded, or the physics simulation has entered an invalid state.
- An element of the environment’s
- Return type:
observation (ObsType)
- class scml.oneshot.ObservationManager[source]
Bases:
ProtocolManages the observations of an agent in an RL environment
- property context: scml.oneshot.context.BaseContext
- encode(awi: scml.oneshot.awi.OneShotAWI) numpy.ndarray[source]
Encodes an observation from the agent’s awi
- make_first_observation(awi: scml.oneshot.awi.OneShotAWI) numpy.ndarray[source]
Creates the initial observation (returned from gym’s reset())
- get_offers(awi: scml.oneshot.awi.OneShotAWI, encoded: numpy.ndarray) dict[str, negmas.outcomes.Outcome | None][source]
Gets the offers from an encoded awi
- class scml.oneshot.FlexibleObservationManager[source]
Bases:
BaseObservationManagerAn observation manager that can be used with any SCML world.
- Parameters:
capacity_multiplier – A factor to multiply by the number of lines to give the maximum quantity allowed in offers
exogenous_multiplier – A factor to multiply maximum production capacity with when encoding exogenous quantities
continuous – If given the observation space will be a Box otherwise it will be a MultiDiscrete
n_prices – The number of prices to use for encoding the unit price (if not
continuous)max_production_cost – The limit for production cost. Anything above that will be mapped to this max
max_group_size – Maximum size used for grouping observations from multiple partners. This will be used in the number of partners in the simulation is larger than the number used for training.
n_past_received_offers – Number of past received offers to add to the observation.
n_bins –
bins to use for discretization (if not
continuous)
n_sigmas – The number of sigmas used for limiting the range of randomly distributed variables
extra_checks – If given, extra checks are applied to make sure encoding and decoding make sense
- Remarks:
…
- _previous_offers: collections.deque
- get_dims() list[int][source]
Get the sizes of all dimensions in the observation space. Used if not continuous.
- make_space() gymnasium.spaces.MultiDiscrete | gymnasium.spaces.Box[source]
Creates the action space
- make_first_observation(awi: scml.oneshot.awi.OneShotAWI) numpy.ndarray[source]
Creates the initial observation (returned from gym’s reset())
- encode(awi: scml.oneshot.awi.OneShotAWI) numpy.ndarray[source]
Encodes the awi as an array
- extra_obs(awi: scml.oneshot.awi.OneShotAWI) list[tuple[float, int] | float][source]
The observation values other than offers and previous offers.
- Returns:
A list of tuples. Each is some observation variable as a real number between zero and one and a number of bins to use for discrediting this variable. If a single value, the number of bins will be self.n_bin
- get_offers(awi: scml.oneshot.awi.OneShotAWI, encoded: numpy.ndarray) dict[str, negmas.outcomes.Outcome | None][source]
Gets offers from an encoded awi.
- scml.oneshot.random_action(obs: numpy.ndarray, env: scml.oneshot.rl.env.OneShotEnv) numpy.ndarray[source]
Samples a random action from the action space of the
- scml.oneshot.random_policy(obs: numpy.ndarray, env: scml.oneshot.rl.env.OneShotEnv, pend: float = 0.05, paccept: float = 0.15) numpy.ndarray[source]
Ends the negotiation or accepts with a predefined probability or samples a random response.
- scml.oneshot.greedy_policy(obs: numpy.ndarray, awi: scml.oneshot.awi.OneShotAWI, obs_manager: scml.oneshot.rl.observation.ObservationManager, action_manager: scml.oneshot.rl.action.ActionManager = FlexibleActionManager(ANACOneShotContext()), debug=False, distributor: Callable[[int, int], list[int]] = all_but_concentrated) numpy.ndarray[source]
A simple greedy policy.
- Parameters:
obs – The current observation
awi – The AWI of the agent running the policy
obs_manager – The observation manager used to encode the observation
action_manager – The action manager to be used to encode the action
debug – If True, extra assertions are tested
distributor – A callable that receives a total quantity to be distributed over n partners and returns a list of n values that sum to this total quantity
- Remarks:
Accepts the subset of offers with maximum total quantity under current needs.
The remaining quantity is distributed over the remaining partners using the distributor function
Prices are set to the worst for the agent if the price range is small else they are set randomly
- class scml.oneshot.RewardFunction[source]
Bases:
ProtocolRepresents a reward function.
- Remarks:
before_actionis called before the action is executed for initialization and should return info to be passed to the call__call__is called with the awi (to get the state), action and info and should return the reward
- before_action(awi: scml.oneshot.awi.OneShotAWI) Any[source]
Called before executing the action from the RL agent to save any required information for calculating the reward in its return
- Remarks:
The returned value will be passed as
infoto__call__()when it is time to calculate the reward.
- __call__(awi: scml.oneshot.awi.OneShotAWI, action: dict[str, negmas.SAOResponse], info: Any) float[source]
Called to calculate the reward to be given to the agent at the end of a step.
- Parameters:
awi –
OneShotAWIto access the agent’s stateaction – The action (decoded) as a mapping from partner ID to responses to their last offer.
info – Information generated from
before_action(). You an use this to store baselines for calculating the reward
- Returns:
The reward (a number) to be given to the agent at the end of the step.
- class scml.oneshot.DefaultRewardFunction[source]
Bases:
RewardFunctionThe default reward function of SCML
- Remarks:
The reward is the difference between the balance before the action and after it.
- before_action(awi: scml.oneshot.awi.OneShotAWI) float[source]
Called before executing the action from the RL agent to save any required information for calculating the reward in its return
- Remarks:
The returned value will be passed as
infoto__call__()when it is time to calculate the reward.
- __call__(awi: scml.oneshot.awi.OneShotAWI, action: dict[str, negmas.SAOResponse], info: float)[source]
Called to calculate the reward to be given to the agent at the end of a step.
- Parameters:
awi –
OneShotAWIto access the agent’s stateaction – The action (decoded) as a mapping from partner ID to responses to their last offer.
info – Information generated from
before_action(). You an use this to store baselines for calculating the reward
- Returns:
The reward (a number) to be given to the agent at the end of the step.
- class scml.oneshot.DefaultOneShotAdapter(*args, **kwargs)[source]
Bases:
negmas.Adapter,scml.oneshot.mixins.OneShotUFunCreatorMixinThe base class of all agents running in OneShot based on OneShotAgent.
Remarks:
It inherits from
Adapterallowing it to just pass any calls not defined explicity in it to the internal_objobject representing the OneShotAgent.
- property awi: scml.oneshot.awi.OneShotAWI
Gets the Agent-world interface.
- property short_type_name
Returns a short name of the type of this entity
- on_negotiation_failure(partners, annotation, mechanism, state)[source]
Called whenever a negotiation ends without agreement
- on_negotiation_success(contract: negmas.Contract, mechanism)[source]
Called whenever a negotiation ends with agreement
- on_contract_executed(contract: negmas.Contract) None[source]
Called after successful contract execution for which the agent is one of the partners.
- on_contract_breached(contract: negmas.Contract, breaches: list[negmas.Breach], resolution: negmas.Contract | None) None[source]
Called after complete processing of a contract that involved a breach.
- Parameters:
contract – The contract
breaches – All breaches committed (even if they were resolved)
resolution – The resolution contract if re-negotiation was successful. None if not.
- init_()[source]
Called to initialize the agent after the world is initialized. the AWI is accessible at this point.
- _respond_to_negotiation_request(initiator: str, partners: list[str], issues: list[negmas.Issue], annotation: dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface, role: str | None, req_id: str | None) negmas.Negotiator | None[source]
Called by the mechanism to ask for joining a negotiation. The agent can refuse by returning a None
- Parameters:
initiator – The ID of the agent that initiated the negotiation request
partners – The partner list (will include this agent)
issues – The list of issues
annotation – Any annotation specific to this negotiation.
mechanism – The mechanism that started the negotiation
role – The role of this agent in the negotiation
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
Negotiatorobject 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
- set_renegotiation_agenda(contract: negmas.Contract, breaches: list[negmas.Breach]) negmas.RenegotiationRequest | None[source]
Received by partners in ascending order of their total breach levels in order to set the renegotiation agenda when contract execution fails
- Parameters:
contract – The contract being breached
breaches – All breaches on
contract
- Returns:
Renegotiation agenda (issues to negotiate about to avoid reporting the breaches).
- respond_to_renegotiation_request(contract: negmas.Contract, breaches: list[negmas.Breach], agenda: negmas.RenegotiationRequest) negmas.Negotiator | None[source]
Called to respond to a renegotiation request
- Parameters:
agenda –
contract –
breaches –
Returns:
- class scml.oneshot._StdSystemAgent(*args, role, **kwargs)[source]
Bases:
DefaultOneShotAdapterImplements an agent for handling system operations
- property type_name
Returns a short name of the type of this entity
- property short_type_name
Returns a short name of the type of this entity
- respond_to_negotiation_request(initiator: str, issues: list[negmas.Issue], annotation: dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface) negmas.Negotiator | None[source]
- on_negotiation_failure(partners: list[str], annotation: dict[str, Any], mechanism: negmas.NegotiatorMechanismInterface, state: negmas.MechanismState) None[source]
Called whenever a negotiation ends without agreement
- class scml.oneshot.OneShotUFun(ex_pin: int, ex_qin: int, ex_pout: int, ex_qout: int, input_product: int, input_agent: bool, output_agent: bool, production_cost: float, disposal_cost: float, storage_cost: float, shortfall_penalty: float, input_penalty_scale: float | None, output_penalty_scale: float | None, storage_penalty_scale: float | None, n_input_negs: int, n_output_negs: int, current_step: int, agent_id: str | None, time_range: tuple[int, int], inventory_in: int = 0, inventory_out: int = 0, input_qrange: tuple[int, int] = (0, 0), input_prange: tuple[int, int] = (0, 0), output_qrange: tuple[int, int] = (0, 0), output_prange: tuple[int, int] = (0, 0), force_exogenous: bool = True, n_lines: int = 10, normalized: bool = False, current_balance: int | float = float('inf'), suppliers: set[str] = set(), consumers: set[str] = set(), perishable=True, **kwargs)[source]
Bases:
negmas.preferences.StationaryMixin,negmas.preferences.UtilityFunctionCalculates the utility function of a list of contracts or offers.
- Parameters:
force_exogenous – Is the agent forced to accept exogenous contracts given through
ex_*arguments?ex_pin – total price of exogenous inputs for this agent
ex_qin – total quantity of exogenous inputs for this agent
ex_pout – total price of exogenous outputs for this agent
ex_qout – total quantity of exogenous outputs for this agent.
cost – production cost of the agent.
disposal_cost – disposal cost per unit of input/output.
shortfall_penalty – penalty for failure to deliver one unit of output.
input_agent – Is the agent an input agent which means that its input product is the raw material
output_agent – Is the agent an output agent which means that its output product is the final product
n_lines – Number of production lines. If None, will be read through the AWI.
input_product – Index of the input product. If None, will be read through the AWI
input_qrange – A 2-int tuple giving the range of input quantities negotiated. If not given will be read through the AWI
input_prange – A 2-int tuple giving the range of input unit prices negotiated. If not given will be read through the AWI
output_qrange – A 2-int tuple giving the range of output quantities negotiated. If not given will be read through the AWI
output_prange – A 2-int tuple giving the range of output unit prices negotiated. If not given will be read through the AWI
n_input_negs – How many input negotiations are allowed. If not given, it will be the number of suppliers as given by the AWI
n_output_negs – How many output negotiations are allowed. If not given, it will be the number of consumers as given by the AWI
current_step – Current simulation step. Needed only for
ufun_rangewhen returning best outcomesnormalized – If given the values returned by
from_*,utility_rangeand__call__will all be normalized between zero and one.
- Remarks:
The utility function assumes that the agent will have to pay for all its input products but will receive money only for the output products it could generate and sell.
The utility function respects production capacity (n. lines). The agent cannot produce more than the number of lines it has.
disposal cost is paid for items bought but not produced only. Items consumed in production (i.e. sold) are not counted.
- property max_utility
The maximum possible utility value
- property min_utility
The minimum possible utility value
- register_sale(q: int, p: int, t: int)[source]
Registers a sale to be considered when calculating utilities
- register_supply(q: int, p: int, t: int)[source]
Registers a supply to be considered when calculating utilities
- eval(offer: tuple[int, int, int] | None) float[source]
Calculates the utility function given a single contract.
- Remarks:
This method calculates the utility value of a single offer assuming all other negotiations end in failure.
It can only be called for agents that exist in the first or last layer of the production graph.
- from_contracts(contracts: Iterable[negmas.Contract], return_info: Literal[False] = False, ignore_exogenous=True) float[source]
- from_contracts(contracts: Iterable[negmas.Contract], return_info: Literal[True], ignore_exogenous=True) UtilityInfo
Calculates the utility function given a list of contracts
- Parameters:
contracts – A list/tuple of contracts
ignore_exogenous – If given, any contracts with a system agent will be ignored.
- Remarks:
This method ignores any unsigned contracts passed to it.
We do not consider time at all so it is implicitly assumed that all contracts have the same delivery time value.
The reason for having the
ignore_exogenousparameter is to avoid double counting exogenous contracts if their information is passed during construction of the ufun and they also exist in the list ofcontractspassed here.
- from_offers(offers: tuple[tuple[int, int, int | float] | None, Ellipsis] | dict[str, tuple[int, int, int] | None], outputs: tuple[bool, Ellipsis] | None = None, return_info: Literal[False] = False, ignore_signed_contracts: bool = True) float[source]
- from_offers(offers: tuple[tuple[int, int, int | float] | None, Ellipsis] | dict[str, tuple[int, int, int] | None], outputs: tuple[bool, Ellipsis] | None, return_info: Literal[True], ignore_signed_contracts: bool = True) UtilityInfo
Calculates the utility value given a list of offers and whether each offer is for output or not (= input).
- Parameters:
offers – An iterable (e.g. list) of tuples each with three values: (quantity, time, unit price) IN THAT ORDER. Time is ignored and can be set to any value.
outputs – An iterable of the same length as offers of booleans specifying for each offer whether it is an offer for buying the agent’s output product.
return_info – If true, detailed utility information is returned as Utility Info
ignore_signed_contracts – If true, ignores the registered signed contracts. This means that only exogenous contracts and offers will be used in evaluating the utility.
- Remarks:
This method takes into account the exogenous contract information passed when constructing the ufun.
You can pass a dictionary mapping partner ID to an offer and the system will use the correct value for the corresponding outputs array.
- from_aggregates(qin: int, qout_signed: int, qout_sold: int, pin: int, pout: int, input_penalty: float, output_penalty: float, storage_penalty: float) float[source]
Calculates the utility from aggregates of input/output quantity/prices
- Parameters:
qin – Input quantity (total including all exogenous contracts).
qout_signed – Output quantity (total including all exogenous contracts) that the agent agreed to sell.
qout_sold – Output quantity (total including all exogenous contracts) that the agent will actually sell.
pin – Input total price (i.e. unit price * qin).
pout – Output total price (i.e. unit price * qin).
input_penalty – total disposal cost
output_penalty – total shortfall penalty
storage_penalty – total storage penalty
- Remarks:
Most likely, you do not need to directly call this method. Consider
from_offersandfrom_contractsthat take current balance and exogenous contract information (passed during ufun construction) into account.The method respects production capacity (n. lines). The agent cannot produce more than the number of lines it has.
This method does not take exogenous contracts or current balance into account.
The method assumes that the agent CAN pay for all input and production.
- breach_level(qin: int = 0, qout: int = 0)[source]
Calculates the breach level that would result from a given quantities
- is_breach(qin: int = 0, qout: int = 0)[source]
Whether the given quantities would lead to a breach.
- minmax(*args, **kwargs) tuple[float, float][source]
Finds the range of the given utility function for the given outcomes
- Parameters:
self – The utility function
issues – List of issues (optional)
outcomes – A collection of outcomes (optional)
max_cardinality – the maximum number of outcomes to try sampling (if sampling is used and outcomes are not given)
above_reserve – If given, the minimum and maximum will be set to reserved value if they were less than it.
- Returns:
(lowest, highest) utilities in that order
- extreme_outcomes(outcome_space: negmas.outcomes.OutcomeSpace | None = None, issues: Iterable[negmas.outcomes.Issue] | None = None, outcomes: Iterable[negmas.outcomes.Outcome] | None = None, max_cardinality=1000) tuple[negmas.outcomes.Outcome, negmas.outcomes.Outcome][source]
- utility_range(outcome_space: negmas.outcomes.OutcomeSpace | None = None, issues: list[negmas.outcomes.Issue] | None = None, outcomes: list[negmas.outcomes.Outcome] | None = None, return_outcomes=False, max_n_outcomes=1000) tuple[float, float] | tuple[float, float, negmas.outcomes.Outcome, negmas.outcomes.Outcome][source]
Finds the utility range and optionally returns the corresponding outcomes from a given issue space or in a single negotiation.
- Parameters:
issues – The set of issues of the negotiation. If not given it will be read from the AWI. Note that you cannot specify these issues except for agent in the first or last layer of the production graph (because otherwise, the agent cannot know whether this negotiation is for buying of selling).
outcomes – A list of outcomes to consider. Using outcomes is much slower than using issues and you should never pass both.
infeasible_cutoff – A utility value under which we consider the outcome infeasible.
return_outcomes – If given the worst and best outcomes (in that order) will be returned.
max_n_outcomes – Maximum number of outcomes to try. Not used.
- Returns:
A tuple of worst and best utility values if
return_outcomesisFalse. otherwise, the worst and best outcomes are appended to the returned utilities leading to a 4-items tuple instead of two.
- Remarks:
You will get a warning if you use a list of outcomes here because it is too slow.
You should only pass
issuesif you know that the agent is either an input agent or an output agent. Agents in the middle of the production graph cannot know whether these issues are for buying of for selling. To find the utility range for these agents, you can useworstandbestthat allow specifying input and output issues separately.It is always assumed that the range required is for a single negotiation not a set of negotiations and under the assumption that all other negotiations if any will end in failure
- find_limit(best: bool, n_input_negs=None, n_output_negs=None, secured_input_quantity=0, secured_input_unit_price=0.0, secured_output_quantity=0, secured_output_unit_price=0.0, ignore_signed_contracts: bool = True) UFunLimit[source]
Finds either the maximum or the minimum of the ufun.
- Parameters:
best – Best(max) or worst (min) ufun value?
n_input_negs – How many input negs are we to consider? None means all
n_output_negs – How many output negs are we to consider? None means all
secured_input_quantity – A quantity that MUST be bought
secured_input_unit_price – The (average) unit price of the quantity that MUST be bought.
secured_output_quantity – A quantity that MUST be sold.
secured_output_unit_price – The (average) unit price of the quantity that MUST be sold.
ignore_signed_contracts – If True all signed contracts will be ignored. Use secured_* to pass this information if you need to in this case.
- Remarks:
You can use the
secured_*arguments and control over the number of negotiations to consider to find the utility limits given some already concluded and signed contracts
- find_limit_brute_force(best, n_input_negs=None, n_output_negs=None, secured_input_quantity=0, secured_input_unit_price=0.0, secured_output_quantity=0, secured_output_unit_price=0.0, ignore_signed_contracts=True) UFunLimit[source]
Finds either the maximum and the minimum of the ufun.
- Parameters:
best – Best(max) or worst (min) ufun value?
n_input_negs – How many input negs are we to consider? None means all
n_output_negs – How many output negs are we to consider? None means all
secured_input_quantity – A quantity that MUST be bought
secured_input_unit_price – The (average) unit price of the quantity that MUST be bought.
secured_output_quantity – A quantity that MUST be sold.
secured_output_unit_price – The (average) unit price of the quantity that MUST be sold.
- Remarks:
You can use the
secured_*arguments and control over the number of negotiations to consider to find the utility limits given some already concluded and signed contractsNote that this function CANNOT take into account the sales or supplies already signed (and registered via
register_saleand/orregister_supply). You MUST pass the quantities and prices for signed contracts through the secured_* parameters.
- Returns:
worst and best outcome information in the form of
UFunLimittuple.
- ok_to_buy_at(unit_price: float) bool[source]
Checks if the unit price can – even in principle – be acceptable for buying
- Remarks:
This method is very optimistic. If it returns
False, an agent should never buy at this price. If it returnsTrue, it may still be a bad idea to buy at this price.If we buy at this price, the best case scenario is that we pay it and pay production cost then receive the unit price of one output.
If we do not buy at this price, the worst case scenario is that we will pay shortfall penalty for one item
We should NOT buy if the best case scenario when buying is worse than the worst case scenario when not buying.
If called for agents not at the end of the production chain, it will always return
Truebecause in these cases we do not know what the the unit price for the output so there is nothing to compare with.
- ok_to_sell_at(unit_price: float) bool[source]
Checks if the unit price can – even in principle – be acceptable for selling
- Remarks:
This method is very optimistic. If it returns
False, an agent should never sell at this price. If it returnsTrue, it may still be a bad idea to sell at this price.Sales decisions does not affect in any way the amount we pay for input materials. It only affects the amount we produce, the amout we get paid in sales and the amount we pay as disposal cost and shortfall penalty.
If we agree to sell an item at this price, the best case scenario is that we can actually produce this item and sell it. We pay production cost and receive the given unit price.
If we do not sell at this price, the worst case scenario is that we really needed that sale. In this case, we will pay disposal cost for one item.
We should NOT sell if the best case scenario when selling is worse than the worst case scenario when not selling.
If called for agents not at the beginning of the production chain, it will always return
Truebecause in these cases we do not know what the the unit price for the input so there is nothing to compare with.
- scml.oneshot.UFunLimit[source]
Information about one utility limit (either highest or lowest). See
OnShotUFun.find_limitfor details.
- class scml.oneshot.SCMLBaseWorld(catalog_prices: numpy.ndarray, profiles: list[scml.oneshot.common.OneShotProfile], agent_types: list[type[scml.oneshot.agent.OneShotAgent]], agent_params: list[dict[str, Any]], catalog_quantities: int | numpy.ndarray = 50, financial_report_period=5, bankruptcy_limit=0.0, penalize_bankrupt_for_future_contracts=True, penalties_scale: Literal[trading, catalog, unit, none] = 'trading', exogenous_contracts: Collection[scml.oneshot.common.OneShotExogenousContract] = tuple(), exogenous_dynamic: bool = False, exogenous_force_max: bool = False, initial_balance: numpy.ndarray | tuple[int, int] | int = 1000, compact=True, no_logs=True, fast=True, n_steps=1000, time_limit=60 * 15, sync_calls=False, neg_n_steps=20, neg_time_limit=None, neg_hidden_time_limit=60, neg_step_time_limit=20, negotiation_speed=None, shuffle_negotiations=False, one_offer_per_step=False, publish_exogenous_summary=True, publish_trading_prices=True, publish_assets=False, publish_production_capacity=True, price_multiplier=0.0, price_range_fraction=0.0, wide_price_range=False, allow_zero_quantity: bool = False, trading_price_discount=0.9, signing_delay=0, force_signing=False, batch_signing=True, name: str | None = None, agent_name_reveals_position: bool = True, agent_name_reveals_type: bool = True, inventory_valuation_catalog=0, inventory_valuation_trading=0, perishable=True, horizon=0, one_time_per_negotiation=True, quantity_multiplier: float = 1.0, nullify_bankrupt_contracts: bool = False, debug: bool = False, verbose: bool = False, **kwargs)[source]
Bases:
negmas.TimeInAgreementMixin,negmas.World[scml.oneshot.awi.OneShotAWI,scml.oneshot.sysagents.DefaultOneShotAdapter]Implements the a generalized form of SCML-OneShot game which supports both oneshot and standard simulations
- Parameters:
catalog_prices – An n_products vector (i.e. n_processes+1 vector) giving the catalog price of all products
profiles – An n_agents list of
OneShotFactoryProfileobjects specifying the private profile of the factory associated with each agent.agent_types – An n_agents list of strings/
OneShotAgentclasses specifying the type of each agentagent_params – An n_agents dictionaries giving the parameters of each agent
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
financial_report_period – The number of steps between financial reports. If < 1, it is a fraction of n_steps
exogenous_force_max – If true, exogenous contracts are forced to be signed independent of the setting of
force_signingcompact – If True, no logs will be kept and the whole simulation will use a smaller memory footprint
n_steps – Number of simulation steps (can be considered as days).
time_limit – Total time allowed for the complete simulation in seconds.
neg_n_steps – Number of negotiation steps allowed for all negotiations.
neg_time_limit – Total time allowed for a complete negotiation in seconds.
neg_step_time_limit – Total time allowed for a single step of a negotiation. in seconds.
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
signing_delay – The number of simulation steps to pass between a contract is concluded and signed
name – The name of the simulations
**kwargs – Other parameters that are passed directly to
SCML2020Worldconstructor.
- property agent_contracts
- property winners
The winners of this world (factory managers with maximum wallet balance
- property trading_prices
- property stats_df: pandas.DataFrame
Returns a pandas data frame with the stats
- property contracts_df: pandas.DataFrame
Returns a pandas data frame with the contracts
- property system_agents: list[scml.oneshot.sysagents._StdSystemAgent]
Returns the two system agents
- property non_system_agents: list[scml.oneshot.sysagents.DefaultOneShotAdapter]
Returns all agents except system agents
- property agreement_fraction: float
Fraction of negotiations ending in agreement and leading to signed contracts
- system_agent_ids
- non_system_agent_ids
- classmethod replace_agents(config: dict, old_types: tuple[str | type[scml.oneshot.agent.OneShotAgent], Ellipsis] | list[str | type[scml.oneshot.agent.OneShotAgent]], types: tuple[str | type[scml.oneshot.agent.OneShotAgent], Ellipsis] | list[str | type[scml.oneshot.agent.OneShotAgent]], params: list[dict[str, Any]] | tuple[dict[str, Any], Ellipsis] | None = None)[source]
Replaces all agents of a given type by agents of a new type
- classmethod generate(agent_types: tuple[str | type[scml.oneshot.agent.OneShotAgent], Ellipsis] | list[str | type[scml.oneshot.agent.OneShotAgent]] | type[scml.oneshot.agent.OneShotAgent] | str, agent_params: list[dict[str, Any]] | tuple[dict[str, Any], Ellipsis] | None = None, agent_processes: list[int] | None = None, n_steps: tuple[int, int] | int = (50, 200), n_processes: tuple[int, int] | int = 2, n_lines: numpy.ndarray | tuple[int, int] | int = 10, n_agents_per_process: numpy.ndarray | tuple[int, int] | int = (4, 8), 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.1, 0.2), profit_stddevs: numpy.ndarray | tuple[float, float] | float = 0.05, max_productivity: numpy.ndarray | tuple[float, float] | float = (0.8, 1.0), initial_balance: numpy.ndarray | tuple[int, int] | int | None = None, 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 = -1, cash_availability: tuple[float, float] | float = (1.5, 2.5), shortfall_penalty: tuple[float, float] | float = (0.2, 1.0), shortfall_penalty_dev: tuple[float, float] | float = (0.0, 0.1), disposal_cost: tuple[float, float] | float = (0.0, 0.2), disposal_cost_dev: tuple[float, float] | float = (0.0, 0.02), storage_cost: tuple[float, float] | float = (0.0, 0.02), storage_cost_dev: tuple[float, float] | float = 0, exogenous_price_dev: tuple[float, float] | float = (0.1, 0.2), price_multiplier: numpy.ndarray | tuple[float, float] | float = (1.5, 2.0), cost_increases_with_level=True, equal_exogenous_supply=False, equal_exogenous_sales=False, force_signing=True, profit_basis=np.max, random_agent_types: bool = False, penalties_scale: str | list[str] = 'trading', cap_exogenous_quantities: bool = True, exogenous_generation_method='profitable', perishable: bool | None = True, max_supply: numpy.ndarray | tuple[float, float] | float = (0.8, 1.0), **kwargs) dict[str, Any][source]
Generates the configuration for a world
- Parameters:
agent_types – All agent types
agent_params – Agent parameters used to initialize them
n_steps – Number of simulation steps
n_processes – Number of processes in the production chain
n_lines – Number of lines per factory
process_inputs – Number of input units per process
process_outputs – Number of output units per process
production_costs – Production cost per factory
profit_means – Mean profitability per production level (i.e. process).
profit_stddevs – Std. Dev. of the profitability of every level (i.e. process).
max_productivity – Maximum possible productivity per level (i.e. process).
max_supply – Maximum possible supply level to the market,
initial_balance – The initial balance of all agents
n_agents_per_process – Number of agents per process
agent_processes – The process for each agent. If not
None, it will overriden_agents_per_processand must be a list/tuple of the same length asagent_types. Morevoer,random_agent_typesmust be False in this casecost_increases_with_level – If true, production cost will be higher for processes nearer to the final product.
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.
equal_exogenous_supply – If true, external supply will be distributed equally among all agents in the first layer
equal_exogenous_sales – If true, external sales will be distributed equally among all agents in the last layer
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
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
force_signing – Whether to force contract signatures (exogenous contracts are treated in the same way).
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
cap_exogenous_quantities – If True, all exogenous quantities in all contracts are capped to be no more than the number of lines
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 ifinitial_balanceis set toNone.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
disposal_cost – A range to sample mean-disposal costs for all factories from (only used if perishable is True)
shortfall_penalty – A range to sample mean-shortfall penalty for all factories from
storage_cost – A range to sample mean-storage costs fro all factories from (only used if perishable is False)
disposal_cost_dev – A range to sample std. dev of disposal costs for all factories from
shortfall_penalty_dev – A range to sample std. dev of shortfall penalty for all factories from
storage_cost_dev – The standard deviation of storage cost relative to the mean price
exogenous_price_dev – The standard deviation of exogenous contract prices relative to the mean price
price_multiplier – A value to multiply with trading/catalog price to get the upper limit on prices for all negotiations
random_agent_types – If True, the final agent types used by the generator will always be sampled from the given types. If False, this random sampling will only happen if len(agent_types) != n_agents.
penalties_scale – What are
disposal_costandshortfall_penaltyrelative to. There are four options:trading,catalogmean trading and catalog prices of the product.unitmeans the unit price in the contract andnonemeans thestorage-costandshortfall_penaltyare absolute values (in money unit). If not given will be read through the AWIexogenous_generation_method – the generation method. This is only for compatibility with SCML2020World and is not used.
perishable – If True, storage_cost is set to zero as there is no storage and if False, disposal_cost is set to zero as there is no disposal. If None, neither is overridden.
**kwargs –
- Returns:
world configuration as a Dict[str, Any]. A world can be generated from this dict by calling OneShotWorld(**d)
Remarks:
- There are two general ways to use this generator:
Pass
random_agent_types = False, and passagent_types,agent_processesto control placement of each agent in each level of the production graph.Pass
random_agent_types = Trueand passagent_types,n_agents_per_processto 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 lengthn_processes, it is used as it is otherwise, it is used to sample values for each process.
- add_financial_report(agent: scml.oneshot.sysagents.DefaultOneShotAdapter, reports_agent, reports_time) None[source]
Records a financial report for the given agent in the agent indexed reports and time indexed reports
- Parameters:
agent – The agent
reports_agent – A dictionary of financial reports indexed by agent id
reports_time – A dictionary of financial reports indexed by time
Returns:
- step_with(actions: dict[str, dict[str, negmas.SAOResponse]], init=False) bool[source]
Runs a simulation step for the agents given in keys passing the corresponding values as counter offers.
- Returns:
False if this is the last negotiation.
- Remarks:
You must call this with
init=Trueonce at the beginning of every simulation to make sure thatinit()and other initialization code is called correctly.Every step advances all negotiations one step.
Negotiators belonging to the given agents are never called as long as a corresponding action (response) is given in the agents dict.
The world MUST be created with
one_offer_per_steppassed asTrue(default isFalse).
- simulation_step(stage=0)[source]
A single step of the simulation.
- Parameters:
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.SimulationStepseveral times with the list of operations while differentiating between these calls.
- on_contract_signed(contract: negmas.Contract) bool[source]
Called to add a contract to the existing set of contract after it is signed
- Parameters:
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.
- contract_record(contract: negmas.Contract) dict[str, Any][source]
Converts a contract to a record suitable for permanent storage
- breach_record(breach: negmas.Breach) dict[str, Any][source]
Converts a breach to a record suitable for storage during the simulation
- execute_action(action, agent, callback: Callable | None = None) bool[source]
Executes the given action by the given agent
- contract_size(contract: negmas.Contract) float[source]
Returns an estimation of the activity level associated with this contract. Higher is better :param contract:
Returns:
- post_step_stats()[source]
Called at the end of the simulation step to update all stats
Kept for backward compatibility and will be dropped. Override
update_statsins
- pre_step_stats()[source]
Called at the beginning of the simulation step to prepare stats or update them
Kept for backward compatibility and will be dropped. Override
update_statsinstead
- relative_welfare(include_bankrupt: bool = False) float | None[source]
Total welfare relative to expected value. Returns None if no expectation is found in self.info
- scores(assets_multiplier: float = 0.0) dict[str, float][source]
Scores of all agents given the asset multiplier.
- Parameters:
assets_multiplier – A multiplier to multiply the assets with.
- trading_prices_for(discount: float = 1.0, condition='executed') numpy.ndarray[source]
Calculates the prices at which all products traded using an optional discount factor
- Parameters:
discount – A discount factor to treat older prices less importantly (exponential discounting).
condition – The condition for contracts to consider. Possible values are executed, signed, concluded, nullified
- Returns:
an n_products vector of trading prices
- draw(steps: tuple[int, int] | int | None = None, what: Collection[str] = DEFAULT_EDGE_TYPES, who: Callable[[negmas.Agent], bool] | None = None, where: Callable[[negmas.Agent], int | tuple[float, float]] | None = None, together: bool = True, axs: Collection[matplotlib.axis.Axis] | None = 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]][source]
- _request_negotiations(agent_id: str, controller: negmas.sao.SAOController | None = None, negotiators: list[negmas.sao.SAONegotiator] | None = None, extra: dict[str, Any] | None = None) bool[source]
Requests negotiations (used internally)
- Parameters:
agent_id – the agent requesting
product – The product to negotiate about
quantity – The minimum and maximum quantities. Passing a single value q is equivalent to passing (q,q)
unit_price – The minimum and maximum unit prices. Passing a single value u is equivalent to passing (u,u)
time – The minimum and maximum delivery step. Passing a single value t is equivalent to passing (t,t)
controller – The controller to manage the complete set of negotiations
negotiators – An optional list of negotiators to use for negotiating with the given partners (in the same order).
extra – Extra information accessible through the negotiation annotation to the caller
consumer_starts (#) – Whether the consumer or supplier sends the first offer in the negotiation
- Returns:
Trueif the partner accepted and the negotiation is ready to start
- _request_negotiation(agent_id: str, product: int, partner: str, negotiator: negmas.sao.SAONegotiator, extra: dict[str, Any] | None = None, is_buy: bool = True) negmas.situated.NegotiationInfo | None[source]
Requests a negotiation
- Parameters:
product – The product to negotiate about
quantity – The minimum and maximum quantities. Passing a single value q is equivalent to passing (q,q)
unit_price – The minimum and maximum unit prices. Passing a single value u is equivalent to passing (u,u)
time – The minimum and maximum delivery step. Passing a single value t is equivalent to passing (t,t)
partner – ID of the partner to negotiate with.
negotiator – The negotiator to use for this negotiation (if the partner accepted to negotiate)
extra – Extra information accessible through the negotiation annotation to the caller
is_buy – whether the consumer starts the negotiation
- Returns:
Trueif the partner accepted and the negotiation is ready to start
- _make_issues(product) tuple[tuple[int, int], tuple[int, int], tuple[int, int]][source]
Creates the negotiation agendas
- Parameters:
product (int) – The product to be negotiated about
- Returns:
A tuple of minimum and maximum values for unit-price, time, and quantity in that order
- order_contracts_for_execution(contracts: Collection[negmas.Contract]) Collection[negmas.Contract][source]
Orders the contracts in a specific time-step that are about to be executed
- start_contract_execution(contract: negmas.Contract) set[negmas.Breach] | None[source]
Tries to execute the contract
- Parameters:
contract –
- Returns:
The set of breaches committed if any. If there are no breaches return an empty set
- Return type:
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).
- complete_contract_execution(contract: negmas.Contract, breaches: list[negmas.Breach], resolution: negmas.Contract) None[source]
Called after breach resolution is completed for contracts for which some potential breaches occurred.
- Parameters:
contract – The contract considered.
breaches – The list of potential breaches that was generated by
_execute_contract.resolution – The agreed upon resolution
Returns:
- classmethod plot_combined_stats(worlds: tuple[SCMLBaseWorld, Ellipsis] | SCMLBaseWorld, stats: str | tuple[str, Ellipsis] | None = None, pertype=False, makefig=False, title=True, ylabel=False, xlabel=False, legend=True, figsize=None, perishable: bool = False, **kwargs)[source]
Plots combined statistics of multiple worlds in a single plot
- Parameters:
stats – The statistics to plot. If
None, some selected stats will be displayedpertype – combine agent-statistics per type
use_sum – plot sum for type statistics instead of mean
title – If given a title will be added to each subplot
ylabel – If given, the ylabel will be added to each subplot
xlabel – If given The xlabel will be added (Simulation Step)
legend – If given, a legend will be displayed
makefig – If given a new figure will be started
figsize – Size of the figure to host the plot
ylegend – y-axis of legend for cases with large number of labels
legend_n_cols – number of columns in the legend
- plot_stats(stats: str | tuple[str, Ellipsis] | None = None, pertype=False, use_sum=False, makefig=False, title=True, ylabel=False, xlabel=False, legend=True, figsize=None, ylegend=2.0, legend_ncols=8)[source]
Plots statistics of the world in a single plot
- Parameters:
stats – The statistics to plot. If
None, some selected stats will be displayedpertype – combine agent-statistics per type
use_sum – plot sum for type statistics instead of mean
title – If given a title will be added to each subplot
ylabel – If given, the ylabel will be added to each subplot
xlabel – If given The xlabel will be added (Simulation Step)
legend – If given, a legend will be displayed
makefig – If given a new figure will be started
figsize – Size of the figure to host the plot
ylegend – y-axis of legend for cases with large number of labels
- class scml.oneshot.OneShotWorld(catalog_prices: numpy.ndarray, profiles: list[scml.oneshot.common.OneShotProfile], agent_types: list[type[scml.oneshot.agent.OneShotAgent]], agent_params: list[dict[str, Any]], catalog_quantities: int | numpy.ndarray = 50, financial_report_period=5, bankruptcy_limit=0.0, penalize_bankrupt_for_future_contracts=True, penalties_scale: Literal[trading, catalog, unit, none] = 'trading', exogenous_contracts: Collection[scml.oneshot.common.OneShotExogenousContract] = tuple(), exogenous_dynamic: bool = False, exogenous_force_max: bool = False, initial_balance: numpy.ndarray | tuple[int, int] | int = 1000, compact=True, no_logs=True, fast=True, n_steps=1000, time_limit=60 * 15, sync_calls=False, neg_n_steps=20, neg_time_limit=None, neg_hidden_time_limit=60, neg_step_time_limit=20, negotiation_speed=None, shuffle_negotiations=False, one_offer_per_step=False, publish_exogenous_summary=True, publish_trading_prices=True, publish_assets=False, publish_production_capacity=True, price_multiplier=0.0, price_range_fraction=0.0, wide_price_range=False, allow_zero_quantity: bool = False, trading_price_discount=0.9, signing_delay=0, force_signing=False, batch_signing=True, name: str | None = None, agent_name_reveals_position: bool = True, agent_name_reveals_type: bool = True, inventory_valuation_catalog=0, inventory_valuation_trading=0, perishable=True, horizon=0, one_time_per_negotiation=True, quantity_multiplier: float = 1.0, nullify_bankrupt_contracts: bool = False, debug: bool = False, verbose: bool = False, **kwargs)[source]
Bases:
SCMLBaseWorldBasic oneshot simulation
- class scml.oneshot.SCML2020OneShotWorld(catalog_prices: numpy.ndarray, profiles: list[scml.oneshot.common.OneShotProfile], agent_types: list[type[scml.oneshot.agent.OneShotAgent]], agent_params: list[dict[str, Any]], catalog_quantities: int | numpy.ndarray = 50, financial_report_period=5, bankruptcy_limit=0.0, penalize_bankrupt_for_future_contracts=True, penalties_scale: Literal[trading, catalog, unit, none] = 'trading', exogenous_contracts: Collection[scml.oneshot.common.OneShotExogenousContract] = tuple(), exogenous_dynamic: bool = False, exogenous_force_max: bool = False, initial_balance: numpy.ndarray | tuple[int, int] | int = 1000, compact=True, no_logs=True, fast=True, n_steps=1000, time_limit=60 * 15, sync_calls=False, neg_n_steps=20, neg_time_limit=None, neg_hidden_time_limit=60, neg_step_time_limit=20, negotiation_speed=None, shuffle_negotiations=False, one_offer_per_step=False, publish_exogenous_summary=True, publish_trading_prices=True, publish_assets=False, publish_production_capacity=True, price_multiplier=0.0, price_range_fraction=0.0, wide_price_range=False, allow_zero_quantity: bool = False, trading_price_discount=0.9, signing_delay=0, force_signing=False, batch_signing=True, name: str | None = None, agent_name_reveals_position: bool = True, agent_name_reveals_type: bool = True, inventory_valuation_catalog=0, inventory_valuation_trading=0, perishable=True, horizon=0, one_time_per_negotiation=True, quantity_multiplier: float = 1.0, nullify_bankrupt_contracts: bool = False, debug: bool = False, verbose: bool = False, **kwargs)[source]
Bases:
OneShotWorldOneshot simulation as used in SCML 2020 competition
- class scml.oneshot.SCML2021OneShotWorld(*args, **kwargs)[source]
Bases:
SCML2020OneShotWorldOneshot simulation as used in SCML 2021 competition
- class scml.oneshot.SCML2022OneShotWorld(*args, **kwargs)[source]
Bases:
SCML2021OneShotWorldOneshot simulation as used in SCML 2022 competition
- class scml.oneshot.SCML2023OneShotWorld(*args, **kwargs)[source]
Bases:
SCML2020OneShotWorldOneshot simulation as used in SCML 2023 competition
- class scml.oneshot.SCML2024OneShotWorld(*args, **kwargs)[source]
Bases:
SCML2023OneShotWorldOneshot simulation as used in SCML 2024 competition