Simpledit Documentation

Simpledit is a powerful molecular editor with a command-line interface, designed for efficient manipulation of molecular structures through an intuitive console.

Quick Start: Press C to open the console. Type help to see all available commands.

Design Principles

1. Verb-Noun Command Structure

All commands follow a consistent Verb-Noun pattern for clarity and predictability: 

add atom C 0 0 0      # Verb: add, Noun: atom
del bond 0 1         # Verb: del, Noun: bond
set dist 0 1 1.5    # Verb: set, Noun: dist

2. Explicit Subcommands

Operations require explicit targets to avoid ambiguity:

  • add atom / add bond / add mol
  • del atom / del bond / del mol
  • list atoms / list mols / list frags

3. Aliases for Efficiency

Common commands have short aliases:

Full Command Aliases
help h
list ls, l
add a
delete del, rm, remove
select sel
trans tr, translation
rotate rot
measure meas, info

4. Powerful Syntax Features

Range Selection

select 0:5         # Select atoms 0,1,2,3,4,5
select :           # Select all atoms
del atom 2:7       # Delete atoms 2-7

Flags and Options

paste --offset 5         # Long form
paste -o 5               # Short form
label --symbol -n        # Multiple flags
capture --no-background  # Boolean flag
capture -n               # Boolean flag

Heredoc Syntax

add mol xyz <<EOF
3
Water molecule
O  0.000  0.000  0.000
H  0.757  0.586  0.000
H -0.757  0.586  0.000
EOF

Line Continuation

add atom C 0 0 0 \
add atom H 1 0 0 \
add atom H 0 1 0

Inline Time Delays

rot 10 0 0 \time 0.2    # Rotate and wait 0.2s

5. Smart Defaults

The system intelligently assists you:

  • Auto-offset: paste and merge automatically shift atoms to avoid collisions
  • Bond detection: Bonds are auto-calculated based on threshold
  • Per-molecule state: Each molecule has independent history and settings

Getting Started

Opening the Console

  1. Press C key to toggle the console
  2. The console appears on the right side with green terminal theme
  3. Type commands and press Enter to execute

Your First Molecule

# Create a water molecule
add atom O 0 0 0
add atom H 0.757 0.586 0
add atom H -0.757 0.586 0

# View what you created
list

# Add bonds
add bond 0 1
add bond 0 2

Console Features

  • Command History: Use ↑ and ↓ arrows to navigate history
  • Multi-line Input: Use \ at end of line to continue
  • Comments: Lines starting with # are ignored
  • Clear Output: Type clear or cls

Visual Elements

Simpledit includes helpful visual aids:

  • Axis Helper: Bottom-right corner shows XYZ orientation (X=red, Y=green, Z=blue)
  • Atom Labels: Toggle with label command
  • Measurements: Visual feedback when measuring geometry

Core Commands

help h

Display available commands or detailed help for a specific command.

help           # List all commands
help add       # Show help for 'add' command
h rotate      # Using alias

list ls, l

List atoms, molecules, or fragments.

list           # List all atoms in active molecule
list -s        # List only selected atoms
list mols      # List all molecules
list frags     # List disconnected fragments
ls             # Alias for list

clear cls

Clear the console output.

clear
cls           # Alias

Atom Management

add atom

Add an atom at specified coordinates.

add atom C 0 0 0              # Carbon at origin
add atom H 1.2 0 0            # Hydrogen at (1.2, 0, 0)
a atom O 0 0 1.5              # Using alias

add mol

Import molecular data using heredoc syntax.

add mol xyz <<EOF
3
Methane
C  0.000  0.000  0.000
H  0.629  0.629  0.629
H -0.629 -0.629  0.629
EOF

select sel

Select atoms for operations.

select 0 1 2                 # Select specific atoms
select 0:5                   # Select range 0-5
select :                     # Select all atoms
sel 0 3 5                    # Using alias

del atom delete, rm, remove

Delete atoms by index.

del atom 0 1 5               # Delete specific atoms
del atom 0:5                 # Delete range
del atom :                   # Delete all atoms
rm atom 3                    # Using alias

Bonds

add bond

Create a bond between two atoms.

add bond 0 1                 # Bond between atoms 0 and 1
a bond 2 3                   # Using alias

del bond

Remove a bond between two atoms.

