Skip to content

GROMACS particle definitions

ParticleType dataclass

Represents a particle type in a molecular dynamics simulation.

Attributes:

Name Type Description
name str

The name of the particle type.
mass float

The mass of the particle type.
charge float

The charge of the particle type.
ptype str

The type of the particle (e.g., atomistic, coarse-grained).
c6 float

The Lennard-Jones C6 parameter for the particle type.
c12 float

The Lennard-Jones C12 parameter for the particle type.
Source code in martignac/parsers/gromacs_particle_definitions.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
@dataclass
class ParticleType:
    """
    Represents a particle type in a molecular dynamics simulation.

    Attributes:
        name (str): The name of the particle type.
        mass (float): The mass of the particle type.
        charge (float): The charge of the particle type.
        ptype (str): The type of the particle (e.g., atomistic, coarse-grained).
        c6 (float): The Lennard-Jones C6 parameter for the particle type.
        c12 (float): The Lennard-Jones C12 parameter for the particle type.
    """

    name: str
    mass: float
    charge: float
    ptype: str
    c6: float
    c12: float

find_particle_type_from_name(itp_filename, particle_name)

Finds and returns a ParticleType object from a GROMACS .itp file based on the particle name.

This function searches through the particle types defined in a specified .itp file, looking for a particle type that matches the given name. It utilizes the parse_particle_types_from_itp function to read and parse the .itp file, extracting all defined particle types into a list of ParticleType objects. It then iterates through this list to find a particle type with a name that matches the particle_name parameter.

Parameters:

Name Type Description Default
itp_filename str

The path to the .itp file to be searched.

 required
particle_name str

The name of the particle type to find.

 required

Returns:

Name Type Description
ParticleType ParticleType

The ParticleType object corresponding to the specified particle name.

Raises:

Type Description
StopIteration

If no particle type with the specified name is found in the .itp file.
Source code in martignac/parsers/gromacs_particle_definitions.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def find_particle_type_from_name(itp_filename: str, particle_name: str) -> ParticleType:
    """
    Finds and returns a ParticleType object from a GROMACS .itp file based on the particle name.

    This function searches through the particle types defined in a specified .itp file, looking for a particle
    type that matches the given name. It utilizes the `parse_particle_types_from_itp` function to read and parse
    the .itp file, extracting all defined particle types into a list of ParticleType objects. It then iterates
    through this list to find a particle type with a name that matches the `particle_name` parameter.

    Parameters:
        itp_filename (str): The path to the .itp file to be searched.
        particle_name (str): The name of the particle type to find.

    Returns:
        ParticleType: The ParticleType object corresponding to the specified particle name.

    Raises:
        StopIteration: If no particle type with the specified name is found in the .itp file.
    """
    particle_types = parse_particle_types_from_itp(itp_filename)
    return next(p for p in particle_types if p.name == particle_name)

generate_gro_for_particle_type(particle_type, gro_filename, box_length=100.0)

Generates a GROMACS .gro file for a single particle type with specified box dimensions.

This function creates a .gro file representing a simulation box containing a single particle of the specified type. The particle is placed at the origin of the box. The function uses MDAnalysis to create an empty universe, sets the particle's attributes, and then writes the .gro file with the specified box dimensions.

Parameters:

Name Type Description Default
particle_type ParticleType

The particle type for which to generate the .gro file. This should be an instance of the ParticleType class, containing the necessary attributes like name, mass, and charge.

 required
gro_filename str

The path and filename where the .gro file will be saved. If the file already exists, it will be overwritten.

 required
box_length float

The length of the sides of the cubic simulation box in which the particle is placed. The default value is 100.0 Ångströms.

 100.0

Returns:

Name Type Description
None None

