TorchANI

TorchANI is a Python implementation of ANI machine learning model for energy calculation. Trained on a large dataset of DFT calculation results, TorchANI is able to obtain DFT-level accuracy in energy calculation in a fraction of the time. For more details, read the original paper. Making use of the PyCall package and Julia's native methods for code integration, ProtoSyn incorporates TorchANI as an EnergyFunctionComponent. The following section explains this integration in more detail, sub-divided in the following topics:

TorchANI EnergyFunctionComponent
TorchANI XML-RPC server
TorchANI reference energy EnergyFunctionComponent

TorchANI EnergyFunctionComponent

ProtoSyn.Calculators.TorchANI.get_ani_species — Function

get_ani_species(container::ProtoSyn.AbstractContainer)

Return a Vector{Int} with the atomic number of each Atom instance in the given AbstractContainer container, according to a periodic table.

Examples

julia> ProtoSyn.Calculators.TorchANI.get_ani_species(pose.graph[1][1])
11-element Vector{Int64}:
 7
 1
 6
 1
 6
 1
 1
 8
 1
 6
 8

source

ProtoSyn.Calculators.TorchANI.calc_torchani_ensemble — Function

Calculators.calc_torchani_ensemble([::A], pose::Pose, update_forces::Bool = false) where {A <: ProtoSyn.AbstractAccelerationType}

Calculate and return the Pose pose energy according to the whole TorchANI neural network ensemble. The optional A parameter defines the acceleration type used. If left undefined the default ProtoSyn.acceleration.active mode will be used. By setting the update_forces flag to true (false by default), this function will also calculate and return the forces acting on each atom based on the whole TorchANI neural network ensemble.

See also:

calc_torchani_model

Examples

julia> ProtoSyn.Calculators.TorchANI.calc_torchani_ensemble(pose)
(-0.12801790237426758, nothing)

julia> ProtoSyn.Calculators.TorchANI.calc_torchani_ensemble(pose, true)
(-0.12801788747310638, [ ... ])

source

ProtoSyn.Calculators.TorchANI.calc_torchani_model — Function

calc_torchani_model([::A], pose::Pose, selection::Opt{AbstractSelection}, update_forces::Bool = false; model::Int = 3) where {A}

Calculate and return the Pose pose energy according to a single TorchANI model neural network. The model can be defined using model_index (from model 1 to 8, default is 3).The optional A parameter defines the acceleration type used. If left undefined the default ProtoSyn.acceleration.active mode will be used. By setting the update_forces flag to true (false by default), this function will also calculate and return the forces acting on each atom based on a single TorchANI model neural network.

Note:

Each model will return a slightly different value for the energy of the molecular system. Use calc_torchani_ensemble for a more accurate (and slow) energy prediction. However, as in most cases the energy value is used in comparison with multiple states/frames, calc_torchani_ensemble prediction may be suficient.

Examples

julia> ProtoSyn.Calculators.TorchANI.calc_torchani_model(pose)
(-0.12573561072349548, nothing)

julia> ProtoSyn.Calculators.TorchANI.calc_torchani_model(pose, true)
(-0.12573561072349548, [ ... ])

Note:

In ProtoSyn >= 1.0, this function has a memory leak on the Python call. Multiple calls to calc_torchani_model require often GC.gc(false) calls to impede the 'CUDA out of memory' error. In order to prevent/automate this process, consider the following options:

