### GaussianSimulator example: squeezing, interferometer, and measurement

Source: https://piquasso.readthedocs.io/en/stable/simulators/gaussian.html

Shows how to create a Gaussian simulator, build a program with squeezing, an interferometer, and particle-number measurement, then execute it with 100 shots. The example uses a 5-mode setup and a random unitary from scipy.stats.unitary_group.

```python
import numpy as np
import piquasso as pq

from scipy.stats import unitary_group

d = 5

U = unitary_group.rvs(d)

with pq.Program() as program:
    pq.Q() | pq.Vacuum()

    for i in range(5):
        pq.Q(i) | pq.Squeezing(r=i*0.1)

    pq.Q(all) | pq.Interferometer(U)

    pq.Q(all) | pq.ParticleNumberMeasurement()

simulator = pq.GaussianSimulator(d=5)
result = simulator.execute(program, shots=100)

```

--------------------------------

### Install Piquasso via pip

Source: https://piquasso.readthedocs.io/en/stable/_sources/installation.rst.txt

Standard installation command for the Piquasso library from PyPI.

```bash
pip install piquasso
```

--------------------------------

### Create a program using an explicit instruction list

Source: https://piquasso.readthedocs.io/en/stable/instructions/index.html

This example demonstrates initializing a pq.Program with a list of instructions and executing it using the GaussianSimulator.

```python
import numpy as np
import piquasso as pq

program = pq.Program(
   instructions=[
      pq.Vacuum(),
      pq.Squeezing(r=0.5).on_modes(0),
      pq.Beamsplitter(theta=np.pi / 4).on_modes(0, 1),
   ]
)

result = pq.GaussianSimulator(d=2).execute(program)
```

--------------------------------

### PostSelectPhotons example with photon_counts=(1, 0)

Source: https://piquasso.readthedocs.io/en/stable/instructions/measurements.html

Example usage of PostSelectPhotons. Builds a program with state vectors, phase shifters, beamsplitters, and a post-selection on photon counts (1,0) on modes 1 and 2.

```python
with pq.Program() as program:
    pq.Q(all) | pq.StateVector([0, 1, 0]) * np.sqrt(0.2)
    pq.Q(all) | pq.StateVector([1, 1, 0]) * np.sqrt(0.3)
    pq.Q(all) | pq.StateVector([2, 1, 0]) * np.sqrt(0.5)

    pq.Q(0) | pq.Phaseshifter(np.pi)

    pq.Q(1, 2) | pq.Beamsplitter(np.pi / 8)
    pq.Q(0, 1) | pq.Beamsplitter(1.1437)
    pq.Q(1, 2) | pq.Beamsplitter(-np.pi / 8)

    pq.Q(1, 2) | pq.PostSelectPhotons(photon_counts=(1, 0))

```

--------------------------------

### Install Piquasso with JAX support

Source: https://piquasso.readthedocs.io/en/stable/_sources/installation.rst.txt

Installs Piquasso along with the necessary dependencies for JAX-based workflows.

```bash
pip install "piquasso[jax]"
```

--------------------------------

### Create instruction example

Source: https://piquasso.readthedocs.io/en/stable/instructions/preparations.html

Use to create a particle on a mode. Applies a creation operator and normalizes the state. Only valid for FockState and PureFockState.

```python
with pq.Program() as program:
    pq.Q(1) | pq.Create()
    pq.Q(2) | pq.Create()
    ...

```

--------------------------------

### Fock-state example: PureFockSimulator with Kerr

Source: https://piquasso.readthedocs.io/en/stable/_sources/states/index.rst.txt

Demonstrates using a Fock-space simulator with a truncated Fock basis controlled by Config(cutoff=...). The example prints the state type and fock_probabilities.

```python
import piquasso as pq

with pq.Program() as program:
   pq.Q() | pq.Vacuum()
   pq.Q(0) | pq.Displacement(r=0.4)
   pq.Q(0) | pq.Kerr(xi=0.05)

simulator = pq.PureFockSimulator(
   d=1,
   config=pq.Config(cutoff=8),
)
result = simulator.execute(program)

state = result.state

print(type(state))
print(state.fock_probabilities)
```

--------------------------------

### DensityMatrix preparation example

Source: https://piquasso.readthedocs.io/en/stable/instructions/preparations.html

