Nodes File

Extension: .pts

The node (or points) file starts with a single header line with the number of nodes, followed by the coordinate of the nodes, one per line, in \(\mu m\). For example, for a mesh with \(n\) nodes we have:

Format Example
\(n\) 10000
\(x_0 \, y_0 \, z_0\) 10.3400 -15.0023 12.023
\(x_1 \, y_1 \, z_1\) 11.4608 -12.0237 11.982
\(\ldots\) \(\ldots\)
\(x_{n-1} \, y_{n-1} \, z_{n-1}\) -8.4523 36.7472 4.6742

Element File

Extension: .elem

In general, CARPentry supports various types of elements which can be mixed in a single mesh. However, not all element types are supported in every context, some limitations apply. In electrophysiology simulations element types can be mixed, whereas in mechanics only tetrahedral and hexahedral elements are support. The simple native element file format is as follow

The file begins with a single header line containing the number of elements, followed by one element definition per line. The element definitions are composed by an element type specifier string, the nodes for that element, then optionally an integer specifying the region to which the element belongs.

For example, for a mesh with \(n\) elements and where

  • \(T_i\) is the type specifier of element \(i\),
  • \(N_{i,j}\) indices the \(j\)-th node of element \(i\),
  • \(m_i\) is the number of nodes of element \(i\) and
  • \(r_i\) is the optional region of element \(i\),

the format is given as:

Format Example
\(n\) 20000
\(T_0 \, N_{0,0} \, N_{0,1} \ldots N_{0,m_i-1} \, [r_0]\) Tt 10 15 123 45 1
\(T_1 \, N_{1,0} \, N_{1,1} \ldots N_{1,m_i-1} \, [r_1]\) Pr 45 36 100 54 35 74 0
\(\ldots\) \(\ldots\)
\(T_{n-1} \, N_{n-1,0} \, N_{n-1,1} \ldots N_{n-1,m_i-1} \, [r_{n-1}]\) Tt 9374 7432 1234 4532 1

The node indicies are determined by their order in the points file. Note that the nodes are 0-indexed, as indicated in Sec. Node File above. The element formats supported in CARP, including their element type specifier strings are given in table. The ordering of nodes in each of the 3D element types is shown here.

Element types supported in CARPentry for different physics. Electrophysiology (EP), Mechanics (MECH) and Fluid (FL). \(^*\) for internal use only, not supported in mesh files.

Type Specifier Description Interpolation #Nodes Supported in
Ln Line linear 2 EP
cH \(^*\) Line cubic 2 HPS
Tr Triangle linear 3 EP
Qd Quadrilateral Ansatz 4 EP
Tt Tetrahedron linear 4 EP, MECH, FL
Py Pyramid Ansatz 5 EP
Pr Prism Ansatz 6 EP
Hx Hexahedron Ansatz 8 EP

Nodal ordering of 3D element types.

Fiber File

Extension: .lon

Fibres are defined in CARP on a per-element basis. They may be defined by just the fibre direction, in which case a traversely isotropic conductivity or mechanics material model must be used, or additionally specifying the sheet (or transverse) direction to allow full orthotropy in the model.

The file format starts with a single header line with the number of fibre vectors defined in the file (1 for fibre direction only, 2 for fibre and sheet directions), and then one line per element with the values of the fibre vector(s). Note that the number of fibres must equal the number of elements read from the element file.

For example, where \(n_f\) is the number of fibre vectors (1 or 2), \(f_i,\{x,y,z\}\) are the components of the fibre vector for element \(i\) and \(s_i,\{x,y,z\}\) are the components of the sheet vector for element \(i\):

