pytorch/docs/source
Avik Chaudhuri ebc7039bcb New export API with dynamic shape specifications instead of constraints (#108448)
Our experience using `constraints` / `dynamic_dim` with the existing export API has found it to be (subjectively) clunky and (objectively) verbose in common cases.

This PR implements a new design for the export API that replaces the use of `constraints` / `dynamic_dim` with a new way of specifying dynamic shapes, involving the following concepts:
* a constructor `Dim` for first-class named dynamic dimensions with ranges (similar to `functorch.dim`, and analogous to internal symbolic sizes)
* a mechanism that uses the above in `export` calls to associate inputs to their dynamic shape specifications (`dynamic_shapes`)

Design doc: https://docs.google.com/presentation/d/168U7XK72C_WSsZpGESP6Cho9udh193fi0gfjxCNcJ4E/edit#slide=id.p (Meta-only). Note that we only implement Option 1 in that doc. An older version of this PR also implemented Option 3, which is an alternative way of specifying dynamic shapes using tensor type annotations on the exported callable; but we have moved that to future work for now.

See docs for these new features in `torch.export`. The existing `torch.export.export` is modified to use the new API, `torch._export.export__RC__`, whenever `constraints=None`. We have not deprecated the existing API yet, but will do in a follow-up.

Constraint violation errors arising through use of the new API will now contain suggested fixes using the new API. No longer do we need to report all specializations for static dimensions and suggest all constraints over dynamic dimensions to fix such errors. Instead, due to the redesign, the suggested fixes are much more concise, only involving modifying the definitions of relevant `Dim`s.

Differential Revision: [D48919204](https://our.internmc.facebook.com/intern/diff/D48919204/)

Pull Request resolved: https://github.com/pytorch/pytorch/pull/108448
Approved by: https://github.com/suo, https://github.com/gmagogsfm
2023-09-22 06:58:26 +00:00
..
_static Refactor torch.onnx documentation (#108379) 2023-09-08 18:23:48 +00:00
_templates Replace master with main in links and docs/conf.py (#100176) 2023-05-02 18:20:32 +00:00
community Add redirect links to the contributor wiki (#106863) 2023-09-21 22:01:20 -04:00
elastic [BE] Prefer dash over underscore in command-line options (#94505) 2023-02-09 20:16:49 +00:00
notes Fix the example in the extending.func.rst (#109279) 2023-09-14 17:29:39 +00:00
rpc
scripts [export] torch.export landing page (#108783) 2023-09-10 01:40:42 +00:00
amp.rst Documentation for torch.autocast (#95760) 2023-07-22 03:56:34 +00:00
autograd.rst [docs] Properly link register_post_accumulate_grad_hook docs (#108157) 2023-08-29 22:13:33 +00:00
backends.rst Fix Backend docs search items (#101214) 2023-05-22 14:58:38 +00:00
benchmark_utils.rst
bottleneck.rst
checkpoint.rst add checkpoint support for custom device (#99626) 2023-05-04 00:23:42 +00:00
complex_numbers.rst Remove CUDA 11.6 note from complex docs (#100118) 2023-04-27 16:26:27 +00:00
conf.py Enable UFMT on a bunch of low traffic Python files outside of main files (#106052) 2023-07-27 01:01:17 +00:00
config_mod.rst
cpp_extension.rst
cpp_index.rst
cpu.rst [core] Bring cpu device module closer to cuda's. (#103172) 2023-07-12 19:43:22 +00:00
cuda._sanitizer.rst Fix typos under docs directory (#88033) 2022-10-31 19:31:56 +00:00
cuda.rst Add more GPU metric instrumentation (#91717) 2023-02-24 00:38:03 +00:00
cudnn_persistent_rnn.rst
cudnn_rnn_determinism.rst
data.rst Revert "reseed all Generators in Dataloader's _worker_loop() -- via GC (#107131)" 2023-08-23 17:08:07 +00:00
ddp_comm_hooks.rst [DOCS][DDP]Fix the simple of saving and reloading PowerSGD state and hook. (#102721) 2023-06-10 00:15:00 +00:00
deploy.rst
distributed.algorithms.join.rst
distributed.checkpoint.rst Replace master with main in links and docs/conf.py (#100176) 2023-05-02 18:20:32 +00:00
distributed.elastic.rst
distributed.optim.rst
distributed.rst [RESUBMIT] Standardize on error types for distributed errors. (#108191) 2023-08-30 21:47:39 +00:00
distributed.tensor.parallel.rst [2D][TP] Enable DDP TP integration with unit test (#106583) 2023-08-17 02:54:17 +00:00
distributions.rst
dlpack.rst
docutils.conf
export.rst New export API with dynamic shape specifications instead of constraints (#108448) 2023-09-22 06:58:26 +00:00
fft.rst
fsdp.rst [FSDP][state_dict] Expose optimizer state_dict config (#105949) 2023-08-21 07:29:49 +00:00
func.api.rst [functorch] linearize (#94173) 2023-02-09 15:45:08 +00:00
func.batch_norm.rst Fix typo under docs directory (#97202) 2023-03-21 01:24:10 +00:00
func.migrating.rst [torch.func] Add migration guide from functorch (#91811) 2023-01-17 22:14:42 +00:00
func.rst Fix typo under docs directory (#92762) 2023-01-23 18:07:22 +00:00
func.ux_limitations.rst [torch.func] Add docs (#91319) 2022-12-30 02:51:18 +00:00
func.whirlwind_tour.rst [torch.func] Add docs (#91319) 2022-12-30 02:51:18 +00:00
futures.rst
fx.rst [fx] change from #users to num_users in graph printout (#101140) 2023-06-20 21:24:32 +00:00
hub.rst Fix typo under docs directory (#92762) 2023-01-23 18:07:22 +00:00
index.rst Refactor torch.onnx documentation (#108379) 2023-09-08 18:23:48 +00:00
jit_builtin_functions.rst
jit_language_reference_v2.rst Fix typo under docs directory (#97202) 2023-03-21 01:24:10 +00:00
jit_language_reference.rst [BE] [1/3] Rewrite super() calls in caffe2 and benchmarks (#94587) 2023-02-11 18:19:48 +00:00
jit_python_reference.rst
jit_unsupported.rst
jit_utils.rst
jit.rst [JIT] Document torch.jit.interface (#109356) 2023-09-15 23:23:47 +00:00
library.rst Enable registering fallthroughs to (op, dk) from torch.library (#106086) 2023-07-28 19:37:59 +00:00
linalg.rst Add a note on the stability of linalg functions. (#88313) 2022-11-07 22:44:23 +00:00
logging.rst [Easy] log graphs in compiled_autograd if TORCH_LOGS=compiled_autograd (#108991) 2023-09-12 00:15:02 +00:00
masked.rst Fix link in docs (#94686) 2023-02-13 20:42:24 +00:00
math-quantizer-equation.png
mobile_optimizer.rst [Reland] Clean Up MobileOptimizerType Rewrite Flags Public API and Documentation (#92081) 2023-01-14 17:06:00 +00:00
model_zoo.rst
monitor.rst
mps.rst [MPS] Introduce torch.mps.Event() APIs (#102121) 2023-08-08 03:45:45 +00:00
multiprocessing.rst
name_inference.rst [docs] Properly link register_post_accumulate_grad_hook docs (#108157) 2023-08-29 22:13:33 +00:00
named_tensor.rst fixing named tensor unflatten example (#106921) 2023-08-22 18:00:10 +00:00
nested.rst Replace master with main in links and docs/conf.py (#100176) 2023-05-02 18:20:32 +00:00
nn.functional.rst [SDPA] update type hint for scaled_dot_product_attention and documentation (#94008) 2023-02-10 18:02:43 +00:00
nn.init.rst
nn.rst Back out "Reland "Make adding buffers more like adding parameters (#104069)" (#106224)" (#106743) 2023-08-08 15:27:34 +00:00
onnx_dynamo_onnxruntime_backend.rst Follow-up #108379 (#108905) 2023-09-09 01:38:36 +00:00
onnx_dynamo.rst Follow-up #108379 (#108905) 2023-09-09 01:38:36 +00:00
onnx_torchscript_supported_aten_ops.rst Refactor torch.onnx documentation (#108379) 2023-09-08 18:23:48 +00:00
onnx_torchscript.rst Follow-up #108379 (#108905) 2023-09-09 01:38:36 +00:00
onnx.rst Refactor torch.onnx documentation (#108379) 2023-09-08 18:23:48 +00:00
optim.rst Optimized EMA implementation (#94820) 2023-04-26 18:02:11 +00:00
package.rst
pipeline.rst docs: Linking ResNeXt PyTorch Hub Pipeline (#98689) 2023-04-11 02:20:26 +00:00
profiler.rst
quantization-accuracy-debugging.rst Fix typo under docs directory (#87583) 2022-10-24 23:52:44 +00:00
quantization-backend-configuration.rst update quantization doc: add x86 backend as default backend of server inference (#86794) 2022-12-02 02:10:25 +00:00
quantization-support.rst [quant][api] Move torch.ao.quantization.pt2e.quantizer to torch.ao.quantization.quantizer (#105885) 2023-07-26 18:20:09 +00:00
quantization.rst Fix doc preview page url at CONTRIBUTING.md (#108580) 2023-09-05 20:17:55 +00:00
random.rst
rpc.rst [BE] RPC is missing RRef docs (#106902) 2023-08-10 16:26:27 +00:00
signal.rst Nuttall window (#90103) 2022-12-16 09:05:53 +00:00
sparse.rst Add torch.sparse.as_sparse_gradcheck decorator of gradcheck that allows gradcheck input function to receive and return sparse tensors (#107150) 2023-08-26 07:24:31 +00:00
special.rst
storage.rst Deprecate TypedStorage, its derived classes, and all of their public methods (#85303) 2022-11-08 18:11:01 +00:00
tensor_attributes.rst Add a warning about performance cost of set_default_device (#92703) 2023-01-21 02:23:13 +00:00
tensor_view.rst
tensorboard.rst
tensors.rst [docs] Properly link register_post_accumulate_grad_hook docs (#108157) 2023-08-29 22:13:33 +00:00
testing.rst document torch.testing.assert_allclose (#89526) 2022-12-01 11:22:50 +00:00
torch_cuda_memory.rst document memory snapshotting (#107660) 2023-08-24 19:20:03 +00:00
torch.ao.ns._numeric_suite_fx.rst
torch.ao.ns._numeric_suite.rst
torch.compiler_api.rst Restructure torch.compile docs (#105376) 2023-07-28 20:58:57 +00:00
torch.compiler_best_practices_for_backends.rst Restructure torch.compile docs (#105376) 2023-07-28 20:58:57 +00:00
torch.compiler_cudagraph_trees.rst Restructure torch.compile docs (#105376) 2023-07-28 20:58:57 +00:00
torch.compiler_custom_backends.rst Restructure torch.compile docs (#105376) 2023-07-28 20:58:57 +00:00
torch.compiler_deepdive.rst Update the instruction to enable dynamo logs (#109409) 2023-09-18 17:49:40 +00:00
torch.compiler_dynamic_shapes.rst Update dynamic shapes documentation (#109764) 2023-09-21 13:53:43 +00:00
torch.compiler_fake_tensor.rst Restructure torch.compile docs (#105376) 2023-07-28 20:58:57 +00:00
torch.compiler_faq.rst Add docs for torch.compile(numpy) (#109710) 2023-09-21 03:05:21 +00:00
torch.compiler_fine_grain_apis.rst Restructure torch.compile docs (#105376) 2023-07-28 20:58:57 +00:00
torch.compiler_get_started.rst [Docs] Fix compiler.list_backends invocation (#109568) 2023-09-19 10:00:04 +00:00
torch.compiler_guards_overview.rst Do not use a specific LOC in link (#108957) 2023-09-13 19:21:45 +00:00
torch.compiler_inductor_profiling.rst Restructure torch.compile docs (#105376) 2023-07-28 20:58:57 +00:00
torch.compiler_ir.rst [export] torch.export landing page (#108783) 2023-09-10 01:40:42 +00:00
torch.compiler_nn_module.rst Reland 3rd try [finishing colesbury's PR 100642] Guard on nn.Module dicts and type (#109323) 2023-09-15 08:44:14 +00:00
torch.compiler_performance_dashboard.rst Restructure torch.compile docs (#105376) 2023-07-28 20:58:57 +00:00
torch.compiler_profiling_torch_compile.rst Restructure torch.compile docs (#105376) 2023-07-28 20:58:57 +00:00
torch.compiler_transformations.rst Restructure torch.compile docs (#105376) 2023-07-28 20:58:57 +00:00
torch.compiler_troubleshooting.rst Fix rst formatting in torch.compiler_troubleshooting.rst (#107360) 2023-08-18 01:04:24 +00:00
torch.compiler.rst [Docs] Fix compiler.list_backends invocation (#109568) 2023-09-19 10:00:04 +00:00
torch.overrides.rst Add torch_dispatch and modes to extending.rst note (#102087) 2023-06-22 12:56:35 +00:00
torch.rst Expose torch.export() API (#106904) 2023-08-16 10:47:26 +00:00
type_info.rst
utils.rst Add torch.utils to the docs page, remove dead code and fix docstrings (#105142) 2023-07-26 14:24:58 +00:00