Use to create a density matrix element from bra and ket vectors. Only valid for FockState. The coefficient defaults to 1.0.

```python
with pq.Program() as program:
    pq.Q() | (
        0.2 * pq.DensityMatrix(ket=(1, 0, 1), bra=(2, 1, 0))
        + 0.3 * pq.DensityMatrix(ket=(2, 0, 1), bra=(0, 1, 1))
        ...
    )
    ...

```

--------------------------------

### Install Piquasso with TensorFlow support

Source: https://piquasso.readthedocs.io/en/stable/_sources/installation.rst.txt

Installs Piquasso along with the necessary dependencies for TensorFlow-based workflows.

```bash
pip install "piquasso[tensorflow]"
```

--------------------------------

### PureFockSimulator example: squeezing, beamsplitter, Kerr

Source: https://piquasso.readthedocs.io/en/stable/simulators/fock.html

Shows how to instantiate a PureFockSimulator with d=2 and a cutoff of 7, then execute a program that applies squeezing, a beamsplitter, and a Kerr gate. The program uses the piquasso API with pq.Q and pq.Program.

```python
import numpy as np
import piquasso as pq


with pq.Program() as program:
    pq.Q(all) | pq.Vacuum()

    pq.Q(0)   | pq.Squeezing(r=0.1)
    pq.Q(1)   | pq.Squeezing(r=0.2)

    pq.Q(0, 1) | pq.Beamsplitter(theta=np.pi / 3)

    pq.Q(0) | pq.Kerr(xi=0.05)

simulator = pq.PureFockSimulator(d=2, config=pq.Config(cutoff=7))
result = simulator.execute(program)
```

--------------------------------

### Perform Particle-Resolved Gaussian Boson Sampling

Source: https://piquasso.readthedocs.io/en/stable/_sources/tutorials/gaussian-boson-sampling.ipynb.txt

This example demonstrates how to set up a Gaussian state with squeezing and an interferometer, then perform a particle number measurement using Piquasso.

```python
import piquasso as pq
import numpy as np

from scipy.stats import unitary_group


shots = 1000
squeezings = np.concatenate([0.25 * np.ones(5), np.zeros(5)])
d = len(squeezings)
unitary = unitary_group.rvs(d)

with pq.Program() as program:
    for i in range(d):
        pq.Q(i) | pq.Squeezing(squeezings[i])

    pq.Q() | pq.Interferometer(unitary)
    pq.Q() | pq.ParticleNumberMeasurement()

simulator = pq.GaussianSimulator(d=d)

result = simulator.execute(program, shots=shots)

print(result.samples)
```

--------------------------------

### Gaussian State Simulation Example

Source: https://piquasso.readthedocs.io/en/stable/_sources/index.rst.txt

Prepares a Gaussian state, applies displacement and beamsplitter operations, and performs a homodyne measurement using the GaussianSimulator.

```python
import numpy as np
import piquasso as pq

with pq.Program() as program:
   pq.Q() | pq.Vacuum()
   pq.Q(0) | pq.Displacement(r=np.sqrt(2), phi=np.pi / 4)
   pq.Q(0, 1) | pq.Beamsplitter(theta=np.pi / 3, phi=np.pi / 2)
   pq.Q(0) | pq.HomodyneMeasurement(phi=0)

simulator = pq.GaussianSimulator(d=3)
result = simulator.execute(program, shots=10)

print(result.samples)
```

--------------------------------

### PureFockSimulator example: prepare and execute a fermionic program

Source: https://piquasso.readthedocs.io/en/stable/experimental/fermionic.html

Creates a pure fermionic Fock simulator with 4 modes and a cutoff of 5, then executes a program that prepares a superposition of two Fock states and applies an interferometer. The resulting state is retrieved from the simulation result.

```python
U = scipy.stats.unitary_group.rvs(4)

with pq.Program() as program:
    pq.Q() | pq.StateVector([0, 0, 1, 1]) / np.sqrt(2)
    pq.Q() | pq.StateVector([1, 1, 0, 0]) / np.sqrt(2)
    pq.Q() | pq.Interferometer(U)

simulator = pq.fermionic.PureFockSimulator(
    d=4, config=pq.Config(cutoff=4 + 1)
)

state = simulator.execute(program).state
```

--------------------------------

### PureFockState

Source: https://piquasso.readthedocs.io/en/stable/states/fock.html

