ruby_siesta

Ruby wrapper for Siesta DFT calculations, with a REST API.

Quick Start

# Start the server
cd /path/to/ruby_siesta
export SIESTA_PP_PATH=/path/to/siesta_pseudo
ruby bin/siesta-api

Then call it from anywhere:

# Check status
curl http://localhost:4567/api/v1/status

# Pass a structure file via curl + jq
curl -X POST http://localhost:4567/api/v1/calculate \
  -H 'Content-Type: application/json' \
  -d "$(jq -n --arg s "$(cat input.STRUCT_OUT)" \
    '{structure: $s, format: "STRUCT_OUT", label: "silicon", xc: "PBE", kpoints: [9,9,9]}')"

Or use the included example script:

ruby examples/api_client.rb input.STRUCT_OUT

Endpoints

Method	Path	Description
GET	/api/v1/status	Siesta version, MPI, environment
POST	/api/v1/calculate	Run a full calculation → energy (eV)
POST	/api/v1/input	Dry-run: generate FDF without running
POST	/api/v1/structure	Parse structure file → coordinates + cell

Parameters

Only structure (file content string) is required. Everything else is optional:

Parameter	Example	Notes
format	"STRUCT_OUT", "vasp", "xyz"	Auto-detected from filename
label	"my_run"	Default: siesta_api
xc	"PBE", "PW92", "LDA", "BLYP"	Default: PBE
kpoints	[9, 9, 9]	Monkhorst-Pack mesh
spin	{"polarized": true}	Also: soc, non_colinear, fix
hubbard_u	{"atom": "Fe", "orbital": "3d", "value": 4.0}	DFT+U
parameters	{"meshcutoff": "400 Ry", "basis": "TZP"}	Override any FDF parameter
vdw	true	DFT-D2 correction
electric_field	{"x": 0.5}	V/Ang

Library Usage

require 'siesta'

siesta = Siesta.import_from_file('input.STRUCT_OUT')
siesta.label('silicon')
siesta.xc('PBE')
siesta.kpoint(kmesh: [9, 9, 9])
energy = siesta.energy

Requirements

Ruby >= 2.6.8, Siesta >= 4.1.5, SIESTA_PP_PATH pointing to pseudopotentials.