<h3 dir="auto">Describe your issue.</h3>
<p dir="auto">The <code class="notranslate">spdiags</code> creation function allows the diagonal offsets to be greater than the matrix shape, which results in an empty array in <code class="notranslate">dia</code> format with a negative number of non-zero values:</p>
<div class="highlight highlight-source-python notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="&gt;&gt;&gt; m = n = 3  # Square, 3x3
&gt;&gt;&gt; k = -5  # diagonal offset
&gt;&gt;&gt; data = np.ones(m)
&gt;&gt;&gt; a = sp.sparse.spdiags(data, diags=k, m=m, n=n)
&gt;&gt;&gt; a
&lt;3x3 sparse matrix of type '&lt;class 'numpy.float64'&gt;'
        with -2 stored elements (1 diagonals) in DIAgonal format&gt;
&gt;&gt;&gt; a.toarray()  # 3x3 array of zeros
array([[0., 0., 0.],
       [0., 0., 0.],
       [0., 0., 0.]])"><pre class="notranslate"><span class="pl-c1">&gt;&gt;</span><span class="pl-c1">&gt;</span> <span class="pl-s1">m</span> <span class="pl-c1">=</span> <span class="pl-s1">n</span> <span class="pl-c1">=</span> <span class="pl-c1">3</span>  <span class="pl-c"># Square, 3x3</span>
<span class="pl-c1">&gt;&gt;</span><span class="pl-c1">&gt;</span> <span class="pl-s1">k</span> <span class="pl-c1">=</span> <span class="pl-c1">-</span><span class="pl-c1">5</span>  <span class="pl-c"># diagonal offset</span>
<span class="pl-c1">&gt;&gt;</span><span class="pl-c1">&gt;</span> <span class="pl-s1">data</span> <span class="pl-c1">=</span> <span class="pl-s1">np</span>.<span class="pl-en">ones</span>(<span class="pl-s1">m</span>)
<span class="pl-c1">&gt;&gt;</span><span class="pl-c1">&gt;</span> <span class="pl-s1">a</span> <span class="pl-c1">=</span> <span class="pl-s1">sp</span>.<span class="pl-s1">sparse</span>.<span class="pl-en">spdiags</span>(<span class="pl-s1">data</span>, <span class="pl-s1">diags</span><span class="pl-c1">=</span><span class="pl-s1">k</span>, <span class="pl-s1">m</span><span class="pl-c1">=</span><span class="pl-s1">m</span>, <span class="pl-s1">n</span><span class="pl-c1">=</span><span class="pl-s1">n</span>)
<span class="pl-c1">&gt;&gt;</span><span class="pl-c1">&gt;</span> <span class="pl-s1">a</span>
<span class="pl-c1">&lt;</span><span class="pl-c1">3</span><span class="pl-s1">x3</span> <span class="pl-s1">sparse</span> <span class="pl-s1">matrix</span> <span class="pl-s1">of</span> <span class="pl-s1">type</span> <span class="pl-s">'&lt;class '</span><span class="pl-s1">numpy</span>.<span class="pl-s1">float64</span><span class="pl-s">'&gt;'</span>
        <span class="pl-k">with</span> <span class="pl-c1">-</span><span class="pl-c1">2</span> <span class="pl-s1">stored</span> <span class="pl-en">elements</span> (<span class="pl-c1">1</span> <span class="pl-s1">diagonals</span>) <span class="pl-c1">in</span> <span class="pl-v">DIAgonal</span> <span class="pl-s1">format</span><span class="pl-c1">&gt;</span>
<span class="pl-c1">&gt;&gt;</span><span class="pl-c1">&gt;</span> <span class="pl-s1">a</span>.<span class="pl-en">toarray</span>()  <span class="pl-c"># 3x3 array of zeros</span>
<span class="pl-s1">array</span>([[<span class="pl-c1">0.</span>, <span class="pl-c1">0.</span>, <span class="pl-c1">0.</span>],
       [<span class="pl-c1">0.</span>, <span class="pl-c1">0.</span>, <span class="pl-c1">0.</span>],
       [<span class="pl-c1">0.</span>, <span class="pl-c1">0.</span>, <span class="pl-c1">0.</span>]])</pre></div>
