API Reference¶

You can also checkout Module Index for a list of all modules implemented in this package.

ServerlessSimulator¶

class pacssim.ServerlessSimulator.ServerlessSimulator(arrival_process=None, warm_service_process=None, cold_service_process=None, expiration_threshold=600, max_time=86400, maximum_concurrency=1000, **kwargs)¶

Bases: object

ServerlessSimulator is responsible for executing simulations of a sample serverless computing platform, mainly for the performance analysis and performance model evaluation purposes.

Parameters

arrival_process (pacssim.SimProcess.SimProcess, optional) – The process used for generating inter-arrival samples, if absent, arrival_rate should be passed to signal exponential distribution, by default None
warm_service_process (pacssim.SimProcess.SimProcess, optional) – The process which will be used to calculate service times, if absent, warm_service_rate should be passed to signal exponential distribution, by default None
cold_service_process (pacssim.SimProcess.SimProcess, optional) – The process which will be used to calculate service times, if absent, cold_service_rate should be passed to signal exponential distribution, by default None
expiration_threshold (float, optional) – The period of time after which the instance will be expired and the capacity release for use by others, by default 600
max_time (float, optional) – The maximum amount of time for which the simulation should continue, by default 24*60*60 (24 hours)
maximum_concurrency (int, optional) – The maximum number of concurrently executing function instances allowed on the system This will be used to determine when a rejection of request should happen due to lack of capacity, by default 1000

Raises

Exception – Raises if neither arrival_process nor arrival_rate are present
Exception – Raises if neither warm_service_process nor warm_service_rate are present
Exception – Raises if neither cold_service_process nor cold_service_rate are present
ValueError – Raises if warm_service_rate is smaller than cold_service_rate

analyze_custom_states(hist_states, skip_init_time=None, skip_init_index=None)¶

Analyses a custom states list and calculates the amount of time spent in each state each time we enterred that state, and the times at which transitions have happened.

Parameters

hist_states (list[object]) – The states calculated, should have the same dimensions as the hist_* arrays.
skip_init_time (float, optional) – The amount of time skipped in the beginning, by default None
skip_init_index (int, optional) – The number of indices skipped in the beginning, by default None

Returns

(residence_times, transition_times) where residence_times is an array of the amount of times we spent in each state, and transition_times are the moments of time at which each transition has occured

Return type

list[float], list[float]

calculate_time_average(values, skip_init_time=None, skip_init_index=None)¶

calculate_time_average calculates the time-averaged of the values passed in with optional skipping a specific number of time steps (skip_init_index) and a specific amount of time (skip_init_time).

Parameters

values (list) – A list of values with the same dimensions as history array (number of transitions)
skip_init_time (Float, optional) – Amount of time skipped in the beginning to let the transient part of the solution pass, by default None
skip_init_index ([type], optional) – Number of steps skipped in the beginning to let the transient behaviour of system pass, by default None

Returns

returns (unq_vals, val_times) where unq_vals is the unique values inside the values list and val_times is the portion of the time that is spent in that value.

Return type

(list, list)

calculate_time_lengths()¶: Calculate the time length for each step between two event transitions. Records the values in self.time_lengths.

cold_start_arrival(t)¶

Goes through the process necessary for a cold start arrival which includes generation of a new function instance in the COLD state and adding it to the cluster.

Parameters: t (float) – The time at which the arrival has happened. This is used to record the creation time for the server and schedule the expiration of the instance if necessary.

generate_trace(debug_print=False, progress=False)¶

Generate a sample trace.

Parameters

debug_print (bool, optional) – If True, will print each transition occuring during the simulation, by default False
progress (bool, optional) – Whether or not the progress should be outputted using the tqdm library, by default False

Raises

Exception – Raises of FunctionInstance enters an unknown state (other than IDLE for idle or TERM for terminated) after making an internal transition

get_average_lifespan()¶

Get the average lifespan of each instance, calculated by the amount of time from creation of instance, until its expiration.

Returns: The average lifespan
Return type: float

