philthiel edited this page May 5, 2017 · 8 revisions


Questions and Answers

How to cite BALL?

For all results that were obtained using BALL please cite:

  • Hildebrandt A. et al., 2010, BMC Bioinformatics, 11:531 (link)

How to Cite BALLView?

For all results that were obtained using BALLView please cite:

  • Moll A. et al., 2006, Bioinformatics, 22(3):365-366 (link)
  • Moll A. et al., 2005, Journal of Computer-Aided Molecular Design, 19(11):791-800 (link)

1.1. Platforms

Does BALL compile on platform X with compiler Y?

BALL 1.5 has been successfully built and tested on the following platforms:

  • Linux/x86_64 2.x using g++ >= 4.8
  • Microsoft Windows 10 Microsoft Visual Studio >= 2013
  • MacOS >= 10.11 using XCode 8.x
  • It should run on a number of additional platforms without too many problems,
    although these platforms have not been tested by us.

1.2. EnvironmentVariables

My BALL program crashes with the error: "File XYZ not found!"

Most likely the environment variable BALL_DATA_PATH is not set correctly.
Under Unix/Bash you can specify the variable as follows: export BALL_DATA_PATH=/path/to/BALL/data
Under Windows you must edit the environment variables under the System Properties.

2.2. Single atoms

When I write the contents of PDB files as HIN files, the resulting file contains loads of molecules each containing just one atom. What's going on?

You did not construct bonds. PDB files do (usually) not contain bonds. However, Hyperchem HIN files define "molecules" as sets of fully connected atoms (connected components). Therefore, if you do not have any bonds, each atom has to be written as its own molecule in order to comply with the Hyperchem file format. In order to avoid this problem, you should construct the bonds prior to writing the HIN file. This can be achieved by code similar to the example below:

// Read a PDB file.
PDBFile infile("test.pdb");
System S;
infile >> S;

// Construct a fragment database containing the required
// topology information and construct the bonds in the system.
FragmentDB frag_db;

// Write the system to a Hyperchem file.
HINFile outfile("test.hin", File::OUT);
outfile << S;

2.3. StructureMapper RMSD values

RMSDs calculated with StructureMapper seem to have strange values. What is wrong?

If your RMSDs seem to have strange values, make sure that all the atoms you want to map on each other are actually mapped by the StrucureMapper. You can check this by looking at the number of bijections the StructureMapper finds. Say you have one small molecule in two different positions and want to know how much they differ. To get a reasonable RMSD, you would want the Mapper to map every atom. Check this with the following code:

// Map two molecules with the same number of atoms
StructureMapper structure_mapper(molecule1, molecule2)

// Check, whether the StructureMapper mapped every atom
Size number_of_bijections = structure_mapper.getBijection().size();
if (number_of_bijections != molecule1.countAtoms())
  Log.warn() << "WARNING: not all atoms were mapped." << std:endl;

One reason for an incomplete mapping might be insufficient naming of the atoms in a molecule. If, for instance, your molecule comes from a HyperChem file and all atoms are named "-", then the StructureMapper cannot distinguish between different atoms. Give those atoms unique names and you will be fine.

2.4. "problem converting '1.33' to a number"

''When starting BALLView or any other BALL applications, on some Linux/Unix platforms users may get error messages like 'problem converting "1.33" to a number' and all kind of strange behaviour.''

This is a problem generated by the local settings on your computer. The conversion of floating point numbers fails if you have set the language to e.g. german. We currently set the locale to 'C' at the initialization of BALL. However if this problem should show up you may try

export LANG=C


export LC_NUMERIC="."


export LC_ALL=en

before starting BALLView or any other BALL application. This should fix your problems...

2.5. Python script crashes

Running your own python script in BALLView leads to crashes.

When running python scripts interactively like in BALLView, users have to account for the following specialites of python:

  • Take care that you have to remain consistent in your use of either tabs or plain spaces for python indentation. Python relies on the relative indentation of nested blocks to determine the grouping of statements correctly.
  • Take care that your script ends with two empty lines. Python needs them to interprete the end of the script.
  • For running a python script using BALL functionalities outside of BALLView you need to set the LD_LIBRARY_PATH correctly and you need to import the BALL-Library in your script
