PyChimera provides access to UCSF Chimera’s modules from any Python 2.x interpreter. This is achieved in two steps:
patch_environ()
patches environment variables with proper paths (packages and libraries). Since the originalsys.path
is exported toPYTHONPATH
, you can use all your virtualenv/conda packages with Chimera. This call restarts Python to inject a newos.environ
withos.execve
.enable_chimera()
initializes Chimera. This is done through their own routines (chimeraInit
).
As a result, if you want to use PyChimera in your developments, you only need to execute these lines at the beginning of the script. For example, PyChimera is used programmatically in the GaudiMM CLI entry point.
import pychimera
pychimera.patch_environ()
pychimera.enable_chimera()
Calling patch_environ()
will result in the interpreter being restarted to inject all UCSF Chimera libraries; take that into account in the logic of your program. This is why you should probably add the lines at the very beginning of the script.
Alternatively, you can leave those lines out and have your users execute the script with pychimera
instead of python
. Up to you, but usually you will prefer to hide the technical details...
PyChimera also offers its interface through python -m
. This has not been thoroughly tested, so it may not work perfectly. Add -i
for interactive mode:
python -[i]m pychimera [-m another_module | -c "string" | script.py | ipython | notebook]
You can also try to launch it from IPython, but, again, some things may not work. Anyway, these two commands have the same effect:
pychimera ipython [notebook]
ipython -m pychimera [notebook]
If you want to run a script with IPython and then inspect the results (-i
flag), your best bet is to run pychimera ipython
and then call %run path/to/file.py
inside the interpreter.
When you run patch_environ
, we try to locate a valid UCSF Chimera installation in the system. This is performed with three alternative strategies:
- Check if a
CHIMERADIR
variable is set. This is normally set by the user when the automated strategies can't work right due to the system configuration. If the path is valid, use that as the UCSF Chimera installation directory. Else, try strategy #2. - Check if an executable called
chimera
is somewhere inPATH
. This is done withdisutils.spawn.find_executable
. If successful, figure out the UCSF Chimera installation directory from the file path after resolving any possible symlinks. - If
chimera
is not inPATH
, we can try to find the installation directory in the default locations (~/.local
or/opt
for Linux,/Applications
for Mac OS X,C:\Program Files
for Windows).
Once we have located a valid UCSF Chimera, we find the needed libraries and Python modules to patch LD_LIBRARY_PATH
, PYTHONPATH
and other environment variables, as specified in their own shell launcher (Linux/OSX) and cpp launcher (Windows). In this step, any additional packages and libraries installed in a conda
environment or virtualenv
are also injected. For all this to work, the interpreter is restarted.
After the restart, enable_chimera
is called, which runs the UCSF Chimera initialization routines contained in chimeraInit.py
. Depending on the CLI options, we then run a script, run IPython/Notebook or start the GUI.