[Proposal] Mark some functions & attributes of the Env API as optional

[Kallinteris-Andreas]

Proposal

current API

The current Env API contains:
Methods

• Env.step()
• Env.reset()
• Env.render()
• Env.close()

Attributes

• Env.action_space
• Env.observation_space
• Env.metadata
• Env.render_mode
• Env.spec
• Env.unwrapped
• Env.np_random

but technically, the only "essential" ("essential" as in minimum every environment must implement to be learning compatible) parts of the API are:

Methods

• Env.step()
• Env.reset()

Attributes

• Env.action_space
• Env.observation_space
• Env.spec
• Env.unwrapped

Proposed API

my proposal is simply marked some parts of the API as optional

Methods

• Env.step()
• Env.reset()
• Env.render() (OPTIONAL: for rendering the environment)
• Env.close() (OPTIONAL: for rendering the environment)

Attributes

• Env.action_space
• Env.observation_space
• Env.metadata (OPTIONAL: for rendering the environment)
• Env.render_mode (OPTIONAL: for rendering the environment)
• Env.spec (TECHNICALLY OPTIONAL: for registering the environment)
• Env.unwrapped
• Env.np_random (TECHNICALLY OPTIONAL: only for stochastic environments)

or alternatively presented as:
Core API Methods & Attributes

• Env.step()
• Env.reset()
• Env.action_space
• Env.observation_space
• Env.spec
• Env.unwrapped

Render extension API Methods & Attributes

• Env.render()
• Env.close()
• Env.metadata
• Env.render_mode

other API Methods & Attributes

• Env.np_random

notes

1. I do not care how it is presented, I just propose some parts of the API to be optional.
   1.1 a proposed implementation would be to add variables in Env like supports_getset_state_API: bool = False and that could be overwritten by the Env developer
2. This does not have to be included in the 1.0 release, it could be in 1.1 or 1.2
3. The implementation of not should be to simply raise NotImplementedError
4. Possible API extensions should be implemented (when it makes sense) in gymnasium and pettingzoo
5. We should a mechanism for user definable extensions
6. Things like GoalEnv_observations and MOEnv_rewards could be possibly implemented as extensions to main API???

Downsides

1. check_env() would have to be more complex
2. possible complexity increases I can not foresee

Motivation

This would make extending the API a lot easier since, it would not be a requirement for all the environments to implement those extensions.

Example #94, #737:

state_clone_restrore extension API Methods & Attributes

• clone_state()
• restore_state()

Pitch

No response

Alternatives

Technically some parts of the API are pseudo optional now anyway, like the "Render API" where unless a user calls .render() on an environment, no error is generated.

Additional context

No response

Checklist

• I have checked that there is no similar issue in the repo

[jamartinh]

I agree @Kallinteris-Andreas , it is essential that this API be effective for research purposes which I think WAS and IS the purpose and not a production ready one with all the subtle things of a professional software engineering project.

As a user, I expect, stability, simplicity and no code breaks, plus improvements that does not break research nor adaptation of past experiments relaying on it.

The reproducibility and stabilization of API should be a priority, this was the reason of the Gym popularity because it favoured standardization and reproducibility without pain.

[pseudo-rnd-thoughts]

I'm just looking through the current list of issues and saw this again. @Kallinteris-Andreas Do you remember how you were interested in achieving this? Was it primarily documentation or actual code changes?