Documentation for the PureFockState class, including its constructor, methods, properties, and usage example.

```APIDOC
## PureFockState

### Description
Represents a simulated pure Fock state, storing only the state vector rather than the full density matrix. It provides methods to access Fock basis coefficients, compute probabilities, and perform state operations.

### Constructor
`PureFockState(d: int, connector: BaseConnector, config: Config | None = None)`

### Parameters
- **d** (int) - The number of modes.
- **connector** (BaseConnector) - Instance containing calculation functions.
- **config** (Config) - Instance containing constants for the simulation.

### Methods

#### reset()
Resets the Fock state to a vacuum state.

#### reduced(modes: Tuple[int, ...]) -> FockState
Reduces the state to a subsystem corresponding to the specified modes.

#### get_particle_detection_probability(occupation_number: ndarray) -> float
Returns the particle number detection probability using the occupation number specified as a parameter.

**Parameters:**
- **occupation_number** (tuple) - Tuple of natural numbers representing the number of particles in each mode.

**Returns:**
- The probability of detection (float).

#### normalize()
Normalizes the state to have norm 1.

#### validate()
Validates the represented state. Raises `InvalidState` if the norm of the state vector is not close to 1.0.

#### quadratures_mean_variance(modes: Tuple[int, ...], phi: float = 0) -> Tuple[float, float]
Calculates the mean and variance of the quadrature operators for a single qumode state.

**Parameters:**
- **phi** (float) - The rotation angle. Default is 0 (position operator). For phi = pi/2, momentum operator.
- **modes** (tuple of int) - The corresponding mode at which the mean of the quadratures are calculated.

**Returns:**
- A tuple containing the expectation value and the variance of the quadrature operator respectively.

#### mean_photon_number()
Returns the mean photon number.

#### variance_photon_number()
Returns the photon number variance.

#### copy() -> PureFockState
Returns an exact copy of this state.

#### get_purity()
Returns the purity of the Fock state.

#### fidelity(state: BaseFockState) -> float
Calculates the state fidelity between two quantum states.

**Parameters:**
- **state** - Either a `PureFockState` or a `FockState` to calculate fidelity against.

**Returns:**
- The calculated fidelity (float).

### Properties
- **state_vector** - The state vector of the quantum state.
- **nonzero_elements** - The nonzero contributions to the state representation in Fock basis.
- **density_matrix** - The density matrix of the state in the truncated Fock space.
- **fock_probabilities** - The particle detection probabilities.
- **fock_probabilities_map** - The particle number detection probabilities in a map.
- **d** - The number of modes.

### Example
```
with pq.Program() as program:
    pq.Q() | pq.StateVector([0, 1]) / 2
    pq.Q() | pq.StateVector([0, 2]) / 2
    pq.Q() | pq.StateVector([1, 1]) / np.sqrt(2)

simulator = pq.PureFockSimulator(d=2, config=pq.Config(cutoff=3))
state = simulator.execute(program).state  # returns PureFockState instance

state[0, 1]  # returns 0.5
state[:, 1]  # returns [0.5, 0.70710678]
```
```

--------------------------------

### Create a Program with the with statement

Source: https://piquasso.readthedocs.io/en/stable/api/program.html

Use the with statement to add instructions to a Program. The example creates a vacuum state, applies squeezing to mode 0, and a beamsplitter to modes 0 and 1, then executes the program with a GaussianSimulator of dimension 5.

```python
import numpy as np
import piquasso as pq

with pq.Program() as program:
    pq.Q() | pq.Vacuum()

    pq.Q(0) | pq.Squeezing(r=0.5)

    pq.Q(0, 1) | pq.Beamsplitter(theta=np.pi / 4)

simulator = pq.GaussianSimulator(d=5)
result = simulator.execute(program)
```

--------------------------------

### FockSimulator example with squeezing, beamsplitter, attenuator, and Kerr gates

Source: https://piquasso.readthedocs.io/en/stable/simulators/fock.html

Creates a Fock simulator with cutoff 7 and executes a program that applies squeezing, beamsplitter, attenuator, and Kerr gates to two modes. The result is stored in `result`.

