15.3 Class Env

mosek.Env

The MOSEK global environment.

Env.Env

pub fn Env::new() -> Option<Env>

pub fn Env::new_mem_debug
   (dbgfile : &str) -> Option<Env>

Constructor of a new environment.

Parameters:

dbgfile (&str) – Name of the memory debugging file. (input)

Groups:

Environment and task management

Env.axpy

pub fn axpy
   (n : i32,
    alpha : f64,
    x : &[f64],
    y : &mut[f64]) -> Result<(),String>
pub fn Env::axpy
   (&self,
    n : i32,
    alpha : f64,
    x : &[f64],
    y : &mut[f64]) -> Result<(),String>

Adds \(\alpha x\) to \(y\), i.e. performs the update

\[y := \alpha x + y.\]

Note that the result is stored overwriting \(y\). It must not overlap with the other input arrays.

Parameters:

• n (i32) – Length of the vectors. (input)

• alpha (f64) – The scalar that multiplies \(x\). (input)

• x (f64[]) – The \(x\) vector. (input)

• y (f64[]) – The \(y\) vector. (input/output)

Groups:

Linear algebra

Env.check_in_all

pub fn check_in_all() -> Result<(),String>
pub fn Env::check_in_all(&mut self) -> Result<(),String>

Check in all unused license features to the license token server.

Groups:

License system

Env.check_in_license

pub fn check_in_license(feature : i32) -> Result<(),String>
pub fn Env::check_in_license
   (&mut self,
    feature : i32) -> Result<(),String>

Check in a license feature to the license server. By default all licenses consumed by functions using a single environment are kept checked out for the lifetime of the MOSEK environment. This function checks in a given license feature back to the license server immediately.

If the given license feature is not checked out at all, or it is in use by a call to Task.optimize, calling this function has no effect.

Please note that returning a license to the license server incurs a small overhead, so frequent calls to this function should be avoided.

Parameters:

feature (Feature) – Feature to check in to the license system. (input)

Groups:

License system

Env.check_out_license

pub fn check_out_license(feature : i32) -> Result<(),String>
pub fn Env::check_out_license
   (&mut self,
    feature : i32) -> Result<(),String>

Checks out a license feature from the license server. Normally the required license features will be automatically checked out the first time they are needed by the function Task.optimize. This function can be used to check out one or more features ahead of time.

The feature will remain checked out until the environment is deleted or the function Env.check_in_license is called.

If a given feature is already checked out when this function is called, the call has no effect.

Parameters:

feature (Feature) – Feature to check out from the license system. (input)

Groups:

License system

Env.check_version

pub fn check_version
   (major : i32,
    minor : i32,
    revision : i32) -> Result<(),String>
pub fn Env::check_version
   (&self,
    major : i32,
    minor : i32,
    revision : i32) -> Result<(),String>

Compares the version of the MOSEK DLL with a specified version. Returns Rescode::OK if the versions match and one of Rescode::ERR_NEWER_DLL, Rescode::ERR_OLDER_DLL otherwise.

Parameters:

• major (i32) – Major version number. (input)

• minor (i32) – Minor version number. (input)

• revision (i32) – Revision number. (input)

Groups:

Versions

Env.compute_sparse_cholesky

pub fn compute_sparse_cholesky
   (numthreads : i32,
    ordermethod : i32,
    tolsingular : f64,
    anzc : &[i32],
    aptrc : &[i64],
    asubc : &[i32],
    avalc : &[f64],
    perm : &mut Vec<i32>,
    diag : &mut Vec<f64>,
    lnzc : &mut Vec<i32>,
    lptrc : &mut Vec<i64>,
    lensubnval : &mut i64,
    lsubc : &mut Vec<i32>,
    lvalc : &mut Vec<f64>) -> Result<(),String>
pub fn Env::compute_sparse_cholesky
   (&self,
    numthreads : i32,
    ordermethod : i32,
    tolsingular : f64,
    anzc : &[i32],
    aptrc : &[i64],
    asubc : &[i32],
    avalc : &[f64],
    perm : &mut Vec<i32>,
    diag : &mut Vec<f64>,
    lnzc : &mut Vec<i32>,
    lptrc : &mut Vec<i64>,
    lensubnval : &mut i64,
    lsubc : &mut Vec<i32>,
    lvalc : &mut Vec<f64>) -> Result<(),String>