(1) - Use an EnergyFunction struct (with automatic calls to GC.gc(false), as in:

EnergyFunction([ProtoSyn.Calculators.TorchANI.get_default_torchani_model()])

(2) - Use calc_torchani_model_xmlrpc instead.

source

ProtoSyn.Calculators.TorchANI.get_default_torchani_ensemble — Function

get_default_torchani_ensemble(;[α::T = 1.0]) where {T <: AbstractFloat}

Return the default TorchANI ensemble EnergyFunctionComponent. α sets the component weight (on an EnergyFunction instance). This component employs the calc_torchani_ensemble method, therefore predicting a structure's TorchANI energy based on the whole TorchANI ensemble (Note: This can be very slow).

Examples

julia> ProtoSyn.Calculators.TorchANI.get_default_torchani_ensemble()
🞧  Energy Function Component:
+---------------------------------------------------+
| Name           | TorchANI_ML_Ensemble             |
| Alpha (α)      | 1.0                              |
| Update forces  | true                             |
| Calculator     | calc_torchani_ensemble           |
+---------------------------------------------------+
 └──  ○  Selection: nothing

source

ProtoSyn.Calculators.TorchANI.get_default_torchani_model — Function

get_default_torchani_model(;[α::T = 1.0]) where {T <: AbstractFloat}

Return the default TorchANI model EnergyFunctionComponent. α sets the component weight (on an EnergyFunction instance). This component employs the calc_torchani_model method, therefore predicting a structure's TorchANI energy based on a single model.

Settings

model::Int - Defines which model of the TorchANI ensemble to use.

Examples

julia> ProtoSyn.Calculators.TorchANI.get_default_torchani_model()
🞧  Energy Function Component:
+---------------------------------------------------+
| Name           | TorchANI_ML_Model                |
| Alpha (α)      | 1.0                              |
| Update forces  | true                             |
| Calculator     | calc_torchani_model              |
+---------------------------------------------------+
 |    +----------------------------------------------------------------------------------+
 ├──  ● Settings                      | Value                                            |
 |    +----------------------------------------------------------------------------------+
 |    | model                         | 3                                                |
 |    +----------------------------------------------------------------------------------+
 |    
 └──  ○  Selection: nothing

source

ProtoSyn TorchANI Components

Figure 1 | A diagram representation of the default TorchANI ML Ensemble and TorchANI ML Model EnergyFunctionComponent instances, obtained by usign the get_default_torchani_ensemble and get_default_torchani_model methods, respectively. While the TorchANI ML Ensemble is more accurate, it's also significantly slower. Depending on the application, employing a single model of the ensemble (of 8 models) might be sufficient.

TorchANI XML-RPC server

ProtoSyn also makes available the TorchANI ML Model EnergyFunctionComponent instance as a call to an XML-RPC server. This protocol spawns a Python server in parallel, running TorchANI, who receives XML requests from Julia and returns the calculated energy and forces. This functionality might be useful in certain systems and machines.

ProtoSyn.Calculators.TorchANI.start_torchANI_server — Function

start_torchANI_server()

If TorchANI.server is set to nothing, start a new TorchANI XML-RPC server. Return a XMLRPC.ClientProxy (used to send XML requests to the created server).

See also:

stop_torchANI_server

Examples

julia> ProtoSyn.Calculators.TorchANI.start_torchANI_server()
Starting TorchANI XML-RPC server ...
TorchANI XML-RPC server is online!
ProtoSyn.XMLRPC.ClientProxy("http://localhost", 50000, "http://localhost:50000")

julia> ProtoSyn.Calculators.TorchANI.start_torchANI_server()
┌ Warning: TorchANI XML-RPC server is already online!
└ @ ProtoSyn.Calculators.TorchANI ~/project_c/ProtoSyn.jl/src/Core/Calculators/torchani_xmlrpc.jl:25
ProtoSyn.XMLRPC.ClientProxy("http://localhost", 50000, "http://localhost:50000")

source

ProtoSyn.Calculators.TorchANI.stop_torchANI_server — Function

stop_torchANI_server()

If TorchANI.server is not set to nothing, kill the current TorchANI XML-RPC server.

See also:

start_torchANI_server

Examples

julia> ProtoSyn.Calculators.TorchANI.stop_torchANI_server()

julia> ProtoSyn.Calculators.TorchANI.stop_torchANI_server()
┌ Warning: No online TorchANI XML-RPC server was found.
└ @ ...

source

ProtoSyn.Calculators.TorchANI.calc_torchani_model_xmlrpc — Function

Calculators.calc_torchani_model_xmlrpc([::A], pose::Pose, selection::Opt{AbstractSelection}, [update_forces::Bool = false]; [model::Int = 3]) where {A}

Calculate the pose energy according to a single TorchANI model neural network, using the XML-RPC protocol. If no TorchANI XML-RPC server is found, a new one is spawned (in parallel) from file torchani_server.py. The model can be defined using model (from model 1 to 8, default is 3). The optional A parameter defines the acceleration mode used (only CUDA_2 is available, any other acceleration type will result in an error). If left undefined the default ProtoSyn.acceleration.active type will be used. If update_forces is set to true (false, by default), return the calculated forces on each atom as well.

Examples

julia> ProtoSyn.Calculators.TorchANI.calc_torchani_model_xmlrpc(pose)
(4.698066234588623, nothing)

julia> ProtoSyn.Calculators.TorchANI.calc_torchani_model_xmlrpc(pose, true)
(4.698066234588623, [ ... ])

Note:

If you use this function in a script, it is recommended to add ProtoSyn.Calculators.TorchANI.stop_torchANI_server() at the end of the script, as the automatic stopping of TorchANI XML-RPC server is not yet implemented, as of ProtoSyn >= 1.0.

source

ProtoSyn.Calculators.TorchANI.get_default_torchani_model_xmlrpc — Function

get_default_torchani_model_xmlrpc(;[α::T = 1.0]) where {T <: AbstractFloat}

Return the default TorchANI model EnergyFunctionComponent. α sets the component weight (on an EnergyFunction instance). This component employs the calc_torchani_model_xmlrpc method, therefore predicting a structure's TorchANI energy based on a single model and starting a new XMLRPC server (in parallel) if necessary.

Settings

model::Int - Defines which model of the TorchANI ensemble to use.

See also

calc_torchani_model_xmlrpc

Examples

julia> ProtoSyn.Calculators.TorchANI.get_default_torchani_model_xmlrpc()
🞧  Energy Function Component:
+---------------------------------------------------+
| Name           | TorchANI_ML_Model_XMLRPC         |
| Alpha (α)      | 1.0                              |
| Update forces  | true                             |
| Calculator     | calc_torchani_model_xmlrpc       |
+---------------------------------------------------+
 |    +----------------------------------------------------------------------------------+
 ├──  ● Settings                      | Value                                            |
 |    +----------------------------------------------------------------------------------+
 |    | model                         | 3                                                |
 |    +----------------------------------------------------------------------------------+
 |    
 └──  ○  Selection: nothing

source

TorchANI reference energy EnergyFunctionComponent

In design protocols (where one or more Residue mutations occur), it is often more important to measure the ΔΔG of mutation, that is, the change in the system's energy with the change of nature (and number) of particles that comprise it. Since the TorchANI EnergyFunctionComponent is, inherently, a sumation of all individual atomic energetic contributions, a change in the number of particles always comes with a change in energy (as an example, in any environment, a bigger aminoacid with almost always induce an increase in the overall system's energy, even if the interactions it creates estabilize this mutation). In fact, when using the TorchANI EnergyFunctionComponent, both the internal and interacting energy of a Residue instance are being measured. By subtracting the TorchANI reference energy EnergyFunctionComponent (that is, only a measure of the internal energy of a Residue), it is possible to have a better gauge at the interacting energies that mutation or change induces, and therefore a better estimation of the ΔΔG value.

