class_docstr: Numerical matrix.
  
  Specify the dimensions or the data as a nested list.
  Elements default to zero.
  Use a flat list to create a column vector easily.
  
  The datatype of the context (mpf for mp, mpi for iv, and float for fp) is used to store the data.
  
  Creating matrices
  -----------------
  
  Matrices in mpmath are implemented using dictionaries. Only non-zero values
  are stored, so it is cheap to represent sparse matrices.
  
  The most basic way to create one is to use the ``matrix`` class directly.
  You can create an empty matrix specifying the dimensions:
  
      >>> from mpmath import *
      >>> mp.dps = 15
      >>> matrix(2)
      matrix(
      [['0.0', '0.0'],
       ['0.0', '0.0']])
      >>> matrix(2, 3)
      matrix(
      [['0.0', '0.0', '0.0'],
       ['0.0', '0.0', '0.0']])
  
  Calling ``matrix`` with one dimension will create a square matrix.
  
  To access the dimensions of a matrix, use the ``rows`` or ``cols`` keyword:
  
      >>> A = matrix(3, 2)
      >>> A
      matrix(
      [['0.0', '0.0'],
       ['0.0', '0.0'],
       ['0.0', '0.0']])
      >>> A.rows
      3
      >>> A.cols
      2
  
  You can also change the dimension of an existing matrix. This will set the
  new elements to 0. If the new dimension is smaller than before, the
  concerning elements are discarded:
  
      >>> A.rows = 2
      >>> A
      matrix(
      [['0.0', '0.0'],
       ['0.0', '0.0']])
  
  Internally ``mpmathify`` is used every time an element is set. This
  is done using the syntax A[row,column], counting from 0:
  
      >>> A = matrix(2)
      >>> A[1,1] = 1 + 1j
      >>> A
      matrix(
      [['0.0', '0.0'],
       ['0.0', mpc(real='1.0', imag='1.0')]])
  
  A more comfortable way to create a matrix lets you use nested lists:
  
      >>> matrix([[1, 2], [3, 4]])
      matrix(
      [['1.0', '2.0'],
       ['3.0', '4.0']])
  
  Convenient advanced functions are available for creating various standard
  matrices, see ``zeros``, ``ones``, ``diag``, ``eye``, ``randmatrix`` and
  ``hilbert``.
  
  Vectors
  .......
  
  Vectors may also be represented by the ``matrix`` class (with rows = 1 or cols = 1).
  For vectors there are some things which make life easier. A column vector can
  be created using a flat list, a row vectors using an almost flat nested list::
  
      >>> matrix([1, 2, 3])
      matrix(
      [['1.0'],
       ['2.0'],
       ['3.0']])
      >>> matrix([[1, 2, 3]])
      matrix(
      [['1.0', '2.0', '3.0']])
  
  Optionally vectors can be accessed like lists, using only a single index::
  
      >>> x = matrix([1, 2, 3])
      >>> x[1]
      mpf('2.0')
      >>> x[1,0]
      mpf('2.0')
  
  Other
  .....
  
  Like you probably expected, matrices can be printed::
  
      >>> print randmatrix(3) # doctest:+SKIP
      [ 0.782963853573023  0.802057689719883  0.427895717335467]
      [0.0541876859348597  0.708243266653103  0.615134039977379]
      [ 0.856151514955773  0.544759264818486  0.686210904770947]
  
  Use ``nstr`` or ``nprint`` to specify the number of digits to print::
  
      >>> nprint(randmatrix(5), 3) # doctest:+SKIP
      [2.07e-1  1.66e-1  5.06e-1  1.89e-1  8.29e-1]
      [6.62e-1  6.55e-1  4.47e-1  4.82e-1  2.06e-2]
      [4.33e-1  7.75e-1  6.93e-2  2.86e-1  5.71e-1]
      [1.01e-1  2.53e-1  6.13e-1  3.32e-1  2.59e-1]
      [1.56e-1  7.27e-2  6.05e-1  6.67e-2  2.79e-1]
  
  As matrices are mutable, you will need to copy them sometimes::
  
      >>> A = matrix(2)
      >>> A
      matrix(
      [['0.0', '0.0'],
       ['0.0', '0.0']])
      >>> B = A.copy()
      >>> B[0,0] = 1
      >>> B
      matrix(
      [['1.0', '0.0'],
       ['0.0', '0.0']])
      >>> A
      matrix(
      [['0.0', '0.0'],
       ['0.0', '0.0']])
  
  Finally, it is possible to convert a matrix to a nested list. This is very useful,
  as most Python libraries involving matrices or arrays (namely NumPy or SymPy)
  support this format::
  
      >>> B.tolist()
      [[mpf('1.0'), mpf('0.0')], [mpf('0.0'), mpf('0.0')]]
  
  
  Matrix operations
  -----------------
  
  You can add and subtract matrices of compatible dimensions::
  
      >>> A = matrix([[1, 2], [3, 4]])
      >>> B = matrix([[-2, 4], [5, 9]])
      >>> A + B
      matrix(
      [['-1.0', '6.0'],
       ['8.0', '13.0']])
      >>> A - B
      matrix(
      [['3.0', '-2.0'],
       ['-2.0', '-5.0']])
      >>> A + ones(3) # doctest:+ELLIPSIS
      Traceback (most recent call last):
        ...
      ValueError: incompatible dimensions for addition
  
  It is possible to multiply or add matrices and scalars. In the latter case the
  operation will be done element-wise::
  
      >>> A * 2
      matrix(
      [['2.0', '4.0'],
       ['6.0', '8.0']])
      >>> A / 4
      matrix(
      [['0.25', '0.5'],
       ['0.75', '1.0']])
      >>> A - 1
      matrix(
      [['0.0', '1.0'],
       ['2.0', '3.0']])
  
  Of course you can perform matrix multiplication, if the dimensions are
  compatible, using ``@`` (for Python >= 3.5) or ``*``. For clarity, ``@`` is
  recommended (`PEP 465 <https://www.python.org/dev/peps/pep-0465/>`), because
  the meaning of ``*`` is different in many other Python libraries such as NumPy.
  
      >>> A @ B # doctest:+SKIP
      matrix(
      [['8.0', '22.0'],
       ['14.0', '48.0']])
      >>> A * B # same as A @ B
      matrix(
      [['8.0', '22.0'],
       ['14.0', '48.0']])
      >>> matrix([[1, 2, 3]]) * matrix([[-6], [7], [-2]])
      matrix(
      [['2.0']])
  
  ..
      COMMENT: TODO: the above "doctest:+SKIP" may be removed as soon as we
      have dropped support for Python 3.5 and below.
  
  You can raise powers of square matrices::
  
      >>> A**2
      matrix(
      [['7.0', '10.0'],
       ['15.0', '22.0']])
  
  Negative powers will calculate the inverse::
  
      >>> A**-1
      matrix(
      [['-2.0', '1.0'],
       ['1.5', '-0.5']])
      >>> A * A**-1
      matrix(
      [['1.0', '1.0842021724855e-19'],
       ['-2.16840434497101e-19', '1.0']])
  
  
  
  Matrix transposition is straightforward::
  
      >>> A = ones(2, 3)
      >>> A
      matrix(
      [['1.0', '1.0', '1.0'],
       ['1.0', '1.0', '1.0']])
      >>> A.T
      matrix(
      [['1.0', '1.0'],
       ['1.0', '1.0'],
       ['1.0', '1.0']])
  
  Norms
  .....
  
  Sometimes you need to know how "large" a matrix or vector is. Due to their
  multidimensional nature it's not possible to compare them, but there are
  several functions to map a matrix or a vector to a positive real number, the
  so called norms.
  
  For vectors the p-norm is intended, usually the 1-, the 2- and the oo-norm are
  used.
  
      >>> x = matrix([-10, 2, 100])
      >>> norm(x, 1)
      mpf('112.0')
      >>> norm(x, 2)
      mpf('100.5186549850325')
      >>> norm(x, inf)
      mpf('100.0')
  
  Please note that the 2-norm is the most used one, though it is more expensive
  to calculate than the 1- or oo-norm.
  
  It is possible to generalize some vector norms to matrix norm::
  
      >>> A = matrix([[1, -1000], [100, 50]])
      >>> mnorm(A, 1)
      mpf('1050.0')
      >>> mnorm(A, inf)
      mpf('1001.0')
      >>> mnorm(A, 'F')
      mpf('1006.2310867787777')
  
  The last norm (the "Frobenius-norm") is an approximation for the 2-norm, which
  is hard to calculate and not available. The Frobenius-norm lacks some
  mathematical properties you might expect from a norm.