```python
import numpy as np
import piquasso as pq


with pq.Program() as program:
    pq.Q(all) | pq.Vacuum()

    pq.Q(0)   | pq.Squeezing(r=0.1)
    pq.Q(1)   | pq.Squeezing(r=0.2)

    pq.Q(0, 1) | pq.Beamsplitter(theta=np.pi / 3)

    pq.Q(0) | pq.Attenuator(theta=0.01)
    pq.Q(1) | pq.Attenuator(theta=0.02)

    pq.Q(0) | pq.Kerr(xi=0.05)

simulator = pq.FockSimulator(d=2, config=pq.Config(cutoff=7))
result = simulator.execute(program)
```

--------------------------------

### PassiveSimulator usage example

Source: https://piquasso.readthedocs.io/en/stable/simulators/passive.html

Demonstrates how to set up a program with a state vector, an interferometer, and a particle number measurement, then execute it using the PassiveSimulator.

```python
import numpy as np
import piquasso as pq

from scipy.stats import unitary_group

d = 5

U = unitary_group.rvs(d)

with pq.Program() as program:
    pq.Q() | pq.StateVector([1, 1, 1, 0, 0])

    pq.Q() | pq.Interferometer(U)

    pq.Q(all) | pq.ParticleNumberMeasurement()

simulator = pq.PassiveSimulator(d=5)
result = simulator.execute(program, shots=100)
```

--------------------------------

### Apply ParticleNumberMeasurement to all modes

Source: https://piquasso.readthedocs.io/en/stable/api/mode.html

Shows how to use the `all` keyword to apply an instruction to all modes. The example includes a `Squeezing` gate on modes 0 and 1, then a `ParticleNumberMeasurement` on all modes.

```python
with pq.Program() as program:
    pq.Q(0, 1) | pq.Squeezing(r=0.5)

    pq.Q(all) | pq.ParticleNumberMeasurement()
```

--------------------------------

### Generate and run a CVQNN program with Piquasso

Source: https://piquasso.readthedocs.io/en/stable/advanced/cvqnn.html

Creates a CVQNN program from random weights and executes it within a Piquasso Program context. The example generates weights for 10 layers and 5 modes, then builds the CVQNN layers and applies them after a series of displacement gates.

```python
import piquasso as pq

weights = pq.cvqnn.generate_random_cvqnn_weights(layer_count=10, d=5)

cvnn_layers = pq.cvqnn.create_program(weights)

with pq.Program() as program:
    for i in range(5):
        pq.Q(i) | pq.Displacement(r=0.1)

    pq.Q() | cvnn_layers

```

--------------------------------

### Run Boson Sampling with PassiveSimulator

Source: https://piquasso.readthedocs.io/en/stable/_sources/tutorials/boson-sampling.ipynb.txt

This example demonstrates how to run a Boson Sampling simulation using Piquasso's PassiveSimulator and Interferometer instruction. It creates a 7-mode program with an initial Fock state, applies a random unitary interferometer, performs particle number measurement, and prints 20 samples.

```python
import piquasso as pq

from scipy.stats import unitary_group

d = 7

interferometer_matrix = unitary_group.rvs(d)

with pq.Program() as program:
    pq.Q(all) | pq.NumberState([1, 1, 1, 0, 0, 0, 0])

    pq.Q(all) | pq.Interferometer(interferometer_matrix)

    pq.Q(all) | pq.ParticleNumberMeasurement()

simulator = pq.PassiveSimulator(d=d)

result = simulator.execute(program, shots=20)

print(result.samples)
```

--------------------------------

### Create and index a PureFockState with pq.PureFockSimulator

Source: https://piquasso.readthedocs.io/en/stable/states/fock.html

Creates a pure Fock state with a superposition of two Fock basis states, executes it with a PureFockSimulator using a cutoff of 3, and demonstrates indexing the resulting state to obtain Fock basis coefficients. The example shows that state[0, 1] returns 0.5 and state[:, 1] returns [0.5, 0.70710678].

```python
with pq.Program() as program:
    pq.Q() | pq.StateVector([0, 1]) / 2

    pq.Q() | pq.StateVector([0, 2]) / 2
    pq.Q() | pq.StateVector([1, 1]) / np.sqrt(2)

simulator = pq.PureFockSimulator(d=2, config=pq.Config(cutoff=3))
state = simulator.execute(program).state  # returns PureFockState instance

state[0, 1]  # returns 0.5
state[:, 1]  # returns [0.5, 0.70710678]
```

--------------------------------

### Build and execute a program with instructions

Source: https://piquasso.readthedocs.io/en/stable/instructions/index.html