Format Example
\(n_f\) 2
\(f_{0,x} \, f_{0,y} f_{0,z} \, [s_{0,x} \, s_{0,y} s_{0,z}]\) 0.831 0.549 0.077 0.473 -0.775 0.417
\(f_{1,x} \, f_{1,y} f_{1,z} \, [s_{1,x} \, s_{1,y} s_{1,z}]\) 0.647 0.026 0.761 -0.678 0.475 0.560
\(\ldots\) \(\ldots\)
\(f_{n-1,x} \, f_{n-1,y} \, f_{n-1,z} \, [s_{n-1,x} \, s_{n-1,y} \, s_{n-1,z}]\) 0.552 0.193 0.810 -0.806 0.369 0.462

The fibre and sheet vectors should be orthogonal and of unit length.

Vertex File

Extension: .vtx

An collection of preferably unique mesh indices may be stored in a vertex file.

Format Example
N # number of nodes 192
intra/extra # definition domain intra
\(node_0\) 47
\(node_1\) 123
\(\ldots\) \(\ldots\)
\(node_{N-1}\) 23943
  • A stimulus electrode file, e.g. apex.vtx may be added in the parameter file as follows: -stimulus[0].vtx_file apex
  • The extra-domain refers to the entire user-specified mesh.
  • The intra-domain refers to the geometry where non-zero fibers were defined.
  • Although intra and extra should be the the same for tissue-only geometries, CARPentry/mechanics may not like vtx-files stating the vertices as intra domain.

Purkinje File

Extension: .pkje

The format of the Purkinje file is very specific and must be followed carefully. The # character begins a comment. It and everything following on a line are ignored. Section gives the exact rules for defining Purkinje networks. Below there are comments explaining the different fields inside the file Purkinje.pkje.

   Number_of_Cables
   Cable 0
   Father1 Father2
   Son1 Son2
   Nodes_Cable
   Size
   Gap_junction_resistance
   Intracellular_conductivity
   Node1_x Node1_y Node1_z
   ...
   NodeN_x NodeN_y NodeN_z
   Cable 1
   ...

Note that if a parent or son is unassigned, it is Father2 or Son2 that is assigned a value of -1. An example of a few lines from a Purkinje file follows:

   97      # Number of Cables present in the tree [0-96]
   Cable 0 # Cable 0 is always the first
   -1 -1   # no Fathers for Cable 0
   1 2     # Son 1 and Son 2
   4       # Number of nodes in this Cable
   75      # Relative size of cable (i.e. #parallel fibres or cross-sectional area)
   100.0   # gap junction resistance (kOhm)
   0.0006  # conductivity (Ohm-cm)
   1100 -3400 2200 # NODE 1
   1149 -3300 2178 # NODE 2
   1184 -3201 2165 # NODE 3
   1201 -3090 2154 # NODE 4
   Cable 1 # Cable 1, (order must be followed)
   0 -1    # FATHER1 = Cable 0, no Father2
   3 -1    # SON1 = Cable 3, no Son2
   80      # Number of nodes = 80
   7.0
   100.0
   0.0006
   1201 -3090 2154
   1245 -3020 2143
   1209 -2975 2133
   .
   .
   .

missing link target purk-file-rules

Purkinje-Myocardial Junction (PMJ) Tuning File

Extension: .pmj

After the global PMJ parameters are applied, individual junction parameters are set based on values in a file. Cables specified must have a PMJ.

   #junctions
   cable_no R_PMJ PMJ_scale
   cable_no R_PMJ PMJ_scale
       .
       .
       .
   cable_no R_PMJ PMJ_scale

Pulse File

Note that time values must increase, that is, \(t_0 < t_1 < \ldots < t_i < \ldots < t_{N-1}\)

   N # Number_of_samples
   t0  val0
   t1  val1
   .
   .
   .
   t(N-1)  val(N-1)

Vertex Adjustment File

Extension: .adj

   N           # Number_of_nodes
   intra|extra # definition domain
   node_0 val_0
   node_1 val_1
   .
   .
   .
   node_n-1 val_n-1

Neumann Boundary File

Extension: .neubc

TBA

Restitution Protocol Definition File

Output File Formats