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.

state

object that is used to pass internal and user-defined state between event handlers. It is created and reset on every run().

Type

State

last_event_name

last event name triggered by the engine.

Type

Events

Examples

Create a basic trainer

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

trainer = Engine(update_model)

@trainer.on(Events.ITERATION_COMPLETED(every=100))
def log_training(engine):
    batch_loss = engine.state.output
    lr = optimizer.param_groups[0]['lr']
    e = engine.state.epoch
    n = engine.state.max_epochs
    i = engine.state.iteration
    print("Epoch {}/{} : {} - batch loss: {}, lr: {}".format(e, n, i, batch_loss, lr))

trainer.run(data_loader, max_epochs=5)

> Epoch 1/5 : 100 - batch loss: 0.10874069479016124, lr: 0.01
> ...
> Epoch 2/5 : 1700 - batch loss: 0.4217900575859437, lr: 0.01

Create a basic evaluator to compute metrics

from ignite.metrics import Accuracy

def predict_on_batch(engine, batch)
    model.eval()
    with torch.no_grad():
        x, y = prepare_batch(batch, device=device, non_blocking=non_blocking)
        y_pred = model(x)

    return y_pred, y

evaluator = Engine(predict_on_batch)
Accuracy().attach(evaluator, "val_acc")
evaluator.run(val_dataloader)

Compute image mean/std on training dataset

from ignite.metrics import Average

def compute_mean_std(engine, batch):
    b, c, *_ = batch['image'].shape
    data = batch['image'].reshape(b, c, -1).to(dtype=torch.float64)
    mean = torch.mean(data, dim=-1).sum(dim=0)
    mean2 = torch.mean(data ** 2, dim=-1).sum(dim=0)
    return {"mean": mean, "mean^2": mean2}

compute_engine = Engine(compute_mean_std)
img_mean = Average(output_transform=lambda output: output['mean'])
img_mean.attach(compute_engine, 'mean')
img_mean2 = Average(output_transform=lambda output: output['mean^2'])
img_mean2.attach(compute_engine, 'mean2')
state = compute_engine.run(train_loader)
state.metrics['std'] = torch.sqrt(state.metrics['mean2'] - state.metrics['mean'] ** 2)
mean = state.metrics['mean'].tolist()
std = state.metrics['std'].tolist()

Resume engine’s run from a state. User can load a state_dict and run engine starting from loaded state :

# Restore from an epoch
state_dict = {"seed": 0, "epoch": 3, "max_epochs": 100, "epoch_length": len(data_loader)}
# or an iteration
# state_dict = {"seed": 0, "iteration": 500, "max_epochs": 100, "epoch_length": len(data_loader)}

trainer = Engine(...)
trainer.load_state_dict(state_dict)
trainer.run(data)

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 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.

Note

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 EXCEPTION_RAISED.

Returns

RemovableEventHandler, which can be used to remove the handler.

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)

Note

Since v0.3.0, Events become more flexible and allow to pass an event filter to the Engine. See Events for more details.

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 run() to call the core events found in Events.

Custom events can be fired if they have been registered before with 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 Events or any event_name added by register_events().

has_event_handler(handler, event_name=None)

Check if the specified event has the specified handler.

Parameters

• handler (callable) – the callable event handler.

• event_name – The event the handler attached to. Set this to None to search all events.

load_state_dict(state_dict)

Setups engine from state_dict.

State dictionary should contain keys: iteration or epoch and max_epochs, epoch_length and seed. Iteration and epoch values are 0-based: the first iteration or epoch is zero.

Parameters

state_dict (Mapping) – a dict with parameters

# Restore from an epoch
state_dict = {"seed": 0, "epoch": 3, "max_epochs": 100, "epoch_length": len(data_loader)}
# or an iteration
# state_dict = {"seed": 0, "iteration": 500, "max_epochs": 100, "epoch_length": len(data_loader)}

trainer = Engine(...)
trainer.load_state_dict(state_dict)
trainer.run(data)

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 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, **kwargs)

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 run() loop even more configurable.

By default, the events from Events are registered.

Parameters

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

• event_to_attr (dict, optional) – A dictionary to map an event to a state attribute.

Example usage:

from enum import Enum
from ignite.engine import Engine

class CustomEvents(CallableEvents, Enum):
    FOO_EVENT = "foo_event"
    BAR_EVENT = "bar_event"

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

Example with State Attribute:

from enum import Enum
from ignite.engine.engine import Engine, CallableEvents

class TBPTT_Events(CallableEvents, Enum):
    TIME_ITERATION_STARTED = "time_iteration_started"
    TIME_ITERATION_COMPLETED = "time_iteration_completed"

TBPTT_event_to_attr = {
    TBPTT_Events.TIME_ITERATION_STARTED: 'time_iteration',
    TBPTT_Events.TIME_ITERATION_COMPLETED: 'time_iteration'
}

engine = Engine(process_function)
engine.register_events(*TBPTT_Events, event_to_attr=TBPTT_event_to_attr)
engine.run(data)
# engine.state contains an attribute time_iteration, which can be accessed using engine.state.time_iteration

remove_event_handler(handler, event_name)

Remove event handler handler from registered handlers of the engine

Parameters

