List all RASPA2 simulation types with descriptions and typical use cases. Call this first to decide which simulation type fits the user's goal.

Return the canonical simulation.input template for the given simulation type. The template contains ${PLACEHOLDER} markers — replace them with actual values before writing the file.

Also returns parameter documentation explaining each placeholder.

List all built-in force fields with their molecule targets, references, and applicability notes. Use this to decide which force field to use.

Return the complete content of pseudo_atoms.def and force_field_mixing_rules.def for the given force field.

These files must be placed in the simulation working directory alongside simulation.input.

Args: forcefield_name: e.g. "TraPPE-CO2", "TraPPE-N2", "TraPPE-CH4"

Given a molecule name (common name, formula, or IUPAC), recommend the most appropriate built-in force field and provide literature guidance.

For molecules NOT in the built-in library, returns structured guidance on how to find parameters from literature using Semantic Scholar.

Args: molecule: e.g. "CO2", "methane", "PH3", "SO2", "water"

List all built-in molecule definitions with metadata. Molecules not listed here require manual .def file construction.

Return the content of the RASPA2 molecule definition file (.def) for a built-in molecule.

The file must be placed at: /molecules/TraPPE/.def

Args: molecule_name: e.g. "CO2", "N2", "CH4", "H2O", "helium"

Create a properly structured RASPA2 simulation workspace directory.

RASPA2 expects a specific directory layout. This tool creates it and copies the CIF file into the right location.

Structure created: / simulation.input ← Claude writes this force_field_mixing_rules.def ← Claude writes this pseudo_atoms.def ← Claude writes this frameworks/ / .cif molecules/ TraPPE/ ← Claude writes .def files here

Args: work_dir: Absolute path for the new simulation directory. framework_name: Name matching the CIF file (without .cif extension). cif_source_path: Absolute path to the existing CIF file.

Security: work_dir must resolve to a path inside the allowed workspace base, controlled by the RASPA_MCP_WORKSPACE_BASE environment variable (default: ~/raspa_workspaces). This prevents an LLM from creating directories or copying files at arbitrary filesystem locations (e.g. /etc, /root) when this MCP runs as a privileged user.

Validate the content of a RASPA2 simulation.input file BEFORE running.

Returns errors (blocking — must fix) and warnings (advisory). Always call this after generating simulation.input and before running simulate.

Args: content: Full text content of the simulation.input file.

Parse RASPA2 output files and return structured results as JSON.

Extracts: loading (mol/kg, mg/g, cm³STP/g), Henry coefficients, void fraction, energies (including Qst and mu_ex), and builds an isotherm table if multiple pressure points are detected.

Args: output_dir: Path to the Output directory produced by RASPA2, typically '/Output/System_0/'.

Parse RASPA2 radial distribution function (RDF) output files (3-3).

RASPA2 writes RDF data to RDF__.dat files when 'ComputeRDF yes' is set in simulation.input (requires NVT-MC or NVT-MD simulation).

Returns r(Å) and g(r) arrays per pair, plus first-peak position — useful for identifying preferred adsorption sites and coordination shells.

component_a / component_b: optional name filters (e.g. "CO2", "framework"). Leave empty to return all RDF datasets in the output directory.

Args: output_dir: Path to RASPA2 Output directory. component_a: Optional filter: only return pairs containing this name. component_b: Optional filter: only return pairs containing this name.

Calculate adsorption selectivity S_AB from mixture GCMC results (4-4).

Uses the adsorption selectivity definition: S_AB = (x_A / x_B) / (y_A / y_B) where x = adsorbed-phase mole fraction, y = gas-phase (feed) mole fraction.

Inputs come from parse_raspa_output()["components"] for a GCMCMixture simulation.

loading_a / loading_b: average loading of each component in mol/kg (or any consistent units — they cancel in the ratio). feed_fraction_a / feed_fraction_b: mole fractions in the feed gas (must sum to 1.0 for a binary; for partial fractions in a larger mixture, pass the relevant pair).

Returns S_AB > 1 means the material prefers A over B. S_AB < 1 means preference for B. S_AB = 1 means no selectivity.

Parse RASPA2 MSD files and compute self- or collective-diffusion coefficients (2-1/3-1/3-2).

Requires a completed NVT-MD or NPT-MD simulation with 'ComputeMSD yes' set. RASPA2 writes MSDSelf_.dat (self-diffusion) and MSDCollective_.dat.

The Einstein relation D = MSD(t) / 6t is fitted to the linear regime (latter 50% of trajectory). Result is given in A²/ps and m²/s.

Typical self-diffusivities in MOFs:

• Fast gas (H2, He): 10⁻⁸ – 10⁻⁷ m²/s