Shows how to build a program by applying instructions to modes with pq.Q(...) | instruction syntax, including a Vacuum preparation, Displacement and Beamsplitter gates, and a ParticleNumberMeasurement, then execute it on a GaussianSimulator with 10 shots and print the samples.

```python
import numpy as np
import piquasso as pq

with pq.Program() as program:
   # Preparation
   pq.Q() | pq.Vacuum()

   # Gates
   pq.Q(0) | pq.Displacement(r=0.2)
   pq.Q(0, 1) | pq.Beamsplitter(theta=np.pi / 4)

   # Measurement
   pq.Q(all) | pq.ParticleNumberMeasurement()

simulator = pq.GaussianSimulator(d=2)
result = simulator.execute(program, shots=10)

print(result.samples)
```

--------------------------------

### TensorflowConnector gradient computation example

Source: https://piquasso.readthedocs.io/en/stable/advanced/connectors.html

Shows how to use the TensorflowConnector to compute gradients of a photonic circuit. Requires TensorFlow to be installed; otherwise an ImportError is raised. Non-deterministic operations like ParticleNumberMeasurement are non-differentiable, so use a deterministic attribute of the resulting state instead.

```python
import piquasso as pq
import tensorflow as tf

r = tf.Variable(0.43)

tensorflow_connector = pq.TensorflowConnector()

simulator = pq.PureFockSimulator(d=1, connector=tensorflow_connector)

with pq.Program() as program:
    pq.Q() | pq.Vacuum()

    pq.Q(0) | pq.Displacement(r=r)

with tf.GradientTape() as tape:
    state = simulator.execute(program).state

    mean = state.mean_photon_number()

gradient = tape.gradient(mean, [r])
```

--------------------------------

### Create GaussianSimulator and execute program

Source: https://piquasso.readthedocs.io/en/stable/_sources/tutorials/getting-started.ipynb.txt

Instantiate pq.GaussianSimulator with d=3 modes and pq.Config with hbar=2, then execute the program with shots=10 to obtain a result.

```python
# Creating the Gaussian simulator
simulator = pq.GaussianSimulator(d=3, config=pq.Config(hbar=2))

# Apply the program with 10 shots.
result = simulator.execute(program, shots=10)
```

--------------------------------

### Basic Piquasso JAX Integration

Source: https://piquasso.readthedocs.io/en/stable/tutorials/jax-example.html

Demonstrates initializing a PureFockSimulator with a JaxConnector to perform a quantum simulation.

```python
import numpy as np
import piquasso as pq


jax_connector = pq.JaxConnector()

simulator = pq.PureFockSimulator(
    d=2,
    config=pq.Config(cutoff=5, dtype=np.float32),
    connector=jax_connector,
)

with pq.Program() as program:
    pq.Q() | pq.Vacuum()

    pq.Q(0) | pq.Displacement(r=0.43)

    pq.Q(0, 1) | pq.Beamsplitter(theta=np.pi / 3)

state = simulator.execute(program).state

print(state.fock_probabilities)
```

```text
[8.3118737e-01 3.8421631e-02 1.1526491e-01 8.8801968e-04 5.3281188e-03
 7.9921819e-03 1.3682902e-05 1.2314616e-04 3.6943855e-04 3.6943876e-04
 1.5812304e-07 1.8974771e-06 8.5386482e-06 1.7077307e-05 1.2807981e-05]
```

--------------------------------

### Create a Program by providing instructions

Source: https://piquasso.readthedocs.io/en/stable/api/program.html

Create a Program by passing a list of instructions to the constructor. Each instruction is applied to specific modes using the on_modes method, then executed with a GaussianSimulator of dimension 5.

```python
program = pq.Program(
    instructions=[
        pq.Vacuum(),
        pq.Squeezing(r=0.5).on_modes(0),
        pq.Beamsplitter(theta=np.pi / 4).on_modes(0, 1),
    ]
)
simulator = pq.GaussianSimulator(d=5)
result = simulator.execute(program)
```

--------------------------------

### Example output of result.samples

Source: https://piquasso.readthedocs.io/en/stable/tutorials/getting-started.html

Example output of `result.samples` for 10 shots. Each tuple corresponds to position and momentum measurements from the homodyne measurement.

