jlmol

A desktop application for molecular visualization built with Electron and JSmol. This application provides a native desktop experience for the powerful JSmol molecular viewer.

Try it online: Browser Version

Download: Latest Release Executables

Features

Visualization

• Powerful JSmol molecular visualization capabilities:
  • 3D structure visualization with multiple display styles (ball&stick, wireframe, spacefill)
  • Support for multiple file formats (XYZ, PDB, MOL, CIF, MOLDEN)
  • Interactive controls for rotation and zoom
  • Spin animation
  • Drag and drop file loading

Database Search

• PubChem Database Integration: Direct access to molecular structures from PubChem without needing to download files locally
  • Combined Search Interface: Modern unified input field with integrated search type selector
  • Compound ID (CID): Search by PubChem compound identifier (e.g., 1983 for caffeine)
  • Chemical Name: Search by common or systematic names (e.g., caffeine, aspirin, glucose)
  • Formula: Search by molecular formula (e.g., C2H5OH)
  • SMILES: Search using SMILES notation (e.g., C6H6 for benzene, CC=O for acetaldehyde)
  • Search Type Enforcement: Click selector to force specific search types (CID, Name, SMILES)
  • Auto-detection: Intelligent query type detection based on input format
  • Enter Key Support: Quick loading by pressing Enter in the search field
  • Network Error Handling: Robust error handling for connection issues

Structure Editing

• Integrated JSME 2D structure editor:

  • Toggle between 3D (JSmol) and 2D (JSME) views
  • Draw and edit molecular structures in intuitive 2D interface
  • Real-time synchronization between 2D and 3D views
  • Standard molecular drawing tools (atoms, bonds, rings)
  • Clean up structure layout

• ModelKit 3D editor:

  • Interactive atom manipulation in 3D space
  • Automatic structure optimization during atom movement
  • Add/delete atoms and modify bonds
  • Bond order modification
  • Right-click menu for advanced editing options
  • Automatic geometry optimization

• Enhanced XYZ structure editor:

  • Direct coordinate editing
  • Live preview of changes
  • Structure optimization
  • Atom selection mode
  • Save edited structures
  • Draggable and resizable editor window

ElemCo.jl Input Generation and Calculation

• Built-in support for generating ElemCo.jl input files
• Direct conversion of molecular structures to ElemCo.jl input format
• Support for common quantum chemistry methods (HF, MP2, CCSD, etc.)
• Basis set selection
• Density fitting toggle for supported methods
• NEW: Integrated calculation runner with customizable Julia command support
• NEW: Windows Subsystem for Linux (WSL) support for running calculations
• NEW: User preferences system for persistent settings

Troubleshooting

For troubleshooting guides and solutions to common issues, see Troubleshooting.md.

Advanced Features

• Orbital visualization:

  • Advanced orbital visualization with HOMO/LUMO identification
  • Easy orbital navigation with arrow keys
  • Orbital energy level display
  • Quick HOMO/LUMO switching
  • Visual distinction between HOMO and LUMO
  • Interactive orbital list

• General features:

  • Cross-platform support (Windows, macOS, Linux)
  • Native desktop application experience
  • Multi-format file support
  • Structure optimization capabilities
  • NEW: User preferences system with persistent settings
  • NEW: ElemCo.jl calculation runner with WSL support

Installation

Pre-built Executables

Executables for Windows and Linux are automatically generated for each release on GitHub. You can:

1. Download the latest version for your platform from the releases page
2. Run the installer for your platform
   • Windows: .exe installer
   • Linux: .AppImage or .deb/.rpm package
   • macOS: .dmg

From Source

1. Clone the repository
2. Install dependencies:

npm install

1. Run the application:

npm start

Building

To build the application:

npm run build

This will create installers in the dist directory.

Development

This application is built with:

• Electron
• JSmol (JavaScript-based molecular viewer)
• Node.js

Credits

• JSmol is part of the Jmol project:
  • Original Jmol code conversion to JavaScript by Bob Hanson
  • Java2Script written by Zhou Renjian, et al.
• JSME (JavaScript Molecular Editor):
  • Developed by Peter Ertl and Bruno Bienfait
  • Original publication: B. Bienfait, P. Ertl, JSME: a free molecule editor in JavaScript, J. Cheminform. 5:24 (2013)

