scml.scml2019.common

Common data-structures and objects used throughout the SCM world implementation

Attributes

INVALID_STEP

NO_PRODUCTION

DEFAULT_NEGOTIATOR

QUANTITY

Index of quantity in negotiation issues

TIME

Index of time in negotiation issues

UNIT_PRICE

Index of unit price in negotiation issues

Classes

Product

InputOutput

An input/output to a production process

Process

ManufacturingProfile

The costs/time required for running a process on a line (with associated cancellation costs etc). This

FactoryStatusUpdate

RunningCommandInfo

Job

Describes a job to be run on one production line of a Factory.

ProductionNeed

Describes some quantity of a product that is needed to honor a (sell) contract.

MissingInput

ProductionFailure

ProductionReport

SCMLAgreement

CFP

A Call for proposal upon which a negotiation can start

SCMLAction

ManufacturingProfileCompiled

The costs/time required for running a process on a line (with associated cancellation costs etc).

ProductManufacturingInfo

Gives full information about a manufacturing process that can generate or consume a product.

FinancialReport

Reports that financial standing of an agent at a given time in the simulation

Loan

InsurancePolicy

FactoryState

Read Only State of a factory

Factory

Represents a factory within an SCML world. It is only accessed by the SCML2020World so it need not be made public.

Module Contents

scml.scml2019.common.INVALID_STEP[source]
scml.scml2019.common.NO_PRODUCTION[source]
scml.scml2019.common.DEFAULT_NEGOTIATOR = 'negmas.sao.AspirationNegotiator'[source]
scml.scml2019.common.QUANTITY = 0[source]

Index of quantity in negotiation issues

scml.scml2019.common.TIME = 1[source]

Index of time in negotiation issues

scml.scml2019.common.UNIT_PRICE = 2[source]

Index of unit price in negotiation issues

class scml.scml2019.common.Product[source]
__slots__ = ['id', 'production_level', 'name', 'expires_in', 'catalog_price'][source]

A product that can be transacted in.

id: int[source]

Product index. Must be set during construction and MUST be unique for products in the same world

production_level: int[source]

The level of this product in the production graph.

name: str[source]

Object name

expires_in: int | None[source]

Number of steps within which the product must be consumed. None means never

catalog_price: float | None[source]

Catalog price of the product.

__str__()[source]

String representation is simply the name

__post_init__()[source]
__hash__()[source]

Return hash(self).

class scml.scml2019.common.InputOutput[source]

An input/output to a production process

__slots__ = ['product', 'quantity', 'step'][source]
product: int[source]

Index of the product used as input or output

quantity: int[source]

Quantity needed/produced

step: float[source]

Relative time within the production at which the input is needed (output is produced)

class scml.scml2019.common.Process[source]
__slots__ = ['id', 'production_level', 'name', 'inputs', 'outputs', 'historical_cost'][source]
id: int[source]

A manufacturing process.

production_level: int[source]

The level of this process in the production graph

name: str[source]

Object name

inputs: List[InputOutput][source]

list of input product name + quantity required and time of consumption relative to the time required for production (value from 0 to 1)

outputs: List[InputOutput][source]

list of output product names, quantity required and when it becomes available relative to the time required for production (value from 0 to 1)

historical_cost: float | None[source]

Average cost for running this process in some world. Filled by the world

__str__()[source]

String representation is simply the name

__post_init__()[source]
__hash__()[source]

The hash depends only on the name

class scml.scml2019.common.ManufacturingProfile[source]

The costs/time required for running a process on a line (with associated cancellation costs etc). This data-structure carries full information about the Process es instead of just its index as in ManufacturingProfileCompiled. It is intended to be used to construct factories

See also

Factory

