Edit on GitHub

State

This section lists functions that work on the system State. These methods are subdivided by topics, for organization purposes:

Cartesian and internal coordinates conversion

The following functions deal with the conversion from internal to cartesian coordinates and vice-versa.

Note:

Internal to cartesian conversion functions (and vice-versa) only apply to AtomState instances that have been modified (and therefore have the :changed field set to true). In the case of internal to cartesian coordinates conversion, updating any AtomState automatically forces downstream AtomState instances to be changed, and therefore updated. Note that the :changed flag is automatically set to true when modifying any AtomState field (including when changing the paired state.x StateMatrix), but the container state.i2c flag is not altered until explicitly request by request_i2c! or request_c2i! methods.

ProtoSyn.request_c2i! — Function
request_c2i!(state::State; [all::Bool = false])

Sets state.c2i to true. If all is set to true (false, by default), update all AtomState instances in the given State state to have :changed field set to true. Return the altered State state.

See also

request_i2c! c2i!

Examples

julia> ProtoSyn.request_c2i!(pose.state)
State{Float64}:
 Size: 343
 i2c: false | c2i: true
 Energy: Dict(:Total => Inf)
source
ProtoSyn.request_i2c! — Function
request_i2c!(state::State; [all::Bool = false])

Sets state.i2c to true. If all is set to true (false, by default), update the first AtomState instance in the given State state (in the Root) to have :changed field set to true. Return the altered State state.

See also

request_c2i! i2c!

Examples

julia> ProtoSyn.request_i2c!(pose.state)
State{Float64}:
 Size: 343
 i2c: true | c2i: false
 Energy: Dict(:Total => Inf)
source
ProtoSyn.c2i! — Function
c2i!(state::State{T}, top::Topology)

Update the internal coordinates to match the measured cartesian coordinates, in the given State state. Note that only the AtomState instances with :changed field set to true will be updated, and the flag is therefore changed to false. Return the altered State state instance. If state.c2i is not set to true, return the original State state instance, without changes.

See also

i2c! request_c2i!

Examples

julia> ProtoSyn.c2i!(pose.state, pose.graph)
State{Float64}:
 Size: 343
 i2c: false | c2i: false
 Energy: Dict(:Total => Inf)
source
ProtoSyn.i2c! — Function
i2c!(state::State{T}, top::Topology)

Update the cartesian coordinates to match the measured internal coordinates, in the given State state. Note that only the AtomState instances with :changed field set to true will be updated, and the flag is therefore changed to false. Return the altered State state instance. If state.c2i is not set to true, return the original State state instance, without changes.

Note:

Any AtomState that requires an update (has :changed flag set to true) will cause all downstream residues to be updated as well (in the same Graph).

See also

c2i! request_i2c!

Examples

julia> ProtoSyn.i2c!(pose.state, pose.graph)
State{Float64}:
 Size: 343
 i2c: false | c2i: false
 Energy: Dict(:Total => Inf)
source
ProtoSyn.sync! — Function
sync!(state::State, topology::Topology)

Check whether the given State state instance has either i2c or c2i flag set to true and if so update the cartesian/internal coordinates accordingly. Return the altered State instance. 

sync!(pose::Pose)

Check whether the given Pose instance has either i2c or c2i flag set to true in its pose.state field and if so update the cartesian/internal coordinates accordingly. Return the altered Pose instance.

Note:

Requesting both i2c and c2i conversions simultaneously is not possible and will result in an error. Consider calling i2c! or c2i! to choose one of the coordinate systems to be synched.

See also

i2c! c2i!

Examples

julia> sync!(pose.state, pose.graph)
State{Float64}:
 Size: 343
 i2c: false | c2i: false
 Energy: Dict(:Total => Inf)
source

ProtoSyn c&i

Figure 1 | A diagram depicting the differences between the cartesian and internal coordinate systems. In the case of cartesian coordinates, each AtomState position is described by 3 numbers, the X, Y and Z coordinates. A StateMatrix compiles all cartesian coordinates and is useful when applying certain types of conformation changes. Employing the c2i! function allows for the synchronization of cartesian coordinates to internal coordinates. In this coordinate system, the position of each atom is still described by 3 numbers, but these are now the distance (b), angle (θ) and dihedral angle (ϕ) values relative to the parent/grand-parents. As an example, the position of the highlighted atom 12 is described by the distance to atom 11, the angle between atoms 9, 11 and itself, and finally by the dihedral angle of the atoms 8, 9, 11 and itself. Since a set of ascendents is necessary to establish the position of an AtomState, a set of 3 pseudoatoms (know as root) is necessary at the beggining of a Topology. Using this type of coordinates, it becomes extremly simple and efficient to perform large scale rotations of dihedral angles, since all positions are calculated based on the relative position to the ascendents. Employing the i2c! function allows for the synchronization from internal coordinates to cartesian coordinates.

Dihedral rotations

The next functions deal with setting and rotating dihedral angles.

ProtoSyn.getdihedral — Function
getdihedral(state::State, atom::Atom)

Get the current dihedral value for Atom atom of State state (in radians, based on the internal coordinates). This value is the sum of the intrisic dihedral angle ϕ and the second ascendent Δϕ.

See also

ascendents setdihedral! dihedral

Examples

julia> getdihedral(pose.state, pose.graph[1][2]["N"])
3.141592653589793
source
ProtoSyn.setdihedral! — Function
setdihedral!(state::State, atom::Atom, value::T) where {T <: AbstractFloat}

Set the dihedral in Atom atom of State state to be exactly value (in radians). Automatically requests internal to cartesian coordinate conversion (by setting state.i2c as true). Return the altered State state.

