Yarn Datatype in Textile Modeling

• Yarn datatype is a computational representation of yarn-scale structure that captures both topological configuration and dynamic simulation in textiles.
• The TopoKnit approach encodes stitch instructions via a process-space grid with local movement vectors to reconstruct fabric topology.
• The differentiable simulation model represents yarns as chains of crossing nodes with detailed material parameters to enable physics-based analysis.

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 (Kapllani et al., 2021), 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 (Gong et al., 2022). 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 (Kapllani et al., 2021).

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 (Gong et al., 2022).

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 (Kapllani et al., 2021).

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 PCNs from cast-on (Kapllani et al., 2021).

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 (Kapllani et al., 2021).

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 CNCells 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 (Kapllani et al., 2021).

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 ACNs 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 (Kapllani et al., 2021).

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 (Kapllani et al., 2021).

The complexity bounds are explicit. FINAL_LOCATION is $(i,j)\in\{0\ldots 2M-1\}\times\{0\ldots N\}$0 because it involves at most one horizontal recursion and at most one vertical chain up to three rows. ACNS_AT is $(i,j)\in\{0\ldots 2M-1\}\times\{0\ldots N\}$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 $(i,j)\in\{0\ldots 2M-1\}\times\{0\ldots N\}$2 steps, each $(i,j)\in\{0\ldots 2M-1\}\times\{0\ldots N\}$3, yielding an overall complexity of $(i,j)\in\{0\ldots 2M-1\}\times\{0\ldots N\}$4 (Kapllani et al., 2021).

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 $(i,j)\in\{0\ldots 2M-1\}\times\{0\ldots N\}$5. If the node is interior rather than a free end, it also stores two Eulerian coordinates $(i,j)\in\{0\ldots 2M-1\}\times\{0\ldots N\}$6 that track local sliding along warp and weft directions, together with a velocity $(i,j)\in\{0\ldots 2M-1\}\times\{0\ldots N\}$7 and, if interior, $(i,j)\in\{0\ldots 2M-1\}\times\{0\ldots N\}$8 (Gong et al., 2022).

Each yarn, whether warp or weft, is a chain of these crossing nodes. Adjacency is encoded as a list of segments

$(i,j)\in\{0\ldots 2M-1\}\times\{0\ldots N\}$9

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 (Gong et al., 2022).

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 (Gong et al., 2022).

The datatype thus integrates Lagrangian and Eulerian information. The node positions $\mathcal{G}=(V,E)$0 describe spatial configuration, while the scalar coordinates $\mathcal{G}=(V,E)$1 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 $\mathcal{G}=(V,E)$2 uses the energy

$\mathcal{G}=(V,E)$3

with force

$\mathcal{G}=(V,E)$4

where $\mathcal{G}=(V,E)$5 and $\mathcal{G}=(V,E)$6. The corresponding Jacobian is given in closed form (Gong et al., 2022).

Bending is defined at each interior node with neighbors along the same yarn. With

$\mathcal{G}=(V,E)$7

the energy is

$\mathcal{G}=(V,E)$8

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 $\mathcal{G}=(V,E)$9. The force includes spring, Coulomb-like, and damping terms, and explicit expressions for $f_{\rm mp}:(k,l)\mapsto \{(2k,l),(2k+1,l)\},$0 and $f_{\rm mp}:(k,l)\mapsto \{(2k,l),(2k+1,l)\},$1 are provided so that the static-to-kinetic transition is smooth (Gong et al., 2022).

Shear is defined between the two crossing segments at a node. If $f_{\rm mp}:(k,l)\mapsto \{(2k,l),(2k+1,l)\},$2 is the angle between the incident directions and $f_{\rm mp}:(k,l)\mapsto \{(2k,l),(2k+1,l)\},$3, then a shear-locking stiffness

$f_{\rm mp}:(k,l)\mapsto \{(2k,l),(2k+1,l)\},$4

is used, where $f_{\rm mp}:(k,l)\mapsto \{(2k,l),(2k+1,l)\},$5 ensures a smooth lock transition at $f_{\rm mp}:(k,l)\mapsto \{(2k,l),(2k+1,l)\},$6. The shear energy is

$f_{\rm mp}:(k,l)\mapsto \{(2k,l),(2k+1,l)\},$7

Additional terms include a parallel-yarn collision penalty

$f_{\rm mp}:(k,l)\mapsto \{(2k,l),(2k+1,l)\},$8

gravity per segment, and a wind force per triangle $f_{\rm mp}:(k,l)\mapsto \{(2k,l),(2k+1,l)\},$9, with the note that all wind-force terms are linear in $DS[2k][l].state=PCN,\qquad DS[2k+1][l].state=PCN.$0 and $DS[2k][l].state=PCN,\qquad DS[2k+1][l].state=PCN.$1, so the derivative is straightforward (Gong et al., 2022).

Contact resolution for vertex-face and edge-edge collisions is formulated as a small quadratic program,

$DS[2k][l].state=PCN,\qquad DS[2k+1][l].state=PCN.$2

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

$DS[2k][l].state=PCN,\qquad DS[2k+1][l].state=PCN.$3

where

$DS[2k][l].state=PCN,\qquad DS[2k+1][l].state=PCN.$4

After solving for $DS[2k][l].state=PCN,\qquad DS[2k+1][l].state=PCN.$5, the state is updated by

$DS[2k][l].state=PCN,\qquad DS[2k+1][l].state=PCN.$6

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 (Gong et al., 2022).

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 (Kapllani et al., 2021). 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 (Gong et al., 2022). 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.