ignite.engine

class ignite.engine.Engine(process_function)

Runs a given process_function over each batch of a dataset, emitting events as it goes.

Parameters

process_function (Callable) – A function receiving a handle to the engine and the current batch in each iteration, and returns data to be stored in the engine’s state

Example usage:

def train_and_store_loss(engine, batch):
    inputs, targets = batch
    optimizer.zero_grad()
    outputs = model(inputs)
    loss = loss_fn(outputs, targets)
    loss.backward()
    optimizer.step()
    return loss.item()

engine = Engine(train_and_store_loss)
engine.run(data_loader)

# Loss value is now stored in `engine.state.output`.

add_event_handler(event_name, handler, *args, **kwargs)

Add an event handler to be executed when the specified event is fired

Parameters

• event_name – An event to attach the handler to. Valid events are from ignite.engine.Events or any event_name added by register_events().

• handler (Callable) – the callable event handler that should be invoked

• *args – optional args to be passed to handler

• **kwargs – optional keyword args to be passed to handler

Notes

The handler function’s first argument will be self, the Engine object it was bound to.

Note that other arguments can be passed to the handler in addition to the *args and **kwargs passed here, for example during Events.EXCEPTION_RAISED.

Example usage:

engine = Engine(process_function)

def print_epoch(engine):
    print("Epoch: {}".format(engine.state.epoch))

engine.add_event_handler(Events.EPOCH_COMPLETED, print_epoch)

fire_event(event_name)

Execute all the handlers associated with given event.

This method executes all handlers associated with the event event_name. This is the method used in Engine.run to call the core events found in ignite.engines.Events.

Custom events can be fired if they have been registerd before with Engine.register_events. The engine state attribute should be used to exchange “dynamic” data among process_function and handlers.

This method is called automatically for core events. If no custom events are used in the engine, there is no need for the user to call the method.

Parameters

event_name – event for which the handlers should be executed. Valid events are from ignite.engine.Events or any event_name added by register_events().

on(event_name, *args, **kwargs)

Decorator shortcut for add_event_handler

Parameters

• event_name – An event to attach the handler to. Valid events are from ignite.engine.Events or any event_name added by register_events().

• *args – optional args to be passed to handler

• **kwargs – optional keyword args to be passed to handler

register_events(*event_names)

Add events that can be fired.

Registering an event will let the user fire these events at any point. This opens the door to make the Engine.run loop even more configurable.

By default, the events from ignite.engines.Events are registerd.

Parameters

*event_names – An object (ideally a string or int) to define the name of the event being supported.

Example usage:

from enum import Enum

class Custom_Events(Enum):
    FOO_EVENT = "foo_event"
    BAR_EVENT = "bar_event"

engine = Engine(process_function)
engine.register_events(*Custom_Events)

run(data, max_epochs=1)

Runs the process_function over the passed data.

Parameters

• data (Iterable) – Collection of batches allowing repeated iteration (e.g., list or DataLoader)

• max_epochs (int, optional) – max epochs to run for (default: 1)

Returns

output state

Return type

State

terminate()

Sends terminate signal to the engine, so that it terminates completely the run after the current iteration

terminate_epoch()

Sends terminate signal to the engine, so that it terminates the current epoch after the current iteration

ignite.engine.create_supervised_evaluator(model, metrics={}, device=None, non_blocking=False, prepare_batch=<function _prepare_batch>)

Factory function for creating an evaluator for supervised models

Parameters

• model (torch.nn.Module) – the model to train

• metrics (dict of str - ignite.metrics.Metric) – a map of metric names to Metrics

• device (str, optional) – device type specification (default: None). Applies to both model and batches.

• non_blocking (bool, optional) – if True and this copy is between CPU and GPU, the copy may occur asynchronously with respect to the host. For other cases, this argument has no effect.

• prepare_batch (Callable, optional) – function that receives batch, device, non_blocking and outputs tuple of tensors (batch_x, batch_y).

Returns

an evaluator engine with supervised inference function

Return type

Engine

ignite.engine.create_supervised_trainer(model, optimizer, loss_fn, device=None, non_blocking=False, prepare_batch=<function _prepare_batch>)

Factory function for creating a trainer for supervised models

Parameters

• model (torch.nn.Module) – the model to train

• optimizer (torch.optim.Optimizer) – the optimizer to use

• loss_fn (torch.nn loss function) – the loss function to use

• device (str, optional) – device type specification (default: None). Applies to both model and batches.

• non_blocking (bool, optional) – if True and this copy is between CPU and GPU, the copy may occur asynchronously with respect to the host. For other cases, this argument has no effect.

• prepare_batch (Callable, optional) – function that receives batch, device, non_blocking and outputs tuple of tensors (batch_x, batch_y).

Returns

a trainer engine with supervised update function

Return type

Engine

class ignite.engine.Events(value)

Events that are fired by the ignite.engine.Engine during execution

COMPLETED = 'completed'

EPOCH_COMPLETED = 'epoch_completed'

EPOCH_STARTED = 'epoch_started'

EXCEPTION_RAISED = 'exception_raised'

ITERATION_COMPLETED = 'iteration_completed'

ITERATION_STARTED = 'iteration_started'

STARTED = 'started'

class ignite.engine.State(**kwargs)

An object that is used to pass internal and user-defined state between event handlers