Foldit Wiki


integer band.AddBetweenSegments(integer segmentIndex1, integer segmentIndex2, [integer atomIndex1], [integer atomIndex2], [integer symnr2])
Add a band between the two segments. By default bands to the backbone. Specify an atom number from 1 to structure.GetAtomCount() to band to a different atom. Returns band number. Specify an symnr from 0 to structure.GetSymCount() to band to segmentIndex2 of a symmetric copy.
V1 Function Name

band.AddBetweenSegments adds a band between the specified segments.

By default, the band is added to the alpha carbon atom of each segment. The parameters atomIndex1 and atomIndex2 can be used to specify different atoms for each segment. Atom numbers must be in the range 1 to structure.GetAtomCount for each segment.

For symmetry puzzles, specifying symnr2 allows the band to end on one of the symmetric copies of the main chain. Bands always begin on the main chain. The value of symnr2 must not exceed the value returned by structure.GetSymCount. If symnr2 is zero, the band endpoint is on the main chain. (Symmetric banding is available starting in the devprev release 20191029-32048a6a12-win_x86-devprev or equivalent on other platforms.)

When using symnr2 for symmetric banding, the optional atom number arguments must be specified. Use nil to band to the default atom:

band.AddBetweenSegments ( 5, 5, nil, nil, 2 )

This example creates a band from segment 5 on the main chain (symmetric chain 0) to segment 5 on symmetric chain 2. The nil arguments mean the band is added between the default atoms (the alpha carbon) of each segment.

The added band has a default goal length of 3.5 Angstroms. Goal length can be changed by band.SetGoalLength, and queried by band.GetGoalLength.

The added band has a default strength of 1.0. Strength can be changed by band.SetStrength, and queried by band.GetStrength.

The added band always has an actual length, which is the distance in Angstroms between the two atoms. The actual length changes as parts of the protein move, but it can't be set directly. The actual length can be queried by band.GetLength.

A band created using the default atom numbers has an actual length that's normally the same as the length reported by structure.GetDistance.

Caution: the returned band index may be zero. A zero band index causes an error in other functions, such as band.SetStrength.

One case which returns a zero band index is banding a segment to itself, for example:

bIdx = band.AddBetweenSegments ( 21, 21 )

This is a rare case of a Foldit Lua function setting a return code. Most other Foldit functions "throw" an error in the case of bad parameters. In most cases, this terminates the recipe, but the thrown error can be "caught" by calling the function in question via the pcall function.