• CO2, CH4 in wide pores: 10⁻⁹ – 10⁻⁸ m²/s

• Slow diffusers (large MOF pores, tight channels): < 10⁻¹¹ m²/s

Args: output_dir: Path to RASPA2 Output directory. molecule: Optional filter by molecule name (e.g. "CO2"). diffusion_type: "self" (MSDSelf) or "collective" (MSDCollective).

Parse RASPA2 Thermodynamic Integration (TI) output and compute ΔA (1-8).

Expects one completed RASPA2 simulation per lambda value (0.0 → 1.0), each in its own subdirectory. The subdirectory name should contain the lambda value (e.g. 'lambda_0.3/', '0.3/', etc.).

RASPA2 must be run with Lambda and LambdaDefinition set in simulation.input. Each output file must contain a line matching: Average <dU/dlambda>: X.XXXXX +/- Y.YYYYY [K]

KNOWN LIMITATION: The exact format of this line varies between RASPA2 versions and build options. If status='no_ti_data' is returned, check:

1. That the simulation used Lambda / LambdaDefinition keywords.

2. That the RASPA2 version writes 'Average <dU/dlambda>'.

3. That subdirectory names contain the numeric lambda value. In that case, extract dU/dlambda values manually from the output files and call numpy.trapezoid() directly.

The function integrates ⟨∂U/∂λ⟩ over λ using the trapezoidal rule: ΔA = ∫₀¹ ⟨∂U/∂λ⟩ dλ [K] → ×R → [kJ/mol]

Fewer lambda points = less accuracy:

• 3 points (0, 0.5, 1): rough estimate

• 5 points: adequate for most cases

• 11 points (0.0, 0.1, ..., 1.0): high accuracy

Args: output_dir: Root directory containing per-lambda subdirectories.

Parse RASPA2 3D density grid files and extract a 2D slice (3-4).

RASPA2 writes .grid files when the simulation.input contains: WriteDensityProfile3DVTKGrid yes DensityAveragingTypeVTK number_of_molecules

The 3D grid is stored as Nx×Ny×Nz float values (row-major). This function returns the full grid metadata and ONE 2D slice. Pass the returned 'slice_data' field to plot_density_slice() to save a PNG.

KNOWN LIMITATION: This tool returns a 2D cross-section only, NOT a full 3D isosurface or volumetric render. For true 3D visualization (isosurfaces, volume rendering), export the raw 'slice_data' and use external tools such as VESTA, py3Dmol, or ParaView with the original .grid/.vtk file. To explore different planes, call this tool multiple times with different slice_axis ('x','y','z') and slice_index values.

KNOWN LIMITATION: The .grid ASCII format written by RASPA2 has minor variations across versions (header line count differs). If parsing fails (status='no_grid_files' or 'warning' in dataset), verify that WriteDensityProfile3DVTKGrid is set and check the raw file header.

Args: output_dir: Path to RASPA2 Output (or parent) directory. molecule: Optional filter on molecule name (e.g. "CO2"). slice_axis: Axis perpendicular to the slice: 'x'/'a', 'y'/'b', 'z'/'c'. slice_index: Grid-plane index along slice_axis; -1 = midpoint.

Render a 2D density slice from parse_density_grid() as a heatmap PNG (3-4).

slice_data is the 'slice_data' field from parse_density_grid() — a 2D list of float density values.

cell_lengths: optional [La, Lb] in Å for axis tick labels. axes_labels: optional [x_label, y_label], defaults to ["a (Å)", "b (Å)"]. colormap: matplotlib colormap name; 'hot', 'viridis', 'Blues' all work well.

Return documentation for RASPA2 simulation.input parameters.

Args: parameter_name: Specific parameter name (e.g. "CutOff", "EwaldPrecision"), or None to get all parameters.

Check whether RASPA2 is correctly installed and configured on this server.

Verifies:

1. 'simulate' binary is on PATH

2. RASPA_DIR environment variable is set and valid

3. Force field and molecule files exist under $RASPA_DIR

Returns a full diagnostic report. If ready=False, run: raspa-mcp-setup (compiles RASPA2 from source).

Generate a single-MOF adsorption isotherm plot (PNG).

isotherm_data is a list of dicts, each with at least:

• a pressure field ("pressure_Pa", "pressure_bar", or "pressure_kPa")

• a loading field (default key: "loading_mol_kg")

Typical source: the "isotherm" list returned by parse_raspa_output() when multiple pressure-point simulations are run and their outputs placed in sub-directories named by pressure value.

