more complex functions

[bob-carpenter]

Is your feature request related to a problem? Please describe.

Yes. Not all of the complex functions are exposed through the language. Here's a list of

• the current signatures.

Describe the solution you'd like

I'd like to see the following functions added with complex signatures. If you only implement some of these functions, please mark them off so we can create a new issue with the remaining ones.

Shorthand:

• CM: any of complex_vector, complex_row_vector, or complex_matrix
• CV: eithercomplex_vector or complex_row_vector

Plus, wherever a complex value is allowed, its corresponding real should also be supported. The signatures exist for these function for real values, except where noted.

• [x] int num_elements(CM)
• [x] int rows(CM)
• [x] int cols(CM)
• [x] operator.*(CM, complex), operator.*(complex, CM)
• [x] dot_product(CV, CV)
• [x] columns_dot_product(T, T), for T in CM (i.e., types must match, unlike for simple dot_product)
• [x] rows_dot_product(T, T), for T in CM
• [x] dot_self(CV)
• [x] columns_dot_self(CM)
• [x] rows_dot_self(CM)
• [x] diag_pre_multiply(CV, CM)
• [x] diag_post_multiply(CM, CV)
• [x] prod(CM)
• [x] rep_vector(complex, int)
• [x] rep_row_vector(complex, int)
• [x] rep_matrix(complex, int, int), rep_matrix(CV, int)
• [x] symmetrize_from_lower_tri(complex_matrix)
• [x] add_diag(complex_matrix, CV), add_diag(complex_matrix, complex)
• [x] diagonal(complex_matrix)
• [x] diag_matrix(CV) (we appear to be missing diag_matrix(row_vector), so OK to skip that)
• [x] col(complex_matrix, int)
• [x] row(complex_matrix, int)
• [x] block(complex_matrix, int, int, int int)
• [x] sub_col(complex_matrix, int, int, int)
• [x] sub_row(complex_matrix, int, int, int)
• [x] head(CV, int)
• [x] tail(CV, int)
• [x] segment(CV, int, int)
• [x] append_col(complex_matrix, complex_matrix), append_col(complex_matrix, complex_vector), append_col(complex_vector, complex_matrix), append_col(complex_vector, complex_vector), append_col(complex_row_vector, complex_row_vector), append_col(complex, complex_row_vector), append_col(complex_row_vector, complex)
• [x] append_row(complex_matrix, complex_matrix), append_row(complex_matrix, complex_row_vector), append_row(complex_row_vector, complex_matrix),append_row(complex_row_vector, complex_row_vector), append_row(complex_vector, complex_vector), append_row(complex, complex_vector), append_row(complex_vector, complex)`
• [x] operator/(complex_row_vector, complex_matrix), operator/(complex_matrix, complex_matrix)
• [x] trace(complex_matrix)
• [x] reverse(CV)
• [x] to_matrix(CM), to_matrix(CM, int, int), to_matrix(CM, int, int, int), to_matrix(array[] complex, int, int), to_matrix(array[] complex, int, int, int), to_matrix(array[] complex_row_vector), to_matrix(array[,] complex)
• [x] to_vector(CM), to_vector(array[] complex)
• [x] to_row_vector(CM), to_row_vector(array[] complex)
• [x] operator+=(complex, complex), operator+=(CM, complex), operator+=(T, T) for T in CM
• [x] operator-=(complex, complex), operator-=(CM, complex), operator-=(T, T) for T in CM
• [x] operator*=(complex, complex), operator*=(CM, complex), operator*=(row_vecotr, matrix), operator*=(matrix, matrix)
• [x] operator/=(complex, complex), operator/=(CM, complex), operator/=(complex_matrix, complex_matrix) (this last one doesn't exist for real so can skip)
• [x] operator.*=(T, T) for T in CM

Functions which fail expression tests at the moment:

• [ ] operator\(complex_matrix, complex_vector), operator\(complex_matrix, complex_matrix)
• [ ] determinant(complex_matrix)
• [ ] inverse(complex_matrix)
• [ ] svd_U(complex_matrix)
• [ ] svd_V(complex_matrix)
• [ ] operator./(CM, complex), operator./(complex, CM), operator./=(T, T) for T in CM
• [ ] singular_values(complex_matrix)
• [ ] eigenvalues_sym(complex_matrix)
• [ ] eigenvectors_sym(complex_matrix)
• [ ] generalized_inverse(complex_matrix) (don't even know if this one's possible)
• [ ] cholesky_decompose(complex_matrix)

These should just work for complex values if the templating is rich enough---the definitions are identical to the real cases.

Describe alternatives you've considered

Not really any alternative if we want these complex functions.

Additional context

n/a

[WardBrian]

operator.(CM, complex), operator.(complex, CM)

We don't define operator.* for scalar-matrix ops for the real-valued versions either, this is just what operator* does in those cases. (Note, this is inconsistent with operator./)

Additionally, the assignment operator overloads already exist (The compiler defines operator*= in terms of operator*, so they all implicitly get added)

[WardBrian]

It seems like operator./ when one of the arguments is a complex scalar is failing expression tests and may need some C++ work before exposing. Going through most of the rest of the list, it's a somewhat slow process.

determinant has too strict a requirement at the moment (uses std::is_arithmetic for the prim overload)

inverse fails for a similar reason

[WardBrian]

mdivide_left (aka operator\) fails to compile the expression tests due to templates. mdivide_right (aka operator/) works fine.

svd_U and svd_V both fail to match templates.

cholesky_decompose fails due to a template error in stan/lib/stan_math/stan/math/prim/err/elementwise_check.hpp:210:28: error: no match for call to ‘(const stan::math::check_not_nan(const char*, const char*, const T_y&) [with T_y = Eigen::Matrix<std::complex<double>, -1, -1>]::<lambda(double)>) (std::complex<double>&)’