<commit_before># Q2MM

Q2MM stands for quantum (mechanics) to molecular mechanics, quantum guided molecular mechanics, etc. Q2MM is free software for force field optimization.


## Python Dependencies

Q2MM uses Python 2.7.4. I'm reluctant to use more recent versions of Python because as far as I know, Schrodinger still uses 2.7.4.

The following modules are required, but are included in the standard library for Python 2.7.4

* argparse
* collections
* copy
* itertools
* logging
* mmap
* os
* random
* re
* sqlite3
* string
* sqlite3
* subprocess
* sys
* textwrap
* time

Required but not in the standard library

* numpy

For particular features

* schrodinger

## Usage

If you'd like to use Schrodinger features, they recommend running external Python scripts using

```
$SCHRODINGER/run somepythoncode.py
```

I will update this when I have more information on how to configure your environment variables such that you can use

```
python somepythoncode.py
```

and still use the Schrodinger modules.

### Running most Q2MM code

Most Q2MM code can be executed from the command line to get help. Here's an example.

```
python calculate.py -h
```

### Using Schrodinger mm3.fld

Towards the end Schrodinger mm3.fld files, there is a section for specific substructure parameters. Substructures can marked for optimization by adding the word OPT to their name. For example, you could name your substructure New Metal Parameters OPT. Try running

```
python parameters.py -f pathtomm3fld -a -pp
```

to print a list of the parameters that Q2MM identified.

### Running an optimization loop

The loop module uses customized input files to manage the optimization of parameters. You can supply it the input file by simply typing

```
python loop.py someinputfile
```

Here's an example of what the input file could look like.

```
FFLD read somedir/mm3.fld # This is a comment.
PARM somedir/params.txt
RDAT -d somedir -je str_a.mae str_b.mae str_c.mae -je str_d.mae str_e.mae -jb str_a.mae str_b.mae str_c.mae str_d.mae str_e.mae
CDAT -d somedir -me str_a.mae str_b.mae str_c.mae -me str_d.mae str_e.mae -mb str_a.mae str_b.mae str_c.mae str_d.mae str_e.mae
COMP -o somedir/opt_start.txt
# Here's another comment.
LOOP 0.15
GRAD
SIMP
END
LOOP 0.05
GRAD
END
FFLD write somedir/mm3.fld
CDAT
COMP -o somedir/opt_end.txt
```

Let's breakdown each line.

```
FFLD read somedir/mm3.fld
```

Read the initial force field.

```
PARM somedir/params.txt
```

Select certain parameters in the force field you just read. Without this, all parameters in the substructre are selected. The format of params.txt looks like

```
1854 1
1854 3
1855 2
1856 1
1856 3
1854 3
1855 2
1857 1

```

The first column refers to the line of the force field file where the parameter is located. The second column is an index refering to the location of the parameter in that line. For Schrodinger and mm3.fld, equilibrium bond lengths are found in column 1, force constants in column 2, dipoles in column 3, etc. See the documentation inside the parameters module for more details. Output like this can also be generated using

```
python parameters.py -f mm3.fld -pt bf af -o params.txt
```

This command would print out the bond and angle force constants in the format described above.

```
RDAT -d somedir -je str_a.mae str_b.mae str_c.mae -je str_d.mae str_e.mae -jb str_a.mae str_b.mae str_c.mae str_d.mae str_e.mae
```

This gathers the reference data used throughout the optimization. All of the arguments following RDAT are the same as the arguments used for the calculate module. See that module's help for more information.

```
CDAT -d somedir -me str_a.mae str_b.mae str_c.mae -me str_d.mae str_e.mae -mb str_a.mae str_b.mae str_c.mae str_d.mae str_e.mae
```

Same as above, except this is for the force field data.

```
COMP -o somedir/opt_start.txt
```

Compare the reference data to the force field data and determine the initial objective function score. Write the data and scores out to somedir/opt_start.txt.

```
LOOP 0.15
```

This marks the beginning of an optimization loop. All commands located between this line and the line containg END will be repeated until convergence is reached. The loop stops if the change in the objective function is less than 15% after a complete cycle. In this case, that includes using the gradient and simplex methods.

```
GRAD
```<commit_msg>Updated README to include information about "neg" keyword.<commit_after># Q2MM

Q2MM stands for quantum (mechanics) to molecular mechanics, quantum guided molecular mechanics, etc. Q2MM is free software for force field optimization.


## Python Dependencies

