cugraph/cudf_interop/
options.rs

1use crate::types::GraphProperties;
2
3/// Options for building a graph from table-shaped cudf data using column indices.
4///
5/// # Example
6///
7/// ```no_run
8/// use cugraph::cudf_interop::TableGraphOptions;
9///
10/// // Minimal: source and destination column indices
11/// let opts = TableGraphOptions::new(0, 1);
12///
13/// // With weight column and renumbering
14/// let opts = TableGraphOptions::new(0, 1).weight_col(2).renumber();
15/// ```
16#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
17#[must_use]
18pub enum GraphConstructionPolicy {
19    /// Preserve the raw libcugraph graph-construction contract.
20    ///
21    /// Applies lower-level [`GraphBuilder`](crate::GraphBuilder) configuration
22    /// directly without pre-normalizing ingress edge tables.
23    RawLibcugraph,
24    /// Match Python `cugraph.Graph.from_cudf_edgelist(...)` semantics for
25    /// high-level cudf ingress workloads.
26    ///
27    /// This policy normalizes ingress edge data before raw graph
28    /// construction:
29    /// - directed simple graphs: drop duplicate directed edges and keep the
30    ///   minimum edge value when weights exist
31    /// - directed multigraphs: preserve multiplicity
32    /// - undirected simple graphs: add reverse edges, then drop duplicate
33    ///   directed edges and keep the minimum edge value when weights exist
34    /// - undirected multigraphs: add reverse edges and preserve multiplicity
35    #[default]
36    PythonCugraph,
37}
38
39#[derive(Debug, Clone)]
40#[must_use]
41pub struct TableGraphOptions {
42    /// Zero-based column index for source vertex IDs.
43    pub src_col: usize,
44    /// Zero-based column index for destination vertex IDs.
45    pub dst_col: usize,
46    /// Optional zero-based column index for edge weights.
47    pub weight_col: Option<usize>,
48    /// Optional zero-based column index for stable edge IDs.
49    pub edge_id_col: Option<usize>,
50    /// Graph properties (directed/undirected, multigraph).
51    pub properties: GraphProperties,
52    /// Whether to renumber vertices into a contiguous zero-based index range.
53    pub renumber: bool,
54    /// High-level graph-construction semantics to apply before crossing into
55    /// libcugraph.
56    pub construction_policy: GraphConstructionPolicy,
57}
58
59impl TableGraphOptions {
60    /// Create options with source and destination column indices.
61    ///
62    /// Defaults: no weight column, directed graph, renumber disabled, and
63    /// Python-compatible construction semantics.
64    pub fn new(src_col: usize, dst_col: usize) -> Self {
65        Self {
66            src_col,
67            dst_col,
68            weight_col: None,
69            edge_id_col: None,
70            properties: GraphProperties::directed(),
71            renumber: false,
72            construction_policy: GraphConstructionPolicy::PythonCugraph,
73        }
74    }
75
76    /// Set the weight column index.
77    pub fn weight_col(mut self, col: usize) -> Self {
78        self.weight_col = Some(col);
79        self
80    }
81
82    /// Set the stable edge-ID column index.
83    pub fn edge_id_col(mut self, col: usize) -> Self {
84        self.edge_id_col = Some(col);
85        self
86    }
87
88    /// Set graph properties.
89    pub fn properties(mut self, properties: GraphProperties) -> Self {
90        self.properties = properties;
91        self
92    }
93
94    /// Enable vertex renumbering.
95    pub fn renumber(mut self) -> Self {
96        self.renumber = true;
97        self
98    }
99
100    /// Set graph-construction semantics for this high-level ingress path.
101    pub fn construction_policy(mut self, policy: GraphConstructionPolicy) -> Self {
102        self.construction_policy = policy;
103        self
104    }
105}
106
107/// Column selection for explicit vertex-pair input from a prepared cudf table
108/// export.
109///
110/// Pairwise similarity preserves row alignment: `first_col` and `second_col`
111/// are read as two equally sized, same-typed vertex columns.  The selected
112/// columns must be `Int32` or `Int64` and match the graph vertex domain.
113///
114/// # Example
115///
116/// ```no_run
117/// use cugraph::cudf_interop::TableVertexPairOptions;
118///
119/// let options = TableVertexPairOptions::new(0, 1);
120/// ```
121#[derive(Debug, Clone, Copy, PartialEq, Eq)]
122#[must_use]
123pub struct TableVertexPairOptions {
124    /// Zero-based column index for the first vertex of each pair.
125    pub first_col: usize,
126    /// Zero-based column index for the second vertex of each pair.
127    pub second_col: usize,
128}
129
130impl TableVertexPairOptions {
131    /// Select the first and second vertex columns by zero-based index.
132    pub const fn new(first_col: usize, second_col: usize) -> Self {
133        Self { first_col, second_col }
134    }
135}
136
137/// Options for building a graph from separate prepared cudf column exports.
138///
139/// # Example
140///
141/// ```no_run
142/// use cugraph::cudf_interop::PreparedGraphOptions;
143///
144/// let opts = PreparedGraphOptions::default().renumber();
145/// ```
146#[derive(Debug, Clone, Default)]
147#[must_use]
148pub struct PreparedGraphOptions {
149    /// Graph properties (directed/undirected, multigraph).
150    pub properties: GraphProperties,
151    /// Whether to renumber vertices.
152    pub renumber: bool,
153    /// High-level graph-construction semantics to apply before crossing into
154    /// libcugraph.
155    pub construction_policy: GraphConstructionPolicy,
156}
157
158impl PreparedGraphOptions {
159    /// Set graph properties.
160    pub fn properties(mut self, properties: GraphProperties) -> Self {
161        self.properties = properties;
162        self
163    }
164
165    /// Enable vertex renumbering.
166    pub fn renumber(mut self) -> Self {
167        self.renumber = true;
168        self
169    }
170
171    /// Set graph-construction semantics for this high-level ingress path.
172    pub fn construction_policy(mut self, policy: GraphConstructionPolicy) -> Self {
173        self.construction_policy = policy;
174        self
175    }
176}
cugraph/cudf_interop/options.rs

cugraph/cudf_interop/
options.rs