```python
[(0.4501947999792735, 12926.564725438904),
 (-0.5527901177646664, -10463.793136424274),
 (3.3685776813034023, 4016.3864717219553),
 (1.814450431718634, -16682.40871883702),
 (2.224714901610408, 4630.904436029417),
 (0.6879338275741113, -9247.094354633904),
 (0.6489117030747604, -3578.776764500346),
 (0.6805547169379911, 6816.377249688921),
 (-2.680094354941116, -11525.839109496135),
 (0.5785633198987801, 32082.76477619564)]
```

--------------------------------

### Program.__init__

Source: https://piquasso.readthedocs.io/en/stable/api/program.html

Initializes a Program instance with an optional list of instructions. The program can be used as a context manager to add instructions via the Q interface.

```APIDOC
## Program.__init__

### Description
Initializes a Program instance with an optional list of instructions. The program can be used as a context manager to add instructions via the Q interface.

### Method
Constructor

### Signature
Program(instructions: list | None = None)

### Parameters
- **instructions** (list[Instruction], optional) - The set of instructions, e.g. quantum gates and measurements.

### Example
```python
import numpy as np
import piquasso as pq

with pq.Program() as program:
    pq.Q() | pq.Vacuum()
    pq.Q(0) | pq.Squeezing(r=0.5)
    pq.Q(0, 1) | pq.Beamsplitter(theta=np.pi / 4)

simulator = pq.GaussianSimulator(d=5)
result = simulator.execute(program)
```

### Example (direct instructions)
```python
program = pq.Program(
    instructions=[
        pq.Vacuum(),
        pq.Squeezing(r=0.5).on_modes(0),
        pq.Beamsplitter(theta=np.pi / 4).on_modes(0, 1),
    ]
)
simulator = pq.GaussianSimulator(d=5)
result = simulator.execute(program)
```
```

--------------------------------

### Boson Sampling example: PassiveSimulator with ParticleNumberMeasurement

Source: https://piquasso.readthedocs.io/en/stable/_sources/states/index.rst.txt

Shows a Boson Sampling-style simulation using a PassiveSimulator. The program includes an interferometer and particle number measurement, and the example prints the samples from 10 shots.

```python
import numpy as np
import piquasso as pq

interferometer = np.array(
   [
      [1 / np.sqrt(2), 1 / np.sqrt(2)],
      [1 / np.sqrt(2), -1 / np.sqrt(2)],
   ]
)

with pq.Program() as program:
   pq.Q() | pq.NumberState([1, 1])
   pq.Q() | pq.Interferometer(interferometer)
   pq.Q(all) | pq.ParticleNumberMeasurement()

simulator = pq.PassiveSimulator(d=2)
result = simulator.execute(program, shots=10)

print(result.samples)
```

--------------------------------

### ImperfectParticleNumberMeasurement example with detector efficiency matrix

Source: https://piquasso.readthedocs.io/en/stable/instructions/measurements.html

Example usage of ImperfectParticleNumberMeasurement. Defines a detector efficiency matrix P, builds a program with state vectors, phase shifters, beamsplitters, and the measurement, then executes it with a PureFockSimulator using cutoff=4.

```python
P = np.array(
    [
        [1.0, 0.1, 0.2],
        [0.0, 0.9, 0.2],
        [0.0, 0.0, 0.6],
    ],
)

with pq.Program() as program:
    pq.Q(all) | pq.StateVector([0, 1, 0]) * np.sqrt(0.2)
    pq.Q(all) | pq.StateVector([1, 1, 0]) * np.sqrt(0.3)
    pq.Q(all) | pq.StateVector([2, 1, 0]) * np.sqrt(0.5)

    pq.Q(0) | pq.Phaseshifter(np.pi)

    pq.Q(1, 2) | pq.Beamsplitter(np.pi / 8)
    pq.Q(0, 1) | pq.Beamsplitter(1.1437)
    pq.Q(1, 2) | pq.Beamsplitter(-np.pi / 8)

    pq.Q(all) | pq.ImperfectParticleNumberMeasurement(
        detector_efficiency_matrix=P,
    )

simulator = pq.PureFockSimulator(d=3, config=pq.Config(cutoff=4))

state = simulator.execute(program).state

```

--------------------------------

### Fermionic GaussianSimulator example

Source: https://piquasso.readthedocs.io/en/stable/experimental/fermionic.html