del bond 0 1                 # Remove bond
rm bond 2 3                  # Using alias

rebond rb

Recalculate all bonds based on current threshold.

set threshold 1.8            # Set bond detection distance
rebond                        # Recalculate bonds
rb                            # Using alias

Geometry

set dist distance

Set distance between two atoms.

set dist 0 1 1.5             # Set distance to 1.5 Å
set distance 0 1 1.5       # Using alias

set angle

Set angle between three atoms.

set angle 0 1 2 109.5       # Set angle to 109.5°

set dihedral

Set dihedral angle between four atoms.

set dihedral 0 1 2 3 180    # Set dihedral to 180°

measure meas, info

Measure distances, angles, or dihedrals.

measure 0 1                  # Measure distance
measure 0 1 2                # Measure angle
measure 0 1 2 3              # Measure dihedral
measure                       # Info on selected atoms
meas 0 1                     # Using alias

rotate rot

Rotate molecule around origin.

rotate 90 0 0                # Rotate 90° around X-axis
rotate 0 45 0                # Rotate 45° around Y-axis
rot 0 0 30                   # Rotate 30° around Z-axis

trans tr, translation

Translate (move) the molecule.

trans 5 0 0                  # Move 5 units on X-axis
trans 0 -2 0                 # Move -2 units on Y-axis
tr 1 1 1                     # Using alias

center cen

Move molecule's center of mass to origin (0,0,0).

center
cen                           # Using alias

set scale

Set visual scale for atoms or bonds.

set scale atom 1.5           # Increase atom size by 1.5x
set scale bond 0.8           # Decrease bond thickness to 0.8x
set scale atom 2.0           # Double atom size
The set scale command adjusts the visual rendering scale without changing actual atomic coordinates. Useful for improving visualization clarity.

substitute sub

Substitute atoms or molecular groups with intelligent fragment alignment.

# Atom substitution
sub atom 0 N                 # Change atom 0 to Nitrogen
sub atom 3 O                 # Change atom 3 to Oxygen

# Group substitution (Explicit mode)
sub grp 1 0 -n SourceMol 1 0  # Target: leaving=1, anchor=0
                                     # Source: leaving=1, anchor=0

# Group substitution (Implicit dummy mode)
sub grp 0 -n SourceMol 0      # Finds terminal 'X' atoms automatically
Group Substitution Syntax:
  • Explicit: sub grp <target_leaving> <target_anchor> -n <source_mol> <source_leaving> <source_anchor>
  • Implicit: sub grp <target_anchor> -n <source_mol> <source_anchor> (uses terminal 'X' dummy atoms)
The -n flag specifies the source molecule name (recommended). Alternatively, -i <index> can specify source molecule by 0-based index, but this is not recommended as indices may change. Fragments are aligned using vector matching for proper orientation.

debug_conn

Display detailed bond connectivity information for debugging.

debug_conn                     # Show all bonds and connectivity
Useful for diagnosing bonding issues, verifying molecular structure, or understanding fragment connectivity.

Molecule Management

new

Create a new empty molecule.

new                           # Create unnamed molecule
new "Benzene"                 # Create with name

switch sw

Switch between molecules.

switch 1                      # Switch by index
switch "Benzene"              # Switch by name
sw 2                          # Using alias

rename rn

Rename the active molecule.

rename "New Name"
rn "Molecule 1"              # Using alias

del mol

Delete a molecule.

del mol                       # Delete active molecule
del mol 2                    # Delete by index
del mol "Benzene"            # Delete by name

merge mg

Merge another molecule into the active one.

merge 1                       # Merge molecule 1
merge "Water"                 # Merge by name
mg 2                          # Using alias
Smart Offset: The merge command automatically applies spatial offset to prevent atom collisions.

Clipboard Operations

copy cp

Copy selected atoms to clipboard.

select 0:3
copy
cp                            # Using alias

paste pa

Paste atoms from clipboard.

paste                         # Paste with smart offset
paste --offset 5             # Explicit offset
paste -o 3                   # Short flag form
pa                            # Using alias

cut ct

Cut selected atoms to clipboard (copy + delete).

select 5:8
cut
ct                            # Using alias

Visualization

label lbl

Control atom labels display.

