PyMol Repository Readme

This is a guide intended to help you install and manage the Bio-Prodict 3DM PyMol Plugin. PyMol includes an easy-to-use plugin repository that lets you effortlessly download and install the Bio-Prodict 3DM PyMol Plugin. The latest stable version number can be found here.

Installing PyMol

You need PyMol to run this plugin. We support the 1.8.x and the 2.x.x version of PyMol at this time. Download the PyMol binaries from PyMol.org, or get the source from SourceForge.net and build the program yourself.

Preparation (OSX Only)

If you are an OSX user, your version of PyMol differs from the standard version. This means that you have to make some preparations to make sure that the PyMol plugin will work.

Change to the X11 version of PyMol.

The standard OS X Pymol application, MacPyMOL.app does not run with the Tcl/Tk interface which is required for plugins to work. However, a quick renaming of the program from MacPyMOL.app to PyMOLX11Hybrid.app makes the application run as an X11 application, and plugins are now available.

1. Right click (or control click) on MacPyMOL and choose "Get Info" in the Panel
2. Change the Name & Extension to PyMOLX11Hybrid.app

Once this change is made, half of the program will show up under the X11 icon, and half will show up under the MacPyMOL icon.

Make sure OpenSSL is updated

To guarantee a secure connection to the Bio-Prodict servers, we use HTTPS to establish secure connections when retrieving content. If your OpenSSL version is not up to date, you will get the following error when you try to log in:

requests.exceptions.SSLError: [Errno 1] _ssl.c:504: error:0D0890A1:asn1
      encoding routines:ASN1_verify:unknown message digest algorithm

Installing the latest version of OpenSSL is easy if you currently have Homebrew installed. If not, please refer to the installation instructions on the Homebrew website.

1. With Homebrew installed, launch a Terminal window.
2. In this window, type the following instructions in order:
• brew update
• brew install openssl
• brew link --force openssl
3. If you had PyMol open, restart it.

Installation (Recommended)

Before you start the installation, you will need to determine which version of the plugin you would like:

• The most stable, reliable version (Stable)
• The most cutting-edge version with the newest features (Edge)

The 3DM plugin is released in these two versions. If you want to use the newest features, it is recommended that you pick the Edge repository. If you would rather have the best tested version, you can pick the Stable repository.

• Stable: https://plugin.bio-prodict.nl/pymol/stable/
• Edge: https://plugin.bio-prodict.nl/pymol/edge/

To start the installation, you need to:

1. Start PyMol
2. Click on Plugins in the control window
3. Select Plugin Manager from the dropdown
4. In the Plugin Manager window, go to the Install new plugin tab.
5. Click on Add in the Repositories frame.
6. Enter the URL for the repository you want use in the URL field and click okay.
7. Select the repository from the Repositories list.
8. Acknowledge that you want to download content from the internet.
9. Select the 3dm_plugin_<repository>.zip file in the Items list
10. Click Install
11. The installer may ask where the plugin should be installed, it is best to accept the default location.

Once you have restarted PyMol, the 3DM plugin can be called from the Plugins menu.

If you encounter any problems during this installation, please proceed to the manual installation steps.

Installation (Manual)

Before installing, you will need to download plugin .zip file from our servers.

• Stable: https://plugin.bio-prodict.nl/pymol/stable/3dm_plugin_pymol_stable.zip
• Edge: https://plugin.bio-prodict.nl/pymol/edge/3dm_plugin_pymol_edge.zip

Store it in a location where you can later find it again.

To start the installation, you need to:

1. Start PyMol
2. Click on Plugins in the control window
3. Select Plugin Manager from the dropdown
4. In the Plugin Manager window, go to the Install new plugin tab.
5. Click on Choose file in the Install from local file frame.
6. Select the zip file you downloaded beforehand.
7. The plugin will now be installed. Answer affirmatively to any prompts you may receive.

Once you have restarted PyMol, the 3DM plugin can be called from the Plugins menu.

Finding out my current plugin version

To find out which version of the plugin you are currently running, perform the following steps:

1. Start PyMol
2. Click on Plugins in the control window
3. Select Plugin Manager from the dropdown
4. In the list of installed plugins that appears, find bioprodict.
5. The version number is located directly beside the name of the plugin.

Updating the plugin

To update the plugin, follow these steps.