Example usage of the Fermionic Gaussian simulator. It constructs a passive Hamiltonian, computes its matrix exponential, defines a state vector, builds a program with a StateVector and Interferometer, then executes it with GaussianSimulator and retrieves the resulting state.

```python
passive_hamiltonian = np.array([[1, 2j, 3j], [-2j, 5, 6], [-3j, 6, 7]])

U = expm(1j * passive_hamiltonian)

state_vector = [1, 0, 1]

with pq.Program() as program:
    pq.Q() | pq.StateVector(state_vector)

    pq.Q() | pq.Interferometer(U)

simulator = pq.fermionic.GaussianSimulator(d=3, connector=connector)

state = simulator.execute(program).state
```

--------------------------------

### Example Output for Subgraph Density

Source: https://piquasso.readthedocs.io/en/stable/tutorials/dense-subgraph-gbs.html

The expected output after running the dense subgraph sampling code.

```text
Subgraph nodes: [5, 6, 7, 9, 11, 14, 17, 19]
Subgraph density: 0.6428571428571429
```

--------------------------------

### Basic Piquasso simulation with JaxConnector

Source: https://piquasso.readthedocs.io/en/stable/_sources/tutorials/jax-example.ipynb.txt

Sets up a PureFockSimulator with JaxConnector and executes a program with displacement and beamsplitter operations. Prints the fock probabilities.

```python
import numpy as np
import piquasso as pq


jax_connector = pq.JaxConnector()

simulator = pq.PureFockSimulator(
    d=2,
    config=pq.Config(cutoff=5, dtype=np.float32),
    connector=jax_connector,
)

with pq.Program() as program:
    pq.Q() | pq.Vacuum()

    pq.Q(0) | pq.Displacement(r=0.43)

    pq.Q(0, 1) | pq.Beamsplitter(theta=np.pi / 3)

state = simulator.execute(program).state

print(state.fock_probabilities)
```

--------------------------------

### Annihilate instruction example

Source: https://piquasso.readthedocs.io/en/stable/instructions/preparations.html

Use to annihilate a particle on a mode. Applies an annihilation operator and normalizes the state. Only valid for FockState and PureFockState.

```python
with pq.Program() as program:
    ...
    pq.Q(0) | pq.Annihilate()
    ...

```

--------------------------------

### Embed Graph Adjacency Matrices

Source: https://piquasso.readthedocs.io/en/stable/_sources/tutorials/gaussian-boson-sampling.ipynb.txt

This example shows how to define a graph adjacency matrix and embed it into a Piquasso program for particle number measurement.

```python
A = np.array(
    [
        [0, 1, 0, 1, 1],
        [1, 0, 0, 0, 1],
        [0, 0, 0, 1, 0],
        [1, 0, 1, 0, 1],
        [1, 1, 0, 1, 0],
    ]
)

with pq.Program() as program:
    pq.Q(all) | pq.Graph(A, mean_photon_number=1.0)

    pq.Q(all) | pq.ParticleNumberMeasurement()
```

--------------------------------

### FockSimulator

Source: https://piquasso.readthedocs.io/en/stable/simulators/fock.html

The FockSimulator class is the main entry point for Fock-based photonic simulations. It supports a wide range of preparations, gates, measurements, and channels, and provides methods to create initial states, execute programs, execute instruction lists, and validate programs.

```APIDOC
## FockSimulator

### Description
Performs photonic simulations using Fock representation. The simulation (when executed) results in an instance of `FockState`.

### Constructor
`FockSimulator(d: int | None = None, config: Config | None = None, connector: BaseConnector | None = None)`

### Parameters
- **d** (int | None) - Optional - The number of modes. If not provided, it will be inferred from the program.
- **config** (Config | None) - Optional - Configuration for the simulator.
- **connector** (BaseConnector | None) - Optional - Connector for the simulator.

### Supported Operations
- **Preparations**: `Vacuum`, `Create`, `Annihilate`, `DensityMatrix`
- **Gates**: `Interferometer`, `Beamsplitter`, `Phaseshifter`, `MachZehnder`, `Fourier`, `Kerr`, `CrossKerr`, `SNAP`, `CubicPhase`, `GaussianTransform`, `Squeezing`, `QuadraticPhase`, `Squeezing2`, `ControlledX`, `ControlledZ`, `Displacement`, `PositionDisplacement`, `MomentumDisplacement`
- **Measurements**: `ParticleNumberMeasurement`, `ImperfectParticleNumberMeasurement`
- **Channels**: `Attenuator`

### Example Usage
```python
import numpy as np
import piquasso as pq


