How to read multiple external geometry files? Improve documentation

What is the best practice to read in external geometry files (e.g., pdb, xyz, etc.) with Psi4?

I’ve been using ORCA for some time now and have become interested in using Psi4. There are some flexible and simple ways to read in geometries in multiple ways with ORCA, and this has become an important part of my workflow. However, it doesn’t seem as easy to do in Psi4. As this is my first post here, please excuse my ignorance with the package as a whole. And, of course, thanks in advance for the hand-holding!

To summarize, there is a single mention in the manual and a few answered questions in the forum, but it is still not exactly clear (to me at least) how it should be done. Below, I collated the relevant information I found.

Starting with the manual, reading in a molecular geometry from an external file is placed under “Advanced Python” in an example where two XYZ files are combined for SAPT using the method Molecule.init_with_xyz. I cannot find any documentation for this method, nor anything else related. Furthermore, it’s confusing having the only mention in the manual mixed up with other instructions rather than providing a simple MWE.

From previous forum posts, the most recent relevant question “Use .xyz file as input coordinate” suggests the use of Molecule.from_string(xyz_contents_here, dtype='xyz') to read in the files previously opened in a Jupyter Notebook. I do not understand how to read the definition of this class method nor which options it’ll accept. I also do not plan on using a Jupyter notebook, but instead I plan to submit jobs to a cluster with a scheduler, so I suppose this means the XYZ file must be read-in previously as a string, but how?

An older forum post, Some beginner questions, asks the same question, and the asker was directed toward Molecule.init_with_xyz, too. User loriab explained in more detail how it could be used. This seems like a good starting point for documentation to add to the manual. Is this simply the way to go? Can it be done with other file formats?

Good questions!

Internally, Psi transforms any input file to an executable Python program, so you can read the file with Python syntax:

with open(filename_here) as f:
	xyz = f.read()

from_string is a lightweight wrapper on this function. return_dict controls whether the method returns a Molecule and a dictionary representing the molecule, or just the Molecule. All other flags are as in the docstring I posted.

The init_with_xyz method no longer exists and shouldn’t be in the documentation at all.

Let me know if anything needs more elaboration. After I’ve heard back from you, I’ll post a GitHub issue about all of this.

This cleared everything up for me.

Seems relatively straightforward once you know what documentation to read.

Is there more documentation for Psi4 apart from the main documentation?

Thank you for such a quick and thorough answer.

Nothing that’s user-facing. If a function is written in C++ but available in Python, the C++ version may have documentation that isn’t included in the main documentation. You’d need to look at the C++ code to see it, but users should never need to look there.

Thanks for the report. I’ll go put up an issue so we don’t lose track of this.