add cloud simulator example (#265)

* cloud simulator usage example

* update to qm-saas 1.1.1

* specify qm-saas version

* fixes to comments

* black

Tutorials/intro-to-simulation/cloud-simulator-example.py

@@ -0,0 +1,73 @@
+from qm import QuantumMachinesManager, SimulationConfig
+from qm.qua import play, program
+from qm_saas import QoPVersion, QmSaas
+
+# for qm-saas version 1.1.1
+
+# Define quantum machine configuration dictionary
+config = {
+    "version": 1,
+    "controllers": {
+        "con1": {
+            "analog_outputs": {
+                1: {"offset": +0.0},
+            },
+        }
+    },
+    "elements": {
+        "qe1": {
+            "singleInput": {"port": ("con1", 1)},
+            "intermediate_frequency": 5e6,
+            "operations": {
+                "playOp": "constPulse",
+            },
+        },
+    },
+    "pulses": {
+        "constPulse": {
+            "operation": "control",
+            "length": 1000,  # in ns
+            "waveforms": {"single": "const_wf"},
+        },
+    },
+    "waveforms": {
+        "const_wf": {"type": "constant", "sample": 0.2},
+    },
+}
+
+# ======================================================================================================================
+# Description: Use default host and port for the QOP simulator. Email and password are mandatory.
+#              Using the context manager ensures them simulator instance is closed properly.
+# ======================================================================================================================
+
+# These should be changed to your credentials.
+email = "john.doe@mail.com"
+password = "Password_given_by_QM"
+
+# Initialize QOP simulator client
+client = QmSaas(email=email, password=password)
+
+# Choose your QOP version (QOP2.x.y or QOP3.x.y)
+# if you choose QOP3.x.y, make sure you are using an adequate config.
+version = QoPVersion.v2_2_2
+
+with client.simulator(version=version) as instance:  # Specify the QOP version
+    # Initialize QuantumMachinesManager with the simulation instance details
+    qmm = QuantumMachinesManager(
+        host=instance.host, port=instance.port, connection_headers=instance.default_connection_headers
+    )
+
+    # Define a QUA program
+    with program() as prog:
+        play("playOp", "qe1")
+
+    # Open quantum machine with the provided configuration and simulate the QUA program
+    qm = qmm.open_qm(config)
+    job = qm.simulate(prog, SimulationConfig(int(1000)))
+
+    # Retrieve and handle simulated samples
+    samples = job.get_simulated_samples()
+    print("Test passed")
+
+# analysis of simulation
+# do something with samples

Tutorials/intro-to-simulation/readme.md

@@ -5,41 +5,57 @@ slug: ./
 id: index
 ---
 
-This example shows usage of the hardware simulator. The simulator mimics the output of the hardware, 
-with its exact timing and voltage level, following the compilation of QUA to the FPGA's low-level. 
-It is a useful tool for predicting and debugging the outcome of a QUA program. 
-Read more on the simulator, and it's capabilities in the [QUA docs](https://qm-docs.qualang.io/guides/simulator).
-
-The Examples
+This script intro-to-simulation.py shows usage of the hardware simulator. The simulator mimics the output of the
+hardware,
+with its exact timing and voltage level, following the compilation of QUA to the FPGA's low-level.
+It is a useful tool for predicting and debugging the outcome of a QUA program.
+Read more on the simulator, and it's capabilities in
+the [QUA docs](https://docs.quantum-machines.co/latest/docs/Guides/simulator/).
+
+In addition, the script cloud-simulator-example.py demonstrates the usage
+of [QM cloud simulator](https://docs.quantum-machines.co/latest/docs/Guides/qm_saas_guide/), enabling to run the HW
+simulator
+on virtual instances (and doesn't require access to actual HW).
+
+The intro-to-simulation Examples
 ============
 
-The following script gives three examples for the usage of the simulator in the QOP.
+The script gives three examples for the usage of the simulator in the QOP.
 
-First and second exampled
+First and second examples
 -------------
 
-The first and second demonstrates basic usage od the simulator. Note that the simulation is done via the QuantumMachinesManager (qmm) object. 
-The simulation function is given the configuration, the program and the `SimulationConfig` instance. The last sets the duration for the 
-simulation. i.e. how many clock cycles should the simulator simulate. The outcome of the simulator is a `job` object. 
+The first and second examples demonstrate basic usage of the simulator. Note that the simulation is done via the
+QuantumMachinesManager (qmm) object.
+The simulation function is given the configuration, the program and the `SimulationConfig` instance. The last sets the
+duration for the
+simulation. i.e. how many clock cycles should the simulator simulate. The outcome of the simulator is a `job` object.
 
-The examples also demonstrate how to obtain and plot the simulated output of the hardware. Finally, the first example also demonstrates
-how the simulator can simulate saving variables to a stream, as would occur in the real hardware. 
+The examples also demonstrate how to obtain and plot the simulated output of the hardware. Finally, the first example
+also demonstrates
+how the simulator can simulate saving variables to a stream, as would occur in the real hardware.
 
 Third Example
 ==============
 
 The third example demonstrates a slightly more advanced usage. It shows how a loop-back connection can be defined,
-to simulate acquisition and demodulation of ADC signals. In the example, a connection from analog output 1 of controller 1
-is connected to analog input 1 of controller 1. The example also shows that the demodulation and adc input can be simulated
-and saved to the stream processing, which later can be fetched and analyzed. It is important to note that the data will only
-be available if the simulation duration was long enough to simulate it. In the current example, to "fill" the buffer in the stream processing,
-the simulation must simulate the entire program with all the loop's iterations.  
+to simulate acquisition and demodulation of ADC signals. In the example, a connection from analog output 1 of controller
+1
+is connected to analog input 1 of controller 1. The example also shows that the demodulation and adc input can be
+simulated
+and saved to the stream processing, which later can be fetched and analyzed. It is important to note that the data will
+only
+be available if the simulation duration was long enough to simulate it. In the current example, to "fill" the buffer in
+the stream processing,
+the simulation must simulate the entire program with all the loop's iterations.
 
 Fourth Example
 =============
 
-The fourth example demonstrates a simulation of a multi-controllers system. This is done by specifying the connectivity between the different controllers.
-This is important since The exact timing of multi-controllers operations is dependent on that connectivity configuration.
+The fourth example demonstrates a simulation of a multi-controllers system. This is done by specifying the connectivity
+between the different controllers.
+This is important since The exact timing of multi-controllers operations is dependent on that connectivity
+configuration.
 In the example we use a tool to create the controllers' connections in the format that is required by the simulator.
 The tool is available in our (very useful) repo [py-qua-tools](https://github.com/qua-platform/py-qua-tools).