Skip to content

Batch summaries

Turn a batch of calculation outputs into a pandas DataFrame and export CSV or JSON.

Shortest example

Python
from molop import AutoParser

batch = AutoParser("water_mp2.out", n_jobs=1)
summary = batch.to_summary_df(
    frame=-1,
    brief=False,
    flatten_columns=True,
)
summary.to_csv("summary.csv", index=False)
print(summary.shape)
Output
Text Only
(1, 23)

Replace water_mp2.out with results/*.out to process a batch. Each successfully parsed file produces one row; inputs that do not parse produce no row.

Parallel batch operations

Parsing and batch operations default to automatic parallelism with n_jobs=-1:

Python
from molop import AutoParser

batch = AutoParser("results/*.out")
normal = batch.filter_state("normal", n_jobs=-1)
summary = normal.to_summary_df(
    frame=-1,
    brief=False,
    flatten_columns=True,
    n_jobs=-1,
)
summary.to_csv("normal.csv", index=False)

n_jobs=-1 follows the process-aware CPU limit. Parsing and operations that do not enter MolGR use the full effective_max_jobs value. Graph-dependent operations, including to_summary_df, graph format transforms, TS endpoint export, grouping, and filter_custom, use the stricter floor(2 * available_cpu_count / 3) MolGR budget, also capped by molopconfig.max_jobs. Use n_jobs=1 while diagnosing a parser or a native-library failure. CLI parse and operation commands have the same independent default.

For a custom per-file operation, use parallel_execute and return explicit values:

Python
def file_format(parsed_file):
    return parsed_file.filename, parsed_file.detected_format_id

rows = batch.parallel_execute(file_format, n_jobs=-1, return_results=True)
print(list(rows))

For the bundled sample, the result is:

Output
Text Only
[('water_mp2.out', 'orcaout')]

Check the shared example

Python
import pandas as pd
from IPython.display import display
from molop import AutoParser

batch = AutoParser("water_mp2.out", n_jobs=1)
summary = batch.to_summary_df(brief=False, flatten_columns=True)
with pd.option_context("display.max_columns", None, "display.max_rows", None, "display.width", 240):
    display(summary)

Complete table output

DiskStorage.FilePath DiskStorage.FileFormat General.Charge General.Multiplicity General.CanonicalSMILES General.NumAtoms General.FrameID Calc Parameter.Software Calc Parameter.Version Calc Parameter.Method Calc Parameter.BasisSet Calc Parameter.Functional Calc Parameter.Keywords Environment.SolventModel Environment.Solvent Status.IsError Status.IsNormal Status.IsTS Status.IsOptimized Energy.electronic_energy.hartree Energy.reference_energy.hartree Energy.mp2_energy.hartree Energy.total_energy.hartree
0 /home/runner/work/MolOP/MolOP/docs/assets/exam... .out 0 1 O 3 0 ORCA 6.0.1 MP2 sto-3g MP2 sto-3g None None False True False False -74.999375 -74.963574 -74.999375 -74.999375

The table comes from the executed output of Notebook 02 and contains all 23 columns from summary without a temporary slice. CI executes the notebook before MkDocs embeds the saved HTML.

Final and all frames

Python
final_rows = batch.to_summary_df(frame=-1)
all_rows = batch.to_summary_df(frame="all")
selected_rows = batch.to_summary_df(frame=[0, -1])
print(final_rows.shape, all_rows.shape, selected_rows.shape)
Output
Text Only
(1, 19) (1, 19) (2, 19)

The default on_missing_frame="skip" omits unavailable indices. Use on_missing_frame="error" when a missing frame should fail the operation.

Brief and full fields

Python
brief = batch.to_summary_df(brief=True, flatten_columns=True)
full = batch.to_summary_df(brief=False, flatten_columns=True)
print(brief.columns[:7].tolist())

The brief summary includes stable file, molecule, calculation, and status columns. The first seven columns for the shared sample are:

Columns
Text Only
['DiskStorage.FilePath', 'DiskStorage.FileFormat', 'General.Charge',
 'General.Multiplicity', 'General.CanonicalSMILES', 'General.NumAtoms',
 'General.FrameID']

The full summary adds available Energy.*, Thermal.*, and Vibration.* columns.

Flat and MultiIndex columns

Python
flat = batch.to_summary_df(flatten_columns=True)
print(flat["General.Charge"].tolist())

multi = batch.to_summary_df(flatten_columns=False)
print(multi[("General", "Charge", "")].tolist())
Output
Text Only
[0]
[0]

Flat columns are easier for CSV, JSON, and general analysis. Keep MultiIndex columns when the three-level group, field, and unit meaning matters.

Group, sample, and preview

These operations keep the batch model and are useful before committing to a full export:

Python
groups = batch.groupby(lambda parsed_file: parsed_file.detected_format_id, n_jobs=-1)
print({key: len(group) for key, group in groups.items()})

sample = batch.sample(n=1, seed=1)
print(sample.file_names)

grid = batch.draw_grid_image(maxMols=16, useSVG=True, n_jobs=1)
print(type(grid).__name__, grid.lstrip()[:4])

For the bundled sample, the textual output is:

Output
Text Only
{'orcaout': 1}
['water_mp2.out']
str <svg

With useSVG=True, grid is an SVG string that can be embedded in a notebook or written to an .svg file. MolOP uses rdkit-dof by default for depth-aware drawing; set molopconfig.use_dof_effect_drawer = False to use the standard RDKit drawer. Set useSVG=False for a raster image. The CLI equivalent is draw-grid-image --out structures.svg or draw-grid-image --out structures.png.

Export JSON

Python
summary.to_json("summary.json", orient="records", indent=2)
print("summary.json")
Created file
Text Only
summary.json

Large-batch guidance

  • Start with 5-20 representative files and n_jobs=1 to inspect fields.
  • Increase n_jobs after confirming the format; disks and large files may limit scaling.
  • Use only_last_frame=True only when optimization trajectories are unnecessary.
  • Compare input paths with batch.file_paths to record omitted files.
  • Group calculations by theory level before comparing total_energy.

CLI equivalent

Bash
molop -q parse "results/*.out" \
  to-summary-df --full --flatten-columns --out summary.csv
Terminal output
Text Only
Summary written to summary.csv

Next steps