ENH: Review API for outcomes and payoffs

[tturocy]

The approach we currently take for payoffs for outcomes is awkward, and also generally inconsistent with the rest of the interface. Give this a thorough review and revision.

[edwardchalstrey1]

Was going to open a new issue but commenting here instead: Add a function or attribute to easily get payoff values from Outcome object

Another open issue #181

Just came across this and was confused. To get a payoff for a particular Player from an Outcome attached to a terminal node, you currently have to do:

outcome.__getitem__(player.label)

Would it make more sense to have something like:

outcome.payoffs

which could return perhaps a dictionary with player label keys and integer values?

Or maybe a function like:

outcome.payoff(player)

[tturocy]

Yes, this is an outstanding item which requires some thinking.

The downside of having payoff is that it's very verbose, and this is a very common operation.

The crux of the design challenge (as I see it) is the following. Focusing for the moment on strategic form games (similar comments would apply to extensive games):

• Many users will think of a strategic form game as just being a collection of payoff matrices/payoff tensor. The notation we have for this right now facilitates that.
• Gambit however thinks of a strategic form game as a matrix/tensor of outcomes, and outcomes have as a property a mapping of players to payoffs.

The second is in our view more careful and more powerful. However, for many use cases it's overkill, because one pure strategy profile equals one outcome by definition.

I have been thinking the problem is in defining __getitem__ on Game as we do. That has the benefit of treating strategic form games as if they're matrices/tensors - but doesn't square fully with games which are extensive games.

A more clear approach might be to have something like:

• game.outcomes[profile] returns the outcome associated with playing profile. (But does this overload cause problems with wanting to access outcomes by text label, so maybe we need a different syntax?)
• game.payoffs[profile] returns the payoffs associated with playing profile

Then we could do game.outcomes[profile].payoffs which would be the same as game.payoffs[profile] in terms of returning payoffs, but with the first syntax you could then do assignment.

I'm not very sure about a lot of this though. We need to test various potential ideas experimentally against tutorials/example codes to see how they play out in practice.

Perhaps it would make sense to close out these two issues (which are both "squishy") and move this to a discussion thread instead for development and clarification?