Simpledit Documentation

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

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:

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
show 3d --no-background  # Boolean flag
show 3d -n               # Short 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 mol 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 atoms

# 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 atoms     # List all atoms in active molecule
list atoms -s  # List only selected atoms
list mols      # List all molecules
list frags     # List disconnected fragments
ls atoms        # 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 or crystal data using heredoc syntax. Supported formats: xyz, smi, sdf, mol, cif, poscar.

# XYZ molecule
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

# CIF crystal structure
add mol cif <<EOF
data_NaCl
_cell_length_a   5.6402
_cell_length_b   5.6402
_cell_length_c   5.6402
_cell_angle_alpha 90
_cell_angle_beta  90
_cell_angle_gamma 90
_symmetry_space_group_name_H-M 'F m -3 m'
loop_
 _atom_site_label
 _atom_site_type_symbol
 _atom_site_fract_x
 _atom_site_fract_y
 _atom_site_fract_z
Na Na 0.0 0.0 0.0
Cl Cl 0.5 0.0 0.0
EOF

# POSCAR / VASP structure
add mol poscar <<EOF
BCC Fe
1.0
2.87 0.00 0.00
0.00 2.87 0.00
0.00 0.00 2.87
Fe
2
Direct
0.0 0.0 0.0
0.5 0.5 0.5
EOF

select sel

Select atoms for operations. Supports index, range, fragment, element, layer, and wyckoff modes.

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

# Fragment selection
select frag 0                # Select all atoms in fragment 0

# Element selection (crystal-friendly)
select element Fe            # Select all Fe atoms
select element Na Cl         # Select Na and Cl atoms

# Layer selection (z-coordinate based, useful for slabs)
select layer 0               # Select bottom layer (layer 0)
select layer top             # Select topmost layer
select layer bottom          # Select bottommost layer
select layer 0:2             # Select layers 0, 1, 2

# Wyckoff-like group selection (crystal mode)
select wyckoff 0             # Select group ID 0
sel wyckoff all             # Select all source-site groups

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 a molecule or fragment in degrees.

rot mol 90 0 0               # Rotate molecule 90 deg around X-axis
rotate mol 0 45 0            # Rotate molecule 45 deg around Y-axis
rot frag 0 0 0 30            # Rotate fragment 0 around Z-axis

mv move

Move atom, fragment, or molecule by offset.

mv atom 2 0 0 1            # Move atom 2 by +1 on z
mv frag 0 1 0 0            # Move fragment 0 by +1 on x
mv mol 0 0 -2              # Move entire molecule
move mol 0.5 0 0           # Using alias

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

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

debug_conn

Display detailed bond connectivity information for debugging.

debug_conn                     # Show all bonds and 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

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

show

Unified visualization snapshots for 3D and 2D outputs.

# 3D snapshot
show 3d                      # Capture with background
show 3d --no-background      # Transparent background
show 3d -n                   # Short flag form

# 2D structure diagram
show 2d                      # SVG output
show 2d -l -h               # With labels and hydrogens
show 2d -s                  # Split fragments
show 2d -p                  # PNG output

view v

Unified atom-overlay toggles.

view magmom on               # Magnetic-moment colormap
view wyckoff on              # Source-site (Wyckoff-like) groups
view fixed on                # Highlight fixed atoms
v fixed off                 # Alias + explicit off
show fixed on                # Backward-compatible alias

Export & Save

read

Load a local file from disk (local mode only).

read structure.cif          # Read CIF file
read POSCAR                 # Read POSCAR/VASP file

run

Execute commands from a local script file (local mode only).

run tests/20_wyckoff_view.txt
run my_workflow.txt

save w

Save the current structure back to a local file (available in local mode only — i.e. when launched via the CLI). The format is inferred from the file extension. Ctrl+S (or ⌘S on macOS) is a keyboard shortcut for saving to the originally opened file.

save                          # Overwrite the file opened on startup
save output.cif               # Save as CIF (format from extension)
save POSCAR                   # Save as POSCAR (no extension → VASP format)
save relaxed.xyz              # Save as XYZ
w                             # Using alias (vi-style)

export exp

Export the active structure to various formats. Prints the result to the console.

export xyz                   # Export as XYZ
export smi                   # Export as SMILES
export sdf                   # Export as SDF / Molfile
export cif                   # Export crystal as CIF
export poscar                # Export crystal as POSCAR (VASP)
exp xyz -s                   # Export with split fragments

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

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 mol 10 0 0 \time 0.2     # Rotate and wait

addh add_hydrogens

Add explicit hydrogen atoms based on valence rules.

addh
add_hydrogens                # Using alias

optimize opt, minimize

Optimize geometry using the built-in force-field workflow.