__slots__ = ['n_steps', 'cost', 'initial_pause_cost', 'running_pause_cost', 'resumption_cost',...[source]
n_steps: int[source]

Number of steps needed to complete the manufacturing

cost: float[source]

Cost of manufacturing

initial_pause_cost: float[source]

Cost of pausing incurred only at the step a pause is started

running_pause_cost: float[source]

Running cost of pausing

resumption_cost: float[source]

Cost of resuming a process

cancellation_cost: float[source]

Cost of cancelling the process before the last step

line: int[source]

The line index

process: Process[source]

The Process associated with this profile

class scml.scml2019.common.FactoryStatusUpdate[source]
__slots__ = ['balance', 'storage'][source]
balance: float[source]

The update to the balance

storage: Dict[int, int][source]

The updates to be applied to the storage after this step

__post_init__()[source]
make_empty() None[source]

Makes the update an empty one.

combine(other: FactoryStatusUpdate) None[source]

Combines this status update with another one in place

Parameters:

other – The other status update

Returns:

None

classmethod combine_sets(dst: Dict[int, FactoryStatusUpdate], src: Dict[int, FactoryStatusUpdate])[source]

Combines a set of updates over time with another in place (overriding first) :param dst: First set of updates to be combined into :param src: second set of updates to be combined from

Returns:

property is_empty[source]
classmethod empty()[source]
__str__()[source]

Return str(self).

class scml.scml2019.common.RunningCommandInfo[source]
__slots__ = ['profile', 'beg', 'end', 'action', 'updates', 'step', 'paused'][source]
profile: ManufacturingProfile[source]

The manufacturing profile associated with this command. Most importantly, it gives the process and line

beg: int[source]

The time the command is to be executed

end: int[source]

The number of steps starting at beg for this command to end (it ends at end - 1)

step: int[source]

The time-step relative to beg at the factory is currently executing the Process indicated in profile. step will always go up by one every simulation step except if the command is paused where it does not change

paused: bool[source]

True if the command is paused

action: str[source]

The command type. For the current implementation it will always be run or none for no command

updates: Dict[int, FactoryStatusUpdate][source]

The status updates implied by this command with their times relative to beg

property n_steps: int[source]
ended_before(t: int)[source]
started_on_or_after(t: int)[source]
__str__()[source]

Return str(self).

property is_none[source]
classmethod do_nothing()[source]
class scml.scml2019.common.Job[source]

Describes a job to be run on one production line of a Factory.

__slots__ = ['profile', 'time', 'line', 'action', 'contract', 'override'][source]
profile: int[source]

The process for run commands

time: int[source]

The time the command is to be executed

line: int[source]

Index of the line on which the job is to be scheduled. Notice that it will be ignored for run actions.

action: str[source]

The command type. For the current implementation it can be run/pause/resume/stop/cancel with cancel cancelling any other command type.

contract: negmas.situated.Contract | None[source]

The sell contract associated with the command

override: bool[source]

Whether to override existing commands when the job is to be executed.

__str__()[source]

Return str(self).

is_cancelling(job: Job) bool[source]

Determines if the given jobs cancels this one

Parameters:

job

Returns:

class scml.scml2019.common.ProductionNeed[source]

Describes some quantity of a product that is needed to honor a (sell) contract.

__slots__ = ['product', 'needed_for', 'quantity_to_buy', 'quantity_in_storage', 'step'][source]
product: int[source]

The product needed

needed_for: negmas.situated.Contract[source]

The contract for which the product is needed

quantity_to_buy: int[source]

The quantity need to be bought

quantity_in_storage: int[source]

The quantity already found in storage

step: int[source]

The time step at which the product is needed

__str__()[source]

String representation is simply the name

class scml.scml2019.common.MissingInput[source]
__slots__ = ['product', 'quantity'][source]
product: int[source]
quantity: int[source]
__str__()[source]

Return str(self).

class scml.scml2019.common.ProductionFailure[source]
__slots__ = ['line', 'command', 'missing_inputs', 'missing_money', 'missing_space'][source]
line: int[source]

ID of the line that failed

command: RunningCommandInfo[source]

Information about the command that failed

missing_inputs: List[MissingInput][source]

The missing inputs if any with their quantities

missing_money: float[source]

The amount of money needed for production that is not available

missing_space: int[source]

The amount space needed in storage but not found

__str__()[source]

Return str(self).

class scml.scml2019.common.ProductionReport[source]
line: int[source]

ID of the line

started: RunningCommandInfo | None[source]

Commands started

continuing: RunningCommandInfo | None[source]

Command that is continuing

finished: RunningCommandInfo | None[source]

Command finished

failure: ProductionFailure | None[source]

Failures

updates: FactoryStatusUpdate[source]

Updates applied to the factory

property failed[source]
property is_empty[source]
property no_production[source]
__str__()[source]

Return str(self).

class scml.scml2019.common.SCMLAgreement[source]
time: int[source]

delivery time

unit_price: float[source]

unit price

quantity: int[source]

quantity

penalty: float | None = None[source]

penalty

signing_delay: int[source]

Delay between agreement conclusion and signing it to be binding

__getitem__(k)[source]
get(k, default=None)[source]
asdict()[source]
to_dict()[source]
keys()[source]
values()[source]
items()[source]
class scml.scml2019.common.CFP[source]

A Call for proposal upon which a negotiation can start

is_buy: bool[source]

If true, the author wants to buy otherwise to sell. Non-negotiable.

publisher: str[source]

the publisher name. Non-negotiable.

product: int[source]

product ID. Non-negotiable.

time: int | Tuple[int, int] | List[int][source]

delivery time. May be negotiable.

unit_price: float | Tuple[float, float] | List[float][source]

unit price. May be negotiable.

quantity: int | Tuple[int, int] | List[int][source]

quantity. May be negotiable.

penalty: float | Tuple[float, float] | List[float] | None = None[source]

penalty per missing item in case the seller cannot provide the required quantity. May be negotiable.

signing_delay: int | Tuple[int, int] | List[int] | None = None[source]

The grace period after which the agents are asked to confirm signing the contract

money_resolution: float | None = None[source]

If not None then it is the minimum unit of money (e.g. 1 for dollar, 0.01 for cent, etc)

id: str[source]

Unique CFP ID

__str__()[source]

Return str(self).

satisfies(query: Dict[str, Any]) bool[source]

Tests whether the CFP satisfies the conditions set by the query

Parameters:

query – A dictionary given the conditions. See Remarks for details

Remarks:

  • The query dictionary can be used to specify any conditions that are required in the CFP. Only CFPs that satisfy ALL the conditions specified in the query are considered satisfying the query. The following keys can be set with corresponding meanings:

    is_buy

    True or False. If both are OK, just do not add this key

    publisher

    A string or SCML2019Agent specifying a specific publisher

    publishers

    A list of publishers (see publisher key)

    product

    A string specifying a product name

    products

    A list of products (see product key)

    time

    A number, list or 2-items-tuple (range) specifying possible times to consider satisfactory

    unit_price

    A number, list or 2-items-tuple (range) specifying possible prices to consider satisfactory

    quantity

    A number, list or 2-items-tuple (range) specifying possible quantities to consider OK

    penalty

    A number, list or 2-items-tuple (range) specifying possible penalties to consider satisfactory

property issues[source]
Returns the set of issues associated with this CFP. Notice that some of the issues may have a single value
property outcomes[source]
property min_time[source]
property max_time[source]
property min_quantity[source]
property max_quantity[source]
property min_unit_price[source]
property max_unit_price[source]
property min_signing_delay[source]
property max_signing_delay[source]
property min_penalty[source]
property max_penalty[source]
to_dict()[source]
classmethod from_dict(idict: Dict[str, Any], class_name: str | None = None) CFP[source]
class scml.scml2019.common.SCMLAction[source]
line: str[source]

Line to execute the action on (need not be given if the profile is given

profile: int | None[source]

Index of the profile to execute

action: str[source]

The action which may be start, stop, pause, resume

time: int = 0[source]

Time to execute the action at

class scml.scml2019.common.ManufacturingProfileCompiled[source]

The costs/time required for running a process on a line (with associated cancellation costs etc).

See also

Factory

__slots__ = ['n_steps', 'cost', 'initial_pause_cost', 'running_pause_cost', 'resumption_cost',...[source]
n_steps: int[source]

Number of steps needed to complete the manufacturing

cost: float[source]

Cost of manufacturing

initial_pause_cost: float[source]

Cost of pausing incurred only at the step a pause is started

running_pause_cost: float[source]

Running cost of pausing

resumption_cost: float[source]

Cost of resuming a process

cancellation_cost: float[source]

Cost of cancelling the process before the last step

line: int[source]

The line index

process: int[source]

The Process index

classmethod from_manufacturing_profile(profile: ManufacturingProfile, process2ind: Dict[Process, int])[source]
class scml.scml2019.common.ProductManufacturingInfo[source]

Gives full information about a manufacturing process that can generate or consume a product.

See also

consuming and producing of Factory

__slots__ = ['profile', 'quantity', 'step'][source]
profile: int[source]

The ManufacturingProfile index

quantity: int[source]

The quantity generated/consumed by running this manufacturing info

step: int[source]

The step from the beginning at which the Product is received/consumed

class scml.scml2019.common.FinancialReport[source]

Reports that financial standing of an agent at a given time in the simulation

agent: str[source]

Agent ID

step: int[source]

Time of the report

cash: float[source]

Cash at hand

liabilities: float[source]

Total liabilities (loans)

inventory: float[source]

Value of everything in the inventory priced at catalog prices.

credit_rating: float[source]

The agent’s credit rating as a fraction of the maximum credit rating (1 indicates highest credit rating).

property balance[source]
The balance of the agent defined as the difference between its available cash + inventory and its liabilities

Remarks:

  • If the inventory was not calculated (due to having at least one product with unknown catalog price), it is used as zero in the equation.

class scml.scml2019.common.Loan[source]
amount: float[source]

Loan amount

starts_at: int[source]

The time-step at which payment starts

total: float[source]

The total to be paid including the amount + interests

interest: float[source]

The interest rate per step

installment: float[source]

The amount to be paid in one installment

n_installments: int[source]

The number of installments

__str__()[source]

Return str(self).

class scml.scml2019.common.InsurancePolicy[source]
premium: float[source]
contract: negmas.situated.Contract[source]
at_time: int[source]
against: scml.scml2019.agent.SCML2019Agent[source]
class scml.scml2019.common.FactoryState[source]

Read Only State of a factory

max_storage: int[source]

Maximum storage allowed in this factory

line_schedules: numpy.ndarray[source]

An array of n_lines * n_steps giving the line schedules

storage: Dict[int, int][source]

Mapping from product index to the amount available in the inventory

wallet: float[source]

Money available for purchases

hidden_money: float[source]

Amount of money hidden by the agent

hidden_storage: Dict[int, int][source]

Mapping from product index to the amount hidden by the agent

loans: float[source]

The total money owned as loans

n_lines: int[source]

The number of lines in the factory, will be set using the profiles input

profiles: List[ManufacturingProfile][source]

A list of profiles used to initialize the factory

next_step: int[source]

Next simulation step for this factory

commands: numpy.ndarray[source]

The production command currently running

jobs: Dict[Tuple[int, int], Job][source]

The jobs waiting to be run on the factory indexed by (time, line) tuples

class scml.scml2019.common.Factory[source]

Represents a factory within an SCML world. It is only accessed by the SCML2020World so it need not be made public.

initial_storage: dataclasses.InitVar[Dict[int, int]][source]

Initial storage

initial_wallet: dataclasses.InitVar[float] = 0.0[source]

Initial Wallet

id: str[source]

Object name

profiles: List[ManufacturingProfile][source]

A list of profiles used to initialize the factory

max_storage: int[source]

Maximum storage allowed in this factory

min_storage: int = 0[source]

Minimum allowed storage per product

min_balance: int | float = 0[source]

Minimum allowed balance

initial_balance: float[source]

Initial balance of the factory

_commands: numpy.ndarray[source]

The production command currently running

_line_schedules: numpy.ndarray[source]
_storage: Dict[int, int][source]

Mapping from product index to the amount available in the inventory

_total_storage: int[source]

Total storage

_wallet: float[source]

Money available for purchases

_hidden_money: float[source]

Amount of money hidden by the agent

_hidden_storage: Dict[int, int][source]

Mapping from product index to the amount hidden by the agent

_loans: float[source]

The total money owned as loans

_n_lines: int[source]

The number of lines in the factory, will be set using the profiles input

_jobs: Dict[Tuple[int, int], Job][source]

The jobs waiting to be run on the factory indexed by (time, line) tuples

_next_step: int[source]

Current simulation step

_carried_updates: FactoryStatusUpdate[source]

Carried updates from last executed command

_world: negmas.situated.World[source]
attach_to_world(world)[source]
__post_init__(initial_storage: Dict[int, int], initial_wallet=0.0)[source]
property hidden_money: float[source]
property hidden_storage: Dict[int, int][source]
property n_lines: int[source]
property jobs: Dict[Tuple[int, int], Job][source]
property commands: numpy.ndarray[source]
property line_schedules: numpy.ndarray[source]
property wallet: float[source]
property storage: Dict[int, int][source]
property loans: float[source]
property total_storage: int[source]
property balance: float[source]

The total balance of the factory

property total_balance: float[source]

total balance including hidden money

property next_step: int[source]
add_loan(total: float) None[source]
receive(payment: float) None[source]
pay(payment: float) None[source]
transport_to(product: int, quantity: int) None[source]
buy(product: int, quantity: int, price: float) None[source]
sell(product: int, quantity: int, price: float) None[source]
transport_from(product: int, quantity: int) None[source]
hide_funds(amount: float) None[source]
hide_product(product: int, quantity: int) None[source]
unhide_funds(amount: float) None[source]
unhide_product(product: int, quantity: int) None[source]
schedule(job: Job, override=False) None[source]

Schedules the given job at its time and line optionally overriding whatever was already scheduled :param job: :param override:

Returns:

Success/failure

_apply_updates(updates: FactoryStatusUpdate) None[source]
step() List[ProductionReport][source]
_run(profile: ManufacturingProfile, override=True) None[source]

running is executed at the beginning of the step t

Parameters:
  • profile – the profile to start giving both the line and process

  • override – If true, override any running processes paying cancellation cost for these processes

Remarks:

  • The output of a process that runs from step t to step t + n - 1 will only be in storage at step t + n

_pause(line: int) None[source]

pausing is executed at the end of the step

Parameters:

line – the line on which the process is running

Returns:

The status updated for all times that need to be updated to cancel the command if it is not None. If None is returned then scheduling failed.

Return type:

Optional[Dict[int, FactoryStatusUpdate]]

Remarks:

  • Not implemented yet

  • pausing when nothing is running is not an error and will return an empty status update

_resume(line: int) None[source]

resumption is executed at the end of the step (starting next step count down)

Parameters:

line – the line on which the process is running

Returns:

The status updated for all times that need to be updated to cancel the command if it is not None. If None is returned then scheduling failed.

Return type:

Optional[Dict[int, FactoryStatusUpdate]]

Remarks:

  • Not implemented yet

  • resuming when nothing is paused is not an error and will return an empty status update

_stop(line: int) None[source]

stopping is executed at the beginning of the current step

Parameters:

line – the line on which the process is running

Returns:

The status updated for all times that need to be updated to cancel the command if it is not None. If None is returned then scheduling failed.

Return type:

Optional[Dict[int, FactoryStatusUpdate]]

Remarks:

  • stopping when nothing is running is not an error and will just return an empty schedule

_step_line(line: int) ProductionReport[source]

Steps the line to the time-step t assuming that it is already stepped to time-step t-1 given the storage

Parameters:

line – the line to step

Returns:

ProductionReport