The function computes a Cholesky factorization of a sparse positive semidefinite matrix. Sparsity is exploited during the computations to reduce the amount of space and work required. Both the input and output matrices are represented using the sparse format.

To be precise, given a symmetric matrix \(A \in \real^{n\times n}\) the function computes a nonsingular lower triangular matrix \(L\), a diagonal matrix \(D\) and a permutation matrix \(P\) such that

\[LL^T - D = P A P^T.\]

If ordermethod is zero then reordering heuristics are not employed and \(P\) is the identity.

If a pivot during the computation of the Cholesky factorization is less than

\[-\rho\cdot\max((PAP^T)_{jj},1.0)\]

then the matrix is declared negative semidefinite. On the hand if a pivot is smaller than

\[\rho\cdot\max((PAP^T)_{jj},1.0),\]

then \(D_{jj}\) is increased from zero to

\[\rho\cdot\max((PAP^T)_{jj},1.0).\]

Therefore, if \(A\) is sufficiently positive definite then \(D\) will be the zero matrix. Here \(\rho\) is set equal to value of tolsingular.

Parameters:

• numthreads (i32) – The number threads that can be used to do the computation. 0 means the code makes the choice. NOTE: API change in version 10: in versions up to 9 the argument in this position indicated whether to use multithreading or not. (input)

• ordermethod (i32) – If nonzero, then a sparsity preserving ordering will be employed. (input)

• tolsingular (f64) – A positive parameter controlling when a pivot is declared zero. (input)

• anzc (i32[]) – anzc[j] is the number of nonzeros in the \(j\)-th column of \(A\). (input)

• aptrc (i64[]) – aptrc[j] is a pointer to the first element in column \(j\) of \(A\). (input)

• asubc (i32[]) – Row indexes for each column stored in increasing order. (input)

• avalc (f64[]) – The value corresponding to row indexed stored in asubc. (input)

• perm (i32[] by reference) – Permutation array used to specify the permutation matrix \(P\) computed by the function. (output)

• diag (f64[] by reference) – The diagonal elements of matrix \(D\). (output)

• lnzc (i32[] by reference) – lnzc[j] is the number of non zero elements in column \(j\) of \(L\). (output)

• lptrc (i64[] by reference) – lptrc[j] is a pointer to the first row index and value in column \(j\) of \(L\). (output)

• lensubnval (i64 by reference) – Number of elements in lsubc and lvalc. (output)

• lsubc (i32[] by reference) – Row indexes for each column stored in increasing order. (output)

• lvalc (f64[] by reference) – The values corresponding to row indexed stored in lsubc. (output)

Groups:

Linear algebra

Env.dot

pub fn dot
   (n : i32,
    x : &[f64],
    y : &[f64],
    xty : &mut f64) -> Result<(),String>
pub fn Env::dot
   (&self,
    n : i32,
    x : &[f64],
    y : &[f64],
    xty : &mut f64) -> Result<(),String>

Computes the inner product of two vectors \(x,y\) of length \(n\geq 0\), i.e

\[x\cdot y= \sum_{i=1}^n x_i y_i.\]

Note that if \(n=0\), then the result of the operation is 0.

Parameters:

• n (i32) – Length of the vectors. (input)

• x (f64[]) – The \(x\) vector. (input)

• y (f64[]) – The \(y\) vector. (input)

• xty (f64 by reference) – The result of the inner product between \(x\) and \(y\). (output)

Groups:

Linear algebra

Env.echo_intro

pub fn echo_intro(longver : i32) -> Result<(),String>
pub fn Env::echo_intro
   (&self,
    longver : i32) -> Result<(),String>

Prints an intro to message stream.

Parameters:

longver (i32) – If non-zero, then the intro is slightly longer. (input)

Groups:

Logging

Env.expirylicenses

pub fn expirylicenses(expiry : &mut i64) -> Result<(),String>
pub fn Env::expirylicenses
   (&mut self,
    expiry : &mut i64) -> Result<(),String>

Reports when the first license feature expires. It reports the number of days to the expiry of the first feature of all the features that were ever checked out from the start of the process, or from the last call to Env.reset_expiry_licenses, until now.

Parameters:

