Add quickstart guide and concepts, issue #108

[vfdev-5]

I propose to address the issue 108 in multiple PRs. Here is the first one with "Quickstart" notes.
Other notes can be added later.

@alykhantejani @jasonkriss could you review this note, please ?

[alykhantejani]

Looks great @vfdev-5! Thanks!

[vfdev-5]

@alykhantejani thanks for the comments! I updated the text according to your comments and added a "(!) Note" as here about "passing other args to handlers".

[vfdev-5]

Added basic concepts

[alykhantejani]

Thanks @vfdev-5!

[vfdev-5]

@alykhantejani do you still want me to integrate your comments, as you merged the branch ?

[alykhantejani]

@vfdev-5 if you don't mind, it was very minor though so didn't want to delay merging this. I need to get the docs ready to be hosted and start building the conda tar + wheels for release

[vfdev-5]

@alykhantejani no problems, go ahead with your tasks. Thanks!

[jasonkriss]

@vfdev-5 Thanks a lot! These both look great. I think the only other thing I would maybe add is a mention in the "State" section of "concepts" about the ability to add arbitrary data to the state object in handlers.

[vfdev-5]

@jasonkriss yes, this is an important point that completly missed, thanks! At the begining I thought we would fix the scope of the state, especially when talking about engine checkpointing and restoration. As it is more or less fixed, I can add this in another PR.

[vfdev-5]

@jasonkriss rethinking about what you said:

the ability to add arbitrary data to the state object in handlers.

Do you talk about this (same with handler functions):

import numpy as np
from torch.utils.data import DataLoader
from ignite.engines import Engine

def update(engine, batch):
    engine.state.new_attribute = 12345

engine = Engine(update)

data = np.arange(100)
data = DataLoader(data, batch_size=10)
state = engine.run(data, max_epochs=2)

for attr, value in state.__dict__.items():
    print(attr, value)

with the output:

iteration 20
epoch 2
max_epochs 2
batch ...

new_attribute 12345

output None
dataloader <torch.utils.data.dataloader.DataLoader object at 0x7f124b81c518>
metrics {}

if yes, we can add a new attribute to state, engine and whatever object...

I thought also to add the method __repr__ to the class State to visualize easily its variable content:

def __repr__(self):
    s = "State:\n"
    for attr, value in self.__dict__.items():
        value = value if not torch.is_tensor(value) else "{} {}".format(type(value), value.shape)
        s += "\t{}: {}\n".format(attr, value)
    return s

@alykhantejani @jasonkriss what do you think about ?

[vfdev-5]

@jasonkriss can you please take a look on the previous comment ?

[jasonkriss]

Sorry for the delay on this @vfdev-5 . The __repr__ sounds like a good idea to me. What do you think @alykhantejani.

@vfdev-5 Did you have another question there? I'm not 100% sure I understood.

[vfdev-5]

@jasonkriss no problem, my question was actually about your comment:

the ability to add arbitrary data to the state object in handlers.

Did you talk about this ?

import numpy as np
from torch.utils.data import DataLoader
from ignite.engines import Engine

def update(engine, batch):
    engine.state.new_attribute = 12345

engine = Engine(update)

data = np.arange(100)
data = DataLoader(data, batch_size=10)
state = engine.run(data, max_epochs=2)

for attr, value in state.__dict__.items():
    print(attr, value)

[jasonkriss]

yep exactly. Setting that new_attribute is what i was talking about. For me, it usually happens in the handlers but setting it in the update_fn is completely valid as well.

[vfdev-5]

Right, but actually this is not only ability of state but whatever object in python... So, you meant to underline that user can use state to add new attributes ?
I mean, user is not restrcited to use engine as a storage of new attributes as well...

[alykhantejani]

@vfdev-5 yes, I think we want to note that this is the preferred way to pass state between handlers.

When we get to serializing the engine + state, we may have to re-visit this. But for now I think if we establish this user pattern it will be easier

[jasonkriss]

@alykhantejani nailed it. I should have made that more clear. The important point is not that you can attach attributes to state, it's that it is the preferred/recommended way of passing information between handlers. On the flip side, attaching attributes to the engine is not something we want to recommend. You can do it. But it's not the recommended approach.

[vfdev-5]

Talking about attaching user attributes in state, probably, user would like also to initialize his/her attribute before calling it in handler or update function (same as for metrics for example). However, today, the state is None before running the engine...

[jasonkriss]

I've been using this feature successfully since we added it. If my attribute is a list or a dict, I will initialize it if its None the first time the handler is called. If you want to, you could also have an initialize handler that you attach to the start event. Anything more than that would be adding too much complexity IMO. I think the goal of the state object is to be a flexible, low-cost abstraction for passing around ad hoc information.

[vfdev-5]

Sure, I agree with what you say. However, for me State is something that describes engine, so why state is None, when engine is initialized and possibly has handlers etc but not yet run... Maybe, we can initialize it on engine creation and complete with data, metrics etc on run()