• handler (callable) – the callable event handler that should be removed

• event_name – The event the handler attached to.

run(data, max_epochs=None, epoch_length=None, seed=None)

Runs the process_function over the passed data.

Engine has a state and the following logic is applied in this function:

• At the first call, new state is defined by max_epochs, epoch_length, seed if provided.

• If state is already defined such that there are iterations to run until max_epochs and no input arguments

  provided, state is kept and used in the function.

• If state is defined and engine is “done” (no iterations to run until max_epochs), a new state is defined.

• If state is defined, engine is NOT “done”, then input arguments if provided override defined state.

Parameters

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

• max_epochs (int, optional) – Max epochs to run for (default: None). If a new state should be created (first run or run again from ended engine), it’s default value is 1. This argument should be None if run is resuming from a state.

• epoch_length (int, optional) – Number of iterations to count as one epoch. By default, it can be set as len(data). If data is an iterator and epoch_length is not set, an error is raised. This argument should be None if run is resuming from a state.

• seed (int, optional) – Seed to setup at each epoch for reproducible runs. This argument should be None if run is resuming from a state.

Returns

output state.

Return type

State

Note

User can dynamically preprocess input batch at ITERATION_STARTED and store output batch in engine.state.batch. Latter is passed as usually to process_function as argument:

trainer = ...

@trainer.on(Events.ITERATION_STARTED)
def switch_batch(engine):
    engine.state.batch = preprocess_batch(engine.state.batch)

Note

In order to perform a reproducible run, if input data is torch.utils.data.DataLoader, its batch sampler is replaced by a batch sampler (ReproducibleBatchSampler) such that random sampling indices are reproducible by prefetching them before data iteration.

state_dict()

Returns a dictionary containing engine’s state: “seed”, “epoch_length”, “max_epochs” and “iteration”

Returns

a dictionary containing engine’s state

Return type

dict

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=None, device=None, non_blocking=False, prepare_batch=<function _prepare_batch>, output_transform=<function <lambda>>)

Factory function for creating an evaluator for supervised models.

Parameters

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

• metrics (dict of str - 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).

• output_transform (callable, optional) – function that receives ‘x’, ‘y’, ‘y_pred’ and returns value to be assigned to engine’s state.output after each iteration. Default is returning (y_pred, y,) which fits output expected by metrics. If you change it you should use output_transform in metrics.

Note: engine.state.output for this engine is defind by output_transform parameter and is

a tuple of (batch_pred, batch_y) by default.

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>, output_transform=<function <lambda>>)

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).

• output_transform (callable, optional) – function that receives ‘x’, ‘y’, ‘y_pred’, ‘loss’ and returns value to be assigned to engine’s state.output after each iteration. Default is returning loss.item().

Note: engine.state.output for this engine is defind by output_transform parameter and is the loss

of the processed batch by default.

Returns

a trainer engine with supervised update function.

Return type

Engine

class ignite.engine.Events(value)

Events that are fired by the Engine during execution.

Since v0.3.0, Events become more flexible and allow to pass an event filter to the Engine:

engine = Engine()

# a) custom event filter
def custom_event_filter(engine, event):
    if event in [1, 2, 5, 10, 50, 100]:
        return True
    return False

@engine.on(Events.ITERATION_STARTED(event_filter=custom_event_filter))
def call_on_special_event(engine):
     # do something on 1, 2, 5, 10, 50, 100 iterations

# b) "every" event filter
@engine.on(Events.ITERATION_STARTED(every=10))
def call_every(engine):
    # do something every 10th iteration

# c) "once" event filter
@engine.on(Events.ITERATION_STARTED(once=50))
def call_once(engine):
    # do something on 50th iteration

Event filter function event_filter accepts as input engine and event and should return True/False. Argument event is the value of iteration or epoch, depending on which type of Events the function is passed.

COMPLETED = 'completed'

EPOCH_COMPLETED = 'epoch_completed'

EPOCH_STARTED = 'epoch_started'

EXCEPTION_RAISED = 'exception_raised'

GET_BATCH_COMPLETED = 'get_batch_completed'

GET_BATCH_STARTED = 'get_batch_started'

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. By default, state contains the following attributes:

state.iteration         # 1-based, the first iteration is 1
state.epoch             # 1-based, the first epoch is 1
state.seed              # seed to set at each epoch
state.dataloader        # data passed to engine
state.epoch_length      # optional length of an epoch
state.max_epochs        # number of epochs to run
state.batch             # batch passed to `process_function`
state.output            # output of `process_function` after a single iteration
state.metrics           # dictionary with defined metrics if any

class ignite.engine.engine.RemovableEventHandle(event_name, handler, engine)

A weakref handle to remove a registered event.

A handle that may be used to remove a registered event handler via the remove method, with-statement, or context manager protocol. Returned from add_event_handler().

Parameters

• event_name – Registered event name.

• handler – Registered event handler, stored as weakref.

• engine – Target engine, stored as weakref.

Example usage:

engine = Engine()

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

with engine.add_event_handler(Events.EPOCH_COMPLETED, print_epoch):
    # print_epoch handler registered for a single run
    engine.run(data)

# print_epoch handler is now unregistered

remove()

Remove handler from engine.