Solvent

Provides methods to interact or prepare solvents for molecular simulation.

get_ion_counts(simlify_config, charge_net, n_waters, water_molecule_volume=28.78277638661025)

Computes the number of cations and anions to add to a molecular simulation system to achieve a desired ionic strength and/or neutralize the system's net charge.

This function calculates the number of ions needed based on the target ionic strength specified in the SimlifyConfig, the estimated volume of the water solvent, and the net charge of the solute. It also considers any pre-defined extra ions specified in the SimlifyConfig.

The volume of the solvent is estimated based on the number of water molecules and an approximate volume per water molecule. The function then calculates the number of ions required to reach the target ionic strength in this volume.

If the charge_neutralize flag is set to True in the SimlifyConfig, the function will also add counterions to neutralize the net charge of the system (charge_net). If the net charge is negative, cations will be added; if positive, anions will be added.

PARAMETER	DESCRIPTION
simlify_config	An instance of the SimlifyConfig class containing simulation parameters, including the desired solvent ionic strength (simlify_config.solution.solvent_ionic_strength), the number of extra cations (simlify_config.solution.charge_cation_extra), the number of extra anions (simlify_config.solution.charge_anion_extra), and the flag for charge neutralization (simlify_config.solution.charge_neutralize). TYPE: SimlifyConfig
charge_net	The net charge of the solute (e.g., a protein or DNA molecule) in the system before any ions are added. This value is used to determine the number of counterions needed for neutralization if specified in the simlify_config. TYPE: int | float
n_waters	The total number of water molecules intended to be present in the simulation system. This number is used to estimate the volume of the solvent. TYPE: int
water_molecule_volume	An approximate volume of a single water molecule in Angstroms cubed (ų). The default value is based on the density of water at standard conditions. TYPE: float DEFAULT: 28.78277638661025

RETURNS	DESCRIPTION
dict[str, int]	A dictionary containing the calculated number of cations and anions to be
dict[str, int]	added to the system. The dictionary has the following keys:
dict[str, int]	"charge_cation_num": The total number of cations to add, including any pre-defined extra cations and those required for ionic strength and/or charge neutralization.
dict[str, int]	"charge_anion_num": The total number of anions to add, including any pre-defined extra anions and those required for ionic strength and/or charge neutralization.

Examples:

Calculating ion counts for a system with a net positive charge and a target ionic strength:

from simlify import SimlifyConfig
from simlify.solvate.ions import get_ion_counts

# Create a SimlifyConfig instance
config = SimlifyConfig(
    solution=dict(
        solvent_ionic_strength=0.150,  # 150 mM ionic strength
        charge_cation_extra=0,
        charge_anion_extra=0,
        charge_neutralize=True,
    )
)
net_charge = 2  # Example net positive charge
num_waters = 10000

ion_counts = get_ion_counts(config, net_charge, num_waters)
print(f"Number of ions to add: {ion_counts}")
# Expected output might vary slightly due to rounding, but will include anions
# for neutralization.

Calculating ion counts for a system with a net negative charge and no charge neutralization:

from simlify import SimlifyConfig
from simlify.solvate.ions import get_ion_counts

# Create a SimlifyConfig instance with charge neutralization disabled
config = SimlifyConfig(
    solution=dict(
        solvent_ionic_strength=0.100,  # 100 mM ionic strength
        charge_cation_extra=1,
        charge_anion_extra=0,
        charge_neutralize=False,
    )
)
net_charge = -3  # Example net negative charge
num_waters = 5000

ion_counts = get_ion_counts(config, net_charge, num_waters)
print(f"Number of ions to add: {ion_counts}")
# Expected output will include the pre-defined extra cation but no ions for
# neutralization.

Calculating ion counts for a neutral system with a specific ionic strength:

from simlify import SimlifyConfig
from simlify.solvate.ions import get_ion_counts

# Create a SimlifyConfig instance for a neutral system
config = SimlifyConfig(
    solution=dict(
        solvent_ionic_strength=0.200,  # 200 mM ionic strength
        charge_cation_extra=0,
        charge_anion_extra=0,
        charge_neutralize=False,
    )
)
net_charge = 0
num_waters = 15000

ion_counts = get_ion_counts(config, net_charge, num_waters)
print(f"Number of ions to add: {ion_counts}")
# Expected output will show the number of cations and anions needed for the
# target ionic strength.