Q2MM uses Python 2.7.4. I'm reluctant to use more recent versions of Python because as far as I know, Schrodinger still uses 2.7.4.

The following modules are required, but are included in the standard library for Python 2.7.4

* argparse
* collections
* copy
* itertools
* logging
* mmap
* os
* random
* re
* sqlite3
* string
* sqlite3
* subprocess
* sys
* textwrap
* time

Required but not in the standard library

* numpy

For particular features

* schrodinger

## Usage

If you'd like to use Schrodinger features, they recommend running external Python scripts using

```
$SCHRODINGER/run somepythoncode.py
```

I will update this when I have more information on how to configure your environment variables such that you can use

```
python somepythoncode.py
```

and still use the Schrodinger modules.

### Running most Q2MM code

Most Q2MM code can be executed from the command line to get help. Here's an example.

```
python calculate.py -h
```

### Using Schrodinger mm3.fld

Towards the end Schrodinger mm3.fld files, there is a section for specific substructure parameters. Substructures can marked for optimization by adding the word OPT to their name. For example, you could name your substructure New Metal Parameters OPT. Try running

```
python parameters.py -f pathtomm3fld -a -pp
```

to print a list of the parameters that Q2MM identified.

### Running an optimization loop

The loop module uses customized input files to manage the optimization of parameters. You can supply it the input file by simply typing

```
python loop.py someinputfile
```

Here's an example of what the input file could look like.

```
FFLD read somedir/mm3.fld # This is a comment.
PARM somedir/params.txt
RDAT -d somedir -je str_a.mae str_b.mae str_c.mae -je str_d.mae str_e.mae -jb str_a.mae str_b.mae str_c.mae str_d.mae str_e.mae
CDAT -d somedir -me str_a.mae str_b.mae str_c.mae -me str_d.mae str_e.mae -mb str_a.mae str_b.mae str_c.mae str_d.mae str_e.mae
COMP -o somedir/opt_start.txt
# Here's another comment.
LOOP 0.15
GRAD
SIMP
END
LOOP 0.05
GRAD
END
FFLD write somedir/mm3.fld
CDAT
COMP -o somedir/opt_end.txt
```

Let's breakdown each line.

```
FFLD read somedir/mm3.fld
```

Read the initial force field.

```
PARM somedir/params.txt
```

Select certain parameters in the force field you just read. Without this, all parameters in the substructre are selected. The format of params.txt looks like

```
1854 1
1854 3 neg
1855 2
1856 1
1856 3 neg
1854 3
1855 2
1857 1

```

The first column refers to the line of the force field file where the parameter is located. The second column is an index refering to the location of the parameter in that line. For Schrodinger and mm3.fld, equilibrium bond lengths are found in column 1, force constants in column 2, dipoles in column 3, etc. See the documentation inside the parameters module for more details. Furthermore, adding "neg" after a parameter will allow that parameter to go to negative values (typically, all parameters are restrained to maintain positive values).

Output like this can also be generated using

```
python parameters.py -f mm3.fld -pt bf af -o params.txt
```

This command would print out the bond and angle force constants in the format described above. Note that you must manually add the keyword "neg".

```
RDAT -d somedir -je str_a.mae str_b.mae str_c.mae -je str_d.mae str_e.mae -jb str_a.mae str_b.mae str_c.mae str_d.mae str_e.mae
```

This gathers the reference data used throughout the optimization. All of the arguments following RDAT are the same as the arguments used for the calculate module. See that module's help for more information.

```
CDAT -d somedir -me str_a.mae str_b.mae str_c.mae -me str_d.mae str_e.mae -mb str_a.mae str_b.mae str_c.mae str_d.mae str_e.mae
```

Same as above, except this is for the force field data.

```
COMP -o somedir/opt_start.txt
```

Compare the reference data to the force field data and determine the initial objective function score. Write the data and scores out to somedir/opt_start.txt.

```
LOOP 0.15
```

This marks the beginning of an optimization loop. All commands located between this line and the line containg END will be repeated until convergence is reached. The loop stops if the change in the objective function is less than 15% after a complete cycle. In this case, that includes using the gradient and simplex methods.

```
GRAD
```
{'fraction_non_alphanumeric': 0.06620093147039255, 'fraction_numerical': 0.01774229319139499, 'mean_word_length': 4.002218524681087, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1388493', 'n_tokens_mistral': 2972, 'n_tokens_neox': 2783, 'n_words': 1316}