---
title: Yarn Datatype in Textile Modeling
url: https://www.emergentmind.com/topics/yarn-datatype
type: topic
---

# Yarn Datatype in Textile Modeling

A yarn datatype is a computational representation of yarn-scale structure, state, and interactions in textile models. In the literature considered here, the term has two distinct but complementary meanings: a process-oriented topological datatype for weft-knitted textiles, formalized by TopoKnit as a contact-neighborhood grid in process space [2101.04560], and a mechanics-oriented `Yarn` object for differentiable yarn-level fabric simulation, in which a yarn is a chain of crossing nodes with geometric, kinematic, and material attributes [2202.00504]. These formulations address different layers of the textile modeling stack: the former encodes topology and fabrication logic, while the latter encodes dynamics, constitutive behavior, and differentiable time evolution.

## 1. Conceptual scope of the yarn datatype

In TopoKnit, the yarn datatype is defined as the “fundamental cell” of a process-space data structure used to represent the topology of weft-knitted textiles at the yarn scale. The central object is the `CNCell`, which stores a process-space coordinate, stitch type, contact-neighborhood state, and a local movement vector. The full data structure is a grid `DS[2*M][N+1]`, where `M×N` is the input stitch pattern, and process space serves as an intermediary between machine space and fabric space [2101.04560].

In the differentiable physics formulation, the yarn datatype is instead a higher-level object representing one warp or weft yarn as a chain of crossing nodes. A `Yarn` object contains crossing-node indices, a segment rest length `L`, a cross-section radius `R`, and material parameters including density `\rho`, stretch modulus `Y`, bending modulus `B`, friction coefficient `\mu`, shear modulus `S`, friction spring constant `k_f`, damping `d_f`, shear-lock parameters `c` and `\sigma`, and collision penalty stiffness `k_c`. This datatype is embedded in a larger structure containing arrays `warpYarns[]`, `weftYarns[]`, and a grid `crossQ[r][c]` of crossing nodes [2202.00504].

These two usages are not interchangeable. One is process-oriented and topological; the other is dynamical and constitutive. This suggests that “yarn datatype” is best understood as a family of yarn-resolved representations whose exact fields and operations depend on whether the target problem is topology extraction, physical simulation, or differentiable inverse design.

## 2. TopoKnit as a process-space topological representation

TopoKnit defines three low-level types that structure the state of each contact neighborhood. `ProcessCoord` stores integer indices `i` and `j`, where `i` is the CN “column” index and `j` is the CN “row” index. `StitchType` is an enumeration with values `Knit`, `Purl`, `Tuck`, `Miss`, `TransferLeft`, `TransferRight`, and `EmptyStitch`. `CNState` is an enumeration with values `PCN` for potential contact neighborhood, `ACN` for actualized contact neighborhood, `UACN` for unanchored actualized neighborhood, and `CNEmpty` for the absence of a contact neighborhood [2101.04560].

A `MoveVec` stores integer offsets `di` and `dj`, representing local horizontal and vertical shifts in the process grid. The fundamental cell, `CNCell`, contains four fields: `P` of type `ProcessCoord`, `st` of type `StitchType`, `state` of type `CNState`, and `mv` of type `MoveVec`. The overall process-space array is initialized so that each `DS[i][j]` is set to `st=EmptyStitch`, `state=CNEmpty`, and `mv=(0,0)`, except for `j=0`, which is assumed to contain `PCN`s from cast-on [2101.04560].

TopoKnit also specifies graph-level types for the final yarn topology. A `Node` has a unique integer identifier, a final process-space location `P`, an `actualIn` field storing whether it was formed by a knit or purl, and lists of incoming and outgoing edges. An `Edge` stores pointers `from` and `to` and a color field, with the example convention `0=teal` and `1=magenta` for even and odd rows. The topological graph is therefore not the primitive representation; it is a derived object produced from process-space evaluation.