with pq.Program() as program:
    pq.Q(all) | pq.Vacuum()

    pq.Q(0)   | pq.Squeezing(r=0.1)
    pq.Q(1)   | pq.Squeezing(r=0.2)

    pq.Q(0, 1) | pq.Beamsplitter(theta=np.pi / 3)

    pq.Q(0) | pq.Attenuator(theta=0.01)
    pq.Q(1) | pq.Attenuator(theta=0.02)

    pq.Q(0) | pq.Kerr(xi=0.05)

simulator = pq.FockSimulator(d=2, config=pq.Config(cutoff=7))
result = simulator.execute(program)
```
```

--------------------------------

### create_program(weights)

Source: https://piquasso.readthedocs.io/en/stable/advanced/cvqnn.html

Creates a Program from the specified weights, with vacuum initial state. This is the main entry point for building a CVQNN program.

```APIDOC
## create_program(weights)

### Description
Creates a Program from the specified weights, with vacuum initial state.

### Parameters
- **weights** (np.ndarray) - Required - The CVQNN circuit weights.

### Returns
- **Program** - The program of the CVQNN circuit, ready to be executed.
```

--------------------------------

### Optimizing Simulation with jax.jit

Source: https://piquasso.readthedocs.io/en/stable/tutorials/jax-example.html

Uses jax.jit to compile a quantum simulation function, showing significant speed improvements after the initial compilation run.

```python
import time

import numpy as np
import piquasso as pq

from jax import jit


def func(r, theta):
    jax_connector = pq.JaxConnector()

    simulator = pq.PureFockSimulator(
        d=2,
        config=pq.Config(cutoff=5, dtype=np.float32),
        connector=jax_connector,
    )

    with pq.Program() as program:
        pq.Q() | pq.Vacuum()

        pq.Q(0) | pq.Displacement(r=r)

        pq.Q(0, 1) | pq.Beamsplitter(theta=theta)

    return simulator.execute(program).state.fock_probabilities


compiled_func = jit(func)

iterations = 10

for i in range(iterations):
    r = np.random.rand()
    theta = np.random.rand()

    start_time = time.time()
    func(r, theta)
    print(f"{i + 1}. original runtime:	{time.time() - start_time} s")
    start_time = time.time()
    compiled_func(r, theta)
    print(f"{i + 1}. compiled runtime:	{time.time() - start_time} s")
```

```text
1. original runtime:    0.053116798400878906 s
1. compiled runtime:    0.48732662200927734 s
2. original runtime:    0.04149889945983887 s
2. compiled runtime:    3.361701965332031e-05 s
3. original runtime:    0.03750133514404297 s
3. compiled runtime:    3.218650817871094e-05 s
4. original runtime:    0.03447985649108887 s
4. compiled runtime:    3.170967102050781e-05 s
5. original runtime:    0.033095598220825195 s
5. compiled runtime:    3.0994415283203125e-05 s
6. original runtime:    0.031104087829589844 s
6. compiled runtime:    3.123283386230469e-05 s
7. original runtime:    0.030498027801513672 s
7. compiled runtime:    3.504753112792969e-05 s
8. original runtime:    0.0323636531829834 s
8. compiled runtime:    3.123283386230469e-05 s
9. original runtime:    0.034629106521606445 s
9. compiled runtime:    3.218650817871094e-05 s
10. original runtime:   0.03313851356506348 s
10. compiled runtime:   3.218650817871094e-05 s
```

--------------------------------

### Prepare vacuum state with pq.Vacuum()

Source: https://piquasso.readthedocs.io/en/stable/instructions/preparations.html

Prepares the system in a vacuum state. This operation can only be used for all modes and is only practical at the beginning of a program declaration.

```python
with pq.Program() as program:
    pq.Q() | pq.Vacuum()
    ...

```

--------------------------------

### StateVector preparation example

Source: https://piquasso.readthedocs.io/en/stable/instructions/preparations.html

Use to prepare a state from occupation numbers. Deprecated since version 8.0.0; use NumberState or FockStateVector instead. Only valid for PureFockState.

```python
with pq.Program() as program:
    pq.Q() | pq.StateVector([2, 1, 0, 3])
    ...

```