class_docstr_tok: ["Numerical","matrix",".","Specify","the","dimensions","or","the","data","as","a","nested","list",".","Elements","default","to","zero",".","Use","a","flat","list","to","create","a","column","vector","easily",".","The","datatype","of","the","context","(","mpf","for","mp",",","mpi","for","iv",",","and","float","for","fp",")","is","used","to","store","the","data",".","Creating","matrices","--","--","--","--","--","--","--","--","-","Matrices","in","mpmath","are","implemented","using","dictionaries",".","Only","non-zero","values","are","stored",",","so","it","is","cheap","to","represent","sparse","matrices",".","The","most","basic","way","to","create","one","is","to","use","the","``","matrix","``","class","directly",".","You","can","create","an","empty","matrix","specifying","the","dimensions",":",">",">",">","from","mpmath","import","*",">",">",">","mp.dps","=","15",">",">",">","matrix","(","2",")","matrix","(","[","[","'","0.0","'",",","'","0.0","'","]",",","[","'","0.0","'",",","'","0.0","'","]","]",")",">",">",">","matrix","(","2",",","3",")","matrix","(","[","[","'","0.0","'",",","'","0.0","'",",","'","0.0","'","]",",","[","'","0.0","'",",","'","0.0","'",",","'","0.0","'","]","]",")","Calling","``","matrix","``","with","one","dimension","will","create","a","square","matrix",".","To","access","the","dimensions","of","a","matrix",",","use","the","``","rows","``","or","``","cols","``","keyword",":",">",">",">","A","=","matrix","(","3",",","2",")",">",">",">","A","matrix","(","[","[","'","0.0","'",",","'","0.0","'","]",",","[","'","0.0","'",",","'","0.0","'","]",",","[","'","0.0","'",",","'","0.0","'","]","]",")",">",">",">","A.rows","3",">",">",">","A.cols","2","You","can","also","change","the","dimension","of","an","existing","matrix",".","This","will","set","the","new","elements","to","0",".","If","the","new","dimension","is","smaller","than","before",",","the","concerning","elements","are","discarded",":",">",">",">","A.rows","=","2",">",">",">","A","matrix","(","[","[","'","0.0","'",",","'","0.0","'","]",",","[","'","0.0","'",",","'","0.0","'","]","]",")","Internally","``","mpmathify","``","is","used","every","time","an","element","is","set",".","This","is","done","using","the","syntax","A","[","row",",","column","]",",","counting","from","0",":",">",">",">","A","=","matrix","(","2",")",">",">",">","A","[","1,1","]","=","1","+","1j",">",">",">","A","matrix","(","[","[","'","0.0","'",",","'","0.0","'","]",",","[","'","0.0","'",",","mpc","(","real=","'","1.0","'",",","imag=","'","1.0","'",")","]","]",")","A","more","comfortable","way","to","create","a","matrix","lets","you","use","nested","lists",":",">",">",">","matrix","(","[","[","1",",","2","]",",","[","3",",","4","]","]",")","matrix","(","[","[","'","1.0","'",",","'","2.0","'","]",",","[","'","3.0","'",",","'","4.0","'","]","]",")","Convenient","advanced","functions","are","available","for","creating","various","standard","matrices",",","see","``","zeros","``",",","``","ones","``",",","``","diag","``",",","``","eye","``",",","``","randmatrix","``","and","``","hilbert","``",".","Vectors",".......","Vectors","may","also","be","represented","by","the","``","matrix","``","class","(","with","rows","=","1","or","cols","=","1",")",".","For","vectors","there","are","some","things","which","make","life","easier",".","A","column","vector","can","be","created","using","a","flat","list",",","a","row","vectors","using","an","almost","flat","nested","list",":",":",">",">",">","matrix","(","[","1",",","2",",","3","]",")","matrix","(","[","[","'","1.0","'","]",",","[","'","2.0","'","]",",","[","'","3.0","'","]","]",")",">",">",">","matrix","(","[","[","1",",","2",",","3","]","]",")","matrix","(","[","[","'","1.0","'",",","'","2.0","'",",","'","3.0","'","]","]",")","Optionally","vectors","can","be","accessed","like","lists",",","using","only","a","single","index",":",":",">",">",">","x","=","matrix","(","[","1",",","2",",","3","]",")",">",">",">","x","[","1","]","mpf","(","'","2.0","'",")",">",">",">","x","[","1,0","]","mpf","(","'","2.0","'",")","Other",".....","Like","you","probably","expected",",","matrices","can","be","printed",":",":",">",">",">","print","randmatrix","(","3",")","#","doctest",":","+SKIP","[","0.782963853573023","0.802057689719883","0.427895717335467","]","[","0.0541876859348597","0.708243266653103","0.615134039977379","]","[","0.856151514955773","0.544759264818486","0.686210904770947","]","Use","``","nstr","``","or","``","nprint","``","to","specify","the","number","of","digits","to","print",":",":",">",">",">","nprint","(","randmatrix","(","5",")",",","3",")","#","doctest",":","+SKIP","[","2.07e-1","1.66e-1","5.06e-1","1.89e-1","8.29e-1","]","[","6.62e-1","6.55e-1","4.47e-1","4.82e-1","2.06e-2","]","[","4.33e-1","7.75e-1","6.93e-2","2.86e-1","5.71e-1","]","[","1.01e-1","2.53e-1","6.13e-1","3.32e-1","2.59e-1","]","[","1.56e-1","7.27e-2","6.05e-1","6.67e-2","2.79e-1","]","As","matrices","are","mutable",",","you","will","need","to","copy","them","sometimes",":",":",">",">",">","A","=","matrix","(","2",")",">",">",">","A","matrix","(","[","[","'","0.0","'",",","'","0.0","'","]",",","[","'","0.0","'",",","'","0.0","'","]","]",")",">",">",">","B","=","A.copy","(",")",">",">",">","B","[","0,0","]","=","1",">",">",">","B","matrix","(","[","[","'","1.0","'",",","'","0.0","'","]",",","[","'","0.0","'",",","'","0.0","'","]","]",")",">",">",">","A","matrix","(","[","[","'","0.0","'",",","'","0.0","'","]",",","[","'","0.0","'",",","'","0.0","'","]","]",")","Finally",",","it","is","possible","to","convert","a","matrix","to","a","nested","list",".","This","is","very","useful",",","as","most","Python","libraries","involving","matrices","or","arrays","(","namely","NumPy","or","SymPy",")","support","this","format",":",":",">",">",">","B.tolist","(",")","[","[","mpf","(","'","1.0","'",")",",","mpf","(","'","0.0","'",")","]",",","[","mpf","(","'","0.0","'",")",",","mpf","(","'","0.0","'",")","]","]","Matrix","operations","--","--","--","--","--","--","--","--","-","You","can","add","and","subtract","matrices","of","compatible","dimensions",":",":",">",">",">","A","=","matrix","(","[","[","1",",","2","]",",","[","3",",","4","]","]",")",">",">",">","B","=","matrix","(","[","[","-2",",","4","]",",","[","5",",","9","]","]",")",">",">",">","A","+","B","matrix","(","[","[","'-1.0","'",",","'","6.0","'","]",",","[","'","8.0","'",",","'13.0","'","]","]",")",">",">",">","A","-","B","matrix","(","[","[","'","3.0","'",",","'-2.0","'","]",",","[","'-2.0","'",",","'-5.0","'","]","]",")",">",">",">","A","+","ones","(","3",")","#","doctest",":","+ELLIPSIS","Traceback","(","most","recent","call","last",")",":","...","ValueError",":","incompatible","dimensions","for","addition","It","is","possible","to","multiply","or","add","matrices","and","scalars",".","In","the","latter","case","the","operation","will","be","done","element-wise",":",":",">",">",">","A","*","2","matrix","(","[","[","'","2.0","'",",","'","4.0","'","]",",","[","'","6.0","'",",","'","8.0","'","]","]",")",">",">",">","A","\/","4","matrix","(","[","[","'","0.25","'",",","'","0.5","'","]",",","[","'","0.75","'",",","'","1.0","'","]","]",")",">",">",">","A","-","1","matrix","(","[","[","'","0.0","'",",","'","1.0","'","]",",","[","'","2.0","'",",","'","3.0","'","]","]",")","Of","course","you","can","perform","matrix","multiplication",",","if","the","dimensions","are","compatible",",","using","``","@","``","(","for","Python",">","=","3.5",")","or","``","*","``",".","For","clarity",",","``","@","``","is","recommended","(","`","PEP","465","<","https",":","\/\/www.python.org\/dev\/peps\/pep-0465\/",">","`",")",",","because","the","meaning","of","``","*","``","is","different","in","many","other","Python","libraries","such","as","NumPy",".",">",">",">","A","@","B","#","doctest",":","+SKIP","matrix","(","[","[","'","8.0","'",",","'22.0","'","]",",","[","'14.0","'",",","'48.0","'","]","]",")",">",">",">","A","*","B","#","same","as","A","@","B","matrix","(","[","[","'","8.0","'",",","'22.0","'","]",",","[","'14.0","'",",","'48.0","'","]","]",")",">",">",">","matrix","(","[","[","1",",","2",",","3","]","]",")","*","matrix","(","[","[","-6","]",",","[","7","]",",","[","-2","]","]",")","matrix","(","[","[","'","2.0","'","]","]",")","..","COMMENT",":","TODO",":","the","above","``","doctest",":","+SKIP","''","may","be","removed","as","soon","as","we","have","dropped","support","for","Python","3.5","and","below",".","You","can","raise","powers","of","square","matrices",":",":",">",">",">","A","*","*","2","matrix","(","[","[","'","7.0","'",",","'10.0","'","]",",","[","'15.0","'",",","'22.0","'","]","]",")","Negative","powers","will","calculate","the","inverse",":",":",">",">",">","A","*","*","-1","matrix","(","[","[","'-2.0","'",",","'","1.0","'","]",",","[","'","1.5","'",",","'-0.5","'","]","]",")",">",">",">","A","*","A","*","*","-1","matrix","(","[","[","'","1.0","'",",","'","1.0842021724855e-19","'","]",",","[","'-2.16840434497101e-19","'",",","'","1.0","'","]","]",")","Matrix","transposition","is","straightforward",":",":",">",">",">","A","=","ones","(","2",",","3",")",">",">",">","A","matrix","(","[","[","'","1.0","'",",","'","1.0","'",",","'","1.0","'","]",",","[","'","1.0","'",",","'","1.0","'",",","'","1.0","'","]","]",")",">",">",">","A.T","matrix","(","[","[","'","1.0","'",",","'","1.0","'","]",",","[","'","1.0","'",",","'","1.0","'","]",",","[","'","1.0","'",",","'","1.0","'","]","]",")","Norms",".....","Sometimes","you","need","to","know","how","``","large","''","a","matrix","or","vector","is",".","Due","to","their","multidimensional","nature","it","'s","not","possible","to","compare","them",",","but","there","are","several","functions","to","map","a","matrix","or","a","vector","to","a","positive","real","number",",","the","so","called","norms",".","For","vectors","the","p-norm","is","intended",",","usually","the","1-",",","the","2-","and","the","oo-norm","are","used",".",">",">",">","x","=","matrix","(","[","-10",",","2",",","100","]",")",">",">",">","norm","(","x",",","1",")","mpf","(","'112.0","'",")",">",">",">","norm","(","x",",","2",")","mpf","(","'100.5186549850325","'",")",">",">",">","norm","(","x",",","inf",")","mpf","(","'100.0","'",")","Please","note","that","the","2-norm","is","the","most","used","one",",","though","it","is","more","expensive","to","calculate","than","the","1-","or","oo-norm",".","It","is","possible","to","generalize","some","vector","norms","to","matrix","norm",":",":",">",">",">","A","=","matrix","(","[","[","1",",","-1000","]",",","[","100",",","50","]","]",")",">",">",">","mnorm","(","A",",","1",")","mpf","(","'1050.0","'",")",">",">",">","mnorm","(","A",",","inf",")","mpf","(","'1001.0","'",")",">",">",">","mnorm","(","A",",","'","F","'",")","mpf","(","'1006.2310867787777","'",")","The","last","norm","(","the","``","Frobenius-norm","''",")","is","an","approximation","for","the","2-norm",",","which","is","hard","to","calculate","and","not","available",".","The","Frobenius-norm","lacks","some","mathematical","properties","you","might","expect","from","a","norm","."]
code: def __setitem__(self, key, value):
      # setitem function for mp matrix class with slice index enabled
      # it allows the following assingments
      #  scalar to a slice of the matrix
      # A[:,2:6] = 2.5
      #  submatrix to matrix (the value matrix should be the same size as the slice size)
      # A[3,:] = B   where A is n x m  and B is n x 1
      # Convert vector to matrix indexing
      if isinstance(key, int) or isinstance(key, slice):
          # only sufficent for vectors
          if self.__rows == 1:
              key = (0, key)
          elif self.__cols == 1:
              key = (key, 0)
          else:
              raise IndexError("insufficient indices for matrix")
      # Slice indexing
      if isinstance(key[0], slice) or isinstance(key[1], slice):
          # Rows
          if isinstance(key[0], slice):
              # Check bounds
              if (key[0].start is None or key[0].start >= 0) and (
                  key[0].stop is None or key[0].stop <= self.__rows + 1
              ):
                  # generate row indices
                  rows = xrange(*key[0].indices(self.__rows))
              else:
                  raise IndexError("Row index out of bounds")
          else:
              # Single row
              rows = [key[0]]
          # Columns
          if isinstance(key[1], slice):
              # Check bounds
              if (key[1].start is None or key[1].start >= 0) and (
                  key[1].stop is None or key[1].stop <= self.__cols + 1
              ):
                  # Generate column indices
                  columns = xrange(*key[1].indices(self.__cols))
              else:
                  raise IndexError("Column index out of bounds")
          else:
              # Single column
              columns = [key[1]]
          # Assign slice with a scalar
          if isinstance(value, self.ctx.matrix):
              # Assign elements to matrix if input and output dimensions match
              if len(rows) == value.rows and len(columns) == value.cols:
                  for i, x in enumerate(rows):
                      for j, y in enumerate(columns):
                          self.__set_element(
                              (x, y), value.__get_element((i, j))
                          )
              else:
                  raise ValueError("Dimensions do not match")
          else:
              # Assign slice with scalars
              value = self.ctx.convert(value)
              for i in rows:
                  for j in columns:
                      self.__set_element((i, j), value)
      else:
          # Single element assingment
          # Check bounds
          if key[0] >= self.__rows or key[1] >= self.__cols:
              raise IndexError("matrix index out of range")
          # Convert and store value
          value = self.ctx.convert(value)
          if value:  # only store non-zeros
              self.__data[key] = value
          elif key in self.__data:
              del self.__data[key]
  
      if self._LU:
          self._LU = None
      return
  
imports: from ..libmp.backend import xrange
  import warnings
label_desc: Use image node_id 11 for calling the _matrix obj's underlying member method code with example usage: obj.__setitem__(key, value) without return types