<p dir="auto">Both <code class="notranslate">identity</code> and <code class="notranslate">eye</code> are implemented using <code class="notranslate">spdiags</code> (at least for some formats), which means that this behavior extends to those functions as well.</p>
<p dir="auto">This behavior is not strictly incorrect, but is likely not what users want nor expect. <code class="notranslate">diags</code>, which the documentation notes is preferred over <code class="notranslate">spdiags</code>, explicitly validates that the diagonal offset is less than the minimum dimension of the requested shape:</p>
<div class="highlight highlight-source-python notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="&gt;&gt;&gt; sp.sparse.diags([data], offsets=[k], shape=(m, n))
Traceback (most recent call last)
   ...
ValueError: Offset -5 (index 0) out of bounds"><pre class="notranslate"><span class="pl-c1">&gt;&gt;</span><span class="pl-c1">&gt;</span> <span class="pl-s1">sp</span>.<span class="pl-s1">sparse</span>.<span class="pl-en">diags</span>([<span class="pl-s1">data</span>], <span class="pl-s1">offsets</span><span class="pl-c1">=</span>[<span class="pl-s1">k</span>], <span class="pl-s1">shape</span><span class="pl-c1">=</span>(<span class="pl-s1">m</span>, <span class="pl-s1">n</span>))
<span class="pl-v">Traceback</span> (<span class="pl-s1">most</span> <span class="pl-s1">recent</span> <span class="pl-s1">call</span> <span class="pl-s1">last</span>)
   ...
<span class="pl-v">ValueError</span>: <span class="pl-v">Offset</span> <span class="pl-c1">-</span><span class="pl-c1">5</span> (<span class="pl-s1">index</span> <span class="pl-c1">0</span>) <span class="pl-s1">out</span> <span class="pl-s1">of</span> <span class="pl-s1">bounds</span></pre></div>
<h3 dir="auto">Proposed change</h3>
<p dir="auto">I propose to modify <code class="notranslate">eye</code> and <code class="notranslate">identity</code> to use <code class="notranslate">diags</code> instead of <code class="notranslate">spdiags</code>. This will change behavior so that <code class="notranslate">eye</code> and <code class="notranslate">identity</code> will raise when the diagonal offset is greater than the shape.</p>
<h3 dir="auto">Reproducing Code Example</h3>
<div class="highlight highlight-source-python notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="See above"><pre class="notranslate"><span class="pl-v">See</span> <span class="pl-s1">above</span></pre></div>
<h3 dir="auto">Error message</h3>
<div class="highlight highlight-source-shell notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="N/A"><pre class="notranslate">N/A</pre></div>
<h3 dir="auto">SciPy/NumPy/Python version and system information</h3>
<div class="highlight highlight-source-shell notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="1.11.0.dev0+2204.675b17e 1.24.3 sys.version_info(major=3, minor=11, micro=3, releaselevel='final', serial=0)
Build Dependencies:
  blas:
    detection method: pkgconfig
    found: true
    include directory: /usr/include
    lib directory: /usr/lib
    name: openblas
    openblas configuration: USE_64BITINT= DYNAMIC_ARCH= DYNAMIC_OLDER= NO_CBLAS= NO_LAPACK=0
      NO_LAPACKE= NO_AFFINITY=1 USE_OPENMP=1 HASWELL MAX_THREADS=8
    pc file directory: /usr/lib/pkgconfig
    version: 0.3.21
  lapack:
    detection method: pkgconfig
    found: true
    include directory: /usr/include
    lib directory: /usr/lib
    name: openblas
    openblas configuration: USE_64BITINT= DYNAMIC_ARCH= DYNAMIC_OLDER= NO_CBLAS= NO_LAPACK=0
      NO_LAPACKE= NO_AFFINITY=1 USE_OPENMP=1 HASWELL MAX_THREADS=8
    pc file directory: /usr/lib/pkgconfig
    version: 0.3.21
  pybind11:
    detection method: config-tool
    include directory: unknown
    name: pybind11
    version: 2.10.4