get_average_residence_times(hist_states, skip_init_time=None, skip_init_index=None)¶

Get the average residence time for each state in custom state encoding.

Parameters

hist_states (list[object]) – The states calculated, should have the same dimensions as the hist_* arrays.
skip_init_time (float, optional) – The amount of time skipped in the beginning, by default None
skip_init_index (int, optional) – The number of indices skipped in the beginning, by default None

Returns

The average residence time for each state, averaged over the times we transitioned into that state

Return type

float

get_average_server_count()¶

Get the time-average server count.

Returns: Average server count
Return type: float

get_average_server_idle_count()¶

Get the time-averaged idle server count.

Returns: Average idle server coutn
Return type: float

get_average_server_running_count()¶

Get the time-averaged running server count.

Returns: Average running server coutn
Return type: float

get_cold_start_prob()¶

Get the probability of cold start for the simulated trace.

Returns: The probability of cold start calculated by dividing the number of cold start requests, over all requests
Return type: float

get_index_after_time(t)¶

Get the first historical array index (for all arrays storing hisotrical events) that is after the time t.

Parameters: t (float) – The time in the beginning we want to skip
Returns: The calculated index in self.hist_times
Return type: int

get_request_custom_states(hist_states, skip_init_time=None, skip_init_index=None)¶

Get request statistics for an array of custom states.

Parameters

hist_states (list[object]) – An array of custom states calculated by the user for which the statistics should be calculated, should be the same size as hist_* objects, these values will be used as the keys for the returned dataframe.
skip_init_time (float, optional) – The amount of time skipped in the beginning, by default None
skip_init_index (int, optional) – The number of indices that should be skipped in the beginning to calculate steady-state results, by default None

Returns

A pandas dataframe including different statistics like p_cold (probability of cold start)

Return type

pandas.DataFrame

get_result_dict()¶

Get the results of the simulation as a dict, which can easily be integrated into web services.

Returns: A dictionary of different characteristics.
Return type: dict

get_skip_init(skip_init_time=None, skip_init_index=None)¶

Get the minimum index which satisfies both the time and index count we want to skip in the beginning of the simulation, which is used to reduce the transient effect for calculating the steady-state values.

Parameters

skip_init_time (float, optional) – The amount of time skipped in the beginning, by default None
skip_init_index ([type], optional) – The number of indices we want to skip in the historical events, by default None

Returns

The number of indices after which both index and time requirements are satisfied

Return type

int

get_trace_end()¶

Get the time at which the trace (one iteration of the simulation) has ended. This mainly due to the fact that we keep on simulating until the trace time goes beyond max_time, but the time is incremented until the next event.

Returns: The time at which the trace has ended
Return type: float

has_server()¶

Returns True if there are still instances (servers) in the simulated platform, False otherwise.

Returns: Whether or not the platform has instances (servers)
Return type: bool

static print_time_average(vals, probs, column_width=15)¶

Print the time average of states.

Parameters

vals (list[object]) – The values for which the time average is to be printed
probs (list[float]) – The probability of each of the members of the values array
column_width (int, optional) – The width of the printed result for vals, by default 15

print_trace_results()¶: Print a brief summary of the results of the trace.

req()¶

Generate a request inter-arrival from self.arrival_process

Returns: The generated inter-arrival sample
Return type: float

reset_trace()¶: resets all the historical data to prepare the class for a new simulation

schedule_warm_instance(t)¶

Goes through a process to determine which warm instance should process the incoming request.

Parameters: t (float) – The time at which the scheduling is happening
Returns: The function instances that the scheduler has selected for the incoming request.
Return type: pacssim.FunctionInstance.FunctionInstance

trace_condition(t)¶

The condition for resulting the trace, we continue the simulation until this function returns false.

Parameters: t (float) – current time in the simulation since the start of simulation
Returns: True if we should continue the simulation, false otherwise
Return type: bool

warm_start_arrival(t)¶

Goes through the process necessary for a warm start arrival which includes selecting a warm instance for processing and recording the request information.

