Package: openprattle
OpenPrattleA command-line tool and python library that provides a seamless interface to both thePybel libraryandobabelcommand-line tool.DependenciesRequiredOpenbabel >= 3.0.0Python >= 3.9OptionalJSON (for printing in JSON format with the --readable and --writable options)pytest (for running the unit tests)UsageOpenPrattle provides both a python library and command-line tool.LibraryFiles are interconverted using converter objects, each of which represents a supported backend.
To automatically get a suitable converter object, useopenprattle.Openbabel_converter.from_file():fromopenprattleimportOpenbabel_convertermy_file="Benzene.xyz"converter=Openbabel_converter.from_file(input_file_path=my_file)By default, the format of the input file is determined automatically from its extension. The format
can be explicitly specified withinput_file_type:converter=Openbabel_converter.from_file(input_file_path=my_file,input_file_type="xyz")Openbabel_converter.from_file()will favour the Pybel backend if it is available, except when
converting files in formats that are not supported by Pybel. To explicitly choose a backend, use
thebackendoption:converter=Openbabel_converter.from_file(input_file_path=my_file,input_file_type="xyz",backend="Pybel"# Either 'Pybel', 'Obabel', or 'Auto')Or use the appropriate class directly.fromopenprattleimportObabel_converter,Pybel_convertermy_file="Benzene.xyz"obabel=Obabel_converter(input_file_path=my_file)pybel=Pybel_converter(input_file_path=my_file)In addition to reading from a file path, all the converters can read from an open file descriptor
usinginput_file:withopen("Benzene.xyz")asmy_file:converter=Openbabel_converter.from_file(input_file=my_file,input_file_type="xyz",)Or from a memory buffer usinginput_file_buffer:withopen("Benzene.xyz")asmy_file:buffer=my_file.read()converter=Openbabel_converter.from_file(input_file_buffer=buffer,input_file_type="xyz",)Whenever theinput_fileorinput_file_bufferoptions are used, the file type must be specified
withinput_file_type.Once an appropriate converter object has been obtained, the file can be converted by callingconvert():converter=Openbabel_converter.from_file(input_file_path="Benzene.xyz")converter.convert("cml","Benzene.cml")convert()can either write to a file (usingoutput_file), or return the converted file as a buffer
(ifoutput_fileis omitted):converter=Openbabel_converter.from_file(input_file_path="Benzene.xyz")output_file=converter.convert("cml")print(output_file)A limited subset of formats support molecular charge and multiplicity information. These can be set
using thechargeandmultiplicityoptions:converter=Openbabel_converter.from_file(input_file_path="Benzene.xyz")converter.convert("cml","Benzene.cml",charge=1,multiplicity=2)The following is a non-exhaustive list of formats that do support charge and multiplicity:com (Gaussian input)dalmol (DALTON input)gau (Gaussian input)gjc (Gaussian input)gjf (Gaussian input)gzmat (Gaussian Z-Matrix Input)Of these, only dalmol is both a readable and writable format.[!IMPORTANT]
Currently, OpenPrattle is not aware of which formats will preserve the specified charge
and multiplicity. If an unsupported format is chosen, any charge and multiplicity information
will be silently discarded.Charge and multiplicity are only supported with thePybel_converterbackend. This means that to
convert from a format that is not supported by Pybel (most noticeably ChemDraw's .cdx), two
conversions should be performed in sequence:fromopenprattleimportOpenbabel_converter,Pybel_converterintermediate=Openbabel_converter.from_file(input_file_path="Benzene.cdx").convert("xyz")final=Pybel_converter(input_file_buffer="intermediate",input_file_type="xyz").convert("com",charge=1,multiplicity=2)1D (eg, SMILES) and 2D (eg, ChemDraw) can be converted to 3D structures using Openbabel'sgen3Doption.
Gen3D performs a rapid geometry optimisation using a molecular force field. While this is normally useful
for generating a good starting geometry for further optimisations, it is rarely desirable for coordinates
that are already in three-dimensions.The default behaviour in OpenPrattle (gen3D = 'auto') is to convert geometries to three-dimensions so
long as the coordinates are not already in 3D. The function to determine the input geometry dimensions
is exposed by Pybel, but not by the obabel command-line tool. This means that automatic conversion with
gen3D will only occur when using the Pybel backend, unless the input format is exclusively non-3D (such
as ChemDraw's cdx).The 3D conversion can be explicitly requested or disabled by usinggen3D = Trueorgen3D = Falserespectively.output=Openbabel_converter.from_file(input_file_path="Benzene.cdx").convert("xyz",gen3D=True)Command-lineThe oprattle command-line tool has the following main syntax:$oprattleinput_file[-iINPUT_FORMAT][-oOUTPUT_FORMAT]-OOUTPUT_FILEFor example:$oprattleBenzene.xyz-OBenzene.cmlExplicit input and output formats can be specified using[-i INPUT_FORMAT]and[-o OUTPUT_FORMAT]respectively.$oprattleBenzene.file1-ixyz-ocml-OBenzene.file2Either (or both) of the input file and output file can be omitted to read from
stdin or to write to stdout:$catBenzene.xyz|oprattleixyz-ocmlThe backend can be chosen with the--backendoption:$oprattleBenzene.cdx-OBenzene.cml--backendObabelCharge, multiplicity, and 3D conversion can be set using--charge,--multiplicity, and--gen3Drespectively.$oprattleBenzene.cdx-OBenzene.cml--charge1--multiplicity2--gen3DTrueThe same caveats for charge, multiplicity, and gen3D apply as for the OpenPrattle library
(see above).To see a list of supported input and output formats, use the--readableand--writableoptions:$oprattle--readable
abinit:ABINITOutputFormat
acesout:ACESoutputformat
acr:ACRformat
...$oprattle--writable
acesin:ACESinputformat
adf:ADFcartesianinputformat
alc:Alchemyformat
...Either--readableor--writablecan be combined with--json(if the JSON library is available)
to print the list of formats in JSON format:$oprattle--readable--json"abinit":"ABINIT Output Format","acesout":"ACES output format","acr":"ACR format"...Why?On the surface, the pybel library and obabel tool appear to offer the same functionality. However, there are important instances where each offers functionality over the other. For example, pybel allows for the molecular charge and multiplicity to be set in some output formats, obabel does not.
Conversely, obabel can read from ChemDraw (.cdx) files, while pybel cannot.In addition, the programmer may not know ahead of time whether pybel and/or obabel will be available on the target system.
OpenPrattle allows for this scenario.Name?A light-hearted pun; 'prattle' and 'babel' are approximate synonyms.LicensingOpenBabelis licensed under GPL 2.0. Because OpenPrattle depends on the pybel library, it too must be licensed under the GPL.