# Core Concepts

This library models Gaussian continuous-variable (CV) systems using mean vectors and covariance matrices in phase space. The main abstractions are designed around three objects:

- `GaussianCVState` — a Gaussian state
- `GaussianCVSystem` — a dynamical generator
- `GaussianSolution` — a time-resolved trajectory

## Gaussian State Representation

An $n$-mode Gaussian state is represented by:

- a mean vector $\mathbf{r} \in \mathbb{R}^{2n}$
- a covariance matrix $V \in \mathbb{R}^{2n \times 2n}$

The phase-space ordering used throughout the library is

$$
(x_1, \dots, x_n, p_1, \dots, p_n)
$$

This ordering is used consistently for:

- state construction
- subsystem extraction
- Hamiltonian matrices
- dissipative channels
- metric evaluation

## Mode Indexing

All public APIs use **1-indexed mode labels**.

For an \(n\)-mode system:

- valid mode labels are `1, 2, ..., n`
- index `0` is invalid by design

Subsystems are specified using physical mode labels, for example:

- `(1,)` for a single-mode subsystem
- `(1, 2)` for a two-mode subsystem

Internally, these are mapped to zero-based array positions.

## Subsystem Ordering

Subsystems are always extracted in x-then-p form.

For subsystem `(i_1, ..., i_k)`, the extracted ordering is

$$
(x_{i_1}, \dots, x_{i_k}, p_{i_1}, \dots, p_{i_k})
$$

This ordering is not interleaved.

## State Mutation Model

`GaussianCVState` methods such as squeezing, displacement, and two-mode mixing act **in place** and return `self`.

For example:

```python
state = GaussianCVState.vacuum(2)
state.single_mode_squeeze((1.0, 0.0), 1)
state.single_mode_squeeze((1.0, 0.0), 2)
```

Use `copy_state()` when an independent copy is needed.

## System Construction

`GaussianCVSystem` stores the dynamical generator of the problem, not the state.

A system is defined by:

- a quadratic Hamiltonian matrix
- a Lindblad Gram matrix

These determine the drift and diffusion matrices governing Gaussian moment evolution.

## Time Evolution

State evolution is computed exactly from the Gaussian channel generated by the system.

The equations of motion have the form

$$
\frac{d}{dt}\langle R \rangle = A \langle R \rangle
$$

$$
\frac{d}{dt}V = A V + V A^T + D
$$

where $A$ is the drift matrix and $D$ is the diffusion matrix.

The library evolves these moments using matrix exponentials.

## Validation and Physicality

The library applies validation throughout construction and evolution.

This includes checks for:

- finite numerical values
- dimension consistency
- valid subsystem indices
- positive semidefinite covariance matrices

Two notions of validity are distinguished:

- **classical covariance validity**: $V \succeq 0$
- **quantum physicality**: $V + \frac{i}{2}\Omega \succeq 0$

Quantum physicality is enforced during evolution.

## Finite-Memory Environments

The library supports a single-pole Ornstein–Uhlenbeck environment through an exact pseudomode embedding.

In this construction:

- the system is enlarged by one auxiliary mode
- the enlarged system is Markovian
- the reduced dynamics reproduce finite-memory behavior

This provides a structured way to model non-Markovian effects while staying within the Gaussian formalism.