sponge.core.Sponge

class sponge.core.Sponge(network: Union[Molecule, WithEnergyCell, RunOneStepCell], potential: PotentialCell = None, optimizer: Optimizer = None, metrics: dict = None, analysis: AnalysisCell = None, **kwargs)

Core engine of MindSPONGE for simulation and analysis.

This Cell is the top-level wrapper for the three modules system ( sponge.system.Molecule),potential (sponge.potential. PotentialCell) and optimizer (mindspore.nn.Optimizer) in MindSPONGE.

There are three ways to wrap the modules:

1. Wraps system, potential and optimizer directly into sponge.core.Sponge.

from sponge import Sponge
from sponge.system import Molecule
from sponge.potential.forcefield import ForceField
from sponge.optimizer import Updater
system = Molecule(template='water.tip3p.yaml')
potential = ForceField(system, parameters='SPCE')
optimizer = Updater(system, controller=None, time_step=1e-3)
md = Sponge(system, potential, optimizer)

In this way ordinary simulations can be achieved

2) Wrap system and potential with sponge.core.WithEnergyCell first, then wrap sponge.core.WithEnergyCell and optimizer with sponge.core.Sponge.

from sponge import WithEnergyCell, Sponge
from sponge.system import Molecule
from sponge.potential.forcefield import ForceField
from sponge.optimizer import Updater
system = Molecule(template='water.tip3p.yaml')
potential = ForceField(system, parameters='SPCE')
optimizer = Updater(system, controller=None, time_step=1e-3)
sys_with_ene = WithEnergyCell(system, potential)
md = Sponge(sys_with_ene, optimizer=optimizer)

In this case, the adjustment of the potential can be achieved by adjusting the sponge.core.WithEnergyCell, for example by setting the neighbour_list and the bias in sponge.core.WithEnergyCell.

3) Wrap system and potential with sponge.core.WithEnergyCell first, then wrap sponge.core.WithEnergyCell and optimizer with sponge.core.RunOneStepCell, and finally pass the sponge.core.RunOneStepCell into sponge.core.Sponge.

from sponge import WithEnergyCell, RunOneStepCell, Sponge
from sponge.system import Molecule
from sponge.potential.forcefield import ForceField
from sponge.optimizer import Updater
system = Molecule(template='water.tip3p.yaml')
potential = ForceField(system, parameters='SPCE')
optimizer = Updater(system, controller=None, time_step=1e-3)
sys_with_ene = WithEnergyCell(system, potential)
one_step = RunOneStepCell(sys_with_ene, optimizer=optimizer)
md = Sponge(one_step)

In this case, the adjustment of the force can be achieved by adjusting the sponge.core.RunOneStepCell, for example by adding a sponge.potential.ForceCell to the sponge.core.RunOneStepCell.

For simulations:

Simulation can be performed by executing the member function sponge.core.Sponge.run().

from sponge import Sponge
from sponge.system import Molecule
from sponge.potential.forcefield import ForceField
from sponge.optimizer import Updater
system = Molecule(template='water.tip3p.yaml')
potential = ForceField(system, parameters='SPCE')
optimizer = Updater(system, controller=None, time_step=1e-3)
md = Sponge(system, potential, optimizer)
md.run(100)

For analysis:

sponge.core.Sponge can also analyse the simulation system by metrics. The metrics should be a dictionary of sponge.metrics.Metric or sponge.colvar.Colvar. The value of the metrics can be calculated by executing the member function sponge.core.Sponge.analyse().

from sponge import Sponge
from sponge.colvar import Torsion
from sponge import Protein
from sponge.potential.forcefield import ForceField
from sponge.optimizer import SteepestDescent
# You can find alad.pdb file under MindSPONGE/tutorials/advanced/alad.pdb
system = Protein(pdb='alad.pdb')
potential = ForceField(system, 'AMBER.FF14SB')
optimizer = SteepestDescent(system.trainable_params(), 1e-7)
phi = Torsion([4, 6, 8, 14])
psi = Torsion([6, 8, 14, 16])
md = Sponge(system, potential, optimizer, metrics={'phi': phi, 'psi': psi})
metrics = md.analyse()
for k, v in metrics.items():
    print(k, v)

Parameters

• network (Union[Molecule, WithEnergyCell, RunOneStepCell]) – Cell of the simulation system. Data type refers to sponge.system.Molecule, sponge.core.WithEnergyCell and sponge.core.RunOneStepCell

• potential (sponge.potential.PotentialCell, optional) – Potential energy. Default: None.

• optimizer (mindspore.nn.Optimizer, optional) – Optimizer. Default: None.

• metrics (dict, optional) – A Dictionary of metrics for system analysis. The key type of the dict should be str, and the value type of the dict should be sponge.metrics.Metric or sponge.colvar.Colvar. Default: None.

