demo.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# PyMOL Remote demo"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1. [Prerequisite] Server side (where PyMOL is running)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This demo should be run on the `client` side, i.e. the machine where you want to run your Python code.\n",
    "To run it, you will need to have run the following command on the `server` side, i.e. the machine where PyMOL is running:\n",
    "\n",
    "```bash\n",
    "# Navigate into your pymol environment\n",
    "#  that environment should have both, pymol and pymol_remote installed\n",
    "# e.g.:\n",
    "# conda activate pymol\n",
    "\n",
    "# If pymol_remote is installed, the following command will start the server\n",
    "pymol_remote\n",
    "```\n",
    "\n",
    "This command will start pymol, and in the pymol console you should see a likely guess of your IP address (and the correct port number, 9123 by default).\n",
    "If this IP address does not work, you might need to use commands like `ifconfig` or `ipconfig` on your computer to find the correct IP address of the server in your local network."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2. Client side (where you want to run your Python code)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pymol_remote.client import PymolSession\n",
    "\n",
    "# NOTE: When you run `pymol_remote` on the server side, it will print a likely guess of your\n",
    "#  IP address (and the correct port number, 9123 by default). Try that IP address first,\n",
    "#  if it doesn't work you might need to use commands like `ifconfig` or `ipconfig` on\n",
    "#  your computer to find the correct IP address of the server in your local network.\n",
    "IP_ADDRESS_OF_SERVER = (\n",
    "    \"YOUR_SERVERS_IP_ADDRESS_GOES_HERE\"  # for example sth. like \"10.123.45.67\"\n",
    ")\n",
    "pymol = PymolSession(hostname=IP_ADDRESS_OF_SERVER, port=9123)\n",
    "\n",
    "# You can now send commands to PyMOL\n",
    "pymol.fetch(\"6lyz\")\n",
    "pymol.do(\"remove solvent\")\n",
    "pymol.do(\"set valence, on\")\n",
    "pymol.get_state(format=\"cif\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "    A class for interacting with a PyMOL RPC server, which allows you to execute PyMOL commands\n",
      "    and retrieve information from a running PyMOL session (possibly running on a remote machine\n",
      "    on the same network).\n",
      "\n",
      "    You can find more information about the available commands here:\n",
      "        - https://pymol.org/pymol-command-ref.html\n",
      "        - https://pymolwiki.org/index.php/Category:Commands\n",
      "\n",
      "    You can invoke all pymol commands using direclty as methods on this object.\n",
      "    For example:\n",
      "\n",
      "    ```python\n",
      "    >>> session.fetch('6lyz')\n",
      "    >>> session.get_names()\n",
      "    ```\n",
      "\n",
      "    You may also use any command that can be called in the pymol console with the `do` method.\n",
      "    For example:\n",
      "\n",
      "    ```python\n",
      "    >>> session.do('set valence, on')\n",
      "    ```\n",
      "\n",
      "    To get the current state of the pymol session from the server, you can use the `get_state` method.\n",
      "    For example:\n",
      "\n",
      "    ```python\n",
      "    session.get_state(selection=\"(all)\", state=-1, format=\"cif\")\n",
      "    session.get_state(selection=\"(all)\", state=-1, format=\"pdb\")\n",
      "    ```\n",
      "\n",
      "    To get help with a specific command, you can use the `help` method.\n",
      "    For example:\n",
      "\n",
      "    ```python\n",
      "    >>> session.help('fetch')  # get help for the fetch command\n",
      "    >>> session.help()  # get a list of all available commands\n",
      "    ```\n",
      "    \n"
     ]
    }
   ],
   "source": [
    "pymol.print_help()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Get help on a specific command"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "fetch(code, name='', state=0, finish=1, discrete=-1, multiplex=-2, zoom=-1, type='', async_=0, path='', file=None, quiet=1, _self=<module 'pymol.cmd' from '/opt/homebrew/Caskroom/miniconda/base/envs/pymol/lib/python3.12/site-packages/pymol/cmd.py'>, **kwargs)\n",
      "\n",
      "DESCRIPTION\n",
      "\n",
      "    \"fetch\" downloads a file from the internet (if possible)\n",
      "\n",
      "USAGE\n",
      "\n",
      "    fetch code [, name [, state [, finish [, discrete [, multiplex\n",
      "        [, zoom [, type [, async [, path ]]]]]]]]]\n",
      "\n",
      "ARGUMENTS\n",
      "\n",
      "    code = a single PDB identifier or a list of identifiers. Supports\n",
      "    5-letter codes for fetching single chains (like 1a00A).\n",
      "\n",
      "    name = the object name into which the file should be loaded.\n",
      "\n",
      "    state = the state number into which the file should loaded.\n",
      "\n",
      "    type = str: cif, pdb, pdb1, 2fofc, fofc, emd, cid, sid {default: cif\n",
      "    (default was \"pdb\" up to 1.7.6)}\n",
      "\n",
      "    async_ = 0/1: download in the background and do not block the PyMOL\n",
      "    command line {default: 0 -- changed in PyMOL 2.3}\n",
      "\n",
      "PYMOL API\n",
      "\n",
      "    cmd.fetch(string code, string name, int state, init finish,\n",
      "              int discrete, int multiplex, int zoom, string type,\n",
      "              int async, string path, string file, int quiet)\n",
      "              \n",
      "NOTES\n",
      "\n",
      "    When running in interactive mode, the fetch command loads\n",
      "    structures asyncronously by default, meaning that the next command\n",
      "    may get executed before the structures have been loaded.  If you\n",
      "    need synchronous behavior in order to insure that all structures\n",
      "    are loaded before the next command is executed, please provide the\n",
      "    optional argument \"async=0\".\n",
      "\n",
      "    Fetch requires a direct connection to the internet and thus may\n",
      "    not work behind certain types of network firewalls.\n",
      "    \n",
      "        \n"
     ]
    }
   ],
   "source": [
    "pymol.help(\"fetch\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "get_state(selection: str = '(all)', state: int = -1, format: str = 'pdb') -> str | bytes\n",
      "Get the current state of the PyMOL session as a PDB string.\n",
      "\n",
      "    This function retrieves the current state of the PyMOL session, including all\n",
      "    molecules, their coordinates, and other relevant information, and returns it\n",
      "    as a PDB string.\n",
      "\n",
      "    Args:\n",
      "        - selection (str, optional): The selection of atoms to include in the PDB string.\n",
      "            Defaults to \"all\".\n",
      "        - state (int, optional): The state of the molecule to include in the PDB string.\n",
      "            Defaults to `-1`, which means the current state. If state is 0, then\n",
      "            a multi-state output file is written.\n",
      "        - format (str, optional): The format of the file to save. Defaults to \"pdb\".\n",
      "            Supported formats: \"pdb\", \"mol\", \"png\", \"cif\"\n",
      "\n",
      "    Returns:\n",
      "        str | bytes: The PDB string or binary file content.\n",
      "    \n"
     ]
    }
   ],
   "source": [
    "pymol.help(\"get_state\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Show all the available commands"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Get help for a specific command by passing the command name to the `help` method.\n",
      "For example:\n",
      "```\n",
      "session.help('fetch')\n",
      "```\n",
      "\n",
      "To get links to more documentation, call `session.print_help()`.\n",
      "Available commands:\n",
      "\n",
      "  -abort\n",
      "  -accept\n",
      "  -add_bond\n",
      "  -alias\n",
      "  -align\n",
      "  -alignto\n",
      "  -alphatoall\n",
      "  -alter\n",
      "  -alter_list\n",
      "  -alter_state\n",
      "  -angle\n",
      "  -api\n",
      "  -as_pathstr\n",
      "  -assign_stereo\n",
      "  -async_\n",
      "  -attach\n",
      "  -auto_measure\n",
      "  -backward\n",
      "  -bg_color\n",
      "  -bg_colour\n",
      "  -block_flush\n",
      "  -bond\n",
      "  -boolean_sc\n",
      "  -button\n",
      "  -cache\n",
      "  -callout\n",
      "  -capture\n",
      "  -cartoon\n",
      "  -cd\n",
      "  -cealign\n",
      "  -center\n",
      "  -centerofmass\n",
      "  -check\n",
      "  -clean\n",
      "  -clip\n",
      "  -cls\n",
      "  -color\n",
      "  -color_deep\n",
      "  -color_sc\n",
      "  -colour\n",
      "  -commands\n",
      "  -config_mouse\n",
      "  -contour_sc\n",
      "  -copy\n",
      "  -copy_image\n",
      "  -copy_to\n",
      "  -count_atoms\n",
      "  -count_discrete\n",
      "  -count_frames\n",
      "  -count_states\n",
      "  -create\n",
      "  -curve_new\n",
      "  -cycle_valence\n",
      "  -decline\n",
      "  -del_colorection\n",
      "  -delete\n",
      "  -deprotect\n",
      "  -desaturate\n",
      "  -deselect\n",
      "  -dihedral\n",
      "  -dirty\n",
      "  -dirty_wizard\n",
      "  -disable\n",
      "  -dist\n",
      "  -distance\n",
      "  -do\n",
      "  -download_chem_comp\n",
      "  -drag\n",
      "  -draw\n",
      "  -dss\n",
      "  -dump\n",
      "  -edit\n",
      "  -edit_mode\n",
      "  -editing_ring\n",
      "  -enable\n",
      "  -ending\n",
      "  -exp_path\n",
      "  -extend\n",
      "  -extendaa\n",
      "  -extra_fit\n",
      "  -extract\n",
      "  -fab\n",
      "  -fast_minimize\n",
      "  -fb_action\n",
      "  -fb_action_sc\n",
      "  -fb_mask\n",
      "  -fb_mask_sc\n",
      "  -fb_module\n",
      "  -fb_module_sc\n",
      "  -feedback\n",
      "  -fetch\n",
      "  -file_read\n",
      "  -filename_to_objectname\n",
      "  -find_pairs\n",
      "  -finish_object\n",
      "  -fit\n",
      "  -fix_chemistry\n",
      "  -flag\n",
      "  -fnab\n",
      "  -focal_blur\n",
      "  -forward\n",
      "  -fragment\n",
      "  -frame\n",
      "  -full_screen\n",
      "  -fuse\n",
      "  -get\n",
      "  -get_angle\n",
      "  -get_area\n",
      "  -get_assembly_ids\n",
      "  -get_atom_coords\n",
      "  -get_bond\n",
      "  -get_bond_print\n",
      "  -get_bonds\n",
      "  -get_bytes\n",
      "  -get_chains\n",
      "  -get_cifstr\n",
      "  -get_clip\n",
      "  -get_collada\n",
      "  -get_color_index\n",
      "  -get_color_indices\n",
      "  -get_color_tuple\n",
      "  -get_colorection\n",
      "  -get_coords\n",
      "  -get_coordset\n",
      "  -get_dihedral\n",
      "  -get_distance\n",
      "  -get_drag_object_name\n",
      "  -get_editor_scheme\n",
      "  -get_extent\n",
      "  -get_fastastr\n",
      "  -get_frame\n",
      "  -get_gltf\n",
      "  -get_idtf\n",
      "  -get_legal_name\n",
      "  -get_modal_draw\n",
      "  -get_model\n",
      "  -get_movie_length\n",
      "  -get_movie_locked\n",
      "  -get_movie_playing\n",
      "  -get_mtl_obj\n",
      "  -get_names\n",
      "  -get_names_of_type\n",
      "  -get_object_color_index\n",
      "  -get_object_list\n",
      "  -get_object_matrix\n",
      "  -get_object_settings\n",
      "  -get_object_state\n",
      "  -get_object_ttt\n",
      "  -get_pdbstr\n",
      "  -get_phipsi\n",
      "  -get_position\n",
      "  -get_povray\n",
      "  -get_progress\n",
      "  -get_raw_alignment\n",
      "  -get_renderer\n",
      "  -get_sasa_relative\n",
      "  -get_scene_list\n",
      "  -get_scene_message\n",
      "  -get_scene_thumbnail\n",
      "  -get_selection_state\n",
      "  -get_session\n",
      "  -get_setting_boolean\n",
      "  -get_setting_float\n",
      "  -get_setting_int\n",
      "  -get_setting_legacy\n",
      "  -get_setting_text\n",
      "  -get_setting_tuple\n",
      "  -get_setting_updates\n",
      "  -get_state\n",
      "  -get_str\n",
      "  -get_symmetry\n",
      "  -get_title\n",
      "  -get_type\n",
      "  -get_unused_name\n",
      "  -get_version\n",
      "  -get_view\n",
      "  -get_viewport\n",
      "  -get_vis\n",
      "  -get_volume_field\n",
      "  -get_volume_histogram\n",
      "  -get_vrml\n",
      "  -get_wizard\n",
      "  -get_wizard_stack\n",
      "  -gradient\n",
      "  -group\n",
      "  -group_sc\n",
      "  -h_add\n",
      "  -h_fill\n",
      "  -h_fix\n",
      "  -help\n",
      "  -help_sc\n",
      "  -help_setting\n",
      "  -hide\n",
      "  -id_atom\n",
      "  -identify\n",
      "  -index\n",
      "  -indicate\n",
      "  -interrupt\n",
      "  -intra_fit\n",
      "  -intra_rms\n",
      "  -intra_rms_cur\n",
      "  -invert\n",
      "  -ipython_image\n",
      "  -is_alive\n",
      "  -is_dict\n",
      "  -is_error\n",
      "  -is_gui_thread\n",
      "  -is_list\n",
      "  -is_ok\n",
      "  -is_sequence\n",
      "  -is_string\n",
      "  -is_tuple\n",
      "  -isodot\n",
      "  -isolevel\n",
      "  -isomesh\n",
      "  -isosurface\n",
      "  -iterate\n",
      "  -iterate_state\n",
      "  -join_states\n",
      "  -kwhash\n",
      "  -label\n",
      "  -label2\n",
      "  -load\n",
      "  -load_brick\n",
      "  -load_callback\n",
      "  -load_cgo\n",
      "  -load_coords\n",
      "  -load_coordset\n",
      "  -load_embedded\n",
      "  -load_map\n",
      "  -load_model\n",
      "  -load_mtz\n",
      "  -load_object\n",
      "  -load_png\n",
      "  -load_raw\n",
      "  -load_traj\n",
      "  -loadable\n",
      "  -loadall\n",
      "  -location_sc\n",
      "  -lock\n",
      "  -lock_attempt\n",
      "  -lock_without_glut\n",
      "  -log\n",
      "  -log_close\n",
      "  -log_open\n",
      "  -look_at\n",
      "  -ls\n",
      "  -madd\n",
      "  -map_double\n",
      "  -map_generate\n",
      "  -map_halve\n",
      "  -map_new\n",
      "  -map_sc\n",
      "  -map_set\n",
      "  -map_set_border\n",
      "  -map_trim\n",
      "  -mappend\n",
      "  -mask\n",
      "  -matrix_copy\n",
      "  -matrix_reset\n",
      "  -matrix_transfer\n",
      "  -mclear\n",
      "  -mcopy\n",
      "  -mdelete\n",
      "  -mdo\n",
      "  -mdump\n",
      "  -mem\n",
      "  -meter_reset\n",
      "  -middle\n",
      "  -minimize\n",
      "  -minsert\n",
      "  -mmatrix\n",
      "  -mmove\n",
      "  -morph\n",
      "  -mouse\n",
      "  -move\n",
      "  -move_on_curve\n",
      "  -mplay\n",
      "  -mpng\n",
      "  -mse2met\n",
      "  -mset\n",
      "  -mstop\n",
      "  -mtoggle\n",
      "  -multifilenamegen\n",
      "  -multifilesave\n",
      "  -multisave\n",
      "  -mview\n",
      "  -object_sc\n",
      "  -order\n",
      "  -orient\n",
      "  -origin\n",
      "  -overlap\n",
      "  -pair_fit\n",
      "  -palette_sc\n",
      "  -paste\n",
      "  -pbc_unwrap\n",
      "  -pbc_wrap\n",
      "  -phi_psi\n",
      "  -pi_interactions\n",
      "  -png\n",
      "  -pop\n",
      "  -pretty\n",
      "  -protect\n",
      "  -pseudoatom\n",
      "  -publication\n",
      "  -push_undo\n",
      "  -pwd\n",
      "  -python_help\n",
      "  -quit\n",
      "  -ramp_new\n",
      "  -ramp_update\n",
      "  -ray\n",
      "  -read_mmodstr\n",
      "  -read_molstr\n",
      "  -read_pdbstr\n",
      "  -read_sdfstr\n",
      "  -read_xplorstr\n",
      "  -ready\n",
      "  -rebond\n",
      "  -rebuild\n",
      "  -recolor\n",
      "  -recolour\n",
      "  -redo\n",
      "  -reference\n",
      "  -refresh\n",
      "  -refresh_wizard\n",
      "  -reinitialize\n",
      "  -remove\n",
      "  -remove_picked\n",
      "  -rename\n",
      "  -replace\n",
      "  -replace_wizard\n",
      "  -repmasks_sc\n",
      "  -repres_sc\n",
      "  -reset\n",
      "  -resume\n",
      "  -rewind\n",
      "  -rms\n",
      "  -rms_cur\n",
      "  -rock\n",
      "  -rotate\n",
      "  -run\n",
      "  -safe_alpha_list_eval\n",
      "  -safe_eval\n",
      "  -safe_list_eval\n",
      "  -save\n",
      "  -scene\n",
      "  -scene_order\n",
      "  -scene_recall_message\n",
      "  -sculpt_activate\n",
      "  -sculpt_deactivate\n",
      "  -sculpt_iterate\n",
      "  -sculpt_purge\n",
      "  -select\n",
      "  -select_list\n",
      "  -selection_sc\n",
      "  -set\n",
      "  -set_bond\n",
      "  -set_color\n",
      "  -set_colorection\n",
      "  -set_colour\n",
      "  -set_dihedral\n",
      "  -set_discrete\n",
      "  -set_frame\n",
      "  -set_geometry\n",
      "  -set_key\n",
      "  -set_name\n",
      "  -set_object_color\n",
      "  -set_object_ttt\n",
      "  -set_raw_alignment\n",
      "  -set_scene_message\n",
      "  -set_session\n",
      "  -set_state_order\n",
      "  -set_symmetry\n",
      "  -set_title\n",
      "  -set_view\n",
      "  -set_vis\n",
      "  -set_wizard\n",
      "  -set_wizard_stack\n",
      "  -show\n",
      "  -show_as\n",
      "  -show_help\n",
      "  -simple\n",
      "  -slice_new\n",
      "  -smooth\n",
      "  -sort\n",
      "  -space\n",
      "  -space_sc\n",
      "  -spawn\n",
      "  -spectrum\n",
      "  -spheroid\n",
      "  -splash\n",
      "  -split_chains\n",
      "  -split_states\n",
      "  -stereo\n",
      "  -stereo_sc\n",
      "  -super\n",
      "  -symexp\n",
      "  -symmetry_copy\n",
      "  -sync\n",
      "  -system\n",
      "  -technical\n",
      "  -test\n",
      "  -toggle\n",
      "  -toggle_sc\n",
      "  -torsion\n",
      "  -transform_object\n",
      "  -transform_selection\n",
      "  -translate\n",
      "  -translate_atom\n",
      "  -turn\n",
      "  -unblock_flush\n",
      "  -unbond\n",
      "  -undo\n",
      "  -ungroup\n",
      "  -uniquify\n",
      "  -unlock\n",
      "  -unmask\n",
      "  -unpick\n",
      "  -unset\n",
      "  -unset_bond\n",
      "  -unset_deep\n",
      "  -update\n",
      "  -valence\n",
      "  -vdw_fit\n",
      "  -view\n",
      "  -viewport\n",
      "  -volume\n",
      "  -volume_color\n",
      "  -volume_panel\n",
      "  -volume_ramp_new\n",
      "  -window\n",
      "  -window_sc\n",
      "  -wizard\n",
      "  -write_html_ref\n",
      "  -zoom\n"
     ]
    }
   ],
   "source": [
    "pymol.help()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}