import BALL

3.2. Picking/Editing mode is slow

Users may experience several second long lags in the editing / picking mode when an atom gets selected.

On some platforms this may happen if a multi-monitor environment is used. This results from a bug in the OpenGL drivers. To circumvent this limitation, try to disable the second monitor or TV output.

3.3. Newly Computed Secondary Structures Not Shown

Why can't I see / Where is my newly computed Secondary Structure?

The Secondary Structure can be shown in the Structures window by choosing "Show Secondary Structures" in the right-mouse-button menu of the desired molecule in the Structures window. The Secondary Structure can be visualised by choosing the representation mode "Cartoon by Secondary Structure".

3.3.1. Show Hydrogen Bonds

How can I show hydrogen bonds in BALLView?

Hydrogen bonds can be computed using BALL's HydrogenBondProcessor. In BALLView this can be done by highlighting a protein's system and clicking "Tools" --> "Calculate HBonds". The resulting hydrogen bonds can be visualised by choosing the representation mode H-Bonds by e.g. element.

3.4. Newly Computed Hydrogen Bonds Not Shown

The computation of hydrogen bonds seems not to work. / Where are my newly computed hydrogen bonds placed?

After computation, the hydrogen bonds have to be visualised by choosing the representation mode H-Bonds by e.g. element.

3.5. Highlighting versus Selecting

What is the difference between the highlighting and the selection concept?

In BALLView clicking on a structure's name is referred to as "highlighting" structures. This is used e.g. for creating representations. Activating the check box in the Structures window sets a Selection. This concept is used e.g. for defining objects subjected to minimization. All "selected" representations are colored with the selection-colour (default is yellow) Selecting a structure corresponds to calling the select method in the BALL library.

3.6. Adding Missing Hydrogens in BALLView

How can I add missing hydrogens in BALLView?

We have to distinguish two cases: proteins and non-proteins. For proteins in general, hydrogens are not contained in pdb files as they can hardly be measured by x-ray crystallography. Hydrogens can be added in BALLView by highlighting the protein's system and clicking "Build"-->"Add Hydrogens". In case of ligands, choose the "Add Hydrogen" method in the Build menu. Note that the positions of the added hydrogens are kind of random. To get more reliable atom positions for the added hydrogens, select all added hydrogens (e.g. using the SMARTS-matcher "element(H)"), right-mouse-click on the Composite (e.g. system or molecule), to which hydrogens have been added, and choose "Highlight Selection". Finally, run an energy minimization by clicking "Molecular Mechanics"-->"Energy Minimization".

3.7. Set Hydrogen Positions

Why do the added hydrogens have strange positions?

Hydrogens that were added by "Saturate with Hydrogens" or "Add Hydrogens" of the Build menu have kind of random positions. To optimize the positions select all hydrogens whose positions should be improved. This can be done very easily using the BALL expressions matcher (bottom of the Structures window). Type "element(H)" and press "Select". Right-mouse-click on the Composite (e.g. system or molecule), to which hydrogens have been added, and choose "Highlight Selection". Finally, run an energy minimization by clicking "Molecular Mechanics"-->"Energy Minimization".

3.8. Saturate with Hydrogens versus Add Hydrogens

What is the difference between "Saturate with Hydrogens" and "Add Hydrogens" in the Build menu?

"Add-Hydrogens" adds hydrogens and other missing atoms based on BALL's FragmentDatabase, where common fragments like amino acids or DNA are specified. "Saturate with Hydrogens" uses a simple heuristic to add hydrogens wherever the atoms have free valences. Note that in both cases the hydrogen's positions have to be further optimized.

3.9. Toolbar Hydrogens Method

Which method is mapped to the Toolbar entry "+H"?

The "+H" button calls the "Saturate with Hydrogens" method.

3.10. Edit mode does not work

Why does the edit mode not work?

A very common mistake is, that the chosen/active representation is set to a non-atom-level type. This can be changed via the context menu of the current representation: 1. Right-click the structure you want to edit. 2. Choose "Modify Model". 3. Now choose e.g. the "Ball and Stick" model. Another reason can be, that the camera is not focused on your new molecule. Mouse right click on the Structure (e.g. System, Residue, or Atom) in the Structures window and choose "Focus". It is also possible, that no molecule is highlighted so BALLView does not know in which structure the new atoms have to be created.

