density_matrix.h

Go to the documentation of this file.

/*
Copyright 2025 SQUANDER Contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

#pragma once

#include "matrix_base.hpp" // From existing SQUANDER
#include <vector>

namespace squander {
namespace density {

class DensityMatrix : public matrix_base<QGD_Complex16> {
public:
  // ================================================================
  // Constructors & Destructor
  // ================================================================

  explicit DensityMatrix(int qbit_num);

  explicit DensityMatrix(const matrix_base<QGD_Complex16> &state_vector);

  DensityMatrix(QGD_Complex16 *data, int dim);

  DensityMatrix(const DensityMatrix &other);

  DensityMatrix(DensityMatrix &&other) noexcept;

  ~DensityMatrix() = default;

  // ================================================================
  // Assignment Operators
  // ================================================================

  DensityMatrix &operator=(const DensityMatrix &other);
  DensityMatrix &operator=(DensityMatrix &&other) noexcept;

  QGD_Complex16 &operator()(int i, int j);
  const QGD_Complex16 &operator()(int i, int j) const;

  // ================================================================
  // Basic Properties
  // ================================================================

  int get_qbit_num() const { return qbit_num_; }

  int get_dim() const { return rows; }

  // ================================================================
  // Quantum Properties
  // ================================================================

  QGD_Complex16 trace() const;

  double purity() const;

  double entropy() const;

  bool is_valid(double tol = 1e-10) const;

  std::vector<double> eigenvalues() const;

  // ================================================================
  // Operations
  // ================================================================

  void apply_unitary(const matrix_base<QGD_Complex16> &U);

  void apply_single_qubit_unitary(const matrix_base<QGD_Complex16> &u_2x2,
                                  int target_qbit);

  void apply_two_qubit_unitary(const matrix_base<QGD_Complex16> &u_2x2,
                               int target_qbit, int control_qbit);

  void apply_local_unitary(const matrix_base<QGD_Complex16> &u_kernel,
                           const std::vector<int> &target_qbits);

  DensityMatrix partial_trace(const std::vector<int> &trace_out) const;

  DensityMatrix clone() const;

  // ================================================================
  // Static Factory Methods
  // ================================================================

  static DensityMatrix maximally_mixed(int qbit_num);

  // ================================================================
  // Utilities
  // ================================================================

  void print() const;

private:
  int qbit_num_; 

  // Helper methods
  void validate_dimensions() const;
  bool is_hermitian(double tol) const;
};

} // namespace density
} // namespace squander