optimize                      # Default method (ff)
optimize ff                   # Explicit method
opt                           # Using alias

Test Suite

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

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 mol 10 0 0 \time 0.1
rot mol 10 0 0 \time 0.1
rot mol 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

set threshold 1.8            # Increase threshold
rebond                        # Recalculate

Molecule Off-Center

center                        # Move to origin

Accidental Deletion

undo                          # Undo last action

Paste Collision

paste -o 10                   # Larger offset

Command Not Found

help add                     # View command help
# Use explicit subcommands:
add atom C 0 0 0              # Not just 'add C 0 0 0'

Crystal / Solid-State Structures

Simpledit Material extends the molecular editor with full periodic boundary condition (PBC) support for crystal and solid-state structures. Load a .cif or POSCAR file to activate crystal mode.

Supported File Formats

Quick Start

# 1. Load a crystal
add mol cif <<EOF
... paste CIF content ...
EOF

# 2. Check the unit cell
cell

# 3. Visualize
unitcell on
ghost on

# 4. Build a supercell
supercell 2 2 2

# 5. Generate a surface
slab 0 0 1 4 10

# 6. Inspect source-site groups for VASP MAGMOM setup
wyckoff list
view wyckoff on

Unit Cell

cell

Show or set unit cell lattice parameters.

cell                          # Show current cell (a, b, c, α, β, γ, volume, space group)
cell 5.64 5.64 5.64 90 90 90  # Set cubic cell (NaCl)
cell 2.87 2.87 2.87 90 90 90  # Set BCC Fe unit cell

unitcell uc

Toggle the unit cell wireframe overlay.

unitcell                      # Toggle
unitcell on                   # Show wireframe
unitcell off                  # Hide wireframe
uc on                         # Using alias

ghost

Toggle periodic image (ghost) atoms that show atoms from neighboring cells at the cell boundary.

ghost                         # Toggle
ghost on                      # Show ghost atoms
ghost off                     # Hide ghost atoms

axes lattice-axes

Toggle lattice vector arrows (a, b, c) on the unit cell.

axes                          # Toggle
axes on                       # Show axes
axes off                      # Hide axes
lattice-axes on               # Using alias

bonds

Toggle bond rendering visibility in the viewport.

bonds                         # Toggle
bonds on                      # Show bonds
bonds off                     # Hide bonds

wrap

Wrap all atoms back into the unit cell [0, 1) in fractional coordinates. Always computed from current Cartesian positions so atoms moved via drag or translate are handled correctly.

wrap                          # Wrap atoms into unit cell

unwrap

Reconnect molecules that are split across periodic boundaries. Uses the same bond-length criteria as autobond to detect cross-boundary bonds, then assigns continuous fractional coordinates to each connected fragment so the molecule is no longer broken across the cell.

unwrap                        # Default threshold (1.1× covalent radii)
unwrap 1.2                    # Custom threshold

fitcell fc

Fit an orthorhombic unit cell (α = β = γ = 90°) around the current molecule. Computes the atomic bounding box, adds vacuum padding on all sides, and centres the molecule in the new cell. Works on both plain molecules and existing crystal structures — useful for preparing DFT input files.

fitcell                       # Default vacuum: 5 Å on each side
fitcell 8                     # 8 Å vacuum
fc 10                         # Using alias

uncell

Remove the unit cell from the active crystal and convert it back to a plain molecule. Atom Cartesian positions and bonds are preserved; the lattice, fractional coordinates, and space-group information are discarded.

uncell                        # Strip cell → plain molecule

reorder

Reorder atoms by ascending atomic number, grouping all atoms of the same element together. Within each element the original relative order is preserved. Especially useful before exporting POSCAR, which conventionally lists atoms grouped by element (e.g. H C N O Pt).

reorder                       # Sort by atomic number → H C N O … Pt …

autobond ab

Recalculate bonds with periodic boundary condition awareness.

autobond                      # PBC-aware auto-bond (default threshold 1.1×sum of covalent radii)
autobond 1.2                  # Custom scale factor
ab                            # Using alias

Supercell Generation

supercell sc

Generate a supercell from the current crystal. Supports both diagonal repetition and full 3×3 transformation matrices.

Diagonal (simple repetition)

supercell 2 2 2              # 2×2×2 supercell
supercell 3 3 1              # 3×3×1 (slab-like)
sc 2 2 2                     # Using alias

3×3 Transformation Matrix (row-major)

# supercell s11 s12 s13  s21 s22 s23  s31 s32 s33
supercell 2 0 0  0 2 0  0 0 2   # Same as supercell 2 2 2
supercell 1 1 0  -1 1 0  0 0 1  # Rotated 45° supercell

Surface Slab Generation

orient