label -s                      # Show element symbols
label --symbol                # Long form
label -n                      # Show atom numbers
label --number                # Long form
label -a                      # Show both
label --all                   # Long form
label -o                      # Turn off labels
label --off                   # Long form
lbl -s                        # Using alias

camera cam

Set camera control mode.

camera orbit                 # Orbit controls (constrained)
camera trackball             # Trackball controls (free rotation)
cam orbit                    # Using alias

projection proj

Set camera projection type.

projection persp             # Perspective projection
projection ps                # Short form
projection ortho             # Orthographic projection
projection ot                # Short form
proj persp                    # Using alias

capture cap

Capture a snapshot of the viewport.

capture                       # Capture with background
capture --no-background      # Transparent background
capture -n                   # Short flag form
cap                           # Using alias

History Management

undo u

Undo the last destructive operation.

undo
u                             # Using alias

redo r, y

Redo the last undone operation.

redo
r                             # Using alias
y                             # Alternative alias
Per-Molecule History: Each molecule maintains its own independent undo/redo stack.

Utilities

time sleep

Pause execution for specified duration (useful in scripts and animations).

time 1                        # Wait 1 second
time 0.5                      # Wait 0.5 seconds
sleep 2                       # Using alias

# Inline usage for animations
rot 10 0 0 \time 0.2         # Rotate and wait

Test Suite

Simpledit includes 19 comprehensive test files covering all features. Each test can be copied and pasted directly into the console.

01_basic_commands.txt

Purpose: Introduction to console interface and basic navigation

Features Tested:

  • help - Command discovery
  • list - Viewing atoms
  • clear - Console management

02_atom_management.txt

Purpose: Fundamental atom manipulation operations

Features Tested:

  • add atom - Creating atoms
  • select - Selection (individual, range, all)
  • del atom - Deletion operations
  • info - Atom information

03_bond_operations.txt

Purpose: Bond creation and automatic connectivity

Features Tested:

  • add bond - Manual bond creation
  • del bond - Bond removal
  • rebond - Automatic bond detection
  • set threshold - Bond distance threshold

04_geometry_adjustments.txt

Purpose: Precise molecular geometry control

Features Tested:

  • set dist - Distance adjustment
  • set angle - Angle adjustment
  • set dihedral - Dihedral angle adjustment
  • measure - Geometry measurements
Tests the sophisticated fragment-based geometry engine that moves only necessary atoms.

05_heredoc_add.txt

Purpose: Import complete molecular structures

Features Tested:

  • Heredoc syntax (<<EOF)
  • XYZ format import
  • Multi-line input handling

06_batch_commands.txt

Purpose: Efficient command chaining