The significance of this design lies in its separation of concerns. The datatype does not directly store a 3D embedding or explicit yarn geometry. Instead, it encodes topological evolution under machine instructions through local cell states and local movement vectors, enabling subsequent reconstruction of yarn order and contact structure.

## 3. Machine, process, and fabric spaces

TopoKnit formalizes three spaces. Machine space consists of discrete needle-row pairs $(k,l)\in\{1\ldots M\}\times\{1\ldots N\}$. Process space is a CN grid $(i,j)\in\{0\ldots 2M-1\}\times\{0\ldots N\}$. Fabric space is the final topological graph $\mathcal{G}=(V,E)$ embedded in 3D [2101.04560].

The machine-to-process initialization map is defined as
$$
f_{\rm mp}:(k,l)\mapsto \{(2k,l),(2k+1,l)\},
$$
with
$$
DS[2k][l].state=PCN,\qquad DS[2k+1][l].state=PCN.
$$
Each stitch instruction at $(k,l)$ writes into four cells,
$$
(i,j),\ (i+1,j),\ (i,j+1),\ (i+1,j+1),
$$
setting `st`, `state`, and `mv` according to the rules in Tables 1–2 of the paper.

The process-to-fabric mapping is defined through a final-location function
$$
g(i,j)=\bigl(i+\Delta i_{\rm horiz},\ j+\Delta j_{\rm vert}\bigr),
$$
where
$$
\Delta i_{\rm horiz}=\sum_h \mathrm{mv}_h.di,\qquad
\Delta j_{\rm vert}=\sum_v \mathrm{mv}_v.dj.
$$
The summation proceeds along the locally connected chain of `CNCell`s until an actualized `PCN\to ACN` occurs. The final yarn graph is then defined by one `Node` per actualized `ACNCell` at its final location $(i^\*,j^\*)=g(i,j)$, while the edge set is traced by the yarn-following algorithm [2101.04560].

This construction makes process space an intermediary in a precise sense. Machine instructions do not directly become graph nodes or edges; they first populate a grid of local contact neighborhoods, whose final positions are recovered by accumulated local displacements. A plausible implication is that the datatype supports topological evaluation without requiring global recomputation of a full geometric embedding.

## 4. Query algorithms and supported topological operations

TopoKnit’s computational efficiency derives from a small set of on-demand queries. `FOLLOW_THE_YARN()` enumerates `ACN`s in yarn order by traversing the process grid in a “square-wave” pattern. It maintains indices `(i,j)`, a Boolean `legNode`, and a row counter `curRow`, and appends either the current location or the `FINAL_LOCATION(i,j)` result depending on whether the traversal is at a leg node or a head node [2101.04560].

`ADD_TO_LIST(i,j,legNode)` determines whether a contact neighborhood should be recorded. For leg nodes, it tests whether `ACNS_AT(i,j)` is nonempty. For head nodes, it rejects `CNEmpty`, conditionally actualizes `UACN` if it is anchored forward or backward along the yarn direction, and otherwise records `PCN` or `ACN`.

`FINAL_LOCATION(i,j)` accumulates shifts to locate the head CN. It first applies horizontal motion if `DS[i][j].mv.di != 0`, and then recursively resolves vertical motion through `FINAL_REC(ii,jj)` until a `Knit` or `Purl` cell is encountered. `ACNS_AT(i,j)` performs a near-constant-time local search: it scans a fixed `13×4` box around `(i,j)`, calls `FINAL_LOCATION` on candidate source cells, and returns those whose final location matches `(i,j)` and whose state is `ACN`. `NEXT_CN(i,j,legNode,curRow)` advances the traversal, either moving to the next row at the row boundary or taking one `SQUARE_WAVE_STEP` otherwise [2101.04560].

