1    	/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
2    	/*                                                                           */
3    	/*                  This file is part of the class library                   */
4    	/*       SoPlex --- the Sequential object-oriented simPlex.                  */
5    	/*                                                                           */
6    	/*  Copyright (c) 1996-2023 Zuse Institute Berlin (ZIB)                      */
7    	/*                                                                           */
8    	/*  Licensed under the Apache License, Version 2.0 (the "License");          */
9    	/*  you may not use this file except in compliance with the License.         */
10   	/*  You may obtain a copy of the License at                                  */
11   	/*                                                                           */
12   	/*      http://www.apache.org/licenses/LICENSE-2.0                           */
13   	/*                                                                           */
14   	/*  Unless required by applicable law or agreed to in writing, software      */
15   	/*  distributed under the License is distributed on an "AS IS" BASIS,        */
16   	/*  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. */
17   	/*  See the License for the specific language governing permissions and      */
18   	/*  limitations under the License.                                           */
19   	/*                                                                           */
20   	/*  You should have received a copy of the Apache-2.0 license                */
21   	/*  along with SoPlex; see the file LICENSE. If not email to soplex@zib.de.  */
22   	/*                                                                           */
23   	/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
24   	
25   	/**@file  slinsolver_rational.h
26   	 * @brief Sparse Linear Solver virtual base class with Rational precision.
27   	 */
28   	#ifndef _SLINSOLVER_RATIONAL_H_
29   	#define _SLINSOLVER_RATIONAL_H_
30   	
31   	
32   	#include <assert.h>
33   	#include <string.h>
34   	
35   	#include "soplex/spxdefines.h"
36   	#include "soplex/svector.h"
37   	#include "soplex/ssvector.h"
38   	#include "soplex/dsvector.h"
39   	#include "soplex/vector.h"
40   	#include "soplex/didxset.h"
41   	
42   	namespace soplex
43   	{
44   	/**@brief   Sparse Linear Solver virtual base class with Rational precision.
45   	   @ingroup Algo
46   	
47   	   Class SLinSolverRational provides a class for solving sparse linear systems with
48   	   a matrix \f$A\f$ and arbitrary right-hand side vectors. For doing so, the
49   	   matrix must be first #load%ed to an #SLinSolverRational object as an array of
50   	   pointers to the \em column \ref SVectorRational "SVectorsRational" of this matrix.
51   	*/
52   	class SLinSolverRational
53   	{
54   	public:
55   	
56   	   //---------------------------------------
57   	   /**@name Types */
58   	   ///@{
59   	   /// status flags of the SLinSolverRational class.
60   	   enum Status
61   	   {
62   	      /** The SLinSolverRational is ready for solving linear systems with the
63   	          loaded matrix */
64   	      OK       = 0,
65   	      /** The loaded matrix allows only for instable solutions to be
66   	          computed */
67   	      INSTABLE = 1,
68   	      /// The loaded matrix is singular.
69   	      SINGULAR = 2,
70   	      /// No matrix has yet been loaded.
71   	      UNLOADED = 4,
72   	      /// An error has occurred.
73   	      ERROR    = 8,
74   	      /// The time limit has been hit
75   	      TIME     = 16
76   	   };
77   	   ///@}
78   	
79   	   //---------------------------------------
80   	   /**@name Miscellaneous */
81   	   ///@{
82   	   /// returns the name of the SLinSolverRational.
83   	   virtual const char* getName() const = 0;
84   	
85   	   /// returns the Status of the SLinSolverRational.
86   	   virtual Status status() const = 0;
87   	
88   	   /// unloads any matrix.
89   	   virtual void clear() = 0;
90   	
91   	   /// returns current memory consumption.
92   	   virtual int memory() const = 0;
93   	
94   	   /// returns dimension of loaded matrix.
95   	   virtual int dim() const = 0;
96   	
97   	   /// loads \p dim column vectors \p vec into the solver.
98   	   /** Initializes SLinSolverRational for the solution of linear systems
99   	       with the matrix consisting of \p dim column vectors given in \p vec.
100  	   */
101  	   virtual Status load(const SVectorRational* vec[], int dim) = 0;
102  	
103  	   /// returns a stability number (0: singularity, 1: perfect stability).
104  	   /** Returns a stability parameter between 0 and 1, where 0 indicates
105  	       singularity, while 1 indicates perfect stability.
106  	   */
107  	   virtual Rational stability() const = 0;
108  	
109  	   /// returns statistical information in form of a string.
110  	   virtual std::string statistics() const = 0;
111  	
112  	   /// Substitute column \p idx with \p subst.
113  	   /** The change method is used to modify the loaded matrix by substituting
114  	       column \p idx with the new vector \p subst. One may also pass the
115  	       optional parameter \p eta to the solution of #solveRight() if
116  	       readily  availabble. This may improve on the performance of the update.
117  	   */
118  	   virtual Status change(int idx, const SVectorRational& subst, const SSVectorRational* eta = 0) = 0;
119  	
120  	   /// consistency check.
121  	   virtual bool isConsistent() const = 0;
122  	
123  	   /// get number of factorizations
124  	   virtual int getFactorCount() const = 0;
125  	   ///@}
126  	
127  	
128  	   /**@name Solving linear systems
129  	      For solving linear systems with an SLinSolverRational object, it must
130  	      have previously been loaded with the matrix to use.
131  	
132  	      Two types of systems can be solved \f$A x = b\f$ and \f$x^T A = b^T\f$.
133  	      Method names related to the first and second type are solveRight() and
134  	      solveLeft(), respectively.
135  	
136  	      The methods receive their right hand-side vector \f$b\f$ as a
137  	      \c const parameter, that will hence be unchanged after termination.
138  	
139  	      Some methods are available with two parameters for right hand-side
140  	      vectors. Then two system are solved in one method invocation. This
141  	      should generally be faster than solving two systems seperately.
142  	
143  	      The result vector(s) are allways given as the first parameter(s). Two
144  	      types of result vectors are supported, VectorRational and SSVectorRational.
145  	   */
146  	   ///@{
147  	   /// Solves \f$Ax=b\f$.
148  	   virtual void solveRight(VectorRational& x, const VectorRational& b) /* const */ = 0;
149  	   /// Solves \f$Ax=b\f$.
150  	   virtual void solveRight(SSVectorRational& x, const SVectorRational& b) /* const */ = 0;
151  	
152  	   /** @brief Solves \f$Ax=b\f$.
153  	       Possibly sets up internal data structures suitable for an optimized
154  	       subsequent change() call with \f$b\f$ as entering column.
155  	   */
156  	   virtual void solveRight4update(SSVectorRational& x, const SVectorRational& b) = 0;
157  	
158  	   /// Solves \f$Ax=b\f$ and \f$Ay=d\f$.
159  	   virtual void solve2right4update(SSVectorRational& x,
160  	                                   VectorRational& y,
161  	                                   const SVectorRational& b,
162  	                                   SSVectorRational& d) = 0;
163  	   /// Solves \f$Ax=b\f$, \f$Ay=d\f$ and \f$Az=e\f$.
164  	   virtual void solve3right4update(SSVectorRational& x,
165  	                                   VectorRational& y,
166  	                                   VectorRational& z,
167  	                                   const SVectorRational& b,
168  	                                   SSVectorRational& d,
169  	                                   SSVectorRational& e) = 0;
170  	   /// solves \f$x^TA=b^T\f$.
171  	   virtual void solveLeft(VectorRational& x, const VectorRational& b) /* const */ = 0;
172  	   /// solves \f$x^TA=b^T\f$.
173  	   virtual void solveLeft(SSVectorRational& x, const SVectorRational& b) /* const */ = 0;
174  	   /// solves \f$x^TA=b^T\f$ and \f$x^TA=rhs2^T\f$ internally using \f$rhs2\f$.
175  	   virtual void solveLeft(SSVectorRational& x,
176  	                          VectorRational& two,
177  	                          const SVectorRational& b,
178  	                          SSVectorRational& rhs2) /* const */ = 0;
179  	   /// solves \f$x^TA=b^T\f$, \f$y^TA=d^T\f$ and \f$z^TA=e^T\f$
180  	   virtual void solveLeft(SSVectorRational& x, VectorRational& y, VectorRational& z,
181  	                          const SVectorRational& b, SSVectorRational& d, SSVectorRational& e) = 0;
182  	   ///@}
183  	
184  	
185  	   //---------------------------------------
186  	   /**@name Constructors / Destructors */
187  	   ///@{
188  	   /// default constructor
189  	   SLinSolverRational()
190  	   {}
191  	   /// destructor
192  	   virtual ~SLinSolverRational()
193  	   {}
194  	   /// clone function for polymorphism
195  	   virtual SLinSolverRational* clone() const = 0;
196  	   ///@}
197  	
198  	
199  	
200  	};
201  	
202  	} // namespace soplex
203  	#endif // _SLINSOLVER_RATIONAL_H_
204