Parameters: t (float) – The time at which the arrival has happened. This is used to record the creation time for the server and schedule the expiration of the instance if necessary.

ServerlessTemporalSimulator¶

class pacssim.ServerlessTemporalSimulator.ExponentialServerlessTemporalSimulator(running_function_instance_count, idle_function_instance_next_terminations, *args, **kwargs)¶

Bases: pacssim.ServerlessTemporalSimulator.ServerlessTemporalSimulator

ExponentialServerlessTemporalSimulator is a simulator assuming exponential distribution for proceesing times which means each process is state-less and we can generate a service time and use that from now on. This class extends ServerlessTemporalSimulator which has functionality for other processes as well.

Parameters

running_function_instance_count (integer) – running_function_instance_count is the number of instances currently processing a request
idle_function_instance_next_terminations (list[float]) – idle_function_instance_next_terminations is an array of next termination scheduled for idle functions if they receive no new requests.

class pacssim.ServerlessTemporalSimulator.ServerlessTemporalSimulator(running_function_instances, idle_function_instances, *args, **kwargs)¶

Bases: pacssim.ServerlessSimulator.ServerlessSimulator

ServerlessTemporalSimulator extends ServerlessSimulator to enable extraction of temporal characteristics. Also gets all of the arguments accepted by ServerlessSimulator

Parameters

running_function_instances (list[FunctionInstance]) – A list containing the running function instances
idle_function_instances (list[FunctionInstance]) – A list containing the idle function instances

FunctionInstance¶

class pacssim.FunctionInstance.FunctionInstance(t, cold_service_process, warm_service_process, expiration_threshold)¶

Bases: object

FunctionInstance aims to simulate the behaviour of a function instance in a serverless platform, with all the internal transitions necessary.

Parameters

t (float) – The time at which the instance is being created
cold_service_process (pacssim.SimProcess.SimProcess) – The process used to sample cold start response times
warm_service_process (pacssim.SimProcess.SimProcess) – The process used to sample warm start response times
expiration_threshold (float) – The amount of time it takes for an instance to get expired and the resources consumed by it released after processing the last request

arrival_transition(t)¶

Make an arrival transition, which causes the instance to go from IDLE to WARM

Parameters: t (float) – The time at which the transition has occured, this also updates the next termination.
Raises: Exception – Raises if currently process a request by being in COLD or WARM states

get_life_span()¶

get_next_departure(t)¶

Get the time until the next departure

Parameters: t (float) – Current time
Returns: Amount of time until the next departure
Return type: float
Raises: Exception – Raises if called after the departure

get_next_termination(t)¶

Get the time until the next termination

Parameters: t (float) – Current time
Returns: Amount of time until the next termination
Return type: float
Raises: Exception – Raises if called after the termination

get_next_transition_time(t=0)¶

Get how long until the next transition.

Parameters: t (float, optional) – The current time, by default 0
Returns: The seconds remaining until the next transition
Return type: float

get_state()¶

is_idle()¶

Whether or not the instance is currently idle, and thus can accept new requests.

Returns: True if idle, false otherwise
Return type: bool

make_transition()¶

Make the next internal transition, either transition into IDLE of already processing a request, or TERM if scheduled termination has arrived.

Returns: The state after making the internal transition
Return type: str
Raises: Exception – Raises if already in TERM state, since no other internal transitions are possible

update_next_termination()¶: Update the next scheduled termination if no other requests are made to the instance.

SimProcess¶

class pacssim.SimProcess.ConstSimProcess(rate)¶

Bases: pacssim.SimProcess.SimProcess

ConstSimProcess extends the functionality of SimProcess for constant processes, meaning this is a deterministic process and fires exactly every 1/rate seconds. This class does not implement the pdf and cdf functions.

ratefloat
The rate at which the process should fire off

generate_trace()¶

generate_trace function is supposed to be replaced with the override function of each of the child classes.

NotImplementedError
By default, this function raises NotImplementedError unless overriden by a child class.

class pacssim.SimProcess.ExpSimProcess(rate)¶