This function does not return a value but writes directly to a file specified by gro_filename.
Source code in martignac/parsers/gromacs_particle_definitions.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
def generate_gro_for_particle_type(
    particle_type: ParticleType, gro_filename: str, box_length: float = 100.0
) -> None:
    """
    Generates a GROMACS .gro file for a single particle type with specified box dimensions.

    This function creates a .gro file representing a simulation box containing a single particle of the specified type.
    The particle is placed at the origin of the box. The function uses MDAnalysis to create an empty universe, sets the
    particle's attributes, and then writes the .gro file with the specified box dimensions.

    Parameters:
        particle_type (ParticleType): The particle type for which to generate the .gro file. This should be an instance
                                      of the ParticleType class, containing the necessary attributes like name, mass,
                                      and charge.
        gro_filename (str): The path and filename where the .gro file will be saved. If the file already exists, it will
                            be overwritten.
        box_length (float): The length of the sides of the cubic simulation box in which the particle is placed. The
                            default value is 100.0 Ångströms.

    Returns:
        None: This function does not return a value but writes directly to a file specified by `gro_filename`.
    """
    u = mda.Universe.empty(n_atoms=1, trajectory=True)

    # Setting properties
    u.add_TopologyAttr("name", values=[particle_type.name])
    u.add_TopologyAttr("type", values=[particle_type.ptype])
    u.add_TopologyAttr("resid", values=[1])
    u.add_TopologyAttr("resname", values=[particle_type.name])
    u.add_TopologyAttr("masses", values=[particle_type.mass])
    u.add_TopologyAttr("charges", values=[particle_type.charge])
    u.atoms.positions = [[0, 0, 0]]  # Setting it to the origin for simplicity
    box_size = [box_length, box_length, box_length, 90.0, 90.0, 90.0]
    u.dimensions = box_size

    logger.info(f"generating {gro_filename} for molecule {particle_type.name}")
    u.atoms.write(gro_filename)

generate_itp_file_for_particle(particle, itp_filename)

Generates a GROMACS .itp file for a single particle type.

This function writes to a .itp file specific information about a particle type, including its name, type, and charge. The .itp (include topology) file format is used by GROMACS to define molecule types in simulations. This function creates a minimal .itp file containing a single [moleculetype] entry and one [atoms] entry for the specified particle.

Parameters:

Name Type Description Default
particle ParticleType

The particle type for which to generate the .itp file. This should be an instance of the ParticleType class, containing the necessary attributes like name, mass, and charge.

 required
itp_filename str

The path and filename where the .itp file will be saved. If the file already exists, it will be overwritten.

 required

Returns:

Name Type Description
None None

This function does not return a value but writes directly to a file specified by itp_filename.
Source code in martignac/parsers/gromacs_particle_definitions.py 
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
def generate_itp_file_for_particle(
    particle: ParticleType,
    itp_filename: str,
) -> None:
    """
    Generates a GROMACS .itp file for a single particle type.

    This function writes to a .itp file specific information about a particle type, including its name, type, and charge.
    The .itp (include topology) file format is used by GROMACS to define molecule types in simulations. This function
    creates a minimal .itp file containing a single [moleculetype] entry and one [atoms] entry for the specified particle.

    Parameters:
        particle (ParticleType): The particle type for which to generate the .itp file. This should be an instance
                                 of the ParticleType class, containing the necessary attributes like name, mass,
                                 and charge.
        itp_filename (str): The path and filename where the .itp file will be saved. If the file already exists, it
                            will be overwritten.

    Returns:
        None: This function does not return a value but writes directly to a file specified by `itp_filename`.
    """
    with open(itp_filename, "w") as f:
        f.write(f";;;;;; {particle.name} bead\n")
        f.write("[moleculetype]\n")
        f.write("; molname       nrexcl\n")
        f.write(f"  {particle.name}\t1\n\n")

        f.write("[atoms]\n")
        f.write("; id    type    resnr   residu  atom    cgnr    charge\n")
        f.write(
            f"  1\t{particle.name}\t1\t{particle.name}\t{particle.ptype}\t1\t{particle.charge}\n"
        )

generate_top_file_for_particle(particle, force_field_filenames, top_filename, num_molecules=1)

Generates a GROMACS topology (.top) file for a single particle type.

This function creates a .top file for a specified particle type, incorporating the specified force field files. The generated .top file includes the definition of the particle type and the number of molecules of that type to be included in the simulation. It delegates the actual writing of the file to the generate_top_file_for_generic_molecule function, which handles the formatting and inclusion of force field parameters.

