Implementation:LaurentMazare Tch rs PyTorch Declarations Yaml

Knowledge Sources	LaurentMazare_Tch_rs
Domains	Code_Generation, FFI
Last Updated	2026-02-08 00:00 GMT

Overview

Data files containing PyTorch C++ API function declarations used for automatic code generation of Rust FFI bindings in the tch-rs library.

Description

Each Declarations YAML file is a serialized list of every public function in the PyTorch C++ (ATen) API for a specific PyTorch release. The files are extracted from the PyTorch build system (which itself generates a Declarations.yaml during compilation) and vendored into the tch-rs repository under third_party/pytorch/.

Every top-level entry in the YAML list represents a single function declaration. The schema of each entry includes the following fields:

• name -- the C++ function name (e.g. _cast_Byte, add, conv2d).
• operator_name / overload_name -- the ATen operator name and overload discriminator, used to disambiguate functions that share a base name but differ in argument signatures.
• schema_string -- the full ATen schema signature, e.g. aten::add.Tensor(Tensor self, Tensor other, *, Scalar alpha=1) -> Tensor.
• arguments -- an ordered list of argument descriptors, each with:
  • name -- the parameter name.
  • dynamic_type -- the C++ type (e.g. at::Tensor, int64_t, bool, at::Scalar, at::IntArrayRef).
  • type -- the full C++ type including qualifiers (e.g. const at::Tensor &).
  • is_nullable -- whether the argument may be null/optional.
  • default -- an optional default value.
  • annotation -- mutation annotation (null for non-mutating arguments).
• returns -- a list of return value descriptors, each with dynamic_type, name, and type.
• method_of -- a list indicating whether the function is accessible as a namespace free function, a Tensor method, or a Type method.
• mode -- always native for these declarations.
• inplace -- whether the function mutates its input in place (conventionally indicated by a trailing underscore in the name).
• deprecated -- whether the function has been deprecated in this PyTorch version.
• is_factory_method -- whether the function creates a new tensor rather than operating on an existing one.
• device_guard / with_gil -- runtime dispatch metadata.

The schema has evolved slightly across PyTorch versions. Earlier files (v1.4.0 through v1.6.0) contain fields such as use_c10_dispatcher, matches_jit_signature, and method_prefix_derived, and use shorter type names (e.g. Tensor rather than at::Tensor). Later files (v1.7.0 onward) introduce schema_order_cpp_signature, schema_order_arguments, manual_kernel_registration, and has_math_kernel, and use fully qualified type names.

These YAML files drive the OCaml-based code generator (gen/gen.ml) that produces the complete set of Rust FFI bindings. The generator reads the YAML, filters out deprecated functions, excluded prefixes/suffixes, and unsupported argument types, then emits five output files that form the bridge between Rust and the PyTorch C++ library.

Usage

These files are consumed by the tch-rs build system to auto-generate the complete set of tensor operation bindings. The code generation pipeline is invoked with dune exec gen/gen.exe. The generator currently reads the most recent YAML file (Declarations-v2.10.0.yaml) and produces bindings that cover the latest supported PyTorch API. When a new PyTorch version is released, a new Declarations YAML file is added to the repository so that the updated API surface can be targeted.

Older YAML files are retained in the repository to preserve historical compatibility and to allow regeneration of bindings for earlier PyTorch releases if needed.

Code Reference

Source Location

