Ivory
MODULE

IVORY.CORE.RUN

</>

This module provides the Run class that is one of the main classes of Ivory library. In addition, Task and Study classes are defined, which manages multiple runs for cross validation, hyperparameter tuning, and so on.

To create an Run instance:

import ivory

client = ivory.create_run('example')

The argument example is an experiment name in which the created run is included. Ivory assumes that example.yml or example.yaml file exists under the client's working directory.

You can comfirm the client's working directory by:

os.path.dirname(client.source_name)

One you got a Run instance. call Run.start() to start training. For test, call Run.start('test') instead. Also, you can perform traing and test by one step with Run.start('both').

Classes
  • Run — Run class is one of the main classes of Ivory library.</>
  • Task — Task class creates a parent run that generates multiple runs.</>
  • Study — Study class create a parent run to manage hyperparameter tuning.</>
class

ivory.core.run.Run(params=None, **instances)

</>
Bases
ivory.core.base.CallbackCaller ivory.core.base.Creator ivory.core.base.Base ivory.core.collections.Dict

Run class is one of the main classes of Ivory library.

Parameters
  • params (optional) — Parameter dictionary to create this instance.
  • **instances — Member instances. Key is its name and value is the member instance.
Attributes
  • dict —
  • id (str) — Instance ID given by MLFlow Tracking.
  • mode —
  • name (str) — Instance name.
  • params (dict, optional) — Parameter dictionary that is used to to create this instance.
  • source_name (str) — Name of the YAML parameter file that is used to create this instance.
Methods
  • create_callbacks() — Creates callback functions and store them in a dictionary.</>
  • create_instance(instance_name, args, name, **kwargs) — Creates an member instance of a Run according to arguments.</>
  • create_params(args, name, **kwargs) (dict, dict) — Returns a tuple of (parameter dictionary, update dictionary).</>
  • create_run(args, name, **kwargs) (Run) — Creates a Run instance according to arguments.</>
  • load(directory) (dict(str: any)) — Loads member instances.</>
  • load_state_dict(state_dict) — Loads a state dictionary to all of member instances.</>
  • save(directory) — Saves member instances.</>
  • set_tracker(tracker, name) — Sets tracker for tracking.</>
  • start(mode) — Starts traing and/or test.</>
  • state_dict() (dict) — Returns a state dictionary for all of member instances.</>
method

create_params(args=None, name='run', **kwargs) → (dict, dict)

</>

Returns a tuple of (parameter dictionary, update dictionary).

The parameter dictionary is deeply copied from original one, then updated according to the arguments. The update dictionary includes updated parameter only.

Parameters
  • args (dict, optional) — Update dictionary.
  • name (str, optional) — Run class name in lower case.
  • **kwargs — Additional update dictionary.
Examples

Use args for parameters including dots:

params, update = experiment.create_params(
    {'hidden_sizes.0': 100}, fold=3
)

The params is the full parameter dictionary, while the update is a part of params, i.e., update = {'hidden_sizes.0': 100, 'fold': 3}.

method

create_run(args=None, name='run', **kwargs)

</>

Creates a Run instance according to arguments.

Parameters
  • args (dict, optional) — Update dictionary.
  • name (str, optional) — Run class name in lower case.
  • **kwargs — Additional update dictionary.
Returns (Run)

Created Run instance. The parameter for this instance is the returned dictionary from the create_params() function.

method

create_instance(instance_name, args=None, name='run', **kwargs)

</>

Creates an member instance of a Run according to arguments.

Parameters
  • instance_name (str) — Name of a member instance to create.
  • args (dict, optional) — Update dictionary.
  • name (optional) — Run class name in lower case.
  • **kwargs — Additional update dictionary.
Returns

Created instance. The parameter for this instance is the returned directory from the create_params() function.

method

create_callbacks()

</>

Creates callback functions and store them in a dictionary.

method

set_tracker(tracker, name)

</>

Sets tracker for tracking.

By setting a tracker, a Run instance can be a run of MLFlow Tracking at the same time. MLFlow Tracking gives the Run ID and name for this instance.

Parameters
  • tracker (Tracker) — Tracker instance.
  • name (str) —
method

start(mode='train')

</>

Starts traing and/or test.

Parameters
  • mode (str, optional) — Mode name: 'train', 'test', or 'both'.
method

state_dict() → dict

</>

Returns a state dictionary for all of member instances.

method

load_state_dict(state_dict)

</>

Loads a state dictionary to all of member instances.

Parameters
  • state_dict (dict) — state dictionary for all of member instances.
method

save(directory)

</>

Saves member instances.

Parameters
  • directory (str) — Directory where member instances are saved.
method

load(directory) → dict(str: any)

</>

Loads member instances.

Parameters
  • directory (str) — Directory where member instances have been saved.
class

ivory.core.run.Task(params=None, **instances)

</>
Bases
ivory.core.run.Run ivory.core.base.CallbackCaller ivory.core.base.Creator ivory.core.base.Base ivory.core.collections.Dict

Task class creates a parent run that generates multiple runs.