Reorient a crystal so the specified (hkl) normal aligns with the z-axis.

orient 1 1 1                 # Align (111) normal with z
orient 1 1 0                 # Align (110) normal with z

slab

Generate a surface slab model from a bulk crystal by specifying Miller indices.

# slab <h> <k> <l> [layers=4] [vacuum=10] [-no-center]
slab 0 0 1                    # (001) surface, 4 layers, 10 Å vacuum (defaults)
slab 1 1 0 6 15               # (110) surface, 6 layers, 15 Å vacuum
slab 1 1 1 4 10 -no-center    # (111) without centering

surfaces facets

Analyze and optionally label unit-cell faces with Miller-index context.

surfaces                      # Print d-spacing / area table, turn labels on
surfaces off                  # Hide face labels
facets on                    # Alias

Typical Slab Workflow

# 1. Load bulk crystal
add mol cif <<EOF
... CIF data ...
EOF

# 2. Optional: align target plane before slab cut
orient 0 0 1

# 3. Generate (001) slab, 6 layers, 12 Å vacuum
slab 0 0 1 6 12

# 4. Inspect face metrics / labels
surfaces

# 5. Select and inspect surface atoms
select layer top
list atoms -s

# 6. Delete selected surface layer
del atom :

# 7. Export as POSCAR for DFT
export poscar

Coordination Polyhedra

poly polyhedra

Toggle coordination polyhedra rendering. Polyhedra are drawn around atoms with coordination number ≥ 3.

poly                          # Toggle (all atoms with CN≥3)
poly on                       # Show all polyhedra
poly off                      # Hide polyhedra
poly on Ti                    # Show polyhedra only around Ti atoms
poly on Si Al                 # Show polyhedra around Si and Al
polyhedra on Fe               # Using full alias

Crystal Utilities

Element & Layer Selection

# Select by element (useful for multi-component crystals)
select element O              # All oxygen atoms
select element Ti O           # Titanium and oxygen

# Select by z-layer (useful after slab generation)
select layer top              # Topmost atomic layer
select layer bottom           # Bottommost atomic layer
select layer 0               # Layer index 0 (bottom)
select layer 0:3             # Layers 0–3

# Select by source-site group
select wyckoff 0             # One group
select wyckoff all           # All groups

wyckoff wyk + view

Use grouped source sites to assign antiferromagnetic sublattices and inspect constraints quickly.

wyckoff list                  # Print grouped site table
wyckoff view on               # Same as: view wyckoff on
view wyckoff off             # Unified explicit toggle
view magmom on               # Switch to magmom overlay
view fixed on                # Highlight constrained atoms

magmom (VASP MAGMOM)

Assign magnetic moments and generate INCAR-compatible MAGMOM strings.

sel wyckoff 0
magmom set sel 2.0
sel wyckoff 1
magmom set sel -2.0
magmom list
magmom gen
magmom view on               # Alias of view magmom on

fix freeze, constrain

Manage selective-dynamics constraints (T/F flags) for slab relaxations.

select layer bottom
fix set sel                 # Fix all axes (F F F)
fix set sel z               # Fix only z axis
fix free sel z              # Free z axis
fix list
view fixed on
view fixed off

Atomic Coordinate Editor

The Atomic Coordinate Editor (accessible from the toolbar) supports XYZ, SMILES, SDF, CIF, POSCAR, and JSON formats. Select the format from the dropdown, then copy out or paste in coordinates directly in the browser — no file system access required.

Complete Crystal Workflow Example

# Load NaCl from CIF
add mol cif <<EOF
data_NaCl
_cell_length_a   5.6402
_cell_length_b   5.6402
_cell_length_c   5.6402
_cell_angle_alpha 90
_cell_angle_beta  90
_cell_angle_gamma 90
_symmetry_space_group_name_H-M 'F m -3 m'
loop_
 _atom_site_label
 _atom_site_type_symbol
 _atom_site_fract_x
 _atom_site_fract_y
 _atom_site_fract_z
Na Na 0.0 0.0 0.0
Cl Cl 0.5 0.0 0.0
EOF

# Inspect cell
cell

# Show unit cell and neighbors
uc on
ghost on

# Make a 2×2×2 supercell
sc 2 2 2

# Generate (001) surface slab
slab 0 0 1 4 10

# Select and remove top Na layer
select layer top
del atom :

# Group atoms by element (VASP convention: Na … Cl …)
reorder

# Assign sublattice MAGMOM from Wyckoff-like groups
wyckoff list
sel wyckoff 0
magmom set sel 2.0
sel wyckoff 1
magmom set sel -2.0
magmom gen

# Fix bottom layer for slab relaxation
select layer bottom
fix set sel
view fixed on

# Export for DFT calculation
export poscar

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