Making Topics that Get Answered

Most questions that are answered on the Psi4 Forums are answered by a small group of developers and powerusers. Their time and energy is divided between their own research, further Psi development, and helping users. Accordingly, if a topic looks like it will take a lot of time and energy to resolve without much benefit to Psi, it may get ignored. And that’s a shame. There are simple things you can do to make answering easier, which may make the difference between whether the topic is solved or not.

1. Search for related questions

Some common questions have already been asked and answered in either the forums or the manual, so always search there first. You can search the forums by clicking the magnifying glass at the right hand side of the top of the webpage. You can search the documentation at http://psicode.org/psi4manual/master/index.html.

2. Describe the problem in your title

The first step to get help is for somebody to open your topic. Before they open it, all they see is the title. Good titles are specific enough so that somebody can reliably guess whether they can help or be helped by the topic, just by reading the title. The following are good guidelines for picking a title:

  • The title should always make the “broad category” of the problem clear. Do you need advice on what methods are appropriate to use for your system? Do you need clarification on documentation? Do you need help with a bug? Are you asking if Psi has a certain method?
  • If your topic is about a specific module in Psi (examples: SAPT, SCF, the geometry optimizer), say which in the title.
  • Don’t just say your topic is about a “problem” or an “issue” in your title. Describe it in a few words if you can.
  • As a corollary, if your topic is about something we have a category for, use it. The most common categories you should use are SAPT for anything SAPT, “build” for any installation problems, and “feature-request” for when you are requesting a feature or checking if Psi has one.

3. Use English as best as you can

Make an effort to write your topic in standard English, as if you were writing for a book. Please do not write as if you are sending a text message. We also understand that English may not be your first language. Please ask your question anyways! Just be aware that the language barrier may make it more difficult for others to understand your question.

4. Create and provide minimal reproducible examples

If your topic is about a Psi4 input file that is not doing what you want it to do, make your input file as simple as possible while still displaying the problem. This simplifies the problem you’re asking others to solve. More importantly, it is often the case that when doing this, you come across the solution to the problem yourself.

Simplifying input means both removing lines of code and making the computation less expensive, either by choosing a cheaper method, a smaller system, or a smaller basis set.

5. If Psi is not doing what you want: include your input file, version number, and relevant part of the output file

This step is both crucial and usually missed. If your topic is about a Psi4 input file that is not doing what you want it to do, please, please, please tell us the version of Psi that you’re using and give us both your input file and the relevant part of the output file. For bug reports, we need these to know how to reproduce the bug and what the bug looks like. If you need help fixing your input file, we need these to know if your version of Psi is at fault, what in the input file may be causing the problem, and what exactly the problem is.

Finding your version of Psi is simple. All Psi4 output files will say right at the top of the file which version of Psi was used for the computation. For instance, the following lines indicate that you are using Psi4 version 1.3.2, and the last change made to this version of Psi was “change” ecbda83:


    -----------------------------------------------------------------------
          Psi4: An Open-Source Ab Initio Electronic Structure Package
                               Psi4 1.3.2 release

                         Git: Rev {HEAD} ecbda83 

As for the “relevant part of the output file,” more information is always better for developers. We know how to find the information we’re looking for. At a minimum, always include the error message at the end of the file if there is one. It’s almost always good to include extra lines from the output for context. For instance, if you are making a topic about an SCF not converging, include all of the SCF iterations.

6. If Psi isn’t building properly: give us command line output

This step is both crucial and usually missed. If Psi isn’t building, then to figure out the problem, we need special information. Run the following commands and post their output:

  • psi4 --version
  • conda list
  • which conda python psi4

7. Enclose code in backticks

Whenever you include code or an excerpt from an input/output file, enclose it in triple backticks, like ```. This lets the forum know that what you posted is code, and it should display it as code. When you don’t do this, the forum tries to display it as text, which includes replacing quotation marks with stylized marks. This means that perfectly good code you copied and pasted won’t run unless you enclose it in backticks.

8. Explain the “big picture goal”

Don’t just explain the technical problem you have. Explain the purpose of solving that technical problem. Often when somebody gives you an answer that seems complete but not satisfying, it is because the answer doesn’t help with the larger problem that leads you to ask the question. If people know the larger problem, they can write an answer that more directly addresses it. In some cases, it can help others suggest a better solution to the problem or steer you out of a dead end.

9. Respond

Sometimes it takes a while for somebody to respond to your topic. If they do, then be sure to respond back, even with a simple thank you, to say that you’re still interested in an answer. When you have a satisfactory answer, it is also good courtesy to mark it as “the” answer by clicking the checkbox towards the bottom of the post that answers your question.