Parameters
  • params (optional) — Parameter dictionary to create this instance.
  • **instances — Member instances. Key is its name and value is the member instance.
Attributes
  • dict —
  • id (str) — Instance ID given by MLFlow Tracking.
  • mode —
  • name (str) — Instance name.
  • params (dict, optional) — Parameter dictionary that is used to to create this instance.
  • source_name (str) — Name of the YAML parameter file that is used to create this instance.
Methods
  • chain(params, use_best_param, **kwargs) (Run) — Makes a chain iterator.</>
  • create_callbacks() — Creates callback functions and store them in a dictionary.</>
  • create_instance(instance_name, args, name, **kwargs) — Creates an member instance of a Run according to arguments.</>
  • create_params(args, name, **kwargs) (dict, dict) — Returns a tuple of (parameter dictionary, update dictionary).</>
  • create_run(args, **kwargs) (Run) — Create a nested run according to arguments</>
  • load(directory) (dict(str: any)) — Loads member instances.</>
  • load_state_dict(state_dict) — Loads a state dictionary to all of member instances.</>
  • product(params, repeat, **kwargs) (Run) — Makes a product iterator.</>
  • save(directory) — Saves member instances.</>
  • set_tracker(tracker, name) — Sets tracker for tracking.</>
  • start(mode) — Starts traing and/or test.</>
  • state_dict() (dict) — Returns a state dictionary for all of member instances.</>
method

create_params(args=None, name='run', **kwargs) → (dict, dict)

</>

Returns a tuple of (parameter dictionary, update dictionary).

The parameter dictionary is deeply copied from original one, then updated according to the arguments. The update dictionary includes updated parameter only.

Parameters
  • args (dict, optional) — Update dictionary.
  • name (str, optional) — Run class name in lower case.
  • **kwargs — Additional update dictionary.
Examples

Use args for parameters including dots:

params, update = experiment.create_params(
    {'hidden_sizes.0': 100}, fold=3
)

The params is the full parameter dictionary, while the update is a part of params, i.e., update = {'hidden_sizes.0': 100, 'fold': 3}.

method

create_instance(instance_name, args=None, name='run', **kwargs)

</>

Creates an member instance of a Run according to arguments.

Parameters
  • instance_name (str) — Name of a member instance to create.
  • args (dict, optional) — Update dictionary.
  • name (optional) — Run class name in lower case.
  • **kwargs — Additional update dictionary.
Returns

Created instance. The parameter for this instance is the returned directory from the create_params() function.

method

create_callbacks()

</>

Creates callback functions and store them in a dictionary.

method

set_tracker(tracker, name)

</>

Sets tracker for tracking.

By setting a tracker, a Run instance can be a run of MLFlow Tracking at the same time. MLFlow Tracking gives the Run ID and name for this instance.

Parameters
  • tracker (Tracker) — Tracker instance.
  • name (str) —
method

start(mode='train')

</>

Starts traing and/or test.

Parameters
  • mode (str, optional) — Mode name: 'train', 'test', or 'both'.
method

state_dict() → dict

</>

Returns a state dictionary for all of member instances.

method

load_state_dict(state_dict)

</>

Loads a state dictionary to all of member instances.

Parameters
  • state_dict (dict) — state dictionary for all of member instances.
method

save(directory)

</>

Saves member instances.

Parameters
  • directory (str) — Directory where member instances are saved.
method

load(directory) → dict(str: any)

</>

Loads member instances.

Parameters
  • directory (str) — Directory where member instances have been saved.
method

create_run(args, **kwargs)

</>

Create a nested run according to arguments

Parameters
  • args (dict, optional) — Update dictionary.
  • **kwargs — Additional update dictionary.
Returns (Run)

Created nested Run instance.

generator

product(params=None, repeat=1, **kwargs) → Run

</>

Makes a product iterator.

This iterator returns runs from cartesian product of input parameters.

Parameters
  • params (dict, optional) — Parameter range. Key is a parameter name and value is an iterable of parameter's value.
  • repeat (int, optional) — Number of repeatation.
  • **kwargs — Additional parameter range.
See Also

Product section in Multiple Runs Tutorial

generator

chain(params=None, use_best_param=True, **kwargs) → Run

</>

Makes a chain iterator.

This iterator returns runs from the first input paramter until it is exhausted, then proceeds to the next parameter, until all of the parameters are exhausted. Other parameters have default values if they don't be specified by additional key-value pairs.

Parameters
  • params (dict, optional) — Parameter range. Key is a parameter name and value is an iterable of parameter's value. use_best_param: If True (default), the parameter that got the best score is used during the following iterations.
  • use_best_param (bool, optional) —
  • **kwargs — Additional parameter range.
See Also

Chain section in Multiple Runs Tutorial

class

ivory.core.run.Study(params=None, **instances)

</>
Bases
ivory.core.run.Task ivory.core.run.Run ivory.core.base.CallbackCaller ivory.core.base.Creator ivory.core.base.Base ivory.core.collections.Dict

Study class create a parent run to manage hyperparameter tuning.

