class_docstr: A sparse matrix (a matrix with a large number of zero elements).
  
  Examples
  ========
  
  >>> from sympy import SparseMatrix, ones
  >>> SparseMatrix(2, 2, range(4))
  Matrix([
  [0, 1],
  [2, 3]])
  >>> SparseMatrix(2, 2, {(1, 1): 2})
  Matrix([
  [0, 0],
  [0, 2]])
  
  A SparseMatrix can be instantiated from a ragged list of lists:
  
  >>> SparseMatrix([[1, 2, 3], [1, 2], [1]])
  Matrix([
  [1, 2, 3],
  [1, 2, 0],
  [1, 0, 0]])
  
  For safety, one may include the expected size and then an error
  will be raised if the indices of any element are out of range or
  (for a flat list) if the total number of elements does not match
  the expected shape:
  
  >>> SparseMatrix(2, 2, [1, 2])
  Traceback (most recent call last):
  ...
  ValueError: List length (2) != rows*columns (4)
  
  Here, an error is not raised because the list is not flat and no
  element is out of range:
  
  >>> SparseMatrix(2, 2, [[1, 2]])
  Matrix([
  [1, 2],
  [0, 0]])
  
  But adding another element to the first (and only) row will cause
  an error to be raised:
  
  >>> SparseMatrix(2, 2, [[1, 2, 3]])
  Traceback (most recent call last):
  ...
  ValueError: The location (0, 2) is out of designated range: (1, 1)
  
  To autosize the matrix, pass None for rows:
  
  >>> SparseMatrix(None, [[1, 2, 3]])
  Matrix([[1, 2, 3]])
  >>> SparseMatrix(None, {(1, 1): 1, (3, 3): 3})
  Matrix([
  [0, 0, 0, 0],
  [0, 1, 0, 0],
  [0, 0, 0, 0],
  [0, 0, 0, 3]])
  
  Values that are themselves a Matrix are automatically expanded:
  
  >>> SparseMatrix(4, 4, {(1, 1): ones(2)})
  Matrix([
  [0, 0, 0, 0],
  [0, 1, 1, 0],
  [0, 1, 1, 0],
  [0, 0, 0, 0]])
  
  A ValueError is raised if the expanding matrix tries to overwrite
  a different element already present:
  
  >>> SparseMatrix(3, 3, {(0, 0): ones(2), (1, 1): 2})
  Traceback (most recent call last):
  ...
  ValueError: collision at (1, 1)
  
  See Also
  ========
  DenseMatrix
  MutableSparseMatrix
  ImmutableSparseMatrix
