Qiflib modules

Core QIF objects.

Submodules: - channel: channel matrices / mechanisms - gvulnerability: g-vulnerability and related leakage quantities - hyper: hyper-distributions over secrets - luncertainty: L-uncertainty measures - secrets: priors / secret spaces

class qiflib.core.Channel(secrets, outputs, channel)[source]

Bases: object

Class used to represent a channel. To create an instance of this class it is necessary to have an instance of Secrets class and a channel matrix C \(n{\times}m\) where \(n\) is the number of secrets, \(m\) is the number of outputs in the channel and C[x][y] is the conditional probability \(p(y|x)\) of the channel outputs \(y\) when the value of the secret is \(x\).

Parameters:

secrets (core.Secrets) – Secrets object.
outputs (list) – Outputs labels.
channel (numpy.ndarray) – Channel matrix. Each line must be a probability distribution.

secrets

Set of secrets.

Type:: core.Secrets

outputs

List of channel outputs labels.

Type:: list

num_ouputs

Number of outputs in the channel.

Type:: int

matrix

Channel matrix where C[x][y] is the conditional probability \(p(y|x)\) of the channel outputs \(y\) when the value of the secret is \(x\).

Type:: list, numpy.ndarray

update_prior(prior)[source]

Update the prior distribution on set of secrets. The number of secrets must match the current number of rows of the channel.

Parameters:: prior (list, numpy.ndarray) – Prior distribution on the set of secrets. prior[i] is the probability of secret named labels[i] beeing the real secret.

class qiflib.core.GVulnerability(secrets, actions, gfunction)[source]

Bases: object

\(g\)-vulnerability. To create an instance of this class it is necessary to have an instance of Secrets class and a gain function, that can be a matrix or a pointer to a function. The matrix G must be G \(w{\times}n\) where \(w\) is the number of actions, \(n\) is the number of secrets and G[w][x] is the adversary’s gain when she takes the action w and the secret’s value is x. The function must have two input parameters (action w and secret x, in this order) and outputs a real value.

Parameters:

secrets (core.Secrets) – Set of secrets.
actions (list) – Set of actions.
gfunction (list, numpy.ndarray, pointer to a function) – A 2d matrix or a pointer to a gain function. If the value is a matrix, its shape must match with the actions and secrets sets size. If the value is a pointer to a function, the function must have 2 input parameters (w,x), where w is the index of an element from the set of actions and x is an index of an element from the set of secrets.

secrets

Secrets object.

Type:: core.Secrets

actions

List of actions’ labels.

Type:: list

num_actions

Number of actions.

Type:: int

matrix

Gain function matrix. gain[w][x] is the adversary’s gain when she takes the action of index w (that has the label actions[w]) and the secret is the one from index x (and has the label secrets.labels[x]).

Type:: numpy.ndarray

leakage(hyper)[source]

Calculates the additive and multiplicative leakages.

Parameters:: hyper (core.hyper.Hyper) – Hyper-distribution
Returns:: add_leakage, mult_leakage – Additive and multiplicative leakage
Return type:: (float, float)

posterior_vulnerability(hyper)[source]

Posterior vulnerability.

Parameters:: hyper (core.Hyper) – Hyper-distribution.
Returns:: posterior_vulnerability – Posterior vulnerability.
Return type:: float

prior_vulnerability()[source]

Prior vulnerability.

Returns:: prior_vulnerability – Prior vulnerability.
Return type:: float

class qiflib.core.Hyper(channel)[source]

Bases: object

Hyper-distribution. To create an instance of this class it is class it is necessary to have an instance of Channel class. Once created an instance of Hyper, the constructor generates the joint, outer and inner distributions.

Parameters:: channel (core.Channel) – Channel object.

channel

Channel object.

Type:: core.Channel

joint

Matrix of joint distribution.

Type:: numpy.ndarray

outer

Outer distribution.

Type:: numpy.ndarray

inners

Matrix of inner distributions.

Type:: numpy.ndarray

num_posteriors

Number of posterior distributions resulted by reducing the hyper-distribution, i.e., remove columns that contains only zeros and merge columns which one of them a linear combination of the other.

Type:: int

update_prior(prior)[source]

Update the prior distribution on set of secrets. The number of secrets must match the current number of rows of the channel.

Parameters:: prior (list, numpy.ndarray) – Prior distribution on the set of secrets. prior[i] is the probability of secret named labels[i] beeing the real secret.

class qiflib.core.LUncertainty(secrets, actions, lfunction)[source]

Bases: object

\(\ell\)-uncertainty. To create an instance of this class it is necessary to have an instance of Secrets class and a loss function, that can be a matrix or a pointer to a function. The matrix G must be G \(w{\times}n\) where \(w\) is the number of actions, \(n\) is the number of secrets and G[w][x] is the adversary’s loss when she takes the action w and the secret’s value is x. The function must have two input parameters (action w and secret x, in this order) and outputs a real value.

Parameters:

secrets (core.Secrets) – Set of secrets.
actions (list) – Set of actions.
lfunction (list, numpy.ndarray, pointer to a function) – A 2d matrix or a pointer to a loss function. If the value is a matrix, its shape must match with the actions and secrets sets size. If the value is a pointer to a function, the function must have 2 input parameters (w,x), where w is the index of an element from the set of actions and x is an index of an element from the set of secrets.

secrets

Secrets object.

Type:: core.Secrets

actions

List of actions’ labels.

Type:: list

num_actions

Number of actions.

Type:: int

matrix

Loss function matrix. loss[w][x] is the adversary’s loss when she takes the action of index w (that has the label actions[w]) and the secret is the one from index x (and has the label secrets.labels[x]).

Type:: numpy.ndarray

leakage(hyper)[source]

Calculates the additive and multiplicative leakages.

Parameters:: hyper (core.hyper.Hyper) – Hyper-distribution
Returns:: add_leakage, mult_leakage – Additive and multiplicative leakage
Return type:: (float, float)

posterior_uncertainty(hyper)[source]

Posterior uncertainty.

Parameters:: hyper (core.Hyper) – Hyper-distribution.
Returns:: posterior_uncertainty – Posterior uncertainty.
Return type:: float

prior_uncertainty()[source]

Prior uncertainty.

Returns:: prior_uncertainty – Prior uncertainty.
Return type:: float

class qiflib.core.Secrets(secrets, prior)[source]

Bases: object

Class used to represent a set of secrets. To create an instance of this class it is necessary a set of labels and a probability distribution to be set as the prior distribution on the set of secrets.

Parameters:

secrets (list) – Secrets labels.
prior (list, numpy.ndarray) – Prior distribution on the set of secrets. prior[i] is the probability of secret named labels[i] beeing the real secret.

labels

List of secrets’ labels.

Type:: list, numpy.ndarray

num_secrets

Number of secrets.

Type:: int

prior

Prior distribution on the set of secrets. prior[i] is the probability of secret named labels[i] beeing the real secret.

Type:: numpy.ndarray

update_prior(prior)[source]

Update prior distribution array. The number of elements in the array must be the same as the current number of secrets.

Parameters:: prior (list, numpy.ndarray) – Prior distribution on the set of secrets. prior[i] is the probability of secret named labels[i] beeing the real secret.