The complexity bounds are explicit. `FINAL_LOCATION` is $O(1)$ because it involves at most one horizontal recursion and at most one vertical chain up to three rows. `ACNS_AT` is $O(1)$ because it scans a fixed `13×4` box, implying `52` calls to `FINAL_LOCATION`. `ADD_TO_LIST` and `NEXT_CN` also perform constant work. `FOLLOW_THE_YARN` visits $O(\#CNs)\simeq O(2\times M\times (N+1))$ steps, each $O(1)$, yielding an overall complexity of $O(MN)$ [2101.04560].

These queries support three fabric-space operations directly. First, `FOLLOW_THE_YARN` produces the raw sequence of contact points in yarn order, which can be post-processed into `Node` and `Edge` lists. Second, any final location `(i,j)` with `state==ACN` is a crossing where two yarn segments intertwine, and `ACNS_AT(i,j)` returns its local pre-images. Third, changing a stitch at `(k,l)` requires recomputing only the four affected process-space cells, after which downstream queries automatically reflect the modification on the next invocation.

## 5. The `Yarn` object in differentiable yarn-level simulation

In the differentiable physics model, the fabric is a `2D` grid of crossing nodes `Q` arranged in `r` rows and `c` columns. Each crossing node `q_i` stores a Lagrangian position $x_i\in\mathbb{R}^3$. If the node is interior rather than a free end, it also stores two Eulerian coordinates $(u_i,v_i)\in\mathbb{R}^2$ that track local sliding along warp and weft directions, together with a velocity $\dot{x}_i$ and, if interior, $(\dot{u}_i,\dot{v}_i)$ [2202.00504].

Each yarn, whether warp or weft, is a chain of these crossing nodes. Adjacency is encoded as a list of segments
$$
S=\{[q_k,q_{k+1}]\}.
$$
Each segment carries the positions of its endpoints and their Eulerian coordinates: `u`-coordinates for warp segments and `v`-coordinates for weft segments. A `Yarn` object therefore contains the indices of its crossing-node endpoints, a segment rest length `L`, a cross-section radius `R`, and the full set of material parameters inherited by every segment [2202.00504].

The multi-yarn data structure consists of two arrays, `warpYarns[]` and `weftYarns[]`, each of length approximately `c` or `r`, and a grid `crossQ[r][c]` of crossing-node objects. Each crossing node holds pointers back to its two yarns and to up to four neighboring segments. Persistent contact at every crossing node enforces zero-penetration and no-slip in the normal direction; friction and shear are computed only between the two segments meeting at that node. Parallel-yarn collisions are handled separately by an overall bounding-volume hierarchy over all segments, with collisions grouped into nonrigid impact zones and resolved via a small quadratic program [2202.00504].

The datatype thus integrates Lagrangian and Eulerian information. The node positions $x_i$ describe spatial configuration, while the scalar coordinates $(u_i,v_i)$ parameterize sliding along yarn directions. This is essential for representing yarn-to-yarn interactions such as frictional slip and shear at crossings.

## 6. Force laws encoded on the yarn datatype

The differentiable simulator defines several force laws per segment or per crossing node. Stretching for a warp segment $[q_0,q_1]$ uses the energy
$$
V^s=\tfrac12\,Y\,\pi\,R^2\,\Delta u\,(\|x_1-x_0\|-L)^2,
$$
with force
$$
F^s_{x_1}=-Y\,\pi\,R^2\,(\|w\|-L)\,d_{01},
$$
where $w=(x_1-x_0)/\Delta u$ and $d_{01}=(x_1-x_0)/\|x_1-x_0\|$. The corresponding Jacobian is given in closed form [2202.00504].

Bending is defined at each interior node with neighbors along the same yarn. With
$$
\theta=\arccos(-d_{01}^\top d_{02}),
$$
the energy is
$$
V^b=B\,\pi\,R^2\,\theta^2/(u_1-u_2),
$$
and the force derivatives with respect to both positions and Eulerian coordinates exist in closed form. Frictional slide at a crossing node is defined along the warp direction `u_0` and analogously along the weft direction `v_0`, using a smoothed transition between static and kinetic regimes via $K(x)=\tanh(px)$. The force includes spring, Coulomb-like, and damping terms, and explicit expressions for $\partial F_{\rm slide}/\partial u_0$ and $\partial F_{\rm slide}/\partial \dot{u}_0$ are provided so that the static-to-kinetic transition is smooth [2202.00504].

Shear is defined between the two crossing segments at a node. If $\phi$ is the angle between the incident directions and $\Delta\phi=\phi-\pi/2$, then a shear-locking stiffness
$$
k_s=(F_n+1)\,S\,\pi\,R^2\cdot \tfrac12\big[(1+\gamma^c)+(1-\gamma^c)\tanh(g(\phi))\big]
$$
is used, where $g(\phi)$ ensures a smooth lock transition at $\phi_l=2\arcsin(R/L)$. The shear energy is
$$
V^{sh}=\tfrac12\,k_s\,L\,\Delta\phi^2.
$$
Additional terms include a parallel-yarn collision penalty
$$
V^c_{01}=\tfrac12\,k_c\,L\,[\mathrm{ReLU}(d-\Delta u)]^2,
$$
gravity per segment, and a wind force per triangle $(q_0,q_1,q_3)$, with the note that all wind-force terms are linear in $x$ and $\dot{x}$, so the derivative is straightforward [2202.00504].

Contact resolution for vertex-face and edge-edge collisions is formulated as a small quadratic program,
$$
\min_{x_{\rm coll}} \ \tfrac12 (x_{\rm coll}-x)^\top W (x_{\rm coll}-x)
\quad \text{subject to}\quad
Gx_{\rm coll}+h\le 0,
$$
and its solution is differentiable via implicit differentiation of KKT conditions. The yarn datatype is therefore not merely a storage schema; it is the carrier of all quantities needed to assemble differentiable force, contact, and collision terms.

## 7. Time integration, differentiation, and relation between the two formulations

The differentiable simulator advances the full system using implicit Euler. With all `5N` degrees of freedom stacked into `q` and velocities `\dot{p}`, the update is
$$
A\,\Delta\dot{p}=h\,F(q,\dot{p})+M\,\dot{p}_{(t)},
$$
where
$$
A=M-h^2\,\partial F/\partial q-h\,\partial F/\partial \dot{p}.
$$
After solving for $\dot{p}_{(t+1)}=\Delta\dot{p}/h$, the state is updated by
$$
q_{(t+1)}=q_{(t)}+h\,\dot{p}_{(t+1)}.
$$
All Jacobians are assembled from stretch, bend, friction, shear, wind, gravity, and collision contributions, and back-propagation uses implicit differentiation through the linear solve, with the same system size as the forward step [2202.00504].

The relation between this simulator-oriented datatype and TopoKnit is structural rather than identical. TopoKnit defines a yarn datatype around local contact neighborhoods, machine/process/fabric mappings, and near-constant-time topological queries. The differentiable simulator defines a yarn datatype around chains of crossing nodes, constitutive parameters, and differentiable updates of positions and sliding coordinates. This suggests a layered interpretation of yarn-scale textile computation: one datatype class captures how yarn crossings are created and connected, while another captures how those crossings deform, slide, and interact under forces.

A common misconception is to treat a yarn datatype as either purely geometric or purely graph-theoretic. The literature here indicates a more specialized landscape. In a process-oriented representation, the primitive object may be a `CNCell` with state transitions and movement vectors rather than a geometric strand [2101.04560]. In a differentiable mechanics representation, the primitive object may be a yarn with node indices, radii, moduli, and collision parameters rather than an abstract contact graph [2202.00504]. The term therefore denotes a formal schema for yarn-resolved computation, but its exact semantics depend on whether the governing problem is topological reconstruction, physical simulation, or differentiable analysis.

Source: https://www.emergentmind.com/topics/yarn-datatype