torus_model.h¶

Namespaces¶

Name
tenzr

Classes¶

	Name
struct	tenzr::TorusDimensions Extents of a three-dimensional torus network.
struct	tenzr::NetworkParameters Latency and bandwidth constants of the modeled network.
class	tenzr::TorusCostModel Analytic cost model comparing torus and ring all-reduce times.

Source code¶

// Copyright 2026 The Tenzr Project Authors
//
// SPDX-License-Identifier: Apache-2.0
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#ifndef TENZR_TOPOLOGY_TORUS_MODEL_H_
#define TENZR_TOPOLOGY_TORUS_MODEL_H_

#include <cstdint>
#include <string>
#include <vector>

namespace tenzr {

  struct TorusDimensions {
    int64_t kx{1};

    int64_t ky{1};

    int64_t kz{1};

    int64_t TotalNodes() const { return kx * ky * kz; }

    std::string ToString() const;
  };

  struct NetworkParameters {
    double alpha_latency{1.0e-6};    // Point-to-point latency per hop (seconds)
    double beta_bandwidth{100.0e9};  // Concurrent multi-path bandwidth (bytes/sec)
  };

  class TorusCostModel {
   public:
    TorusCostModel(TorusDimensions dims, NetworkParameters params);

    const TorusDimensions& Dimensions() const { return dims_; }

    const NetworkParameters& Parameters() const { return params_; }

    // Evaluates:
    // T_torus ≈ 2 * ((Kx - 1) + (Ky - 1) + (Kz - 1)) * alpha +
    //           2 * ((Kx - 1)/Kx + (Ky - 1)/Ky + (Kz - 1)/Kz) * (N / beta)
    double PredictTimeSeconds(uint64_t payload_bytes) const;

    // Standard ring allreduce time:
    // T_ring = 2 * (P - 1) * alpha + 2 * ((P - 1) / P) * (N / beta_ring)
    // If ring_bandwidth <= 0, defaults to single-link bandwidth (beta / 3 for 3D)
    double PredictRingTimeSeconds(uint64_t payload_bytes, double ring_bandwidth = 0.0) const;

    double SpeedupOverRing(uint64_t payload_bytes, double ring_bandwidth = 0.0) const;

    // Finds optimal factorization (Kx, Ky, Kz) for given total node count minimizing latency
    static TorusDimensions OptimizeDimensions(int64_t total_nodes);

    std::string GenerateReport(uint64_t payload_bytes) const;

   private:
    TorusDimensions dims_;
    NetworkParameters params_;
  };

}  // namespace tenzr

#endif  // TENZR_TOPOLOGY_TORUS_MODEL_H_