Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve and uniformize naming #353

Open
21 tasks
maxtremblay opened this issue Dec 6, 2024 · 0 comments
Open
21 tasks

Improve and uniformize naming #353

maxtremblay opened this issue Dec 6, 2024 · 0 comments
Labels
documentation Improvements or additions to documentation enhancement New feature or request

Comments

@maxtremblay
Copy link
Collaborator

maxtremblay commented Dec 6, 2024

I propose the following nomenclature to uniformize the names within CubeCL.

Nomenclature

Indexing

  • Use index for linear (contiguous) buffers, slices and arrays.
  • Use coordinate for the cartesian coordinate of a tensor element.
  • Use pos or position for cube related objected (CubePos, UnitPos)
  • Use axis instead of dim for tensor.

Objects in containers

  • Use element for a value inside a tensor or indexing a line.
  • Use line or something_line when indexing returns a Line<T>.
  • A container is lined if it stored Line<T> instead of T. (Currently both lined and vectorized are used).

Example

let element_line = tensor[index];
let element = element_line[0];

Length, size and shape

  • Use len (or length) for linear memory to match rust convention and lines.
  • Use size for the total number of elements in a tensor or in a line. Thus we always use line_size, never vectorization or vectorization_factor or other similar variations.
  • Use shape for the length of a tensor's axis. The shape of a tensor is a list (vec, slice or tuple) of the shape of each axis.
  • Use rank for the number of axes in a tensor.
  • Prefer something_count instead of num_something. (ex: CubeCount, unit_count)

Tensors

  • An axis is contiguous if its stride is 1.
  • The lines of a tensor are parallel to an axis if either it is the only contiguous axis or if it is contiguous and it has a shape greater than 1. Otherwise, the axis is perpendicular.
  • A tensor is in increasing_order if stride(axis1) < stride(axis2) whenever axis1 < axis2. This is also named column_major_order when the tensor is a matrix (rank == 2).
  • A tensor is in decreasing_order if stride(axis1) > stride(axis2) whenever axis1 < axis2. This is also named row_major_order when the tensor is a matrix (rank == 2).
  • A tensor is in non_monotonic_order if it is neither in increasing_order nor decreasing_order.
  • A stride is all the elements obtained when fixing the coordinates of all axes but one.

Meta

  • Prefer postfix names such as ReduceError and ReduceStrategy.
  • Avoid abbreviation except if they are really common and widely used.
  • Create a conventions.md file in the project root to help users and contributors follow the naming convention (and possible other conventions in the future).
@maxtremblay maxtremblay added documentation Improvements or additions to documentation enhancement New feature or request labels Dec 6, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

1 participant