Sessions changes

[beckykd]

closes #124

reviewed prematurely. should have sign off from SMEs

[jyu00]

I think we can take this opportunity to restructure the page a bit, so topics related to how session works are grouped together. For example:

# The mechanics of sessions

For each backend, the first job in the session waits its turn in the queue normally. 
When the first job starts running, the session becomes active. 
Jobs within an active session take priority over any other queued jobs (but not system jobs such as calibration). 

A quantum processor still executes one job at a time. Therefore, jobs that belong to a session still need to wait for their turn if one is already running.

<the following paragraph is taken from "How long a session stays active">

The length of time a session is active is controlled by the maximum session timeout (`max_time`) value 
and the interactive timeout value (ITTL, or interactive time to live). 
The `max_time` timer starts when the session becomes active - that is, when the first job runs, not when it is queued. 
It does not stop if a session becomes inactive. The ITTL timer starts each time a session job finishes.

## Maximum session timeout

...

## Interactive timeout value

...

## What happens when a session ends

... 

## Querying session status

You can query the status of a session using `session.status()`. 

Session status can be one of the following:

- `Pending`: Session has not started or has been deactivated. 
- `In progress, accepting new jobs`: session is active and accepting new jobs.
- `In progress, not accepting new jobs`: session is active but not accepting new jobs. Job submission to the session will be rejected, but outstanding session jobs will run to completion. The session will be automatically closed once all jobs finish. 
- `Closed`: Session maximum timeout value has been reached, or session was explicitly closed.

## Summary

- Jobs within an active session take priority over other queued jobs
- A session becomes active when its first job starts running
- A session stays active until
  - Its maximum timeout value is reached. In this case all queued jobs are cancelled, but running jobs would finish. 
  - Its interactive timeout value is reached. In this case the session is deactivated but can be resumed when the next job starts running. 
  - The session is closed or cancelled by the user
- `session.status()` can be used to query session status. `session.details()` can be used to query the timeout values. 

# Different ways of using session

<This section should be moved to "run jobs in a session" with code example, but that can be later>

Sessions can be used for iterative or batch execution.

...

[beckykd]

I think we can take this opportunity to restructure the page a bit, so topics related to how session works are grouped together. For example:

I'm totally on board with that. Do you want me to get rid of the session details section? I see that it's mentioned in the summary, so I'm going to put the summary after the session details section

[jyu00]

I'm totally on board with that. Do you want me to get rid of the session details section? I see that it's mentioned in the summary, so I'm going to put the summary after the session details section

Session details section is still needed, since that's how people find out about the TTLs. I was debating if we should move everything code related to Run jobs in a session and keep this page as concept only. What do you think?

[beckykd]

Summary

...

• A session stays active until
  • Its maximum timeout value is reached. In this case all queued jobs are cancelled, but running jobs would finish.
  • Its interactive timeout value is reached. In this case the session is deactivated but can be resumed when the next job starts running.
  • The session is closed or cancelled by the user

It seems like there's a 4th way a session is closed: The context manager is exited and all session jobs are finished.

Right? Because it will be ended immediately after the jobs are done without the session reaching the max timeout value or reaching the interactive timeout value.

[jyu00]

Summary

...

• A session stays active until

  • Its maximum timeout value is reached. In this case all queued jobs are cancelled, but running jobs would finish.
  • Its interactive timeout value is reached. In this case the session is deactivated but can be resumed when the next job starts running.
  • The session is closed or cancelled by the user

It seems like there's a 4th way a session is closed: The context manager is exited and all session jobs are finished.

It's the same as calling session.closed(). We can change the wording to say something like

- The session is closed or cancelled. This can be done using the corresponding methods or upon exiting a session context.

[beckykd]

Session details section is still needed, since that's how people find out about the TTLs. I was debating if we should move everything code related to Run jobs in a session and keep this page as concept only. What do you think?

I think that makes sense - I can rearrange.

[beckykd]

"Session maximum execution time" in max-execution-time can just go away.

In that section we tell them how to change the maximum execution time though. Don't we still want that? I could delete the Defaults section if we really don't want to tell them (https://docs.quantum-computing.ibm.com/run/max-execution-time#defaults)

We tell them how to set mac time in run-jobs-in-session, so we deleted this section, including the defaults.

[jyu00]

Thank you @beckykd!