docs: update masked tensor section and add references and improve AI disclosure

Author: theo-barfoot

paper/jats/paper.jats

@@ -159,11 +159,13 @@ a Creative Commons Attribution 4.0 International License (CC BY
   <p>PyTorch also provides <monospace>MaskedTensor</monospace>, which
   distinguishes specified and unspecified elements and is conceptually
   closer to the constrained-subspace interpretation of sparsity.
-  However, <monospace>MaskedTensor</monospace> remains at prototype
-  stage with incomplete operator coverage, and storing a full boolean
-  mask incurs a significant memory overhead, partially negating the
-  memory benefits of sparse index-based representations for large-scale
-  problems.</p>
+  However, PyTorch classifies the API as prototype stage, operator
+  support is limited, and each <monospace>MaskedTensor</monospace>
+  stores a separate mask tensor matching the data tensor’s size and
+  storage format, introducing additional mask-storage overhead
+  (<xref alt="PyTorch Contributors, 2026b" rid="ref-pytorch_maskedtensor" ref-type="bibr">PyTorch
+  Contributors, 2026b</xref>,
+  <xref alt="2026a" rid="ref-pytorch_maskedtensor_sparsity" ref-type="bibr">2026a</xref>).</p>
   <p>Other libraries provide efficient sparse kernels but do not
   directly solve “sparsity-preserving gradients in PyTorch”: SciPy
   (<xref alt="Virtanen et al., 2020" rid="ref-scipy" ref-type="bibr">Virtanen
@@ -410,15 +412,28 @@ SMVN(torch.zeros(n), torch.ones(n), scale_tril=L).rsample().sum().backward()</co
 </sec>
 <sec id="ai-usage-disclosure">
   <title>AI usage disclosure</title>
-  <p>Generative AI tools were used during development of this software
-  and manuscript. Various large language models were used to assist with
-  code generation, refactoring, and test scaffolding for portions of the
-  codebase, and AI assistance was used to draft and edit parts of the
-  documentation and this manuscript. The repository was initiated prior
-  to widespread AI coding assistant adoption, with AI tools incorporated
-  during later development phases. All AI-assisted outputs were
-  reviewed, edited, and validated by the human authors, who take
-  responsibility for the final software and paper.</p>
+  <p>Generative AI tools were used intermittently during later
+  development and maintainence of the software and preparation of the
+  documentation and manuscript. This is a best-effort retrospective
+  disclosure because exact provider-side model snapshots were not
+  recorded contemporaneously for every historical interaction. Based on
+  the authors’ records and recollection, and on commit dates relative to
+  public model-release dates, OpenAI ChatGPT with GPT-4, GPT-4o, and
+  GPT-5-series models was used for code suggestions, refactoring,
+  debugging, test scaffolding, and documentation drafting when those
+  models were the latest available ChatGPT models. The original
+  unit-test suite and foundational sparse operators were developed
+  before the authors began using generative AI. Later maintenance,
+  tests, and documentation may include AI-assisted contributions, and
+  OpenAI Codex is also used for release-pipeline management.</p>
+  <p>All AI-assisted outputs were reviewed, edited, and validated by the
+  human authors. Software changes were checked using code review,
+  automated tests, continuous integration, and comparisons with
+  reference behaviour where applicable, and all pull requests were
+  reviewed entirely manually by human reviewers. The human authors made
+  the primary mathematical, architectural, scientific, and editorial
+  decisions and take responsibility for the final software and
+  manuscript.</p>
 </sec>
 <sec id="acknowledgements">
   <title>Acknowledgements</title>
@@ -651,6 +666,28 @@ SMVN(torch.zeros(n), torch.ones(n), scale_tril=L).rsample().sum().backward()</co
       <uri>https://github.com/pytorch/pytorch/issues/87448</uri>
     </element-citation>
   </ref>
+  <ref id="ref-pytorch_maskedtensor">
+    <element-citation>
+      <person-group person-group-type="author">
+        <string-name>PyTorch Contributors</string-name>
+      </person-group>
+      <article-title>torch.masked: MaskedTensor documentation</article-title>
+      <publisher-name>PyTorch documentation</publisher-name>
+      <year iso-8601-date="2026">2026</year>
+      <uri>https://docs.pytorch.org/docs/stable/masked.html</uri>
+    </element-citation>
+  </ref>
+  <ref id="ref-pytorch_maskedtensor_sparsity">
+    <element-citation>
+      <person-group person-group-type="author">
+        <string-name>PyTorch Contributors</string-name>
+      </person-group>
+      <article-title>MaskedTensor sparsity</article-title>
+      <publisher-name>PyTorch tutorial</publisher-name>
+      <year iso-8601-date="2026">2026</year>
+      <uri>https://docs.pytorch.org/tutorials/unstable/maskedtensor_sparsity.html</uri>
+    </element-citation>
+  </ref>
   <ref id="ref-flaport2020sparse">
     <element-citation>
       <person-group person-group-type="author">

paper/paper.bib

@@ -118,6 +118,24 @@ @misc{pytorch_sparse_issue_87448
   url          = {https://github.com/pytorch/pytorch/issues/87448}
 }
 
+@misc{pytorch_maskedtensor,
+  title        = {{torch.masked}: MaskedTensor documentation},
+  author       = {{PyTorch Contributors}},
+  year         = {2026},
+  howpublished = {{PyTorch} documentation},
+  url          = {https://docs.pytorch.org/docs/stable/masked.html},
+  note         = {Accessed: 2026-07-01}
+}
+
+@misc{pytorch_maskedtensor_sparsity,
+  title        = {{MaskedTensor} sparsity},
+  author       = {{PyTorch Contributors}},
+  year         = {2026},
+  howpublished = {{PyTorch} tutorial},
+  url          = {https://docs.pytorch.org/tutorials/unstable/maskedtensor_sparsity.html},
+  note         = {Accessed: 2026-07-01}
+}
+
 @misc{flaport2020sparse,
   title        = {Solving sparse linear systems in PyTorch},
   author       = {Laporte, Floris},

paper/paper.md

@@ -45,7 +45,7 @@ However, learning these models with gradient-based optimisation requires backpro
 
 PyTorch [@pytorch] exposes sparse layouts (COO, CSR, and related formats) and implements a growing set of sparse operations. However, PyTorch's design goal is *dense-equivalent semantics* for sparse layouts: a guiding invariant is that applying an operation in sparse form should match applying it in dense form after conversion, including the backward function [@pytorch_sparse_issue_87448]. This makes it difficult to learn parameters that are intended to remain structurally sparse, because gradients may be produced for implicit zeros, or intermediate computations may densify.
 
-PyTorch also provides `MaskedTensor`, which distinguishes specified and unspecified elements and is conceptually closer to the constrained-subspace interpretation of sparsity. However, `MaskedTensor` remains at prototype stage with incomplete operator coverage, and storing a full boolean mask incurs a significant memory overhead, partially negating the memory benefits of sparse index-based representations for large-scale problems.
+PyTorch also provides `MaskedTensor`, which distinguishes specified and unspecified elements and is conceptually closer to the constrained-subspace interpretation of sparsity. However, PyTorch classifies the API as prototype stage, operator support is limited, and each `MaskedTensor` stores a separate mask tensor matching the data tensor's size and storage format, introducing additional mask-storage overhead [@pytorch_maskedtensor; @pytorch_maskedtensor_sparsity].
 
 Other libraries provide efficient sparse kernels but do not directly solve "sparsity-preserving gradients in PyTorch": SciPy [@scipy] provides mature sparse linear algebra but no automatic differentiation; CuPy [@cupy] and JAX [@jax] provide sparse solvers in their respective ecosystems but are not drop-in components for PyTorch autograd/training loops. GPyTorch [@gpytorch] targets scalable Gaussian process inference via kernel structure and approximations (e.g., inducing/structured methods) rather than arbitrary user-specified sparse covariance/precision factors. PyTorch Geometric’s torch_sparse [@pytorch_geometric] focuses on graph message-passing primitives rather than sparse covariance/precision modelling and differentiable sparse solves for probabilistic models.
 
@@ -137,7 +137,9 @@ On the SuiteSparse Rothberg/cfd2 matrix [@davis2011university; @rothberg1997cfd2
 
 # AI usage disclosure
 
-Generative AI tools were used during development of this software and manuscript. Various large language models were used to assist with code generation, refactoring, and test scaffolding for portions of the codebase, and AI assistance was used to draft and edit parts of the documentation and this manuscript. The repository was initiated prior to widespread AI coding assistant adoption, with AI tools incorporated during later development phases. All AI-assisted outputs were reviewed, edited, and validated by the human authors, who take responsibility for the final software and paper.
+Generative AI tools were used intermittently during later development and maintainence of the software and preparation of the documentation and manuscript. This is a best-effort retrospective disclosure because exact provider-side model snapshots were not recorded contemporaneously for every historical interaction. Based on the authors' records and recollection, and on commit dates relative to public model-release dates, OpenAI ChatGPT with GPT-4, GPT-4o, and GPT-5-series models was used for code suggestions, refactoring, debugging, test scaffolding, and documentation drafting when those models were the latest available ChatGPT models. The original unit-test suite and foundational sparse operators were developed before the authors began using generative AI. Later maintenance, tests, and documentation may include AI-assisted contributions, and OpenAI Codex is also used for release-pipeline management.
+
+All AI-assisted outputs were reviewed, edited, and validated by the human authors. Software changes were checked using code review, automated tests, continuous integration, and comparisons with reference behaviour where applicable, and all pull requests were reviewed entirely manually by human reviewers. The human authors made the primary mathematical, architectural, scientific, and editorial decisions and take responsibility for the final software and manuscript.
 
 # Acknowledgements