Package: hydrophobicity-explorer
Polymer Calculation SuiteThis project enables users to perform several calulations on a limitless scope of polymers as long as the primary structure is known.The command-line toolmakePolhas a wide range of command-line options that allow fine control over polymer specification and output format. These can be obtained by runningmakePol -h. A large, but non-comprehensive list of examples will be covered in the next section. The utility is also available through a jupyter notebook. An example can be generated with the commandHXNB.Seeherefor installation instructions.Usage and ExamplesNote that the following examples all use the-qflag. This suppresses the default behavior, which asks the user for confirmation that the polymer they have specified has been interpreted correctly. For example:Is the confirmation image that would appear whenthis exampleis run without the-qflag.This confirmation process may be more important when using smiles inputs that do not come stock with this program for the first time. Addtional details about adding your own smiles to the included dictionaries can be foundhere. This is the default behavior to protect users from optimizing the geometry for incorrect polymers, which can be a time-consuming process for large values ofn, but this can be dissabled for use in scripting or batch jobs.Regardless of the provided value ofn, the preview will only show one monomer orblock of comonomersfor simplicity.This prompt will not be shown if both end groups are Hydrogen.Specifying Polymer ComponentsThere are dictionaries of monomers and terminal units insmiles.pyThe composition of a polymer containing units in these dictionaries can be spelled out in the following manner. The-vflag increases verbosity.$makePol-n3-mStyrene-vGeneratingSMILES:━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━100%0:00:00OptimizingConformers:━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━100%0:00:00
Savedpolymerimagetopolymer.png
requestedcalculationsareNoneBecause verbosity was enabled an image of the polymer was saved with a default name. The name of the image can be specified with the-dflag.
The initiator and terminal groups default to Hydrogen if none are specified.Specifying Multiple ComonomersHere is another example with a more complex set of arguments:$makePol-n2-b2Butylacrylate"CC(C)"-iBenzoyl-tBenzyl-vqGeneratingSMILES:━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━100%0:00:00OptimizingConformers:━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━100%0:00:01
Savedpolymerimagetopolymer.png
requestedcalculationsareNoneThe-bflag defines a sequence of comonomers in a specific repeating pattern. Comonomers can be specified using the monomer dictionary or with a SMILES string in quotation marks (i.e. "CC(C)"). When a coefficient is provided in the list of arguments defined by the-bflag, this changes the number of monomers per unit defined by the-nflag. In the above example, each unit of n refers to 3 monomers. The-iand-tflags are used to define initiators and terminators from either the dictionary or from SMILES. The number of monomers per n will be used for plots and image labels.Performing CalculationsThe-cflag is followed by abbreviations for calulations that are desired. Availible options are:LogP, SA (surface area), MV (Molecular Volume), MHP (LogP/SA; each of which will also be reported. Use XMHP to exclude those constituent calculations) and RG (radius of gyration).When RG is selected, an exponential regression is performed. Polymer RG scales by n^(1/3) with the MMFF94 force field. This gives a sense of how reasonable the optimization steps were.A run with Styrene to n=10 had the following regression:Modifying The SMILES DictionaryUse the command line toolHXLib -wto generatesmiles.jsonwhich can be filled with custom key-value pairs. Examples that are ignored will be included, but the format of the SMILES should be as follows:The tail of the monomer at the left of the SMILES string and the head at the right. For example, propylene would be writtenCC(C). This allows easy construction of the polymer body by simply repeating this stringntimes.For non-palindromic end groups the atom to which the rest of the polymer should attatch must be denoted with*. The use of*is inspired by polymergenome.org. Additionally, the SMILES must be written such that the*is the first or last character in the string.The use of the-eor-mflag withHXLibwill show all the endgroups or monomers recognizable to the program, including those user-specified ones insmiles.json.Reading a Polymer From A FileYou will notice with the second example the run time is noticable since there are several conformations being compared to make the final mol object in rdkit. Additionally, this process is not perfectly reproducible. If desired, one can load a premade.sdf,.molor.pdbfile instead of spelling out the polymer with the-mor-bflag. Polymers spelled out with the previously demonstrated methods can be converted to files as well with the-sflag. See the following section for details.$makePol-n5-rpol.mol-cSARGLogPSALogPRGNsmi0370.9618668.77074.0760595C[C@H](C[C@H](C[C@H](CCc1ccccc1)c1ccccc1)c1ccc...Note that-nis required since the smiles is not analyzed to determine the number of monomers.Alternative Input MethodsCustom InputIf the methods contained within this program are inadequate for the type of molecule desired, the accessory command line toolcustomPolmay be useful. It can read Smiles, Smarts or Inchi strings and produce a.molfile that can be read for calculations with the master script.Use the following to show instructions for this script:customPol -hRandom CompositionThe accessory script-aoption ofmakePolcan be used to interpret a ratio of monomers and develop a polymer that satisfy the user's desired monomer ratio. The monomers will be in a random order. Use the-bflag to specify the ratio of the comonomers.For example, the commandmakePol -n 20 -b 2 Styrene Vinylalcohol -a -c MVwill generate a randomly ordered 20 unit-long polymer with a 2:1 ratio of Styrene to Vinylalcohol (rounded if necessry, but the actual ratios used will be shown).Saving Polymer to FileThe name or path of the file can be specified with the-sflag. Valid extentions are.mol,.pdband.xyz. Be aware that.xyzfiles cannot be read back into this program.$makePol-n4-mStyrene-cMHP-v-spol.molGeneratingSMILES:━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━100%0:00:00OptimizingConformers:━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━100%0:00:00
writingmoleculetopol.mol
Successwritingmoleculetopol.mol
Savedpolymerimagetopolymer.png
requestedcalculationsare['MHP']SALogPLogP/SANsmi0607.6699528.77070.0144334CC(c1ccccc1)CC(c1ccccc1)CC(c1ccccc1)CC(c1ccccc1)In the next plotting section it is shown that many polymers of different lengths can be generated with the-pflag. When the-sflag is specified as well, each of those molecules will be saved to its own file with a name based off the one specified as a CLI argument. The number of repeat units will be used as a suffix.Plotting Size-Dependent CalculationsThe size-dependent plots of any calculations performed can be generated with the-pflag. The sizes plotted will range from 1 repeat unit to the number specified by the-nflag. Because the repeat unit needs to be well-defined, this plotting option is unavailable if the polymer is being read from a file. Since the-vflag is used, a grid image of all the generated molecules will be created as well.The data can be exported to a.csvfile with the-eflag.#XMHP requests that the MHP data be eXclusively returned instead of including the LogP and SA values as well.$makePol-n2-mStyrene-cXMHP-edata.csv-vpGeneratingSMILES:━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━100%0:00:00OptimizingConformers:━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━100%0:00:00
Savedpolymerimagetopolymer.png
requestedcalculationsare['XMHP']SavedplottoSize-dependent-stats.pngLogP/SANsmi00.0123791CC(c1ccccc1)10.0136592CC(c1ccccc1)CC(c1ccccc1)#popup of plot appears.Doneexportingdatato.csvfile.Nearly all of this output, including the plot popup and the polymer grid image, are excluded if the-vflag is excluded, but the image of the plot is still saved to a file. Because the calculation of MHP requires surface area and LogP values, they will always be included when MHP is specified in the list of desired calculations. When in this mode, if a name for an polymer file is specified, each molecule will be saved to a file based off the provided name. However, the number of mers in each molecule will be appended to the filename.An example plot of Styrene LogP/SA with n <= 10:This plot has a lot of noise at higher n. It is possible tomitigate this.Improving Data Quality in PlotsA plot generated with this tool may not always show a smooth curve, especially at higher n, where it is more difficult to optimize the polymer geometry. Calculations that depend on geometry like surface area or LogP/SA will be affected by poor geometry optimizations. This can be partially fixed bychanging the default settingsto increase the number of conformations used for calculations or the maximum number of iterations a conformer is allowed to use before it is either accepted or discarded for not converging (i.e. the change in energy between optimization steps is still not yet small enough to be considered 'done'). Both of these in effect increase the population of conformers used to calculate an average of a requested property, which reduces noise on the graph.The default settings are meant to find a balance between run time and reasonable results. These parameters are better suited to some monomers than others, so tweaking the parameters may be necessary not only to reduce noise on the plot, but to get the run to complete at all. The following is an example of how changing the default settings may benefit the plots produced by this program:Styrene | MaxIters 1500 | numConfs 5Styrene | MaxIters 2000 | numConfs 5Styrene | MaxIters 1500 | numConfs 10Styrene | MaxIters 2000 | numConfs 10In this case, increasing both parameters independently or together improved the quality of the graph. However, each increase in either parameter increased the run time.Changing Default SettingsSome settings are not accessible with command-line arguments. Defaults are hardcoded but can be overwritten when a file calledHXSettings.jsonis present in the working directory. The settings uses are explained below. All settings must be present in the file unless. A fresh settings file can be generated with theHXSettings -wcommand line tool.HXSettings -sshows the settings all hydrophobicity_explorer tools will use, whether default or custom.{"opt_numConfs":5,#The number of conformations you would like to generate. Increasing this greatly increases run time."opt_numThreads":0,#The number of threads you would like to use for the optimization and conf generation. 0 means maximum possible."opt_maxIters":1500,#The number of iterations used in optimization. Increase this if a job fails to optimize."drawing_subImgSize_edge":250,#The side length of a subimage when saved."drawing_default":"polymer.png",#The name of an image saved by default (verbosity turned on with no image name specified.)"MV_gridSpacing":0.2,#Used for molar volume calculation."MV_boxMargin":2.0,#Used for molar volume calculation."plot_dataPoint":"o",#Matplotlib argument to change plot point appearence."plot_Filename":"Size-dependent-stats.png",#name of plot."dielectricModel":2,#Model 1 is constant; model 2 is distant-dependent"dielectricConstant":78,#Dielectric constant 78 corresponds to water"NB_THRESH":100#Value to cut off long-distance interactions. 100 is rdkit default.}Some of the values are used by external functions and others by functions in this program. If it is desired to change the appearence of the plot points from blue circles to red pluses, change"plot_dataPoint":"o"to"plot_dataPoint":"r+", as per thematplotlib documentation.If the settings file cannot be found hardcoded defaults will be used instead.InstallationGeneral StepsThis project uses conda to manage dependencies. You can install this package through conda or using git.First:Install conda using theofficial guide.Then, if you are using Windows, follow the additional steps for that operating system. For other Linux orwindows subsystem for linux, just open a terminal. Windows users should press the Windows Key, then search for and openAnaconda Prompt.Install with condaCreate the environment and install the dependencies. You may replace the argument after -n with any environment name you wish.conda create -c conda-forge -c scohenjanes -n HX-env hydrophobicity_explorerActivate the environmentconda activate HX-envInstall with pippip install hydrophobicity_explorerInstall with GitExtra Step For WindowsInstallgit for WindowsSteps For All UsersClone the repositorygit clone https://github.com/TheHydrophobicityProject/HydrophobicityExplorer.gitSet up the conda environmentconda create -c conda-forge -n HX-env rdkit scipy richAllow conda to install the dependenciesActivate the environmentconda activate HX-envInstall the package from the downloaded sourcepython3 -m pip install PATH/TO/DOWNLOADED/PACKAGE