• analysis (sponge.core.AnalysisCell, optional) – Analysis network. Default: None.

Supported Platforms:

Ascend GPU

analyse(dataset: Dataset = None, callbacks: Union[Callback, List[Callback]] = None)

Analysis API.

Note

To use this API, the metrics must be set at sponge.core.Sponge initialization.

Parameters

• dataset (Dataset) – Dataset of simulation to be analysed. Default: None.

• callbacks (Union[mindspore.train.Callback, List[mindspore.train.Callback]]) – List of callback objects which should be executed while training. Default: None.

Returns

Dict, the key is the metric name defined by users and the value is the metrics value for the model in the test mode.

Examples

>>> from mindsponge.colvar import Torsion
>>> from mindsponge.colvar import Torsion
>>> phi = Torsion([4, 6, 8, 14])
>>> psi = Torsion([6, 8, 14, 16])
>>> md = Sponge(system, potential, optimizer, metrics={'phi': phi, 'psi': psi})
>>> metrics = md.analyse()
>>> for k, v in metrics.items():
>>>     print(k, v)
phi [[3.1415927]]
psi [[3.1415927]]

calc_biases()

Calculate the bias potential terms.

Returns

biases (Tensor), Tensor of shape \((B, V)\).

Bias terms. Here \(B\) is the batch size, \(V\) is the number of bias potential terms. Data type is float.

calc_energies()

Calculate the energy terms of the potential energy.

Returns

energies (Tensor), Tensor of shape \((B, U)\).

Energy terms. Here \(B\) is the batch size, i.e. the number of walkers of the simulation, U is the number of potential energy terms. Data type is float.

calc_energy()

Calculate the total potential energy (potential energy and bias potential) of the simulation system.

Returns

energy (Tensor), Tensor of shape \((B, 1)\). Here \(B\) is the batch size, i.e. the number of walkers of the simulation. Data type is float. Total potential energy.

calc_potential()

Calculate and return the potential energy

Returns

energy, Tensor of shape \((B, 1)\).

Total potential energy. Here B is the batch size, i.e. the number of walkers of the simulation. Data type is float.

change_optimizer(optimizer: Optimizer)

Change optimizer.

Parameters

optimizer (mindsponge.optimizer.Optimizer) – Optimizer will be used.

change_potential(potential: PotentialCell)

Change potential energy.

Parameters

potential (sponge.potential.PotentialCell) – Potential energy will be used.

property create_time

Create time of the Sponge instance.

Returns

int, create time of the Sponge instance.

property energy_names: List[str]

Names of energy terms

Returns

list of str, names of energy terms

get_bias()

Get the total bias potential energy.

Returns

bias, Tensor of shape \((B, 1)\).

Here \(B\) is the batch size, i.e. the number of walkers of the simulation. Data type is float.

get_biases()

Get the bias potential energies.

Returns

biases, Tensor of shape \((B, V)\).

Bias terms. Here \(B\) is the batch size, i.e. the number of walkers of the simulation, \(V\) is the number of bias potential terms. Data type is float.

get_energies()

Get the potential energy terms.

Returns

energies, Tensor of shape \((B, U)\).

Energy terms. Here B is the batch size, i.e. the number of walkers of the simulation, \(U\) is the number of potential energy terms. Data type is float.

property num_biases: int

Number of bias potential energies V

Returns

int, number of bias potential energies

property num_energies: int

Number of energy terms

Returns

int, number of energy terms

recompile()

Recompile the simulation network

run(steps: int, callbacks: Union[Callback, List[Callback]] = None, dataset: Dataset = None, show_time: bool = True)

Simulation API.

Parameters

• steps (int) – Simulation steps.

• callbacks (Union[mindspore.train.Callback, List[mindspore.train.Callback]]) – Callback function(s) to obtain the information of the system during the simulation. Default: None.

• dataset (Dataset) – Dataset used at simulation process. Default: None.

• show_time (bool) – Whether to show the time of the simulation. Default: True.

Examples

>>> from sponge import Sponge
>>> from sponge.system import Molecule
>>> from sponge.potential.forcefield import ForceField
>>> from sponge.optimizer import Updater
>>> from sponge.callback import RunInfo
>>> system = Molecule(template='water.tip3p.yaml')
>>> potential = ForceField(system, parameters='SPCE')
>>> optimizer = Updater(system, controller=None, time_step=1e-3)
>>> md = Sponge(system, potential, optimizer)
>>> md.run(100, callbacks=[RunInfo(10)])

update_bias(step: int)

Update bias potential.

Parameters

step (int) – step of the simulation.

update_modifier(step: int)

Update force modifier

Parameters

step (int) – step of the simulation.

update_neighbour_list()

Update neighbour list

update_wrapper(step: int)

Update energy wrapper.

Parameters

step (int) – step of the simulation.