1. Start PyMol
2. Click on Plugins in the control window
3. Select Plugin Manager from the dropdown
4. In the Plugin Manager window, go to the Install new plugin tab.
5. Click on the Bio-Prodict repository. You may have to scroll through the repository list to see it.
• If there are no repository urls with plugin.bio-prodict.nl listed, follow these steps for installation to add the repository.
6. Select the 3dm_plugin_<repository>.zip file in the Items list.
7. Click on install.
8. PyMol will prompt you that you already have the plugin installed. Acknowledge that you wish to replace it.
9. The plugin has been updated.

Removing the plugin

To remove the plugin, follow these steps.

1. Start PyMol
2. Click on Plugins in the control window
3. Select Plugin Manager from the dropdown
4. In the list of installed plugins that appears, find bioprodict.
5. Click "uninstall"
6. The plugin has been removed.

Selecting a repository

For maximum compatibility, please ensure that you only have one version of the plugin installed. You can have more than one repository in your repository list in the plugin manager, but using both the edge and the stable version is not supported.

Adjusting API URLs in the configuration

If you are running a 3DM installation on a server that is not hosted by Bio-Prodict, you will need to change the configuration of the plugin to speak to that server. To do so, you will need to alter the plugin configuration file the PyMol plugin loads. There are two ways of doing this.

Basic method

Currently, this procedure will need to be run every time the plugin is updated, as the default configuration is included as part of the plugin. It is, however, rather simple to perform.

1. Open your favorite plain-text editor (notepad, gedit, kate...)
2. Find the configuration file. It is located here:
   <PyMol Directory>/modules/pmg_tk/startup/bio-prodict/config.json
3. It is recommended that you make a backup of the config.json file, so you can quickly and easily revert to the previous settings.
4. Open the config.json file with your editor.
5. Replace each of the URLs in this file with the proper URL for your server.
6. Save the file and exit your text editor.
7. Restart PyMol to have the settings take effect.

If you have entered a wrong URL, PyMol will alert you of that fact when you start using the 3DM plugin.

Advanced method

This method will only need to be applied once, but is more involved. You may need experience with the command line for your operating system.

1. Find the configuration file. It is located here:
   <PyMol Directory>/modules/pmg_tk/startup/bio-prodict/config.json
2. Copy this file to another directory where you have write and read access.
3. Using your favorite plain-text editor, replace the urls in the copied file with the proper urls for your server.
4. Save the file and exit your editor.
5. When starting PyMol from here on out, start it with the THREEDM_PLUGIN_CONFIG environment variable pointing to the location of the copied file you created.
• For Linux and Mac OSX, this involves launching PyMol from the terminal like this: THREEDM_PLUGIN_CONFIG=/path/to/config.json <PyMol Directory>/pymol
• In Windows, you can either set a System Environment Variable, or create a shortcut to the PyMol executable with the THREEDM_PLUGIN_CONFIG variable set. You can also use PowerShell to launch PyMol with the variable.

If you have entered a wrong URL, PyMol will alert you of that fact when you start using the 3DM plugin.

Using the PyMol plugin with a proxy

Using the PyMol plugin with your proxy is easier then ever with our integrated proxy settings screen. You can find this settings screen under 3DM > Info > Set proxy information. You do not need to be logged in to set your proxy settings. Simply enter your HTTP(S) proxy urls in the text fields, click Test proxy to verify your proxy works, and click Apply proxy settings to apply the changes. You do may need to restart PyMol for the settings to take effect. If our plugin detects that access to the proxy information is required, it will automatically show the proxy information window.

If you have proxy settings defined as environment variables, these will take precedent over the those set in the built-in menu.

Proxy troubleshooting

I entered the correct proxy server, but testing results in an error with code 407.
Your proxy requires authentication information to proceed. You may need to retrieve this information from your IT department. Please enter the proxy information in the following format:

        http://<username>:<password>@<proxy_server>/
        https://<username>:<password>@<proxy_server>/
    

I am required to connect to a proxy, but the proxy settings screen does not pop up/is empty.
Automatic update checking is turned off and our plugin cannot detect the need for a proxy. Please turn on automatic update checking in the configuration file, or enter the proxy information in the .PROXIES file. (see below)

I would like to automatically transfer the proxy information.
The plugin gathers its proxy information from the .PROXIES file, situated in the directory where PyMol is run from. It will be automatically created when you click "Apply proxy settings." You can transfer this file between computers and between versions, or create it yourself. It is formatted like this (username and password optional):

       {
           "http": "http://<username>:<password>@<proxy_server>/",
           "https": "https://<username>:<password>@<proxy_server>/"
       }