pressure_unit: unit of pressure values in isotherm_data (Pa, bar, kPa). loading_key: key name for the loading column (e.g. "loading_mol_kg", "loading_mg_g", "loading_cm3_STP_g"). output_path: absolute path where the PNG file will be saved.

Returns: {"status": "ok", "path": ..., "n_points": ...} or {"status": "error", "message": ...}

Generate a multi-MOF comparison isotherm plot (PNG) — all MOFs on one figure.

datasets is a list of dicts, each representing one MOF: { "label": "MIL-101(Cr)", # legend label "isotherm_data": [{...}, {...}, ...] # same format as plot_isotherm() }

Designed for the final "top-N candidates" comparison step: pass in the isotherm_data from each MOF's parse_raspa_output() call together with a descriptive label, and receive a single publication-ready comparison figure.

pressure_unit / loading_key: same semantics as plot_isotherm(). output_path: absolute path where the PNG will be saved.

Returns: {"status": "ok", "path": ..., "n_series": ...} or {"status": "error", "message": ...}

Generate force_field.def (the OVERWRITE-rules file) at work_dir.

With no extra arguments, produces the safe minimal "3 zeros" form, which is what most users actually need when their LJ parameters live in force_field_mixing_rules.def.

DO NOT confuse this file with force_field_mixing_rules.def — putting LJ epsilon/sigma here is the most common cause of cryptic :# parse errors from RASPA2. Use generate_force_field_mixing_rules_def for those.

Args: work_dir: Workspace directory (must be inside RASPA_MCP_WORKSPACE_BASE). rules_to_overwrite, interactions_to_define, mixing_rules_to_overwrite: Optional lists of {"line": str, "comment": str | None} entries. return_only: If True, do not touch disk; just return the rendered text.

Generate force_field_mixing_rules.def — the LJ epsilon/sigma file.

Each atom_types item: {"name": str, "epsilon_K": float, "sigma_A": float, "interaction": "lennard-jones", "comment": str | None}.

For the "shifted vs truncated" choice, "shifted" zeroes the LJ potential at the cutoff (smoother energies); "truncated" matches RASPA2 legacy behaviour. Set tail_corrections=True for fluid-phase work.

Args: work_dir: Workspace directory (sandboxed). atom_types: Required list of atom-type dicts. general_mixing_rule: Lorentz-Berthelot (default) or Jorgensen. general_truncation: shifted (default) or truncated. tail_corrections: Apply analytic LJ tail corrections. return_only: Dry-run; do not write to disk.

Generate pseudo_atoms.def — the atom registry. Every atom-type symbol that appears in the CIF, in force_field_mixing_rules.def, or in any molecule .def must be listed here.

Each atoms item must include at minimum: name, chem, mass, charge. Optional keys with defaults: print=yes, print_as=name, oxidation=0, polarization=0, b_factor=1.0, radii=1.0, connectivity=0, anisotropic=0, anisotropic_type='absolute', tinker_type=0.

Generate a per-molecule .def file at <work_dir>/molecules/<subdirectory>/<molecule_name>.def.

atoms items: {"type": str, "x": float, "y": float, "z": float}. Coords are Å relative to the molecule centre of mass.

bonds items: [i, j, "RIGID_BOND"] (or any RASPA2 bond keyword). bends items: [i, j, k, "<bend_keyword>"]. torsions items: [i, j, k, l, "<torsion_keyword>"].

Set MoleculeDefinition <subdirectory> in simulation.input so RASPA2 finds this file. Avoid MoleculeDefinition local — that points to $RASPA_DIR/share/raspa/molecules/local/, not your workspace.

Inspect a CIF file: formula, cell parameters, charge column status, minimum interatomic distance. Flags common pitfalls (no charges, non-neutral cell, atom overlap).

Use before launching a simulation against an unfamiliar CIF.

Recommend an integer supercell (nx, ny, nz) such that each axis is at least 2 × cutoff_A (the RASPA2 minimum-image rule). Also recommends a ChargeMethod based on whether the CIF has non-zero charges.

Validate a workspace directory before launching simulate.

Checks:

• simulation.input exists and passes validate_simulation_input

• the CIF named by FrameworkName exists at frameworks//.cif

• force_field.def exists and is in overwrite-rules format (NOT mixing)

• force_field_mixing_rules.def exists and lists atom types

• pseudo_atoms.def covers every atom type used by the mixing-rules file

• each Component in simulation.input has a matching molecule .def

Returns {"ok": bool, "errors": [...], "warnings": [...], "findings": {...}}.

Return an ordered, tool-by-tool recipe for a common RASPA2 scenario.

Args: scenario: One of custom_mof_gcmc, henry_widom, diffusion_md, or None to list all available scenarios.