License

This project is licensed under LGPL-2.1.

Documentation

For more information about the underlying JSmol viewer:

• Jmol Documentation
• JSmol Documentation

Using the XYZ Editor

The application includes a draggable XYZ structure editor that allows you to:

• View and edit molecular coordinates in XYZ format
• Switch between selection and edit modes
• Select individual atoms in the structure
• Optimize molecular geometry using JSmol's built-in minimization
• Preview changes in real-time in the 3D viewer
• Save edited structures to XYZ files
• Move the editor window anywhere on screen by dragging its header
• Resize the editor window by dragging its bottom-right corner

To use the editor:

1. Load a molecular structure
2. Click the "Edit XYZ" button
3. Use Selection mode to highlight specific atoms
4. Switch to Edit mode to modify coordinates
5. Click "Optimize Structure" to improve geometry
6. Click "Update Structure" to apply your changes
7. Click "Save XYZ File" to save the current structure

Orbital Visualization

The orbital viewer provides enhanced visualization of molecular orbitals:

• Interactive orbital list showing energy levels
• Color-coded HOMO and LUMO identifiers
• Keyboard navigation (↑/↓ arrow keys)
• Quick HOMO/LUMO access buttons
• Translucent orbital surface display
• Draggable and resizable control panel

To visualize orbitals:

1. Load a structure with orbital data (e.g., MOLDEN format)
2. Click "Show/Hide Orbitals" button
3. Use arrow keys or buttons to navigate orbitals
4. Click HOMO or LUMO buttons for quick access
5. Select specific orbitals from the energy-sorted list

2D Structure Editor (JSME)

The application includes JSME (JavaScript Molecular Editor), providing an integrated 2D structure editing experience:

• Toggle between 3D (JSmol) and 2D (JSME) views with a single click
• Draw and edit molecular structures in a familiar 2D interface
• Automatic conversion between 2D and 3D structures
• Real-time synchronization of changes between editors
• Support for standard molecular drawing tools:
  • Add/remove atoms and bonds
  • Change atom types
  • Adjust bond orders
  • Ring templates
  • Clean up structure layout

To use the 2D editor:

1. Click the "2D Editor" button to switch to JSME
2. Draw or edit your structure using the JSME tools
3. Changes are automatically synchronized with the 3D view
4. Click "3D Viewer" to return to JSmol visualization
5. Use the "Ball & Stick" or other display styles to view your structure in 3D

The 2D editor is particularly useful for:

• Creating new molecular structures from scratch
• Quick structural modifications
• Drawing complex molecular scaffolds
• Teaching and presentation purposes

ModelKit - 3D Structure Editor

The application includes JSmol's built-in ModelKit for interactive 3D structure editing:

• Click the "3D" button in the Edit section to activate ModelKit mode
• Default mode - Drag & Minimize:
  • Click and drag atoms to move them in 3D space
  • Structure is automatically optimized after each movement
  • Helps in quick structure refinement and conformation exploration

Advanced ModelKit features (activated via right-click menu):

• Add/Delete atoms
  • Right-click to access the atom menu
  • Choose from common elements (H, C, N, O, etc.)
  • Click on existing atoms to add new ones
  • Delete atoms using the delete option
• Bond manipulation
  • Change bond orders (single, double, triple)
  • Add/remove bonds between atoms
  • Adjust bond angles and lengths
• Structure cleaning
  • Automatic geometry optimization
  • Bond length normalization
  • Angle adjustment to standard values

To use ModelKit:

1. Click the "3D" button to activate
2. Left-click and drag atoms to move them (default mode)
3. Right-click for additional editing options
4. Changes are applied in real-time
5. Click "3D" again to exit ModelKit mode

This feature complements the XYZ editor and 2D JSME editor, providing a complete set of molecular editing tools.

ElemCo.jl Integration

The application includes built-in support for generating ElemCo.jl input files for quantum chemistry calculations:

ElemCo.jl Features

