Skip to content

NEXT_STEPS.md

Latest commit

 

History

History
334 lines (246 loc) · 8.46 KB

NEXT_STEPS.md

File metadata and controls

334 lines (246 loc) · 8.46 KB

QUARKS - Next Steps After Reorganization

✅ Completed

The QUARKS codebase has been successfully reorganized into a professional Python package:

  • ✅ Created unified quarks/ package structure
  • ✅ Consolidated 13 duplicate core modules
  • ✅ Eliminated code duplication (100% identical files merged)
  • ✅ Organized into logical sub-packages (core, gui, conformer, orca_manager, input_generator, extractor)
  • ✅ Created professional packaging files (setup.py, pyproject.toml, requirements.txt)
  • ✅ Archived 12 debug files
  • ✅ Created comprehensive documentation (README.md, LICENSE, CITATION.cff)
  • ✅ Updated imports from src.core.* to quarks.core.*
  • ✅ Created CLI interfaces for all modules
  • ✅ Basic package import testing successful

🔄 Immediate Next Steps (Required)

1. Install Dependencies

cd /Users/thomasquaid/Projects/QUARKS

# Option A: Install all dependencies
pip install numpy scipy pandas matplotlib PySide6 psutil pyyaml cclib

# Option B: Use requirements.txt (once dependencies are installed in venv)
pip install -r requirements.txt

# Option C: Install package in development mode (installs dependencies automatically)
pip install -e .

Note: Some imports currently fail because numpy, PySide6, and psutil aren't installed in the current environment.

2. Full Import Testing

After installing dependencies, test all imports:

# Test package
python -c "import quarks; print(f'QUARKS v{quarks.__version__}')"

# Test core modules
python -c "from quarks.core import load_molecule_from_file, MoleculeFunctionalizer"

# Test GUI components
python -c "from quarks.gui import InteractiveMoleculeViewer"

# Test conformer
python -c "from quarks.conformer import StructureRefinement"

# Test ORCA manager
python -c "from quarks.orca_manager import OrcaQueue"

# Test input generator
python -c "from quarks.input_generator import OrcaInputGenerator"

3. Functional Testing

Test each module's functionality:

A. Conformer Module:

# Test GUI (requires PySide6, XTB, CREST)
python -m quarks.conformer.gui

# Test CLI
python -m quarks.conformer.cli --help

B. ORCA Manager:

# Test GUI
python -m quarks.orca_manager.gui

# Or use entry point (after pip install -e .)
quarks-orca

C. Input Generator:

# Test GUI
python -m quarks.input_generator

# Test CLI
python -m quarks.input_generator.cli --help

D. Extractor:

# Test CLI
python -m quarks.extractor.cli --help

4. Run Example Workflow

Test the complete pipeline with actual data:

# 1. Prepare a test XYZ file
cp data/examples/water.xyz test_molecule.xyz

# 2. Run conformer search (if XTB/CREST installed)
python -m quarks.conformer.cli --input test_data/ --output conformers/ --charge 0

# 3. Generate ORCA inputs
python -m quarks.input_generator.cli --input conformers/ --output orca_inputs/ --functional PBE0

# 4. Extract data (after ORCA calculations)
python -m quarks.extractor.cli energy --input orca_outputs/

📋 Recommended Next Steps

5. Clean Up Old Directories (After Testing)

Once you've verified the new package works correctly:

# Backup first!
mkdir -p archive/old_structure/
mv Conformer_Engine archive/old_structure/
mv Orca_Prime archive/old_structure/
mv input_file_generator archive/old_structure/
mv Extractor archive/old_structure/

# Or just remove the duplicate ligand_screening_tool folders:
rm -rf Conformer_Engine/ligand_screening_tool
rm -rf Orca_Prime/ligand_screening_tool

⚠️ Important: Keep the top-level directories for now until you're 100% confident the new package works.

6. Update External References

If you have scripts or notebooks that use the old structure:

Old:

import sys
sys.path.append('/path/to/Conformer_Engine/ligand_screening_tool')
from src.core.molecule_factory import load_molecule_from_file

New:

from quarks.core import load_molecule_from_file

7. Create Example Workflows

Add example scripts to docs/examples/:

docs/examples/
├── basic_conformer_search.py
├── batch_input_generation.py
├── complete_pipeline.py
└── descriptor_extraction.py

8. Write Unit Tests

