Problem

In this package, we assume the following initial optimization problem definition,

\[\underset{y}{\min} \ f (y; x).\]

This optimization problem is defined by :

• an objective function \(f\) shared across a problem class;

• a context \(x\) specific to each problem instance.

Moreover, it is assumed that the gradient \(\nabla_y f\) is defined.

Every class of problem differs from one another. This package provides an interface that should be respected for compatibility with our neural network library.

Problem

class Problem

Bases: ABC

Base abstract class for graph-based optimization or learning problems.

Subclasses must implement methods to retrieve the problem context graph, an initial zero decision graph, compute gradients, evaluate score, and provide problem metadata.

Notes:

• All returned Graph objects must adhere to the energnn.graph.Graph API.

• Methods returning tuples will return additional information in the dict when get_info=True for tracking purpose.

Problem.__init__	Initialize the problem instance.
Problem.get_context	Retrieve the context graph math:x of the problem instance.
Problem.get_gradient	Compute the gradient graph \(\nabla_y f\) for a given decision \(y\).
Problem.get_score	Should return a scalar score that evaluates the decision graph \(y\).
Problem.decision_structure	Should define the structure of all decision graphs.
Problem.context_structure	Should define the structure of all context graphs.

Batch

class ProblemBatch

Bases: ABC

Abstract base class for handling batches of problem instances.

Subclasses should implement methods to retrieve batch of context, compute gradients and scores for batches of decision graphs, and provide an initial zero decision batch.

ProblemBatch.__init__	Initialize the batch handler.
ProblemBatch.get_context	Retrieve the batch of context graphs \(x\).
ProblemBatch.get_gradient	Compute gradients \(\nabla_y f\) for a batched of decision graphs \(y\).
ProblemBatch.get_score	Evaluate a scalar score for each decision graph in the batch.
ProblemBatch.decision_structure	Should define the structure of all decision graphs.
ProblemBatch.context_structure	Should define the structure of all context graphs.

Loader

class ProblemLoader(batch_size, shuffle=False)

Bases: ABC, Sized, Iterator[ProblemBatch]

Abstract base class for problem loaders that yield batches of problem instances.

Iterates over problem instances in batches, optionally shuffling the dataset.

Parameters:

• batch_size (int) – Number of instances per batch returned by the iterator.

• shuffle (bool) – If true, randomly shuffle the dataset.

ProblemLoader.__init__	Initialize the problem loader.
ProblemLoader.__iter__	Return the loader iterator.
ProblemLoader.__next__	Retrieve the next batch of problems.
ProblemLoader.__len__	Number of batches per epoch.
ProblemLoader.context_structure	Should define the structure of all context graphs.
ProblemLoader.decision_structure	Should define the structure of all decision graphs.