• Direct conversion of molecular structures to ElemCo.jl input format
• Support for common quantum chemistry methods:
  • Hartree-Fock (HF)
  • Second-order Møller-Plesset perturbation theory (MP2)
  • Distinguishable Cluster Singles and Doubles (DCSD)
  • Coupled Cluster with Singles, Doubles, and perturbative Triples (CCSD(T))
  • Coupled Cluster with Singles, Doubles, and Triples (CCSDT)
  • Distinguishable Cluster CCSDT (DC-CCSDT)
  • SVD-Distinguishable Cluster methods (SVD-DC-CCSDT and SVD-DCSD)

Available Options

• Basis Sets:
  • Correlation-consistent basis sets (cc-pVDZ, cc-pVTZ)
  • Augmented correlation-consistent basis sets (aug-cc-pVDZ, aug-cc-pVTZ)
  • Automatic or manual selection of auxiliary basis sets for:
    • JK-fitting (cc-pVXZ-jkfit, def2-universal-jkfit)
    • MP2-fitting (cc-pVXZ-mpfit, aug-cc-pVXZ-mpfit)
• Density Fitting (DF) toggle for supported methods
• Charge and multiplicity specification
• Direct text editing of generated input

Using ElemCo.jl Integration

1. Load or create a molecular structure in the viewer
2. Click the ElemCo.jl logo button in the control panel
3. Select desired calculation options:
   • Choose quantum chemistry method
   • Select basis sets
   • Toggle density fitting if desired
   • Set charge and multiplicity if needed
4. Review the generated input in the text editor
5. Copy the input directly to clipboard
6. Use the input with ElemCo.jl for calculations

The integration provides a convenient way to prepare quantum chemistry calculations while visualizing the molecular structure. For more information about ElemCo.jl and its capabilities, visit elem.co.il.

Running ElemCo.jl Calculations

jlmol now includes an integrated calculation runner that can execute ElemCo.jl calculations directly from the application:

1. Generate ElemCo.jl Input: Use the ElemCo.jl integration to create input files
2. Configure Julia Command: Set up your Julia executable path in Settings (see User Preferences below)
3. Run Calculation: Click "Run ElemCo.jl" to execute the calculation
4. View Results: Monitor progress and view calculation output in real-time

WSL (Windows Subsystem for Linux) Support

For Windows users running Julia under WSL, jlmol provides seamless integration:

• Automatic Path Translation: Temp files are automatically converted to WSL-compatible paths
• WSL Command Support: Configure Julia commands like wsl julia or wsl --shell-type login julia
• Error Handling: Detailed troubleshooting information for WSL-specific issues

Remote Execution on Linux Machines

For running calculations on a remote Linux machine, you can use the runremote script located in the scripts directory. This script uses ssh and scp to execute the calculation remotely. It works the best if you have a passwordless SSH setup to the remote machine.

1. Configure the script: Open scripts/runremote and set the following variables at the top of the file:

   • REMOTE_USER: Your username on the remote machine.
   • REMOTE_HOST: The hostname or IP address of the remote machine.
   • REMOTE_WORKDIR: A working directory on the remote machine where calculation files will be stored.

2. Configure jlmol: In the jlmol settings, set the Julia command to execute the script. You might need to provide the full path to the script.

   • On Linux/macOS: /path/to/jlmol/scripts/runremote julia
   • On Windows: bash /path/to/jlmol/scripts/runremote julia (if you have bash, e.g. from Git for Windows) or wsl --shell-type login runremote julia (if you have WSL configured and runremote is in your PATH)

This setup allows you to leverage more powerful remote resources for your calculations directly from the jlmol interface.

User Preferences and Settings

jlmol includes a comprehensive settings system that allows you to customize the application behavior and set up calculation environments.

Accessing Settings

Click the Settings button next to the Console button in the main interface to open the preferences panel.

Available Settings

Display Preferences

• Startup Display Mode: Choose the default molecular display style (Ball & Stick, Wireframe, etc.)
• Spin Animation: Enable/disable automatic rotation of molecules

ElemCo.jl Defaults

• Default Method: Set your preferred quantum chemistry method (HF, MP2, CCSD(T), etc.)
• Default Basis Set: Choose your standard basis set for calculations
• Density Fitting: Enable/disable density fitting by default

Application Settings