• Repository: LaurentMazare_Tch_rs
• Code Generator: gen/gen.ml (892 lines)
• Files:
  • third_party/pytorch/Declarations-v1.4.0.yaml (60,108 lines)
  • third_party/pytorch/Declarations-v1.5.0.yaml (63,549 lines)
  • third_party/pytorch/Declarations-v1.6.0.yaml (64,390 lines)
  • third_party/pytorch/Declarations-v1.7.0.yaml (111,616 lines)
  • third_party/pytorch/Declarations-v1.8.0.yaml (121,870 lines)
  • third_party/pytorch/Declarations-v1.9.0.yaml (129,672 lines)
  • third_party/pytorch/Declarations-v1.10.0.yaml (137,757 lines)
  • third_party/pytorch/Declarations-v1.11.0.yaml (139,252 lines)
  • third_party/pytorch/Declarations-v1.12.0.yaml (159,390 lines)
  • third_party/pytorch/Declarations-v1.13.0.yaml (195,618 lines)
  • third_party/pytorch/Declarations-v2.0.0.yaml (198,402 lines)
  • third_party/pytorch/Declarations-v2.1.0.yaml (202,710 lines)
  • third_party/pytorch/Declarations-v2.2.0.yaml (204,701 lines)
  • third_party/pytorch/Declarations-v2.3.0.yaml (207,278 lines)
  • third_party/pytorch/Declarations-v2.4.0.yaml (209,665 lines)
  • third_party/pytorch/Declarations-v2.5.0.yaml (210,790 lines)
  • third_party/pytorch/Declarations-v2.6.0.yaml (211,760 lines)
  • third_party/pytorch/Declarations-v2.7.0.yaml (212,267 lines)
  • third_party/pytorch/Declarations-v2.8.0.yaml (213,851 lines)
  • third_party/pytorch/Declarations-v2.9.0.yaml (214,483 lines)
  • third_party/pytorch/Declarations-v2.10.0.yaml (215,895 lines)

Schema

A representative YAML entry from Declarations-v2.10.0.yaml:

- name: _cast_Byte
  operator_name: _cast_Byte
  overload_name: ''
  manual_kernel_registration: false
  category_override: ''
  schema_string: aten::_cast_Byte(Tensor self, bool non_blocking=False) -> Tensor
  arguments:
  - annotation: null
    dynamic_type: at::Tensor
    is_nullable: false
    name: self
    type: const at::Tensor &
  - annotation: null
    default: false
    dynamic_type: bool
    is_nullable: false
    name: non_blocking
    type: bool
  schema_order_cpp_signature: at::Tensor (const at::Tensor &, bool)
  schema_order_arguments:
  - annotation: null
    dynamic_type: at::Tensor
    is_nullable: false
    name: self
    type: const at::Tensor &
  - annotation: null
    default: false
    dynamic_type: bool
    is_nullable: false
    name: non_blocking
    type: bool
  method_of:
  - Type
  - namespace
  mode: native
  python_module: ''
  returns:
  - dynamic_type: at::Tensor
    name: result
    type: at::Tensor
  inplace: false
  is_factory_method: false
  abstract: false
  device_guard: true
  with_gil: false
  deprecated: false
  has_math_kernel: true

I/O Contract

Inputs

The YAML files serve as the sole structured input to the code generation pipeline. The generator (gen/gen.ml) reads one YAML file at a time, currently configured to use Declarations-v2.10.0.yaml. Each file is parsed by splitting on top-level list items (lines beginning with -) and processing each entry as a map.

The generator applies the following filters to the parsed declarations:

• Excluded functions -- A hardcoded set of function names that are skipped due to ambiguity or incompatibility (e.g. multi_margin_loss, clone, copy_, backward, normal).
• Excluded prefixes -- Functions beginning with _thnn_, _th_, _foreach, _fused_adam, sym_, fbgemm_, and other internal prefixes are skipped.
• Excluded suffixes -- Functions ending with _forward or _forward_out are skipped.
• Deprecated functions -- Any declaration marked deprecated: true is skipped.
• Unsupported argument types -- Functions with argument types that do not map to a known Rust type are silently dropped.

Outputs

The code generator produces five output files that together form the complete FFI bridge:

Output File	Lines	Purpose
torch-sys/libtch/torch_api_generated.cpp	19,043	C++ wrapper functions that call into the PyTorch C++ API. Each function is wrapped in a PROTECT macro for exception safety. Namespace functions call torch::func_name(); method functions call self->func_name().
torch-sys/libtch/torch_api_generated.h	2,643	C header declaring all generated atg_* functions with extern "C" linkage so they can be called from Rust.
torch-sys/src/c_generated.rs	16,003	Rust FFI declarations (extern "C" block) matching the C header, using raw pointer types (*mut C_tensor, *mut C_scalar).
src/wrappers/tensor_fallible_generated.rs	38,876	Safe Rust wrapper methods on Tensor that return Result<T, TchError>. Each method name is prefixed with f_. These handle pointer marshaling, list conversion, optional arguments, and error propagation.
src/wrappers/tensor_generated.rs	19,602	Convenience Rust wrapper methods on Tensor that call the fallible variants and unwrap() the result, panicking on error. These provide the primary public API surface.

Usage Examples

Build System Invocation

The code generator is invoked from the repository root:

dune exec gen/gen.exe

The entry point in gen/gen.ml hardcodes the current YAML file and output paths:

let () =
  run
    ~yaml_filename:"third_party/pytorch/Declarations-v2.10.0.yaml"
    ~cpp_filename:"torch-sys/libtch/torch_api_generated"
    ~ffi_filename:"torch-sys/src/c_generated.rs"
    ~wrapper_filename:"src/wrappers/tensor_generated.rs"
    ~fallible_wrapper_filename:"src/wrappers/tensor_fallible_generated.rs"

End-to-End Transformation Example

The following shows how a single YAML declaration flows through the code generation pipeline to produce bindings at each layer.

1. YAML Declaration (input):

- name: __and__
  operator_name: __and__
  overload_name: Scalar
  schema_string: aten::__and__.Scalar(Tensor self, Scalar other) -> Tensor
  arguments:
  - dynamic_type: at::Tensor
    name: self
    type: const at::Tensor &
  - dynamic_type: at::Scalar
    name: other
    type: const at::Scalar &
  method_of:
  - Type
  - namespace
  returns:
  - dynamic_type: at::Tensor
    name: result
    type: at::Tensor

2. Generated C++ (torch_api_generated.cpp):

void atg___and__(tensor *out__, tensor self, scalar other) {
  PROTECT(
    auto outputs__ = torch::__and__(*self, *other);
    out__[0] = new torch::Tensor(outputs__);
  )
}

3. Generated C Header (torch_api_generated.h):

void atg___and__(tensor *, tensor, scalar);

4. Generated Rust FFI (c_generated.rs):

pub fn atg___and__(out__: *mut *mut C_tensor, self_: *mut C_tensor, other_: *mut C_scalar);

5. Generated Fallible Rust Wrapper (tensor_fallible_generated.rs):

pub fn f_internal_and_<S: Into<Scalar>>(&mut self, other: S) -> Result<Tensor, TchError> {
    let mut c_tensors = [std::ptr::null_mut(); 1];
    unsafe_torch_err!(atg___and__(
        c_tensors.as_mut_ptr(),
        self.c_tensor,
        other.into().c_scalar
    ));
    Ok(Tensor { c_tensor: c_tensors[0] })
}

6. Generated Convenience Rust Wrapper (tensor_generated.rs):

pub fn internal_and_<S: Into<Scalar>>(&mut self, other: S) -> Tensor {
    self.f_internal_and_(other).unwrap()
}

Type Mapping

The generator maps C++ types from the YAML dynamic_type field to Rust types as follows:

C++ Type (dynamic_type)	Rust Type (public API)	C FFI Type
at::Tensor	&Tensor / Option<T>	*mut C_tensor
at::Scalar	S: Into<Scalar>	*mut C_scalar
bool	bool	c_int
int64_t	i64	i64
double	f64	f64
at::IntArrayRef	impl IntList	*const i64, c_int
at::ArrayRef<double>	impl DoubleList	*const f64, c_int
at::TensorList	&[T]	*const *mut C_tensor, c_int
at::TensorOptions	(Kind, Device)	c_int, c_int
at::ScalarType	Kind	c_int
at::Device	Device	c_int
c10::string_view	&str	*const u8, c_int
at::Layout	Layout	i8

Related Pages

• Principle:LaurentMazare_Tch_rs_PyTorch_Binding_Code_Generation