3.11. Change Representation Type

How can I change the representation type?

Representations can be changed by right mouse clicking on an existing representation and choosing "Modify Model". Representations can be added by right mouse clicking on the Structure (e.g. System, Reside, or Atom) and choosing "Create Representation". In the following menu first select a representation type, then the colouring method. The default representation model can be set via "Display"-->"Display Properties".

3.12. Change Background Color

How can I change the background color in BALLView?

Open the Preference dialog via the Edit menu, in the left list view double click on the entry "Display", then select "Main". By clicking on the "Edit" button in the group box "Background color" a "Select color" dialog opens where the background color can be changed.

3.13. Screenshots

How can I improve my screenshots?

Activate the offscreen rendering option in the Preferences dialog: Open Main-Menu "Edit"--> "Preferences" --> Entry "Display" --> Main. Activate the checkbox in the lower right corner "Use offscreen rendering for PNGs". Furthermore you can activate the antialiasing option of your graphics card. If you are still not satisfied with your obtained results, you should consider to export your scene to POVRay via "File" --> "Export Image" --> "POVRay Scene". Please note the following entry!

3.14. Offscreen Rendering does not work

Why does my offscreen rendering not work?

This problem is related to the graphics cards or the graphic cards drivers. Older OpenGL versions (older than 2 years, laptops...) seem to not support offscreen rendering. Solution: either resize your BALLView as large as possible, go into Fullscreen by clicking "Display" --> "Toogle Fullscreen" and export the scene as png (return by again clicking "Display" --> "Toogle Fullscreen"). If you have access to a BALLView on a computer, whose graphic card supports offscreen rendering, just export your current scene as BALLView-Project by clicking "File" --> "Save Project", load it on this other BALLView and export the scene there. If you need really good picture quality with shadows, you can use the POVRay exporter. A POVRay file will be created containing the corresponding POVRay command within the first lines as comment.

3.15. Loaded Molecule not shown

Why does BALLView not show my loaded molecule?

BALLView remembers your last created representation model. It may happen that this model is not suited for your newly loaded molecule, e.g. there are no Secondary Structures to be shown. The default representation model can be changed by clicking "Display"-->"Display Properties". A representation can be changed directly via the Right-mouse-click menu entry "Modify Model" of the respective representation in the Representations window. Another reason for not seeing the newly loaded molecule can be a wrong focus. This can easily happen, if several molecules were loaded into BALLView. The focus can be changed by either selecting the molecule of interest in the Structures window or one of its representations in the Representations window and right mouse clicking "Focus".

3.16. Modify Model versus Modify Representation

What is the difference between "Modify Model" and "Modify Representation"?

"Modify Model" opens a dialog for switching between different representation modelse.g. Ball-and-Stick, Van-der-Waals (VDW), or Solvent-excluded-Surface (SES). The dialog can be accessed via either clicking "Display"-->"Display Properties" or the Right mouse click menu of a representation in the Representations window. "Modify Representation" offers a dialog to for changing the representation type (not model!) parameters like Color by Grid, Material Settings, or the Drawing Mode. This dialog can be accessed via either clicking "Display"-->"Modify Representation" or the Right mouse click menu of a representation in the Representations window.

3.17. Minimization using the Python interpreter

Why does minimization via python not work?

Suppose you wrote code like this:

mol2 = MOL2File("~/scripts/BetulinicAcid.mol2")
S = System()

And you are wondering that the last statement has no effect. There are 2 causes for this: 1.You need to highlight the structure you wish to minimize. 1.The BALLView GUI and the Python interpreter are running in a different thread. Thus if you pass data from Python to the GUI it might take a while until this change is applied. In order to wait for this change to happen, you need to tell Python to wait for the GUI thread.

This can be achieved by the two lines added to the script:

mol2 = MOL2File("~/scripts/BetulinicAcid.mol2")
S = System()

#Highlight the inserted system
#Wait for the threads to synchronize

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.