Compilers:
  c:
    commands: ccache, cc
    linker: ld.bfd
    name: gcc
    version: 13.1.1
  c++:
    commands: ccache, c++
    linker: ld.bfd
    name: gcc
    version: 13.1.1
  cython:
    commands: cython
    linker: cython
    name: cython
    version: 0.29.35
  fortran:
    commands: gfortran
    linker: ld.bfd
    name: gcc
    version: 13.1.1
  pythran:
    include directory: ../../../.virtualenvs/sp-dev/lib/python3.11/site-packages/pythran
    version: 0.13.1
Machine Information:
  build:
    cpu: x86_64
    endian: little
    family: x86_64
    system: linux
  cross-compiled: false
  host:
    cpu: x86_64
    endian: little
    family: x86_64
    system: linux
Python Information:
  path: /home/ross/.virtualenvs/sp-dev/bin/python
  version: '3.11'"><pre class="notranslate">1.11.0.dev0+2204.675b17e 1.24.3 sys.version_info(major=3, minor=11, micro=3, releaselevel=<span class="pl-s"><span class="pl-pds">'</span>final<span class="pl-pds">'</span></span>, serial=0)
Build Dependencies:
  blas:
    detection method: pkgconfig
    found: <span class="pl-c1">true</span>
    include directory: /usr/include
    lib directory: /usr/lib
    name: openblas
    openblas configuration: USE_64BITINT= DYNAMIC_ARCH= DYNAMIC_OLDER= NO_CBLAS= NO_LAPACK=0
      NO_LAPACKE= NO_AFFINITY=1 USE_OPENMP=1 HASWELL MAX_THREADS=8
    pc file directory: /usr/lib/pkgconfig
    version: 0.3.21
  lapack:
    detection method: pkgconfig
    found: <span class="pl-c1">true</span>
    include directory: /usr/include
    lib directory: /usr/lib
    name: openblas
    openblas configuration: USE_64BITINT= DYNAMIC_ARCH= DYNAMIC_OLDER= NO_CBLAS= NO_LAPACK=0
      NO_LAPACKE= NO_AFFINITY=1 USE_OPENMP=1 HASWELL MAX_THREADS=8
    pc file directory: /usr/lib/pkgconfig
    version: 0.3.21
  pybind11:
    detection method: config-tool
    include directory: unknown
    name: pybind11
    version: 2.10.4
Compilers:
  c:
    commands: ccache, cc
    linker: ld.bfd
    name: gcc
    version: 13.1.1
  c++:
    commands: ccache, c++
    linker: ld.bfd
    name: gcc
    version: 13.1.1
  cython:
    commands: cython
    linker: cython
    name: cython
    version: 0.29.35
  fortran:
    commands: gfortran
    linker: ld.bfd
    name: gcc
    version: 13.1.1
  pythran:
    include directory: ../../../.virtualenvs/sp-dev/lib/python3.11/site-packages/pythran
    version: 0.13.1
Machine Information:
  build:
    cpu: x86_64
    endian: little
    family: x86_64
    system: linux
  cross-compiled: <span class="pl-c1">false</span>
  host:
    cpu: x86_64
    endian: little
    family: x86_64
    system: linux
Python Information:
  path: /home/ross/.virtualenvs/sp-dev/bin/python
  version: <span class="pl-s"><span class="pl-pds">'</span>3.11<span class="pl-pds">'</span></span></pre></div>
<p dir="auto">Deprecated in documentation only since <a class="issue-link js-issue-link" data-error-text="Failed to load title" data-id="544444888" data-permission-text="Title is private" data-url="https://github.com/scipy/scipy/issues/11304" data-hovercard-type="pull_request" data-hovercard-url="/scipy/scipy/pull/11304/hovercard" href="https://github.com/scipy/scipy/pull/11304">#11304</a></p>
<p dir="auto">CC <a class="user-mention notranslate" data-hovercard-type="user" data-hovercard-url="/users/ilayn/hovercard" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/ilayn">@ilayn</a></p>