Add serverless guide with function template example: hamiltonian simu…

[frankharkins]

Continuation of #2276

[qiskit-bot]

One or more of the following people are relevant to this code:

• @jenglick
• @pandasa123

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[garrison]

This will close #2242 when it is merged.

[garrison]

I opened #2302 since I don't have permission to push to this repository.

[abbycross]

I recommend we rename the file something more human-readable, like /serverless-function-template

[pandasa123]

@frankharkins, @garrison, @jenglick I'd recommend adding two things:

1. Handling SIGTERM to clean up gracefully, if a user decides to cancel their workload, Example below:

import traceback
import signal
from qiskit_serverless import save_result

class FunctionTemplate:

    def signal_handler(self, signum, frame):
        """Handle termination signals."""
        signame = signal.Signals(signum).name
        logger.info("Received %s signal, shutting down...", signame)
        for job in self._jobs:
            try:
                job.cancel()
            except Exception as exc:
                # The cancel will give a RuntimeInvalidStateError if the job has already
                # finished, but it's more efficient to always cancel than to check for status first.
                if not isinstance(exc, RuntimeInvalidStateError):
                    logger.error("Unable to cancel Qiskit Runtime job %s", job.job_id())
        self._session.close()


class Runner:
    def run(self, arguments: dict) -> dict:
        try:
            func = FunctionTemplate(**arguments)
            signal.signal(signal.SIGTERM, func.signal_handler)
            return func.run()
        except Exception:
            save_result(traceback.format_exc())
            raise

2. In job.result(), adding a metadata property to output that neatly lists arguments passed in (akin to Runtime)

# job.result()

{
     'twoqubit_depth': ...,
     'metadata': {
          'hamiltonian': ...,
          'backend_name': ...,
          ... 
     }
}

[garrison]

2. In job.result(), adding a metadata property to output that neatly lists arguments passed in (akin to Runtime)

This is a great idea.

1. Handling SIGTERM to clean up gracefully

@pandasa123, It's not entirely clear to me how to integrate this code snippet with the function. How are the two classes to be used?

But also: I wonder if it might be better for serverless to expose an abstraction that does this, rather than people needing to copy and paste a snippet of code like this.