setdihedral!(pose::Pose, sele::AbstractSelection, value::T) where {T <: AbstractFloat}

Alternativelly, set the dihedral in the (first) selected Atom instance given by the AbstractSelection sele in the given Pose pose to the provided value. Return the altered Pose pose.

See also

ascendents request_i2c! getdihedral rotate_dihedral!

Examples

julia> setdihedral!(pose.state, pose.graph[1][1][end], Float64(π))
State{Float64}:
 Size: 343
 i2c: true | c2i: false
 Energy: Dict(:Total => Inf)
source
ProtoSyn.rotate_dihedral! — Function
rotate_dihedral!(state::State, atom::Atom, value::T) where {T <: AbstractFloat}

Rotate the dihedral in Atom atom of State state by value (in radians, adds to the current dihedral angle). Automatically requests internal to cartesian coordinate conversion (by setting state.i2c as true). Return the altered State state.

See also

ascendents request_i2c! getdihedral setdihedral!

Examples

julia> rotate_dihedral!(pose.state, pose.graph[1][1][end], Float64(π))
State{Float64}:
 Size: 343
 i2c: true | c2i: false
 Energy: Dict(:Total => Inf)
source
ProtoSyn.setoffset! — Function
setoffset!(state::State{T}, at::Atom, default::Number) where {T <: AbstractFloat}

Rotate all sibling dihedrals of Atom atom in the given State state so that the dihedral angle identified by atom is equal to default. Set the i2c flag to true and return the altered State state.

See also

LGrammar

Examples

julia> ProtoSyn.setoffset!(pose.state, pose.graph[1][2]["CA"], 3.14)
State{Float64}:
 Size: 343
 i2c: true | c2i: false
 Energy: Dict(:Total => Inf)
source

ProtoSyn c&i

Figure 2 | An illustration of rotate_dihedral! method in action. This method (as well as setdihedral!) rotate a dihedral by altering the :Δφ field in the correct AtomState instance. For this example, the rotate_dihedral! was applied to atom C. The position of this atom, according to the internal coordinates system, is dictated by 3 numbers: the distance, angle and dihedral angle to its ascendents. This last value, the dihedral angle, can be further decomposed in 2 contributions: the AtomState intrinsic dihedral field (:φ) plus the parent AtomState :Δφ field. Since this logic applies to all AtomState instances, both atoms CB and HA of this example also have their position dictated by its parent AtomState :Δφ field, which, in this case, is CA. This means that altering :Δφ in CA will affect the position of C, CB and HA by the same measure, in a concerted manner. This, in essence, means rotating the C-N-CA-C dihedral (or Phi dihedral of the aminoacid, in this example). Note that since we are using internal coordinates, this rotation is also applied to all children AtomState instances, since their position is relative to the parent.

Measuring distances, angles and dihedrals

ProtoSyn.distance — Function
distance(at1::AtomState, at2::AtomState)

Calculates the distance between the two AtomState instances (at1 and at2), based on the cartesian coordinates. Note: Make sure the corresponding Pose instance has been synched (using the sync! method). Returns result in Angstrom (Å).

See also

angle dihedral

Examples

julia> d = ProtoSyn.distance(pose.state[1], pose.state[2])
1.0093879999999997
source
ProtoSyn.angle — Function
angle(at1::AtomState, at2::AtomState, at3::AtomState)

Calculates the angle between the three AtomState instances (at1, at2 and at3), based on the cartesian coordinates. Note: Make sure the corresponding Pose instance has been synched (using the sync! method). Returns result in radians.

See also

distance dihedral

Examples

julia> a = ProtoSyn.angle(pose.state[1], pose.state[2], pose.state[3])
0.6444967663659441
source
ProtoSyn.dihedral — Function
dihedral(at1::AtomState, at2::AtomState, at3::AtomState, at4::AtomState)

Calculates the dihedral angle between the four AtomState instances (at1, at2, at3 and at4), based on the cartesian coordinates. Note: Make sure the corresponding Pose instance has been synched (using the sync! method). Returns result in radians.

Examples

julia> a = ProtoSyn.dihedral(pose.state[1], pose.state[2], pose.state[3], pose.state[4])
-1.2318251145557122
source

Indexation

In order to access an AtomState instance in a State, ProtoSyn makes available, essentially, three methods:

  • Using the regular syntax;
julia> pose.state.items[4]ERROR: UndefVarError: pose not defined
Note:

In the items field, AtomState instances are indexed including the Root (which occupies the first three positions). Atom 1 is therefore at index 4. This is taken into account when using the short syntax (recommended).

  • Using the short syntax with index;
julia> pose.state[1]ERROR: UndefVarError: pose not defined
  • Using the short syntax with an Atom instance;
julia> atom = pose.graph[1, 1, 1]ERROR: UndefVarError: pose not defined
julia> pose.state[atom]ERROR: UndefVarError: pose not defined

Indexation methods make sure the Pose State structure remains coherent with the Graph structure, in terms of order.

ProtoSyn.reindex — Method
reindex(state::State)

Re-indexes the whole State state (excluding the Root), setting the :index field of AtomState instances. Return the altered State state.

Note:

Since we are altering a field of AtomState structs, the :changed field will automatically be set to true and therefore be updated in a future sync! call (if either :i2c or :c2i flag in the corresponding state is set to true).

See also

reindex(::Topology, ::Bool)

Examples

julia> reindex(pose.state)
State{Float64}:
 Size: 343
 i2c: false | c2i: false
 Energy: Dict(:Total => Inf)
source