ProtoSyn.Calculators.TorchANI.calc_torchani_internal_energy — Function

calc_torchani_internal_energy(M::Type{<: ProtoSyn.AbstractAccelerationType}, pose::Pose, selection::AbstractSelection, [update_forces::Bool = false]; [static_ref_energy::T = 0.0], [use_ensemble::Bool = false], [model::Int = 3]) where {T <: AbstractFloat}

Calculate and return the Pose pose internal energy according to a single TorchANI model neural network. The internal energy is the TorchANI energy value for intra-residue interactions only. This should be used in conjuntion with the calc_torchani_model and calc_torchani_ensemble in design efforts (thus providing a correct ΔΔG of mutation). The employed model can be defined using the model parameter (from model 1 to 8, default is 3). Optionally, if the use_ensemble flag is set to true, the whole TorchANI ensemble will be used to calculate the internal energy. The optional A parameter defines the acceleration type used. If left undefined the default ProtoSyn.acceleration.active mode will be used. By setting the update_forces flag to true (false by default), this function will also calculate and return the forces acting on each atom based on a single TorchANI model neural network. If provided, an AbstractSelection selection defines a sub-set of Residue instances to calculate the internal energy on (if the provided AbstractSelection selection is not of Residue type, it will be promoted using the promote method). The parameter static_ref_energy defines an energy value that is summed to the calculated energy. In order to improve performance: it is often the case where a single Residue instance is being design at a time. In such cases, by applying an AbstractSelection selection and defining the static_ref_energy as the internal energy of all non-mutated Residue instances, a faster internal energy calculation can be accurately reproduced.

Examples

julia> ProtoSyn.Calculators.TorchANI.calc_torchani_internal_energy(pose, nothing)
(-1.9374065455049276, nothing)

source

ProtoSyn.Calculators.TorchANI.get_default_torchani_internal_energy — Function

get_default_torchani_internal_energy(;[α::T = 1.0]) where {T <: AbstractFloat}

Return the default TorchANI internal energy model EnergyFunctionComponent. α sets the component weight (on an EnergyFunction instance). This component employs the calc_torchani_internal_energy method, therefore predicting a structure's TorchANI internal energy based on a single model or ensemble.

Settings

use_ensemble::Bool - Defines whether to use a single model or the whole TorchANI ensemble to calculate the structure's internal energy;
model::Int - If using a single model to calculate the structure's internal energy, define which model (from 1 to 8);
static_ref_energy::T - Define a static energy value to add to the calculated internal energy (where T <: AbstractFloat);

Examples

julia> ProtoSyn.Calculators.TorchANI.get_default_torchani_internal_energy()
🞧  Energy Function Component:
+---------------------------------------------------+
| Name           | TorchANI_Ref_Energy              |
| Alpha (α)      | 1.0                              |
| Update forces  | true                             |
| Calculator     | calc_torchani_internal_energy    |
+---------------------------------------------------+
 |    +----------------------------------------------------------------------------------+
 ├──  ● Settings                      | Value                                            |
 |    +----------------------------------------------------------------------------------+
 |    | static_ref_energy             | 0.0                                              |
 |    | use_ensemble                  | false                                            |
 |    | model                         | 3                                                |
 |    +----------------------------------------------------------------------------------+
 |    
 └──  ○  Selection: nothing

source

ProtoSyn.Calculators.TorchANI.fixate_static_ref_energy! — Function

fixate_static_ref_energy!(efc::EnergyFunctionComponent, pose::Pose, [selection::Opt{AbstractSelection} = nothing])

If the given EnergyFunctionComponent efc is a TorchANI Reference Energy EnergyFunctionComponent, calculate a new static_ref_energy on the given Pose pose and apply it as a static internal energy value (improved performance). If an AbstractSelection selection is provided, the internal energy is only calculated in the subset of selected Residue instances.

See also

get_default_torchani_internal_energy

Examples

julia> ProtoSyn.Calculators.TorchANI.fixate_static_ref_energy!(efc, pose, rid"1:20")
-0.3799925707280636

source