Parameters
  • params (optional) — Parameter dictionary to create this instance.
  • **instances — Member instances. Key is its name and value is the member instance.
Attributes
  • dict —
  • id (str) — Instance ID given by MLFlow Tracking.
  • mode —
  • name (str) — Instance name.
  • params (dict, optional) — Parameter dictionary that is used to to create this instance.
  • source_name (str) — Name of the YAML parameter file that is used to create this instance.
Methods
  • chain(params, use_best_param, **kwargs) (Run) — Makes a chain iterator.</>
  • create_callbacks() — Creates callback functions and store them in a dictionary.</>
  • create_instance(instance_name, args, name, **kwargs) — Creates an member instance of a Run according to arguments.</>
  • create_params(args, name, **kwargs) (dict, dict) — Returns a tuple of (parameter dictionary, update dictionary).</>
  • create_run(args, **kwargs) (Run) — Create a nested run according to arguments</>
  • load(directory) (dict(str: any)) — Loads member instances.</>
  • load_state_dict(state_dict) — Loads a state dictionary to all of member instances.</>
  • optimize(suggest_name, **kwargs) — Performs parameter optimizations using Optuna.</>
  • product(params, repeat, **kwargs) (Run) — Makes a product iterator.</>
  • save(directory) — Saves member instances.</>
  • set_tracker(tracker, name) — Sets tracker for tracking.</>
  • start(mode) — Starts traing and/or test.</>
  • state_dict() (dict) — Returns a state dictionary for all of member instances.</>
method

create_params(args=None, name='run', **kwargs) → (dict, dict)

</>

Returns a tuple of (parameter dictionary, update dictionary).

The parameter dictionary is deeply copied from original one, then updated according to the arguments. The update dictionary includes updated parameter only.

Parameters
  • args (dict, optional) — Update dictionary.
  • name (str, optional) — Run class name in lower case.
  • **kwargs — Additional update dictionary.
Examples

Use args for parameters including dots:

params, update = experiment.create_params(
    {'hidden_sizes.0': 100}, fold=3
)

The params is the full parameter dictionary, while the update is a part of params, i.e., update = {'hidden_sizes.0': 100, 'fold': 3}.

method

create_instance(instance_name, args=None, name='run', **kwargs)

</>

Creates an member instance of a Run according to arguments.

Parameters
  • instance_name (str) — Name of a member instance to create.
  • args (dict, optional) — Update dictionary.
  • name (optional) — Run class name in lower case.
  • **kwargs — Additional update dictionary.
Returns

Created instance. The parameter for this instance is the returned directory from the create_params() function.

method

create_callbacks()

</>

Creates callback functions and store them in a dictionary.

method

set_tracker(tracker, name)

</>

Sets tracker for tracking.

By setting a tracker, a Run instance can be a run of MLFlow Tracking at the same time. MLFlow Tracking gives the Run ID and name for this instance.

Parameters
  • tracker (Tracker) — Tracker instance.
  • name (str) —
method

start(mode='train')

</>

Starts traing and/or test.

Parameters
  • mode (str, optional) — Mode name: 'train', 'test', or 'both'.
method

state_dict() → dict

</>

Returns a state dictionary for all of member instances.

method

load_state_dict(state_dict)

</>

Loads a state dictionary to all of member instances.

Parameters
  • state_dict (dict) — state dictionary for all of member instances.
method

save(directory)

</>

Saves member instances.

Parameters
  • directory (str) — Directory where member instances are saved.
method

load(directory) → dict(str: any)

</>

Loads member instances.

Parameters
  • directory (str) — Directory where member instances have been saved.
method

create_run(args, **kwargs)

</>

Create a nested run according to arguments

Parameters
  • args (dict, optional) — Update dictionary.
  • **kwargs — Additional update dictionary.
Returns (Run)

Created nested Run instance.

generator

product(params=None, repeat=1, **kwargs) → Run

</>

Makes a product iterator.

This iterator returns runs from cartesian product of input parameters.

Parameters
  • params (dict, optional) — Parameter range. Key is a parameter name and value is an iterable of parameter's value.
  • repeat (int, optional) — Number of repeatation.
  • **kwargs — Additional parameter range.
See Also

Product section in Multiple Runs Tutorial

generator

chain(params=None, use_best_param=True, **kwargs) → Run

</>

Makes a chain iterator.

This iterator returns runs from the first input paramter until it is exhausted, then proceeds to the next parameter, until all of the parameters are exhausted. Other parameters have default values if they don't be specified by additional key-value pairs.

Parameters
  • params (dict, optional) — Parameter range. Key is a parameter name and value is an iterable of parameter's value. use_best_param: If True (default), the parameter that got the best score is used during the following iterations.
  • use_best_param (bool, optional) —
  • **kwargs — Additional parameter range.
See Also

Chain section in Multiple Runs Tutorial

method

optimize(suggest_name='', **kwargs)

</>

Performs parameter optimizations using Optuna.

Parameters
  • suggest_name (str, optional) — Name of suggest function.
  • **kwargs — Key-iterable pairs for parametric optimization.
See Also

Hyperparameter Tuning in Tutorial