Bases: pacssim.SimProcess.SimProcess

ExpSimProcess extends the functionality of SimProcess for exponentially distributed processes. This class also implements the pdf and cdf functions which can be used for visualization purposes.

ratefloat
The rate at which the process should fire off

cdf(x)¶

cdf function is called for visualization for classes with self.has_cdf = True.

Parameters: x (float) – The time for which the cdf value (density) should be returned
Raises: NotImplementedError – By default, this function raises NotImplementedError unless overriden by a child class.

generate_trace()¶

generate_trace function is supposed to be replaced with the override function of each of the child classes.

NotImplementedError
By default, this function raises NotImplementedError unless overriden by a child class.

pdf(x)¶

pdf function is called for visualization for classes with self.has_pdf = True.

Parameters: x (float) – The time for which the pdf value (density) should be returned
Raises: NotImplementedError – By default, this function raises NotImplementedError unless overriden by a child class.

class pacssim.SimProcess.GaussianSimProcess(rate, std)¶

Bases: pacssim.SimProcess.SimProcess

GaussianSimProcess extends the functionality of SimProcess for gaussian processes. This class also implements the pdf and cdf functions which can be used for visualization purposes.

ratefloat
The rate at which the process should fire off

stdfloat
The standard deviation of the simulated process

cdf(x)¶

cdf function is called for visualization for classes with self.has_cdf = True.

Parameters: x (float) – The time for which the cdf value (density) should be returned
Raises: NotImplementedError – By default, this function raises NotImplementedError unless overriden by a child class.

generate_trace()¶

generate_trace function is supposed to be replaced with the override function of each of the child classes.

NotImplementedError
By default, this function raises NotImplementedError unless overriden by a child class.

pdf(x)¶

pdf function is called for visualization for classes with self.has_pdf = True.

Parameters: x (float) – The time for which the pdf value (density) should be returned
Raises: NotImplementedError – By default, this function raises NotImplementedError unless overriden by a child class.

class pacssim.SimProcess.SimProcess¶

Bases: object

SimProcess gives us a single interface to simulate different processes. This will later on be used to simulated different processes and compare them agaist a custom analytical model. In the child class, after performing super().__init__(), properties self.has_pdf and self.has_cdf by default value of False will be created. In case your class has the proposed PDF and CDF functions available, you need to override these values in order for your model PDF to show up in the output plot.

cdf(x)¶

cdf function is called for visualization for classes with self.has_cdf = True.

Parameters: x (float) – The time for which the cdf value (density) should be returned
Raises: NotImplementedError – By default, this function raises NotImplementedError unless overriden by a child class.

generate_trace()¶

generate_trace function is supposed to be replaced with the override function of each of the child classes.

NotImplementedError
By default, this function raises NotImplementedError unless overriden by a child class.

pdf(x)¶

pdf function is called for visualization for classes with self.has_pdf = True.

Parameters: x (float) – The time for which the pdf value (density) should be returned
Raises: NotImplementedError – By default, this function raises NotImplementedError unless overriden by a child class.

visualize(num_traces=10000, num_bins=100)¶

visualize function visualizes the PDF and CDF of the simulated process by generating traces from your function using generate_trace() and converting the resulting histogram values (event counts) to densities to be comparable with PDF and CDF functions calculated analytically.

num_tracesint, optional
Number of traces we want to generate for calculating the histogram, by default 10000

num_binsint, optional
Number of bins for the histogram which created the density probabilities, by default 100

Utility¶

pacssim.Utility.convert_hist_pdf(_values, num_bins)¶

convert_hist_pdf converts the histogram resulting from _values and num_bins to a density plot by dividing the probability of falling into a bin by the bin size, converting the values to density. The resulting values could be plotted and compared with the analytical pdf and cdf functions.

_valueslist[float]
A list of values that we want to analyze and calculate the histogram for

num_binsint
Number of bins used for generating the histogram

list[float], list[float], list[float]
base, values, cumulative are returned which are the histogram bases, density values, and cumulative densities which can be compared with the analytical cdf function