class_docstr_tok: ["A","sparse","matrix","(","a","matrix","with","a","large","number","of","zero","elements",")",".","Examples","========",">",">",">","from","sympy","import","SparseMatrix",",","ones",">",">",">","SparseMatrix","(","2",",","2",",","range","(","4",")",")","Matrix","(","[","[","0",",","1","]",",","[","2",",","3","]","]",")",">",">",">","SparseMatrix","(","2",",","2",",","{","(","1",",","1",")",":","2","}",")","Matrix","(","[","[","0",",","0","]",",","[","0",",","2","]","]",")","A","SparseMatrix","can","be","instantiated","from","a","ragged","list","of","lists",":",">",">",">","SparseMatrix","(","[","[","1",",","2",",","3","]",",","[","1",",","2","]",",","[","1","]","]",")","Matrix","(","[","[","1",",","2",",","3","]",",","[","1",",","2",",","0","]",",","[","1",",","0",",","0","]","]",")","For","safety",",","one","may","include","the","expected","size","and","then","an","error","will","be","raised","if","the","indices","of","any","element","are","out","of","range","or","(","for","a","flat","list",")","if","the","total","number","of","elements","does","not","match","the","expected","shape",":",">",">",">","SparseMatrix","(","2",",","2",",","[","1",",","2","]",")","Traceback","(","most","recent","call","last",")",":","...","ValueError",":","List","length","(","2",")","!","=","rows","*","columns","(","4",")","Here",",","an","error","is","not","raised","because","the","list","is","not","flat","and","no","element","is","out","of","range",":",">",">",">","SparseMatrix","(","2",",","2",",","[","[","1",",","2","]","]",")","Matrix","(","[","[","1",",","2","]",",","[","0",",","0","]","]",")","But","adding","another","element","to","the","first","(","and","only",")","row","will","cause","an","error","to","be","raised",":",">",">",">","SparseMatrix","(","2",",","2",",","[","[","1",",","2",",","3","]","]",")","Traceback","(","most","recent","call","last",")",":","...","ValueError",":","The","location","(","0",",","2",")","is","out","of","designated","range",":","(","1",",","1",")","To","autosize","the","matrix",",","pass","None","for","rows",":",">",">",">","SparseMatrix","(","None",",","[","[","1",",","2",",","3","]","]",")","Matrix","(","[","[","1",",","2",",","3","]","]",")",">",">",">","SparseMatrix","(","None",",","{","(","1",",","1",")",":","1",",","(","3",",","3",")",":","3","}",")","Matrix","(","[","[","0",",","0",",","0",",","0","]",",","[","0",",","1",",","0",",","0","]",",","[","0",",","0",",","0",",","0","]",",","[","0",",","0",",","0",",","3","]","]",")","Values","that","are","themselves","a","Matrix","are","automatically","expanded",":",">",">",">","SparseMatrix","(","4",",","4",",","{","(","1",",","1",")",":","ones","(","2",")","}",")","Matrix","(","[","[","0",",","0",",","0",",","0","]",",","[","0",",","1",",","1",",","0","]",",","[","0",",","1",",","1",",","0","]",",","[","0",",","0",",","0",",","0","]","]",")","A","ValueError","is","raised","if","the","expanding","matrix","tries","to","overwrite","a","different","element","already","present",":",">",">",">","SparseMatrix","(","3",",","3",",","{","(","0",",","0",")",":","ones","(","2",")",",","(","1",",","1",")",":","2","}",")","Traceback","(","most","recent","call","last",")",":","...","ValueError",":","collision","at","(","1",",","1",")","See","Also","========","DenseMatrix","MutableSparseMatrix","ImmutableSparseMatrix"]
code: def _handle_creation_inputs(cls, *args, **kwargs):
      if len(args) == 1 and isinstance(args[0], MatrixBase):
          rows = args[0].rows
          cols = args[0].cols
          smat = args[0].todok()
          return rows, cols, smat
  
      smat = {}
      # autosizing
      if len(args) == 2 and args[0] is None:
          args = [None, None, args[1]]
  
      if len(args) == 3:
          r, c = args[:2]
          if r is c is None:
              rows = cols = None
          elif None in (r, c):
              raise ValueError(
                  "Pass rows=None and no cols for autosizing."
              )
          else:
              rows, cols = as_int(args[0]), as_int(args[1])
  
          if isinstance(args[2], Callable):
              op = args[2]
  
              if None in (rows, cols):
                  raise ValueError(
                      "{} and {} must be integers for this "
                      "specification.".format(rows, cols)
                  )
  
              row_indices = [cls._sympify(i) for i in range(rows)]
              col_indices = [cls._sympify(j) for j in range(cols)]
  
              for i in row_indices:
                  for j in col_indices:
                      value = cls._sympify(op(i, j))
                      if value != cls.zero:
                          smat[i, j] = value
  
              return rows, cols, smat
  
          elif isinstance(args[2], (dict, Dict)):
  
              def update(i, j, v):
                  # update smat and make sure there are no collisions
                  if v:
                      if (i, j) in smat and v != smat[i, j]:
                          raise ValueError(
                              "There is a collision at {} for {} and {}.".format(
                                  (i, j), v, smat[i, j]
                              )
                          )
                      smat[i, j] = v
  
              # manual copy, copy.deepcopy() doesn't work
              for (r, c), v in args[2].items():
                  if isinstance(v, MatrixBase):
                      for (i, j), vv in v.todok().items():
                          update(r + i, c + j, vv)
                  elif isinstance(v, (list, tuple)):
                      _, _, smat = cls._handle_creation_inputs(
                          v, **kwargs
                      )
                      for i, j in smat:
                          update(r + i, c + j, smat[i, j])
                  else:
                      v = cls._sympify(v)
                      update(r, c, cls._sympify(v))
  
          elif is_sequence(args[2]):
              flat = not any(is_sequence(i) for i in args[2])
              if not flat:
                  _, _, smat = cls._handle_creation_inputs(
                      args[2], **kwargs
                  )
              else:
                  flat_list = args[2]
                  if len(flat_list) != rows * cols:
                      raise ValueError(
                          "The length of the flat list ({}) does not "
                          "match the specified size ({} * {}).".format(
                              len(flat_list), rows, cols
                          )
                      )
  
                  for i in range(rows):
                      for j in range(cols):
                          value = flat_list[i * cols + j]
                          value = cls._sympify(value)
                          if value != cls.zero:
                              smat[i, j] = value
  
          if rows is None:  # autosizing
              keys = smat.keys()
              rows = max([r for r, _ in keys]) + 1 if keys else 0
              cols = max([c for _, c in keys]) + 1 if keys else 0
  
          else:
              for i, j in smat.keys():
                  if i and i >= rows or j and j >= cols:
                      raise ValueError(
                          "The location {} is out of the designated range"
                          "[{}, {}]x[{}, {}]".format(
                              (i, j), 0, rows - 1, 0, cols - 1
                          )
                      )
  
          return rows, cols, smat
  
      elif len(args) == 1 and isinstance(args[0], (list, tuple)):
          # list of values or lists
          v = args[0]
          c = 0
          for i, row in enumerate(v):
              if not isinstance(row, (list, tuple)):
                  row = [row]
              for j, vv in enumerate(row):
                  if vv != cls.zero:
                      smat[i, j] = cls._sympify(vv)
              c = max(c, len(row))
          rows = len(v) if c else 0
          cols = c
          return rows, cols, smat
  
      else:
          # handle full matrix forms with _handle_creation_inputs
          rows, cols, mat = super()._handle_creation_inputs(*args)
          for i in range(rows):
              for j in range(cols):
                  value = mat[cols * i + j]
                  if value != cls.zero:
                      smat[i, j] = value
  
          return rows, cols, smat
  
imports: from collections.abc import Callable
  from sympy.core.containers import Dict
  from sympy.utilities.exceptions import sympy_deprecation_warning
  from sympy.utilities.iterables import is_sequence
  from sympy.utilities.misc import as_int
  from .matrixbase import MatrixBase
  from .repmatrix import MutableRepMatrix, RepMatrix
  from .utilities import _iszero
  from .decompositions import _liupc, _row_structure_symbolic_cholesky, _cholesky_sparse, _LDLdecomposition_sparse
  from .solvers import _lower_triangular_solve_sparse, _upper_triangular_solve_sparse
label_desc: Use image node_id 1 for calling the SparseRepMatrix obj's underlying member method code with example usage: obj._handle_creation_inputs(cls) and returns: rows,  cols,  smat, rows,  cols,  smat, rows,  cols,  smat, rows,  cols,  smat, rows,  cols,  smat