expiry (i64 by reference) – If nonnegative, then it is the minimum number days to expiry of any feature that has been checked out. (output)

Groups:

License system

Env.gemm

pub fn gemm
   (transa : i32,
    transb : i32,
    m : i32,
    n : i32,
    k : i32,
    alpha : f64,
    a : &[f64],
    b : &[f64],
    beta : f64,
    c : &mut[f64]) -> Result<(),String>
pub fn Env::gemm
   (&self,
    transa : i32,
    transb : i32,
    m : i32,
    n : i32,
    k : i32,
    alpha : f64,
    a : &[f64],
    b : &[f64],
    beta : f64,
    c : &mut[f64]) -> Result<(),String>

Performs a matrix multiplication plus addition of dense matrices. Given \(A\), \(B\) and \(C\) of compatible dimensions, this function computes

\[C:= \alpha op(A)op(B) + \beta C\]

where \(\alpha,\beta\) are two scalar values. The function \(op(X)\) denotes \(X\) if transX is Transpose::NO, or \(X^T\) if set to Transpose::YES. The matrix \(C\) has \(m\) rows and \(n\) columns, and the other matrices must have compatible dimensions.

The result of this operation is stored in \(C\). It must not overlap with the other input arrays.

Parameters:

• transa (Transpose) – Indicates whether the matrix \(A\) must be transposed. (input)

• transb (Transpose) – Indicates whether the matrix \(B\) must be transposed. (input)

• m (i32) – Indicates the number of rows of matrix \(C\). (input)

• n (i32) – Indicates the number of columns of matrix \(C\). (input)

• k (i32) – Specifies the common dimension along which \(op(A)\) and \(op(B)\) are multiplied. For example, if neither \(A\) nor \(B\) are transposed, then this is the number of columns in \(A\) and also the number of rows in \(B\). (input)

• alpha (f64) – A scalar value multiplying the result of the matrix multiplication. (input)

• a (f64[]) – The pointer to the array storing matrix \(A\) in a column-major format. (input)

• b (f64[]) – The pointer to the array storing matrix \(B\) in a column-major format. (input)

• beta (f64) – A scalar value that multiplies \(C\). (input)

• c (f64[]) – The pointer to the array storing matrix \(C\) in a column-major format. (input/output)

Groups:

Linear algebra

Env.gemv

pub fn gemv
   (transa : i32,
    m : i32,
    n : i32,
    alpha : f64,
    a : &[f64],
    x : &[f64],
    beta : f64,
    y : &mut[f64]) -> Result<(),String>
pub fn Env::gemv
   (&self,
    transa : i32,
    m : i32,
    n : i32,
    alpha : f64,
    a : &[f64],
    x : &[f64],
    beta : f64,
    y : &mut[f64]) -> Result<(),String>

Computes the multiplication of a scaled dense matrix times a dense vector, plus a scaled dense vector. Precisely, if trans is Transpose::NO then the update is

\[y := \alpha A x + \beta y,\]

and if trans is Transpose::YES then

\[y := \alpha A^T x + \beta y,\]

where \(\alpha,\beta\) are scalar values and \(A\) is a matrix with \(m\) rows and \(n\) columns.

Note that the result is stored overwriting \(y\). It must not overlap with the other input arrays.

Parameters:

• transa (Transpose) – Indicates whether the matrix \(A\) must be transposed. (input)

• m (i32) – Specifies the number of rows of the matrix \(A\). (input)

• n (i32) – Specifies the number of columns of the matrix \(A\). (input)

• alpha (f64) – A scalar value multiplying the matrix \(A\). (input)

• a (f64[]) – A pointer to the array storing matrix \(A\) in a column-major format. (input)

• x (f64[]) – A pointer to the array storing the vector \(x\). (input)

• beta (f64) – A scalar value multiplying the vector \(y\). (input)

• y (f64[]) – A pointer to the array storing the vector \(y\). (input/output)

Groups:

Linear algebra

Env.get_build_info

pub fn get_build_info() -> Result<(String,String),String>

Obtains build information.

Return:

• buildstate (String) – State of binaries, i.e. a debug, release candidate or final release.

• builddate (String) – Date when the binaries were built.

Groups:

Versions

Env.get_code_desc

pub fn get_code_desc(code : i32) -> Result<(String,String),String>

