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[source]¶

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[source]¶

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.

Dataset¶

class ProblemDataset(name, split, version, instances, size, context_max_shape, decision_max_shape, generation_date, selection_criteria, tags=None)[source]¶

Bases: dict

Dictionary-like container for datasets of problem instances.

Stores dataset-level metadata and a list of ProblemMetadata instances.

Parameters:

name (str) – Identifier for the dataset.
split (str) – Dataset split name (e.g., “train”, “val”, “test”).
version (int) – Version number of the dataset.
instances (list[ProblemMetadata]) – List of ProblemMetadata objects describing each instance.
size (int) – Total number of instances in the dataset.
context_max_shape (dict) – Maximum dimensions of context graphs across instances.
decision_max_shape (dict) – Maximum dimensions of decision graphs across instances.
generation_date (datetime) – Timestamp when the dataset was generated.
selection_criteria (dict) – A dictionary that contains some criteria
tags – Key-value tags associated with the dataset for grouping or filtering.

`ProblemDataset.get_infos_for_feature_store`	Retrieve the dataset's information to send to the feature store.
`ProblemDataset.get_locally_missing_instances`	Identify instances whose files are missing in a local directory.
`ProblemDataset.get_instance_paths`	List the storage paths for all instances in the dataset.
`ProblemDataset.to_json`	Serialize the dataset to a JSON file for human-readable archives.
`ProblemDataset.to_pickle`	Serialize the dataset to a pickle file for efficient reload.
`ProblemDataset.from_pickle`	Load a dataset from a pickle file produced by to_pickle.

Metadata¶

class ProblemMetadata(name, config_id, code_version, context_shape, decision_shape, storage_path='', filter_tags=None)[source]¶

Bases: dict

Metadata of a Problem instance.

Parameters:

name (str) – Name of the instance.
config_id (str) – Identifier of the configuration file used to generate the instance.
code_version (int) – Version of the code used to generate the instance.
context_shape (dict) – Shape of the context of the instance, formatted as a dict containing only int values (no jax.Array).
decision_shape (dict) – Shape of the decision of the instance, formatted as a dict containing only int values (no jax.Array).
filter_tags (dict | None) – Dictionary of the criteria used to select the instance to form datasets.

Loader¶

class ProblemLoader(batch_size, shuffle=False)[source]¶

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.