-Additionally, this project maintains compatibility with the
-[`numpy.ndarray`][] interface rather than the
-[`numpy.matrix`][] interface used in
-[`scipy.sparse`][]
-
-These differences make this project useful in certain situations where
-scipy.sparse matrices are not well suited, but it should not be
-considered a full replacement. The data structures in pydata/sparse
-complement and can be used in conjunction with the fast linear algebra
-routines inside [`scipy.sparse`][]. A format conversion or copy may be
-required.
-
-## Motivation
-
-Sparse arrays, or arrays that are mostly empty or filled with zeros, are
-common in many scientific applications. To save space we often avoid
-storing these arrays in traditional dense formats, and instead choose
-different data structures. Our choice of data structure can
-significantly affect our storage and computational costs when working
-with these arrays.
-
-## Design
-
-The main data structure in this library follows the [Coordinate List
-(COO)](https://en.wikipedia.org/wiki/Sparse_matrix#Coordinate_list_(COO))
-layout for sparse matrices, but extends it to multiple dimensions.
-
-The COO layout, which stores the row index, column index, and value of
-every element:
-
-
-| row | col | data |
-|-----|-----|------|
-| 0 | 0 | 10 |
-| 0 | 2 | 13 |
-| 1 | 3 | 9 |
-| 3 | 8 | 21 |
-
-It is straightforward to extend the COO layout to an arbitrary number of
-dimensions:
-
+ {width=10%, align=left}
+
Introduction
+ { .card }
-| dim1 | dim2 | dim3 | \... | data |
-|------|------|------|------|------|
-| 0 | 0 | 0 | . | 10 |
-| 0 | 0 | 3 | . | 13 |
-| 0 | 2 | 2 | . | 9 |
-| 3 | 1 | 4 | . | 21 |
+ {width=10%, align=left}
+
Install
+ { .card }
-This makes it easy to *store* a multidimensional sparse array, but we
-still need to reimplement all of the array operations like transpose,
-reshape, slicing, tensordot, reductions, etc., which can be challenging
-in general.
+ {width=10%, align=left}
+
Tutorials
+ { .card }
-This library also includes several other data structures. Similar to
-COO, the [Dictionary of Keys
-(DOK)](https://en.wikipedia.org/wiki/Sparse_matrix#Dictionary_of_keys_(DOK))
-format for sparse matrices generalizes well to an arbitrary number of
-dimensions. DOK is well-suited for writing and mutating. Most other
-operations are not supported for DOK. A common workflow may involve
-writing an array with DOK and then converting to another format for
-other operations.
+ {width=10%, align=left}
+
How-to guides
+ { .card }
-The [Compressed Sparse Row/Column
-(CSR/CSC)](https://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_column_(CSC_or_CCS))
-formats are widely used in scientific computing are now supported by
-pydata/sparse. The CSR/CSC formats excel at compression and mathematical
-operations. While these formats are restricted to two dimensions,
-pydata/sparse supports the GCXS sparse array format, based on [GCRS/GCCS
-from](https://ieeexplore.ieee.org/abstract/document/7237032/similar#similar)
-which generalizes CSR/CSC to n-dimensional arrays. Like their
-two-dimensional CSR/CSC counterparts, GCXS arrays compress well. Whereas
-the storage cost of COO depends heavily on the number of dimensions of
-the array, the number of dimensions only minimally affects the storage
-cost of GCXS arrays, which results in favorable compression ratios
-across many use cases.
+ {width=10%, align=left}
+
API
+ { .card }
-Together these formats cover a wide array of applications of sparsity.
-Additionally, with each format complying with the
-[`numpy.ndarray`][] interface and following
-the appropriate dispatching protocols, pydata/sparse arrays can interact
-with other array libraries and seamlessly take part in
-pydata-ecosystem-based workflows.
-## LICENSE
+ {width=10%, align=left}
+
Contributing
+ { .card }
-This library is licensed under BSD-3.
+
diff --git a/docs/introduction.md b/docs/introduction.md
new file mode 100644
index 00000000..fcead3ce
--- /dev/null
+++ b/docs/introduction.md
@@ -0,0 +1,97 @@
+# Sparse
+
+This implements sparse arrays of arbitrary dimension on top of
+[numpy][] and
+[`scipy.sparse`][]. It generalizes the
+[`scipy.sparse.coo_matrix`][] and
+[`scipy.sparse.dok_matrix`][] layouts, but
+extends beyond just rows and columns to an arbitrary number of
+dimensions.
+
+Additionally, this project maintains compatibility with the
+[`numpy.ndarray`][] interface rather than the
+[`numpy.matrix`][] interface used in
+[`scipy.sparse`][]
+
+These differences make this project useful in certain situations where
+scipy.sparse matrices are not well suited, but it should not be
+considered a full replacement. The data structures in pydata/sparse
+complement and can be used in conjunction with the fast linear algebra
+routines inside [`scipy.sparse`][]. A format conversion or copy may be
+required.
+
+## Motivation
+
+Sparse arrays, or arrays that are mostly empty or filled with zeros, are
+common in many scientific applications. To save space we often avoid
+storing these arrays in traditional dense formats, and instead choose
+different data structures. Our choice of data structure can
+significantly affect our storage and computational costs when working
+with these arrays.
+
+## Design
+
+The main data structure in this library follows the [Coordinate List
+(COO)](https://en.wikipedia.org/wiki/Sparse_matrix#Coordinate_list_(COO))
+layout for sparse matrices, but extends it to multiple dimensions.
+
+The COO layout, which stores the row index, column index, and value of
+every element:
+
+
+| row | col | data |
+|-----|-----|------|
+| 0 | 0 | 10 |
+| 0 | 2 | 13 |
+| 1 | 3 | 9 |
+| 3 | 8 | 21 |
+
+It is straightforward to extend the COO layout to an arbitrary number of
+dimensions:
+
+
+| dim1 | dim2 | dim3 | \... | data |
+|------|------|------|------|------|
+| 0 | 0 | 0 | . | 10 |
+| 0 | 0 | 3 | . | 13 |
+| 0 | 2 | 2 | . | 9 |
+| 3 | 1 | 4 | . | 21 |
+
+This makes it easy to *store* a multidimensional sparse array, but we
+still need to reimplement all of the array operations like transpose,
+reshape, slicing, tensordot, reductions, etc., which can be challenging
+in general.
+
+This library also includes several other data structures. Similar to
+COO, the [Dictionary of Keys
+(DOK)](https://en.wikipedia.org/wiki/Sparse_matrix#Dictionary_of_keys_(DOK))
+format for sparse matrices generalizes well to an arbitrary number of
+dimensions. DOK is well-suited for writing and mutating. Most other
+operations are not supported for DOK. A common workflow may involve
+writing an array with DOK and then converting to another format for
+other operations.
+
+The [Compressed Sparse Row/Column
+(CSR/CSC)](https://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_column_(CSC_or_CCS))
+formats are widely used in scientific computing are now supported by
+pydata/sparse. The CSR/CSC formats excel at compression and mathematical
+operations. While these formats are restricted to two dimensions,
+pydata/sparse supports the GCXS sparse array format, based on [GCRS/GCCS
+from](https://ieeexplore.ieee.org/abstract/document/7237032/similar#similar)
+which generalizes CSR/CSC to n-dimensional arrays. Like their
+two-dimensional CSR/CSC counterparts, GCXS arrays compress well. Whereas
+the storage cost of COO depends heavily on the number of dimensions of
+the array, the number of dimensions only minimally affects the storage
+cost of GCXS arrays, which results in favorable compression ratios
+across many use cases.
+
+Together these formats cover a wide array of applications of sparsity.
+Additionally, with each format complying with the
+[`numpy.ndarray`][] interface and following
+the appropriate dispatching protocols, pydata/sparse arrays can interact
+with other array libraries and seamlessly take part in
+pydata-ecosystem-based workflows.
+
+## LICENSE
+
+This library is licensed under BSD-3.
diff --git a/mkdocs.yml b/mkdocs.yml
index 83b9052a..62c60ac1 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,20 +1,26 @@
site_name: sparse
repo_url: https://github.com/pydata/sparse.git
edit_uri: edit/main/docs/
+#use_directory_urls: false
theme:
name: material
palette:
- primary: black
+ primary: custom
+ accent: cyan
font: false #avoid Google Fonts to adhere to data privacy regulations
logo: assets/images/logo.png
favicon: assets/images/logo.svg
features:
+ - navigation.tabs
+ - navigation.tabs.sticky
- navigation.tracking
- navigation.instant
- navigation.instant.progress
- navigation.prune
- navigation.footer
- navigation.indexes
+ - navigation.expand
+ - navigation.top # adds a back-to-top button when user scrolls up
- content.code.copy
markdown_extensions:
@@ -27,7 +33,8 @@ markdown_extensions:
toc_depth: 2
- pymdownx.arithmatex: # To display math content with KaTex
generic: true
- - attr_list # To be able to link to a header on another page
+ - attr_list # To be able to link to a header on another page, use grids
+ - md_in_html # Used for grids
extra_javascript:
- javascripts/katex.js
@@ -39,39 +46,54 @@ extra_css:
- css/mkdocstrings.css
plugins:
-- search
-- section-index
-- autorefs
-- gen-files:
- scripts:
- - scripts/gen_ref_pages.py
-- literate-nav
-- mkdocstrings:
- handlers:
- python:
- import:
- - https://numpy.org/doc/stable/objects.inv
- - https://docs.python.org/3/objects.inv
- - https://docs.scipy.org/doc/scipy/objects.inv
- options:
- inherited_members: yes
- show_root_members_full_path: false
- show_if_no_docstring: true
- members_order: source
- docstring_style: numpy
- show_source: true
- filters: ["!^_"]
+ - search
+ - section-index
+ - autorefs
+ - gen-files:
+ scripts:
+ - scripts/gen_ref_pages.py
+ - literate-nav
+ - mkdocstrings:
+ handlers:
+ python:
+ import:
+ - https://numpy.org/doc/stable/objects.inv
+ - https://docs.python.org/3/objects.inv
+ - https://docs.scipy.org/doc/scipy/objects.inv
+ options:
+ inherited_members: yes
+ show_root_members_full_path: false
+ show_if_no_docstring: true
+ members_order: source
+ docstring_style: numpy
+ show_source: true
+ filters: ["!^_"]
+ group_by_category: true
+ show_category_heading: true
+
+ - mkdocs-jupyter:
+ include_source: True
nav:
-- index.md
-- install.md
-- quickstart.md
-- construct.md
-- operations.md
-- API:
- - api/*
-- roadmap.md
-# - completed-tasks.md
-- contributing.md
-- changelog.md
-- conduct.md
+ - Home:
+ - index.md
+ - Introduction:
+ - introduction.md
+ - Install:
+ - install.md
+ - Tutorials: #examples/sparse_finch.ipynb
+ - examples.md
+ - examples/sparse_finch.ipynb
+ - How to guides:
+ - how-to-guides.md
+ - quickstart.md
+ - construct.md
+ - operations.md
+ - API:
+ - api/*
+ - Contributing:
+ - contributing.md
+ - roadmap.md
+ - completed-tasks.md
+ - changelog.md
+ - conduct.md
diff --git a/pyproject.toml b/pyproject.toml
index 5630509a..4e83392f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -34,6 +34,7 @@ docs = [
"mkdocs-gen-files",
"mkdocs-literate-nav",
"mkdocs-section-index",
+ "mkdocs-jupyter",
"scipy",
]
tests = [
diff --git a/sparse/numba_backend/_coo/core.py b/sparse/numba_backend/_coo/core.py
index 91105a1e..0a5baefc 100644
--- a/sparse/numba_backend/_coo/core.py
+++ b/sparse/numba_backend/_coo/core.py
@@ -486,7 +486,7 @@ def from_iter(cls, x, shape=None, fill_value=None, dtype=None):
Examples
--------
- You can convert items of the format ``[`sparse.COO`][].
+ You can convert items of the format [`sparse.COO`][].
Here, the first part represents the coordinate and the second part represents the value.
>>> x = [((0, 0), 1), ((1, 1), 1)]
@@ -511,7 +511,7 @@ def from_iter(cls, x, shape=None, fill_value=None, dtype=None):
array([[1, 0],
[0, 1]])
- You can also pass in a [collections.abc.Iterator][] object.
+ You can also pass in a [`collections.abc.Iterator`][] object.
>>> x = [((0, 0), 1), ((1, 1), 1)].__iter__()
>>> s = COO.from_iter(x)