Obtains a short description of the meaning of the response code given by code.

Parameters:

code (Rescode) – A valid MOSEK response code. (input)

Return:

• symname (String) – Symbolic name corresponding to code.

• str (String) – Obtains a short description of a response code.

Groups:

Names, Responses, errors and warnings

Env.get_response_class

pub fn get_response_class
   (r : i32,
    rc : & mut i32) -> Result<(),String>

Obtain the class of a response code.

Parameters:

• r (Rescode) – A response code indicating the result of function call. (input)

• rc (Rescodetype by reference) – The response class. (output)

Groups:

Responses, errors and warnings

Env.get_version

pub fn get_version
   (major : &mut i32,
    minor : &mut i32,
    revision : &mut i32) -> Result<(),String>

Obtains MOSEK version information.

Parameters:

• major (i32 by reference) – Major version number. (output)

• minor (i32 by reference) – Minor version number. (output)

• revision (i32 by reference) – Revision number. (output)

Groups:

Versions

Env.global_env_finalize

pub fn global_env_finalize() -> Result<(),String>

Finalize global env.

Env.global_env_initialize

pub fn global_env_initialize
   (maxnumalloc : i64,
    dbgfile : &str) -> Result<(),String>

Initialize global env.

Parameters:

• maxnumalloc (i64) – If it is nonnegative then it is the maximum number of alloacations allowed. (input)

• dbgfile (&str) – A user-defined file debug file. (input)

Env.is_infinity

pub fn is_infinity(value : f64) -> Result<(),String>

Return true if value is considered infinity by MOSEK.

Parameters:

value (f64) – The value to be checked (input)

Env.license_cleanup

pub fn license_cleanup() -> Result<(),String>

Stops all threads and deletes all handles used by the license system. If this function is called, it must be called as the last MOSEK API call. No other MOSEK API calls are valid after this.

Groups:

License system

Env.link_file_to_stream

pub fn link_file_to_stream
   (whichstream : i32,
    filename : &str,
    append : i32) -> Result<(),String>
pub fn Env::link_file_to_stream
   (&mut self,
    whichstream : i32,
    filename : &str,
    append : i32) -> Result<(),String>

Sends all output from the stream defined by whichstream to the file given by filename.

Parameters:

• whichstream (Streamtype) – Index of the stream. (input)

• filename (&str) – A valid file name. (input)

• append (i32) – If this argument is 0 the file will be overwritten, otherwise it will be appended to. (input)

Groups:

Logging

Env.optimize_batch

pub fn optimize_batch
   (israce : bool,
    maxtime : f64,
    numthreads : i32,
    task : &[ & mut Task ],
    trmcode : &mut[i32],
    rcode : &mut[i32]) -> Result<(),String>
pub fn Env::optimize_batch
   (&self,
    israce : bool,
    maxtime : f64,
    numthreads : i32,
    task : &[ & mut Task ],
    trmcode : &mut[i32],
    rcode : &mut[i32]) -> Result<(),String>

Optimize a number of tasks in parallel using a specified number of threads. All callbacks and log output streams are disabled.

Assuming that each task takes about same time and there many more tasks than number of threads then a linear speedup can be achieved, also known as strong scaling. A typical application of this method is to solve many small tasks of similar type; in this case it is recommended that each of them is allocated a single thread by setting Iparam::NUM_THREADS to \(1\).

If the parameters israce or maxtime are used, then the result may not be deterministic, in the sense that the tasks which complete first may vary between runs.

The remaining behavior, including termination and response codes returned for each task, are the same as if each task was optimized separately.

Parameters:

• israce (bool) – If nonzero, then the function is terminated after the first task has been completed. (input)

• maxtime (f64) – Time limit for the function: if nonnegative, then the function is terminated after maxtime (seconds) has expired. (input)

• numthreads (i32) – Number of threads to be employed. (input)

• trmcode (Rescode[]) – The termination code for each task. (output)

• rcode (Rescode[]) – The response code for each task. (output)

Groups:

Optimization

Env.potrf

pub fn potrf
   (uplo : i32,
    n : i32,
    a : &mut[f64]) -> Result<(),String>
pub fn Env::potrf
   (&self,
    uplo : i32,
    n : i32,
    a : &mut[f64]) -> Result<(),String>

