Refactor TorchAOBaseTensor for better BC support

[jerryzh168]

Stacked PRs:

• [test only] testing adding optioanl tensor arg to float8 tensor #2840
• ->Refactor TorchAOBaseTensor for better BC support #2793

---

Refactor TorchAOBaseTensor for better BC support

Summary:

After this PR, tensors inheriting from TorchAOBaseTensor will have better support BC, that is if they add some optional tensor data attribute or optional non-tensor attribute, we will still have BC without any additional changes.

More Details: The BC story we are looking at is that, after we land some tensor, e.g. Int4Tensor, Float8Tensor, future changes should only add optional Tensor data attributes and optional non-Tensor attributes to the Tensor (other bigger changes will require a version bump, we need to add that too). The current TorchAOBaseTensor doesn’t support this very well.

also see #2840 for a real test that adds both an optional tensor and optional non-tensor attribute to Float8Tensor, and the BC test in https://github.com/pytorch/ao/blob/main/test/integration/test_load_and_run_checkpoint.py that tests Float8Tensor does not fail.

Docs for current TorchAOBaseTensor:

ao/torchao/utils.py

Lines 726 to 731 in e6b38bb

	class variables to define to simplify implmentation of tensor subclasses:
	`tensor_data_names` (List[str]): list of names of all requires tensor_data, order should match
	the `__init__` list of tensor subclass
	`optional_tensor_data_names` (List[str]): it's optional to define this field to have the additional boilerplate functions been implemented for you, but this will be need if there are some optional Tensor attributes, when defined, this will be a list of names of Tensors that can be optional
	`tensor_attribute_names` (List[str]): list of names of non-Tensor attributes,
	order should match the `__init__` list of tensor subclass, following all the `tensor_data_names` arguments and `optional_tensor_data_names`

tensor_data_names (List[str]): list of names of all requires tensor_data, order should match
the __init__ list of tensor subclass
optional_tensor_data_names (List[str]): it's optional to define this field to have the additional boilerplate functions been implemented for you, but this will be need if there are some optional Tensor attributes, when defined, this will be a list of names of Tensors that can be optional
tensor_attribute_names (List[str]): list of names of non-Tensor attributes,
order should match the __init__ list of tensor subclass, following all the tensor_data_names arguments and optional_tensor_data_names

Problems: current optional_tensor_data_names is not truly optional, since it is followed by tensor_attribute_names which contains both required and optional attributes. So if we add a tensor data attribute to Tensor, it will break BC.

Here are a few options:

class Int4Tensor(TorchAOBaseTensor):
    tensor_data_names = ["qdata", "scale", "zero_point"]
    optional_tensor_data_names = ["act_scale"]
    tensor_attribute_names = ["block_size", "shape", "_demo_only_optional_attr"]

    def __init__(self, qdata, scale, zero_point, act_scale=None, block_size=None, shape=None, _demo_only_optional_attr=None):
        ...

   # for BC
   def __setstate__(self, state):
      torch._utils._set_obj_state(self, state)
      if "act_scale" not in self.__dict__:
          self.act_scale = None

class Int4Tensor(TorchAOBaseTensor):
    tensor_data_names = ["qdata", "scale", "zero_point"]
    optional_tensor_data_names = ["act_scale"]
    required_tensor_attribute_names = ["block_size", "shape"]
    optional_tensor_attribute_names = ["_demo_only_optional_attr"]

    def __init__(self, qdata, scale, zero_point, block_size, shape, act_scale=None, _demo_only_optional_attr = None):
        ...

   # for BC
   def __setstate__(self, state):
      torch._utils._set_obj_state(self, state)
      if "act_scale" not in self.__dict__:
          self.act_scale = None

class Int4Tensor(TorchAOBaseTensor):
    tensor_data_names = ["qdata", "scale", "zero_point"]
    tensor_attribute_names = ["block_size", "shape", "_demo_only_optional_attr"]
    optional_tensor_data_names = ["act_scale"]

    def __init__(self, qdata, scale, zero_point, block_size, shape, _demo_only_optional_attr = None, act_scale = None):
        ...

   # for BC
   def __setstate__(self, state):
      torch._utils._set_obj_state(self, state)
      if "act_scale" not in self.__dict__:
          self.act_scale = None

Test Plan:
python test/integration/test_load_and_run_checkpoint.py

Reviewers:

Subscribers:

Tasks:

Tags:

[pytorch-bot]

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/ao/2793

• 📄 Preview Python docs built from this PR

Note: Links to docs will display an error until the docs builds have been completed.

❌ 2 New Failures, 1 Unrelated Failure

As of commit fdbd53e with merge base 8812365 ():

NEW FAILURES - The following jobs have failed:

• Run Regression Tests / test (CUDA 2.8, linux.g5.12xlarge.nvidia.gpu, torch==2.8.0, cuda, 12.6) / linux-job (gh)
  RuntimeError: Command docker exec -t 9c78c1a63c18b72473cebae9a2f532cab2fbd42c73b4eb084aceb5ca193ef014 /exec failed with exit code 1
• Run Regression Tests / test-nightly (CUDA Nightly, linux.g5.12xlarge.nvidia.gpu, --pre torch --index-url https://downloa... / linux-job (gh)
  RuntimeError: Command docker exec -t aaaa75e20f0ded27d9e87cdd97e72b69fede21d9b5b7836f31bb1f5502585473 /exec failed with exit code 1

BROKEN TRUNK - The following job failed but were present on the merge base:

👉 Rebase onto the `viable/strict` branch to avoid these failures

• Run 1xH100 Tests / test (H100, linux.aws.h100, --pre torch torchvision torchaudio fbgemm-gpu-genai --index-url https... / linux-job (gh) (trunk failure)
  test/dtypes/test_affine_quantized_float.py::TestAffineQuantizedFloat8Compile::test_expected_kernels_on_gpu_granularity1_float8_config_version_2

This comment was automatically generated by Dr. CI and updates every 15 minutes.