Features Tested:

  • Backslash (\) line continuation
  • Comment syntax (#)
  • Multi-line command execution

07_molecule_management.txt

Purpose: Multi-molecule workflows

Features Tested:

  • new - Creating molecules
  • switch - Switching between molecules
  • rename - Renaming molecules
  • del mol - Molecule deletion
  • Independent history per molecule

08_copy_paste_merge.txt

Purpose: Transfer and combine molecular structures

Features Tested:

  • copy / cut - Clipboard operations
  • paste - With smart offset
  • merge - Molecule combination
  • --offset flag - Manual offset control
Demonstrates the smart collision avoidance system for paste/merge operations.

09_display_labels.txt

Purpose: Visual customization

Features Tested:

  • label - Different label modes (symbol, number, all, off)
  • camera - Camera control modes
  • projection - Perspective vs orthographic

10_fragment_analysis.txt

Purpose: Connectivity analysis

Features Tested:

  • list frags - Fragment detection
  • unbond - Breaking connectivity
  • Fragment-based selection

    • 11_range_selection.txt

    Purpose: Efficient atom selection patterns

    Features Tested:

    • Range syntax (0:3)
    • All selection (:)
    • Mixed selection modes
    • Range deletion

    12_aliases.txt

    Purpose: Command aliases and shortcuts

    Features Tested:

    • tr for trans
    • Flag shortcuts (-o, -s, -n)
    • paste -o - Offset flag
    • label -o - Label flags
    • ps / ot - Projection shortcuts

    13_undo_redo.txt

    Purpose: History management and state recovery

    Features Tested:

    • undo - Reverting changes
    • redo - Reapplying changes
    • Visual verification with time delays
    • Per-molecule history independence

    14_transformations.txt

    Purpose: Molecular transformations and positioning

    Features Tested:

    • rotate - Incremental rotations (10° steps)
    • trans - Incremental translations (0.5 unit steps)
    • center - Center of mass repositioning
    • Inline \time for smooth animations
    • Combined transformations
    Uses small incremental steps with timing to create smooth visual animations of molecular movements.

    15_visual_scaling.txt

    Purpose: Molecular scaling and coordinate transformations

    Features Tested:

    • scale - Uniform coordinate scaling
    • Factor-based size adjustment
    • Incremental scaling with smooth animations
    • Combined with rotation for visual effects

    16_debug_connectivity.txt

    Purpose: Bond connectivity debugging and verification

    Features Tested:

    • debug_conn - Connectivity information display
    • Bond verification after manual operations
    • Fragment connectivity analysis
    • Troubleshooting bonding issues

    17_substitute_command.txt

    Purpose: Atom and group substitution

    Features Tested:

    • sub atom - Element substitution
    • sub grp (Mode A) - Explicit group substitution
    • sub grp (Mode B) - Implicit dummy atom mode
    • Vector alignment for fragment orientation
    • Bond preservation during substitution
    Demonstrates the advanced molecular fragment substitution engine with intelligent geometric alignment.

    18_substitute_benzene.txt

    Purpose: Complex group substitution with benzene, methane, and water

    Features Tested:

    • Benzene-Methane substitution
    • Benzene-Water substitution
    • Terminal dummy atom ('X') handling
    • Multi-molecule substitution workflows
    • Source molecule removal after substitution
    Comprehensive test for the substitute command using real organic molecules.

    19_geometry_comprehensive.txt

    Purpose: Comprehensive geometry adjustment testing

    Features Tested:

    • set dist - Bond length adjustments with fragment movement
    • set angle - Angle adjustments with proper pivot behavior
    • set dihedral - Dihedral rotation with rigid body mechanics
    • Real-time UI slider updates
    • Fragment-based geometry engine verification
    Tests the sophisticated fragment identification and rigid body rotation mechanics that ensure only intended atoms move during geometry adjustments.

    Running Tests

    1. Navigate to the tests/ directory
    2. Open any test file in a text editor
    3. Copy the entire content
    4. Paste into the Simpledit console
    5. Watch the automated execution with time delays

    Efficient Workflows

    Building Molecules

    Use heredoc for complex structures:

    add mol xyz <<EOF
6
Benzene
C  1.40  0.00  0.00
C  0.70  1.21  0.00
C -0.70  1.21  0.00
C -1.40  0.00  0.00
C -0.70 -1.21  0.00
C  0.70 -1.21  0.00
EOF
rebond                        # Auto-detect bonds

    Incremental Adjustments

    Use small steps with timing for visual feedback:

    rot 10 0 0 \time 0.1
rot 10 0 0 \time 0.1
rot 10 0 0 \time 0.1

    Working with Multiple Molecules

    new "Reactant"
# Build first molecule...

new "Product"
# Build second molecule...

sw 1                          # Switch back
list mols                     # View all molecules

    Clipboard Workflows

    select 0:5                    # Select fragment
copy                          # Copy to clipboard
sw 2                          # Switch molecule
paste -o 5                    # Paste with offset

    Troubleshooting

    Atoms Not Bonding

    Solution: Adjust the bond threshold and recalculate. 
    set threshold 1.8            # Increase threshold
rebond                        # Recalculate

    Molecule Off-Center

    Solution: Use the center command. 
    center                        # Move to origin

    Accidental Deletion

    Solution: Use undo to revert. 
    undo                          # Undo last action

    Paste Collision

    Solution: The system auto-applies offset, or specify manually. 
    paste -o 10                   # Larger offset

    Command Not Found

    Solution: Check subcommands and syntax. 
    help add                     # View command help
# Use explicit subcommands:
add atom C 0 0 0              # Not just 'add C 0 0 0'

    Additional Resources

    • Quick Reference: /docs/usage.md - Command syntax cheat sheet
    • Test README: tests/README.md - Test file descriptions
    • Source Code: src/commandRegistry.js - Full command implementations
    Pro Tip: Use help <command> extensively to learn command syntax and options.