Computes a Cholesky factorization of a real symmetric positive definite dense matrix.

Parameters:

• uplo (Uplo) – Indicates whether the upper or lower triangular part of the matrix is stored. (input)

• n (i32) – Dimension of the symmetric matrix. (input)

• a (f64[]) – A symmetric matrix stored in column-major order. Only the lower or the upper triangular part is used, accordingly with the uplo parameter. It will contain the result on exit. (input/output)

Groups:

Linear algebra

Env.put_license_code

pub fn put_license_code(code : &[i32]) -> Result<(),String>
pub fn Env::put_license_code
   (&mut self,
    code : &[i32]) -> Result<(),String>

Input a runtime license code. This function has an effect only before the first optimization.

Parameters:

code (i32[]) – A runtime license code. (input)

Groups:

License system

Env.put_license_debug

pub fn put_license_debug(licdebug : i32) -> Result<(),String>
pub fn Env::put_license_debug
   (&mut self,
    licdebug : i32) -> Result<(),String>

Enables debug information for the license system. If licdebug is non-zero, then MOSEK will print debug info regarding the license checkout.

Parameters:

licdebug (i32) – Whether license checkout debug info should be printed. (input)

Groups:

License system

Env.put_license_path

pub fn put_license_path(licensepath : &str) -> Result<(),String>
pub fn Env::put_license_path
   (&mut self,
    licensepath : &str) -> Result<(),String>

Set the path to the license file. This function has an effect only before the first optimization.

Parameters:

licensepath (&str) – A path specifying where to search for the license. (input)

Groups:

License system

Env.put_license_wait

pub fn put_license_wait(licwait : i32) -> Result<(),String>
pub fn Env::put_license_wait
   (&mut self,
    licwait : i32) -> Result<(),String>

Control whether MOSEK should wait for an available license if no license is available. If licwait is non-zero, then MOSEK will wait for licwait-1 milliseconds between each check for an available license.

Parameters:

licwait (i32) – Whether MOSEK should wait for a license if no license is available. (input)

Groups:

License system

Env.reset_expiry_licenses

pub fn reset_expiry_licenses() -> Result<(),String>
pub fn Env::reset_expiry_licenses(&mut self) -> Result<(),String>

Reset the license expiry reporting startpoint.

Groups:

License system

Env.sparse_triangular_solve_dense

pub fn sparse_triangular_solve_dense
   (transposed : i32,
    lnzc : &[i32],
    lptrc : &[i64],
    lsubc : &[i32],
    lvalc : &[f64],
    b : &mut[f64]) -> Result<(),String>
pub fn Env::sparse_triangular_solve_dense
   (&self,
    transposed : i32,
    lnzc : &[i32],
    lptrc : &[i64],
    lsubc : &[i32],
    lvalc : &[f64],
    b : &mut[f64]) -> Result<(),String>

The function solves a triangular system of the form

\[L x = b\]

or

\[L^T x = b\]

where \(L\) is a sparse lower triangular nonsingular matrix. This implies in particular that diagonals in \(L\) are nonzero.

Parameters:

• transposed (Transpose) – Controls whether to use with \(L\) or \(L^T\). (input)

• lnzc (i32[]) – lnzc[j] is the number of nonzeros in column j. (input)

• lptrc (i64[]) – lptrc[j] is a pointer to the first row index and value in column j. (input)

• lsubc (i32[]) – Row indexes for each column stored sequentially. Must be stored in increasing order for each column. (input)

• lvalc (f64[]) – The value corresponding to the row index stored in lsubc. (input)

• b (f64[]) – The right-hand side of linear equation system to be solved as a dense vector. (input/output)

Groups:

Linear algebra

Env.syeig

pub fn syeig
   (uplo : i32,
    n : i32,
    a : &[f64],
    w : &mut[f64]) -> Result<(),String>
pub fn Env::syeig
   (&self,
    uplo : i32,
    n : i32,
    a : &[f64],
    w : &mut[f64]) -> Result<(),String>

Computes all eigenvalues of a real symmetric matrix \(A\). Given a matrix \(A\in\real^{n\times n}\) it returns a vector \(w\in\real^n\) containing the eigenvalues of \(A\).

Parameters:

• uplo (Uplo) – Indicates whether the upper or lower triangular part is used. (input)