Parameters:

Name Type Description Default
particle ParticleType

The particle type for which to generate the .top file. This should be an instance of the ParticleType class, containing the necessary attributes like name, mass, and charge.

 required
force_field_filenames list[str]

A list of paths to the force field files to be included in the .top file. These files contain the parameters necessary for the simulation, such as bond lengths, angles, and Lennard-Jones parameters.

 required
top_filename str

The path and filename where the .top file will be saved. If the file already exists, it will be overwritten.

 required
num_molecules int

The number of molecules of the specified particle type to include in the simulation. Defaults to 1.

 1

Returns:

Name Type Description
None None

This function does not return a value but writes directly to a file specified by top_filename.
Source code in martignac/parsers/gromacs_particle_definitions.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
def generate_top_file_for_particle(
    particle: ParticleType,
    force_field_filenames: list[str],
    top_filename: str,
    num_molecules: int = 1,
) -> None:
    """
    Generates a GROMACS topology (.top) file for a single particle type.

    This function creates a .top file for a specified particle type, incorporating the specified force field files.
    The generated .top file includes the definition of the particle type and the number of molecules of that type
    to be included in the simulation. It delegates the actual writing of the file to the
    `generate_top_file_for_generic_molecule` function, which handles the formatting and inclusion of force field
    parameters.

    Parameters:
        particle (ParticleType): The particle type for which to generate the .top file. This should be an instance
                                 of the ParticleType class, containing the necessary attributes like name, mass,
                                 and charge.
        force_field_filenames (list[str]): A list of paths to the force field files to be included in the .top file.
                                           These files contain the parameters necessary for the simulation, such as
                                           bond lengths, angles, and Lennard-Jones parameters.
        top_filename (str): The path and filename where the .top file will be saved. If the file already exists, it
                            will be overwritten.
        num_molecules (int): The number of molecules of the specified particle type to include in the simulation.
                             Defaults to 1.

    Returns:
        None: This function does not return a value but writes directly to a file specified by `top_filename`.
    """
    return generate_top_file_for_generic_molecule(
        particle.name, force_field_filenames, top_filename, num_molecules
    )

parse_particle_types_from_itp(filename)

Parses particle types from a GROMACS .itp file.

This function reads a GROMACS topology (.itp) file and extracts the definitions of particle types listed under the [ atomtypes ] section. Each particle type is represented by a ParticleType object, which includes properties such as name, mass, charge, particle type (ptype), and Lennard-Jones parameters (c6, c12).

Parameters:

Name Type Description Default
filename str

The path to the .itp file to be parsed.

 required

Returns:

Type Description
list[ParticleType]

list[ParticleType]: A list of ParticleType objects extracted from the .itp file.
Source code in martignac/parsers/gromacs_particle_definitions.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def parse_particle_types_from_itp(filename: str) -> list[ParticleType]:
    """
    Parses particle types from a GROMACS .itp file.

    This function reads a GROMACS topology (.itp) file and extracts the definitions of particle types
    listed under the [ atomtypes ] section. Each particle type is represented by a `ParticleType` object,
    which includes properties such as name, mass, charge, particle type (ptype), and Lennard-Jones parameters (c6, c12).

    Parameters:
        filename (str): The path to the .itp file to be parsed.

    Returns:
        list[ParticleType]: A list of `ParticleType` objects extracted from the .itp file.
    """
    particle_types = []
    with open(filename) as file:
        lines = file.readlines()
        in_atomtypes = False
        for line in lines:
            line = line.strip()
            if line == "[ atomtypes ]":
                in_atomtypes = True
            elif in_atomtypes:
                if line.startswith(";") or not line:  # Skip comments and empty lines
                    continue
                try:
                    parts = line.split()
                    name = parts[0]
                    mass = float(parts[1])
                    charge = float(parts[2])
                    ptype = parts[3]
                    c6 = float(parts[4])
                    c12 = float(parts[5])
                    bead = ParticleType(name, mass, charge, ptype, c6, c12)
                    particle_types.append(bead)
                except (
                    ValueError,
                    IndexError,
                ):  # Exit the loop if line format doesn't match
                    break

    return particle_types