Documented State class, fixed bug getting imaginary part of State.

.gitignore

@@ -1,3 +1,4 @@
+cmake_commands.sh
 build
 install
 julia/products

docs/documentation/blocks/spinhalf.md

@@ -52,8 +52,22 @@ Representation of a block in a spin $S=1/2$  Hilbert space.
 		int64_t n_sites() const
 		```
 
+!!! method "dim"
+	Returns the dimension of the block.
+
+	=== "Julia"
+		```julia
+		dim(block::Spinhalf)
+		```
+
+	=== "C++"	
+		```c++
+		int64_t dim() const;
+		```
+
+
 !!! method "size"
-	Returns the size of the block, i.e. its dimension.
+	Returns the size of the block locally. Same as "dim" for non-distributed Blocks but different for distributed blocks.
 
 	=== "Julia"
 		```julia

docs/documentation/index.md

@@ -32,6 +32,12 @@ title: Overview
 | [Coupling](operators/coupling.md) | Describes the coupling of a local operator       | :simple-cplusplus: :simple-julia: |
 
 
+## States
+|                          |                                                    |                                   |
+|:-------------------------|:---------------------------------------------------|----------------------------------:|
+| [State](states/state.md) | A generic state describing a quantum wave function | :simple-cplusplus: :simple-julia: |
+
+
 ## Symmetries
 |                                                     |                                                     |                                   |
 |:----------------------------------------------------|:----------------------------------------------------|----------------------------------:|

docs/documentation/states/state.md

@@ -0,0 +1,217 @@
+---
+title: State
+---
+
+A generic state describing a quantum wave function
+
+**Source** [state.hpp](https://github.com/awietek/xdiag/blob/main/xdiag/states/state.hpp)
+
+## Constructors
+
+=== "Julia"
+	```julia
+	State(block::Block; real::Bool = true, n_cols::Int64 = 1)
+	State(block::Block, vec::Vector{Float64})
+	State(block::Block, vec::Vector{ComplexF64})
+	State(block::Block, mat::Matrix{Float64})
+	State(block::Block, mat::Matrix{ComplexF64})
+	```
+
+=== "C++"	
+	```c++
+    State(Block const &block, bool real = true, int64_t n_cols = 1);
+
+	template <typename block_t, typename coeff_t>
+	State(block_t const &block, arma::Col<coeff_t> const &vector);
+
+	template <typename block_t, typename coeff_t>
+	State(block_t const &block, arma::Mat<coeff_t> const &matrix);
+	```
+
+| Parameter | Description                                                                                    |   |
+|:----------|:-----------------------------------------------------------------------------------------------|---|
+| block     | The block of a Hilbertspace on which the state is defined                                      |   |
+| real      | Flag whether or not the state has real coefficients                                            |   |
+| n_cols    | Number of columns of the state (default 1)                                                     |   |
+| vector    | A vector containing the coefficients of the state. Must be same size as block.                 |   |
+| matrix    | A matrix containing the coefficients of the state. Number of rows must be same as block size . |   |
+
+
+## Methods
+
+!!! method "n_sites"
+
+	Returns the number of sites of the block the state is defined on.
+
+	=== "Julia"
+		```julia
+		n_sites(state::State)
+		```
+
+	=== "C++"	
+		```c++
+		int64_t n_sites() const
+		```
+
+!!! method "isreal"
+	Returns whether the state is real.
+
+	=== "Julia"
+		```julia
+	    isreal(state::State)
+		```
+
+	=== "C++"	
+		```c++
+		int64_t isreal() const;
+		```
+
+!!! method "real"
+	Returns whether the real part of the State.
+
+	=== "Julia"
+		```julia
+	    real(state::State)
+		```
+
+	=== "C++"	
+		```c++
+		State real() const;
+		```
+
+!!! method "imag"
+	Returns whether the imaginary part of the State.
+
+	=== "Julia"
+		```julia
+	    imag(state::State)
+		```
+
+	=== "C++"	
+		```c++
+		State imag() const;
+		```
+		
+!!! method "make_complex! / make_complex"
+	Turns a real State into a complex State. Does nothing if the state is already complex
+
+	=== "Julia"
+		```julia
+	    make_complex!(state::State)
+		```
+
+	=== "C++"	
+		```c++
+		void make_complex();
+		```
+
+
+!!! method "dim"
+	Returns the dimension of the block the state is defined on.
+
+	=== "Julia"
+		```julia
+		dim(block::Spinhalf)
+		```
+
+	=== "C++"	
+		```c++
+		int64_t dim() const;
+		```
+
+
+!!! method "size"
+	Returns the size of the block  the state is defined on. locally. Same as "dim" for non-distributed Blocks but different for distributed blocks.
+
+	=== "Julia"
+		```julia
+		size(block::Spinhalf)
+		```
+
+	=== "C++"	
+		```c++
+		int64_t size() const;
+		```
+
+!!! method "n_rows"
+	Returns number of rows of the local storage. Same as "size"
+
+	=== "Julia"
+		```julia
+		n_rows(block::Spinhalf)
+		```
+
+	=== "C++"	
+		```c++
+		int64_t n_rows() const;
+		```
+		
+!!! method "n_cols"
+	Returns number of columns of the local storage.
+
+	=== "Julia"
+		```julia
+		n_cols(block::Spinhalf)
+		```
+
+	=== "C++"	
+		```c++
+		int64_t n_cols() const;
+		```
+
+!!! method "col"
+	Returns a state created from the n-th column of the storage. Whether or not the storage is copied can be specified by setting the flag "copy".
+
+	=== "Julia"
+		```julia
+		col(state::State, n::Int64 = 1; copy::Bool = true)
+		```
+
+	=== "C++"	
+		```c++
+		State col(int64_t n, bool copy = true) const;
+		```
+
+!!! method "vector/vectorC"
+	Returns a vector from the n-th column of the storage. In C++ use "vector"/"vectorC" to either get a real or complex vector.
+
+	=== "Julia"
+		```julia
+		vector(state::State; n::Int64 = 1)
+		# no vectorC method in julia
+		```
+
+	=== "C++"	
+		```c++
+		arma::vec vector(int64_t n = 0, bool copy = true) const;
+		arma::cx_vec vectorC(int64_t n = 0, bool copy = true) const;
+		```
+
+!!! method "matrix/matrixC"
+	Returns matrix representing the storage. In C++ use "matrix"/"matrixC" to either get a real or complex matrix.
+
+	=== "Julia"
+		```julia
+		matrix(state::State)
+		# no matrixC method in julia
+		```
+
+	=== "C++"	
+		```c++
+		arma::vec matrix(bool copy = true) const;
+		arma::cx_vec matrixC(bool copy = true) const;
+		```
+
+
+## Usage Example
+
+=== "Julia"
+	```c++
+	--8<-- "examples/usage_examples/main.jl:state"
+	```
+
+=== "C++"
+	```c++
+	--8<-- "examples/usage_examples/main.cpp:state"
+	```
+

examples/usage_examples/main.cpp

@@ -260,7 +260,30 @@ XDIAG_SHOW(cpl.as<arma::cx_mat>());
 // --8<-- [end:coupling]
 } 
 