• n (i32) – Dimension of the symmetric input matrix. (input)

• a (f64[]) – A symmetric matrix \(A\) stored in column-major order. Only the part indicated by uplo is used. (input)

• w (f64[]) – Array of length at least n containing the eigenvalues of \(A\). (output)

Groups:

Linear algebra

Env.syevd

pub fn syevd
   (uplo : i32,
    n : i32,
    a : &mut[f64],
    w : &mut[f64]) -> Result<(),String>
pub fn Env::syevd
   (&self,
    uplo : i32,
    n : i32,
    a : &mut[f64],
    w : &mut[f64]) -> Result<(),String>

Computes all the eigenvalues and eigenvectors a real symmetric matrix. Given the input matrix \(A\in \real^{n\times n}\), this function returns a vector \(w\in \real^n\) containing the eigenvalues of \(A\) and it also computes the eigenvectors of \(A\). Therefore, this function computes the eigenvalue decomposition of \(A\) as

\[A= U V U^T,\]

where \(V=\diag(w)\) and \(U\) contains the eigenvectors of \(A\).

Note that the matrix \(U\) overwrites the input data \(A\).

Parameters:

• uplo (Uplo) – Indicates whether the upper or lower triangular part is used. (input)

• n (i32) – Dimension of the symmetric input matrix. (input)

• a (f64[]) – A symmetric matrix \(A\) stored in column-major order. Only the part indicated by uplo is used. On exit it will be overwritten by the matrix \(U\). (input/output)

• w (f64[]) – Array of length at least n containing the eigenvalues of \(A\). (output)

Groups:

Linear algebra

Env.sym_nam_to_value

pub fn sym_nam_to_value(name : &str) -> Result<String,String>

Obtains the value corresponding to a symbolic name defined by MOSEK.

Parameters:

name (&str) – Symbolic name. (input)

Return:

value (String) – The corresponding value.

Groups:

Parameters

Env.syrk

pub fn syrk
   (uplo : i32,
    trans : i32,
    n : i32,
    k : i32,
    alpha : f64,
    a : &[f64],
    beta : f64,
    c : &mut[f64]) -> Result<(),String>
pub fn Env::syrk
   (&self,
    uplo : i32,
    trans : i32,
    n : i32,
    k : i32,
    alpha : f64,
    a : &[f64],
    beta : f64,
    c : &mut[f64]) -> Result<(),String>

Performs a symmetric rank-\(k\) update for a symmetric matrix.

Given a symmetric matrix \(C\in \real^{n\times n}\), two scalars \(\alpha,\beta\) and a matrix \(A\) of rank \(k\leq n\), it computes either

\[C := \alpha A A^T + \beta C,\]

when trans is set to Transpose::NO and \(A\in \real^{n\times k}\), or

\[C := \alpha A^T A + \beta C,\]

when trans is set to Transpose::YES and \(A\in \real^{k\times n}\).

Only the part of \(C\) indicated by uplo is used and only that part is updated with the result. It must not overlap with the other input arrays.

Parameters:

• uplo (Uplo) – Indicates whether the upper or lower triangular part of \(C\) is used. (input)

• trans (Transpose) – Indicates whether the matrix \(A\) must be transposed. (input)

• n (i32) – Specifies the order of \(C\). (input)

• k (i32) – Indicates the number of rows or columns of \(A\), depending on whether or not it is transposed, and its rank. (input)

• alpha (f64) – A scalar value multiplying the result of the matrix multiplication. (input)

• a (f64[]) – The pointer to the array storing matrix \(A\) in a column-major format. (input)

• beta (f64) – A scalar value that multiplies \(C\). (input)

• c (f64[]) – The pointer to the array storing matrix \(C\) in a column-major format. (input/output)

Groups:

Linear algebra

Env.task

pub fn Env::task
   (&self) -> Option<Task>

pub fn Env::task_with_capacity
   (&self,
    numcon : i32,
    numvar : i32) -> Option<Task>

Creates a new task in this environment.

Parameters:

• numcon (i32) – An optional hint about the maximal number of constraints in the task. (input)

• numvar (i32) – An optional hint about the maximal number of variables in the task. (input)

Return:

newtask (Task) – A new task.

Groups:

Environment and task management