dualing.core

Core is the core. Essentially, it is the parent of everything. You should find parent classes defining the basis of our structure. They should provide variables and methods that will help to construct other modules.

A core package, containing all the basic class and functions that serves as the foundation of Dualing common modules.

class dualing.core.Base(name: Optional[str] = '')

Bases: tensorflow.keras.Model

A Base class is responsible for easily-implementing the base twin architecture of a Siamese Network.

__init__(self, name: Optional[str] = '')

Initialization method.

Parameters

name – Naming identifier.

abstract call(self, x: tensorflow.Tensor)

Method that holds vital information whenever this class is called.

Note that you need to implement this method directly on its child. Essentially, each neural network has its own forward pass implementation.

Parameters

x – Tensor containing the input sample.

Raises

NotImplementedError. –

class dualing.core.BinaryCrossEntropy

A BinaryCrossEntropy class defines the binary cross-entropy loss.

__call__(self, y_true: tensorflow.Tensor, y_pred: tensorflow.Tensor)

Method that holds vital information whenever this class is called.

Parameters

  • y_true – Tensor containing the true labels.

  • y_pred – Tensor containing the predictions, e.g., similar or dissimilar.

Returns

Binary cross-entropy loss.

Return type

(tf.Tensor)

class dualing.core.ContrastiveLoss

A ContrastiveEntropy class defines the contrastive loss.

__call__(self, y_true: tensorflow.Tensor, y_pred: tensorflow.Tensor, margin: Optional[float] = 1.0)

Method that holds vital information whenever this class is called.

Parameters

  • y_true – Tensor containing the true labels.

  • y_pred – Tensor containing the predictions, e.g., distance.

  • margin – Radius around the embedding space.

Returns

Contrastive loss.

Return type

(tf.Tensor)

class dualing.core.Dataset(batch_size: Optional[int] = 1, input_shape: Optional[Tuple[int, Ellipsis]] = None, normalize: Optional[Tuple[int, int]] = (0, 1), shuffle: Optional[bool] = True, seed: Optional[int] = 0)

A Dataset class is responsible for receiving raw data, pre-processing it and persisting batches that will be feed as inputs to the networks.

__init__(self, batch_size: Optional[int] = 1, input_shape: Optional[Tuple[int, Ellipsis]] = None, normalize: Optional[Tuple[int, int]] = (0, 1), shuffle: Optional[bool] = True, seed: Optional[int] = 0)

Initialization method.

Parameters

  • batch_size – Batch size.

  • input_shape – Shape of the reshaped array.

  • normalize – Normalization bounds.

  • shuffle – Whether data should be shuffled or not.

  • seed – Provides deterministic traits when using random module.

abstract _build(self)

Method that builds the class.

Note that you need to implement this method directly on its child. Essentially, each Dataset has its building procedure.

Raises

NotImplementedError. –

property batch_size(self)

Batch size.

property input_shape(self: Tuple[int, Ellipsis])

Shape of the input tensors.

property normalize(self)

Normalization bounds.

preprocess(self, data: numpy.array)

Pre-process the data by reshaping and normalizing, if necessary.

Parameters

data – Array of data.

Returns

Pre-processed data.

Return type

(np.array)

property shuffle(self)

Whether data should be shuffled or not.

class dualing.core.Siamese(base: Base, name: Optional[str] = '')

Bases: tensorflow.keras.Model

An Siamese class is responsible for implementing the base of Siamese Neural Networks.

property B(self)

Twin architecture.

__init__(self, base: Base, name: Optional[str] = '')

Initialization method.

Parameters

  • base – Twin architecture.

  • name – Naming identifier.

abstract compile(self, optimizer: tensorflow.keras.optimizers)

Method that builds the network by attaching optimizer, loss and metrics.

Note that you need to implement this method directly on its child. Essentially, each type of Siamese has its own set of loss and metrics.

Parameters

optimizer – Optimization algorithm.

Raises

NotImplementedError. –

abstract evaluate(self, batches: dualing.core.dataset.Dataset)

Method that evaluates the model over validation or testing batches.

Note that you need to implement this method directly on its child. Essentially, each type of Siamese may use a distinct type of dataset.

Parameters

batches – Batches of tuples holding validation / testing samples and labels.

Raises

NotImplementedError. –

extract_embeddings(self, x: Union[numpy.array, tensorflow.Tensor])

Method that extracts embeddings by performing a forward pass over the base architecture (embedder).

Parameters

x – Array or tensor containing the inputs to be embedded.

Returns

A tensor containing the embedded inputs.

Return type

(tf.Tensor)

abstract fit(self, batches: dualing.core.dataset.Dataset, epochs: Optional[int] = 100)

Method that trains the model over training batches.

Note that you need to implement this method directly on its child. Essentially, each type of Siamese may use a distinct type of dataset.

Parameters

  • batches – Batches of tuples holding training samples and labels.

  • epochs – Maximum number of epochs.

Raises

NotImplementedError. –

abstract predict(self, x: tensorflow.Tensor)

Method that performs a forward pass over samples and returns the network’s output.

Note that you need to implement this method directly on its child. Essentially, each type of Siamese may predict in a different way.

Parameters

x – Tensor containing samples.

Raises

NotImplementedError. –

abstract step(self, x: tensorflow.Tensor, y: tensorflow.Tensor)

Method that performs a single batch optimization step.

Note that you need to implement this method directly on its child. Essentially, each type of Siamese has an unique step.

Parameters

  • x – Tensor containing samples.

  • y – Tensor containing labels.

Raises

NotImplementedError. –

class dualing.core.TripletHardLoss

A TripletHardLoss class defines the triplet loss with hard negative mining.

__call__(self, y_true: tensorflow.Tensor, y_pred: tensorflow.Tensor, margin: Optional[float] = 1.0, soft: Optional[bool] = False, distance_metric: Optional[str] = 'L2')

Method that holds vital information whenever this class is called.

Parameters

  • y_true – Tensor containing the true labels.

  • y_pred – Tensor containing the predictions, e.g., embeddings.

  • margin – Radius around the embedding space.

  • soft – Whether network should use soft margin or not.

  • distance_metric – Distance metric.

Returns

Triplet loss with hard negative mining.

Return type

(tf.Tensor)

class dualing.core.TripletSemiHardLoss

A TripletSemiHardLoss class defines the triplet loss with semi-hard negative mining.

__call__(self, y_true: tensorflow.Tensor, y_pred: tensorflow.Tensor, margin: Optional[float] = 1.0, soft: Optional[bool] = None, distance_metric: Optional[str] = 'L2')

Method that holds vital information whenever this class is called.

Parameters

  • y_true – Tensor containing the true labels.

  • y_pred – Tensor containing the predictions, e.g., embeddings.

  • margin – Radius around the embedding space.

  • soft – Only for retro-compatibility.

  • distance_metric – Distance metric.

Returns

Triplet loss with semi-hard negative mining.

Return type

(tf.Tensor)