-// clang-format on
+
+
+{
+// --8<-- [start:state]
+auto block = Spinhalf(2);
+auto psi1 = State(block, arma::vec("1.0 2.0 3.0 4.0"));
+XDIAG_SHOW(psi1);
+XDIAG_SHOW(psi1.vector());
+psi1.make_complex();
+XDIAG_SHOW(psi1.vectorC());
+
+auto psi2 = State(block, false, 3);
+XDIAG_SHOW(psi2);
+XDIAG_SHOW(psi2.matrixC());
+
+auto psi3 = State(block, arma::cx_vec(arma::vec("1.0 2.0 3.0 4.0"),
+				      arma::vec("4.0 3.0 2.0 1.0")));
+XDIAG_SHOW(psi3.vectorC());
+XDIAG_SHOW(psi3.real().vector());
+XDIAG_SHOW(psi3.imag().vector());
+// --8<-- [end:state]
+}
+
+  // clang-format on
 
 } catch (Error e) {
   error_trace(e);

examples/usage_examples/main.jl

@@ -240,3 +240,21 @@ cpl = Coupling([1 2; -2 1])
 @show convert(Matrix{Float64}, cpl)
 @show convert(Matrix{ComplexF64}, cpl)
 # --8<-- [end:coupling]
+
+# --8<-- [start:state]
+block = Spinhalf(2)
+psi1 = State(block, [1.0, 2.0, 3.0, 4.0])
+@show psi1
+display(vector(psi1))
+make_complex!(psi1)
+display(vector(psi1))
+
+psi2 = State(block, real=false, n_cols=3)
+@show psi2
+display(matrix(psi2))
+
+psi3 = State(block, [1.0+4.0im, 2.0+3.0im, 3.0+2.0im, 4.0+1.0im])
+display(vector(psi3))
+display(vector(real(psi3)))
+display(vector(imag(psi3)))
+# --8<-- [end:state]

tests/algorithms/time_evolution/test_time_evolution.cpp

@@ -221,9 +221,9 @@ TEST_CASE("tj_complex_timeevo", "[time_evolution]") try {
   for (int x = 0; x < L; ++x) {
     for (int y = 0; y < L; ++y) {
       if (((x + y) % 2) == 0) {
-        pstate << "Dn";
+        pstate.push_back("Dn");
       } else {
-        pstate << "Up";
+        pstate.push_back("Up");
       }
     }
   }

tests/algorithms/time_evolution/test_time_evolution_distributed.cpp

@@ -47,9 +47,9 @@ TEST_CASE("time_evolution_distributed", "[time_evolution]") try {
   for (int x = 0; x < L; ++x) {
     for (int y = 0; y < L; ++y) {
       if (((x + y) % 2) == 0) {
-        pstate << "Dn";
+        pstate.push_back("Dn");
       } else {
-        pstate << "Up";
+        pstate.push_back("Up");
       }
     }
   }

xdiag/states/fill.cpp

@@ -34,7 +34,7 @@ void fill(State &state, RandomState const &rstate, int64_t col) try {
 }
 
 void fill(State &state, ProductState const &pstate, int64_t col) try {
-  if (state.n_sites() != pstate.n_sites()) {
+  if (state.size() != pstate.size()) {
     XDIAG_THROW("State and ProductState do not have the same number of sites");
   } else if (col >= state.n_cols()) {
     XDIAG_THROW("Column index larger than number of columns in State");