scine-add-calculator

name	scine-add-calculator
description	Add a new quantum chemistry (QM) software or tool as a SCINE calculator. Use when implementing a new external QM code (e.g., ORCA, Turbomole, Gaussian, CP2K, MRCC, or any custom QM tool) as a calculator in SCINE Utils (C++) and/or Puffin (Python). Covers the full workflow: C++ class hierarchy, settings, file I/O parsers, output parsers, module registration, CMake, Python bindings, Puffin program class, Puffin job class, and config registration.
argument-hint	Name of the QM software to add as a calculator (e.g., MyProgram)

Add New QM Software as a SCINE Calculator

When to Use

• Implementing a new external QM code as a Core::Calculator in scine_utilities (C++)
• Adding a corresponding Puffin program and job class in scine_puffin (Python)
• Either phase independently (utils only or puffin only)

Overview

Adding a new calculator has two sequential phases:

Phase	Repo	Language	Guide
1. Utils	scine_utilities	C++	utils-guide.md
2. Puffin	scine_puffin	Python	puffin-guide.md

Dependency: Puffin requires a working Utils calculator. Complete Phase 1 before Phase 2.

---

Phase 1: Utils — C++ Calculator

Full reference: utils-guide.md

Development Order

1. Start with energy only → add gradients → add Hessian → additional properties
2. Test each component individually before integrating
3. Validate with unit tests after each incremental step

Files to Create

All new files go in src/Utils/Utils/ExternalQC/<NewSoftware>/:

File	Class	Purpose
NewSoftwareCalculator.h/.cpp	NewSoftwareCalculator	Main calculator (inherits CloneInterface<..., Calculator>)
NewSoftwareCalculatorSettings.h/.cpp	NewSoftwareCalculatorSettings	Settings (inherits Settings)
NewSoftwareFiles.h/.cpp	NewSoftwareFiles	File path bookkeeping struct
NewSoftwareInputFileCreator.h/.cpp	NewSoftwareInputFileCreator	Writes QM input files
NewSoftwareMainOutputParser.h/.cpp	NewSoftwareMainOutputParser	Parses QM output files
NewSoftwareHelper.h/.cpp	NewSoftwareHelper	Runs external binary via ExternalProgram

Module registration (one new file + one edit):

File	Action
src/Utils/Module/NewSoftwareModule.h/.cpp	Create (inherits Core::Module)
src/Utils/Module/ModuleFactory.cpp	Add include + add NewSoftwareModule::make() to return vector

Quick Checklist — Utils

• NewSoftwareCalculator — implements all Calculator virtual methods
• NewSoftwareCalculatorSettings — defines all settings descriptors
• NewSoftwareFiles — defines input/output/coordinate/gradient file paths
• NewSoftwareInputFileCreator — writes method, basis, coords, and job-type sections
• NewSoftwareMainOutputParser — parses energy, gradients, Hessian, bond orders
• NewSoftwareHelper — wraps ExternalProgram::execute() and success checks
• NewSoftwareModule — registers Calculator interface + NEW_SOFTWARE model
• ModuleFactory.cpp updated — include added, ::make() call added
• CMake re-run — files are auto-collected via GLOB_RECURSE, no manual edits needed
• Unit tests added in src/Utils/Tests/
• (Optional) Python bindings in src/Utils/Python/

Key Conventions — Utils

• static constexpr const char* model = "NEW_SOFTWARE"; — defines the model name string
• Use Core::UnsuccessfulCalculationException for failed calculations
• Exception types live in Core:: namespace
• Template argument deduction (CTAD): prefer std::vector v{"a", "b"}; over explicit type

---

Phase 2: Puffin — Python Job

Full reference: puffin-guide.md

Files to Create/Modify

File	Action	Purpose
scine_puffin/programs/my_program.py	Create	MyProgram(Program) — env setup + binary search
scine_puffin/config.py	Edit	Add "my_program" entry to self._data["programs"]
scine_puffin/jobs/my_program_single_point.py	Create	MyProgramSinglePoint(Job) — run calculation

Quick Checklist — Puffin

• my_program.py — install(), check_install(), setup_environment(), available_models(), initialize()
• initialize() calls Program.search_program() with correct program_key, environment_variable, expected_binaries, path_transform
• config.py — entry with available, source, root, version keys
• my_program_single_point.py — write_input_file(), parse_output_file(), execute_program(), run(), required_programs()
• required_programs() returns ["database", "utils", "my_program"]
• subprocess.run(...) does NOT use check=True — calculation_context handles failure
• Properties stored via self.store_property(...) before setting db.Status.COMPLETE
• Enable via env vars for testing

Key Conventions — Puffin

• Program key = filename without .py (snake_case): my_program
• Class name = CamelCase of key: MyProgram
• Job order name = job filename without .py: my_program_single_point
• setup_environment() = bootstrap only; initialize() = every Puffin startup
• calculation_context(self) writes success/failed sentinel files

---

Quality Gates

Before marking an implementation complete:

Utils:

• All unit tests pass: ctest -R NewSoftware (or similar)
• Module loads: Core::ModuleManager can instantiate NewSoftwareCalculator
• Energy calculation returns a valid result for a small molecule

Puffin:

• Job is importable: from scine_puffin.jobs.my_program_single_point import MyProgramSinglePoint
• required_programs() returns the correct list
• A sample single-point calculation submits and completes in the database