Create tests for core functionality:

tests/
├── test_core/
│   ├── test_molecule.py
│   ├── test_molecule_factory.py
│   └── test_functionalizer.py
├── test_conformer/
│   └── test_structure_refinement.py
├── test_input_generator/
│   └── test_generator.py
└── test_extractor/
    └── test_energy_extraction.py

9. Fill In JACS Methods Template

Edit docs/jacs_methods_template.md with your specific details:

  • Replace [X] with actual values
  • Add specific functional groups tested
  • Specify exact software versions
  • Add computational resources used

10. Version Control

# Stage all new files
git add quarks/
git add setup.py pyproject.toml requirements.txt
git add README.md LICENSE CITATION.cff
git add docs/ tests/

# Commit reorganization
git commit -m "Major reorganization: Create unified QUARKS package

- Consolidated duplicate ligand_screening_tool code
- Created quarks/ package with sub-modules
- Added professional packaging (setup.py, pyproject.toml)
- Created comprehensive documentation
- Updated all imports to use quarks.* namespace
- Added CLI interfaces for all tools
- Archived debug files

See REORGANIZATION_SUMMARY.md for details."

🐛 Troubleshooting

Issue: Import Errors

Symptom: ModuleNotFoundError: No module named 'quarks'

Solution:

# Install in development mode from package root
cd /Users/thomasquaid/Projects/QUARKS
pip install -e .

Issue: Dependency Errors

Symptom: ModuleNotFoundError: No module named 'numpy' (or other dependencies)

Solution:

pip install -r requirements.txt

Issue: GUI Doesn't Launch

Symptom: PySide6 import errors or Qt plugin errors

Solution:

pip install PySide6
# If Qt plugin errors, set environment variable:
export QT_QPA_PLATFORM_PLUGIN_PATH=$(python -c "import PySide6; print(PySide6.__path__[0])")/Qt/plugins

Issue: Old Code Still Running

Symptom: Changes don't appear when running Python scripts

Solution:

# Clear Python cache
find . -type d -name __pycache__ -exec rm -rf {} +
find . -name "*.pyc" -delete

# Reinstall package
pip install -e . --force-reinstall --no-deps

📊 Current Status

Package Structure: ✅ Complete

  • quarks/core/ (13 modules)
  • quarks/gui/ (2 modules)
  • quarks/conformer/ (3 modules + entry point)
  • quarks/orca_manager/ (7 sub-packages)
  • quarks/input_generator/ (10+ modules)
  • quarks/extractor/ (4 modules)

Packaging: ✅ Complete

  • setup.py ✓
  • pyproject.toml ✓
  • requirements.txt ✓
  • MANIFEST.in ✓
  • Entry points defined ✓

Documentation: ✅ Complete

  • README.md ✓
  • LICENSE (MIT) ✓
  • CITATION.cff ✓
  • JACS methods template ✓
  • Reorganization summary ✓

Testing: ⚠️ Partial

  • Package imports ✓
  • Module imports ⚠️ (requires dependencies)
  • Functional testing ❌ (next step)

Code Cleanup: ⚠️ Partial

  • Debug files archived ✓
  • Duplicate code consolidated ✓
  • Old directories ⚠️ (kept for reference)

🎯 Success Criteria

Before considering the reorganization complete:

  • All dependencies installed
  • All module imports work without errors
  • Conformer GUI launches successfully
  • ORCA manager GUI launches successfully
  • Input generator GUI launches successfully
  • CLI tools work and accept arguments
  • At least one complete pipeline run succeeds
  • Old code directories removed or archived

📞 Support

If you encounter issues:

  1. Check REORGANIZATION_SUMMARY.md for detailed changes
  2. Review import statements (old src.core.* → new quarks.core.*)
  3. Ensure dependencies are installed (pip install -r requirements.txt)
  4. Verify you're using the correct Python environment

🎓 Learning Resources

For understanding the new structure:

  • Read README.md for overview
  • Check quarks/__init__.py for package exports
  • Review setup.py for entry points
  • See docs/jacs_methods_template.md for scientific context

For using the package:

  • CLI help: quarks-conformer --help, quarks-input-gen --help, etc.
  • Python API: python -c "from quarks.core import X; help(X)"
  • Examples: docs/examples/ (to be created)

Status: Reorganization complete, ready for testing and deployment.

Next Action: Install dependencies and run functional tests.