• Julia Command: Configure the command used to run Julia for ElemCo.jl calculations

Julia Command Configuration

The Julia command setting allows you to specify how jlmol should invoke Julia for running ElemCo.jl calculations. This is particularly useful for custom Julia installations or WSL environments.

Examples

Standard Julia Installation:

julia

Custom Julia Path:

/usr/local/bin/julia

Windows Subsystem for Linux (WSL):

wsl julia

WSL with Specific Shell:

wsl --shell-type login julia

WSL with Distribution:

wsl -d Ubuntu-20.04 julia

WSL Setup Instructions

1. Install Julia in WSL: Follow standard Julia installation in your WSL distribution
2. Verify Julia Works: Test that julia command works in WSL terminal
3. Configure jlmol: Set Julia command to wsl julia (or appropriate variant)
4. Test Calculation: Run a simple ElemCo.jl calculation to verify setup

Troubleshooting Julia Command

• Path Issues: Use full paths if Julia is not in your system PATH
• WSL Issues: Ensure Julia is properly installed and accessible in your WSL environment
• Permission Issues: Check that Julia executable has proper permissions
• Network Issues: Some calculations may require internet access for package downloads

Settings Persistence

All user preferences are automatically saved and restored between application sessions using local storage.

Database Search and Molecule Loading

The application includes comprehensive database search functionality for loading molecular structures directly from online databases.

PubChem Database

PubChem integration allows direct access to over 100 million chemical structures without requiring local file downloads.

Search Methods

1. Compound ID (CID) Search

   • Enter numeric PubChem compound identifier
   • Example: 1983 (loads caffeine)
   • Most reliable method for known compounds

2. Chemical Name Search

   • Search by common names, systematic names, or trade names
   • Examples: caffeine, aspirin, benzene, glucose
   • Case-insensitive matching

3. Molecular Formula Search

   • Search by molecular formula
   • Examples: H2O, C2H5OH

4. SMILES Search

   • Use SMILES notation for precise structure specification
   • Examples: C6H6 (benzene), CC=O (acetaldehyde), CC(=O)OC1=CC=CC=C1C(=O)O (aspirin)
   • Useful for specific structural queries

Using Database Search

1. Locate the Database Search Section in the control panel
2. Select Search Method (optional):
   • Click the search type selector on the right side of the input field
   • Choose from: Auto-detect (default), CID, Name, Formula or SMILES
   • The input placeholder text will update to show relevant examples
3. Enter Query in the input field
4. Execute Search:
   • Click "Load from PubChem" button
   • Or press Enter for quick loading

Search Tips

• Search Type Selection: Click the selector on the right side of the input field to override auto-detection:
  • Auto-detect: Smart detection based on input patterns (default)
  • CID: Force search by compound identifier (most reliable)
  • Name: Force search by chemical name (reliable for common names)
  • Formula: Force search by molecular formula
  • SMILES: Force SMILES search (useful when auto-detection fails or for complex SMILES)
• Auto-Detection: When using auto-detect mode, the application automatically detects query type:
  • Pure numbers are treated as CIDs
  • Text with chemical patterns is treated as names
  • Strings with SMILES-specific characters are detected as SMILES
• Error Handling: Network issues and invalid queries show helpful error messages
• Display Mode: Loaded structures automatically use your current display mode preference
• Integration: Database-loaded structures work with all editing and analysis features

Troubleshooting Database Search

• Connection Issues: Check internet connectivity if searches fail
• Name Not Found: Try alternative names or systematic nomenclature
• SMILES Issues:
  • Auto-detected SMILES searches may return unexpected compounds due to database indexing
  • Solution: Click the search type selector on the right and choose "SMILES" for more predictable results
  • Multiple compounds may match the same SMILES pattern
  • Use chemical names or CID numbers for more predictable results
• Invalid SMILES: Verify SMILES syntax using online validators
• Slow Loading: Large molecules may take longer to load and render

The database search feature enhances jlmol's educational and research capabilities by providing instant access to PubChem's vast molecular database, making it ideal for:

• Educational Use: Quick access to textbook molecules
• Research Planning: Loading known compounds for analysis
• Structure Comparison: Loading reference structures
• Method Development: Testing with diverse molecular structures