pfcc-extras

name

pfcc-extras

description

pfcc_extras (Matlantis/ASE workflow utilities) を使うコード生成時に使用します。 可視化 (show_gui, view_ngl, SurfaceEditor)、構造加工 (smiles_to_atoms, LiquidGenerator, make_alloy, makesurface, 各種 interface)、MD スケジューラー (DepositionScheduler, ApplyUniformEfield など)、物性解析 (MonteCarlo, GCMC, calculate_bulk_modulus, 粘度・熱伝導率, trajectory 変換)、吸着・構造探索 (adsorption_structure_search)、ジョブ実行制御 (run_jobs, ResourceAwareJobScheduler, parameter sweep) を扱います。

pfcc_extras ユーティリティ

概要

pfcc_extras は Matlantis / ASE ワークフローを補完する実務ユーティリティ群です。可視化・構造加工・MDスケジューラー・物性解析・ジョブ実行制御といった、ASE 単体では不足しやすい機能をカバーします。以下のサンプルコード中で事前に生成していないオブジェクトに関しては事前に生成しておくようにすること。

カテゴリ	主な機能
可視化	show_gui, view_ngl, SurfaceEditor, AddEditor, traj_to_gif, traj_to_apng, pov_to_png, png_to_gif, save_traj_pov
構造加工	smiles_to_atoms, generate_conformers, LiquidGenerator, PartialOccupancy, wrap_molecule, CollisionDetector, make_alloy, select_subset, fill_interstitial_sites, makesurface, make_surfaces_pmg, make_rectangular_slab, make_mol_surface, get_hkl_bulk_structure
MD スケジューラー	DepositionScheduler, DeleteMoleculeScheduler, ElasticVirtualWall, ApplyUniformEfield, LinearTemperatureScheduler, CellDeformationScheduler, EarlyStopScheduler, TemperatureScaleScheduler
物性解析	IsosurfaceCalculator, calculate_bulk_modulus, ChemicalWindow, MonteCarlo
吸着・構造探索	adsorption_structure_search, IsotropicFilter
ジョブ実行制御	run_jobs, ResourceAwareJobScheduler, QueueScheduler, PapermillScheduler, ParameterizedJob
Light-PFP 構造ビルダー	cut_sphere, cut_cube, solid_molecule_interface, liquid_liquid_interface, soak, solid_solid_interface_random
Calculator ユーティリティ	get_pfp_calculator, WrappedCalculator, TimeProfileHook
アルゴリズム	farthest_point_sampling, opt, opt_cell_size, opt_with_symmetry
軌跡変換	asetraj_to_mdtraj, asetraj_to_mdanalysis, modify_trajectory_by_mic

---

可視化

show_gui

from pfcc_extras.visualize import show_gui
atoms = read("input.traj")
show_gui(atoms, show_axes=True, show_atom_index=True, ball_size=0.3)

view_ngl / view_ngl_traj

from pfcc_extras.visualize.view import view_ngl

view_ngl(atoms, representations=["ball+stick"])  # representationsで結合表示も指定可能

SurfaceEditor（表面系インタラクティブ編集）

Calculator を設定した状態で使うと、エネルギー・最大力の表示や簡易最適化まで GUI 上で実行できます。

from pfcc_extras.visualize.surface_editor import SurfaceEditor

atoms.calc = calculator   # Calculator 設定が必要
editor = SurfaceEditor(atoms, w=600, h=500)

主な機能: カラースキーム・描画軸変更 / 選択原子の削除・置換・移動・回転 / エネルギー・最大力表示 / 簡易最適化（Run mini opt）/ 画像保存 / ポインターによる ID・座標表示

AddEditor（分子系インタラクティブ編集）

from pfcc_extras.visualize.addeditor import AddEditor
editor = AddEditor(atoms)
editor.display()

POVRay アニメーション

traj_to_gif / traj_to_apng が最もシンプルなワンライナーです。内部的には save_traj_pov → pov_to_png → png_to_gif / png_to_apng のパイプラインになっており、個別関数を呼ぶと細かく制御できます。

from pfcc_extras.visualize.povray import traj_to_gif, traj_to_apng

# GIF（ワンライナー）
traj_to_gif(
    atoms_list,
    gif_filepath="anim.gif",
    rotation="30x,30y",       # 固定回転（str）または lambda index, atoms: "..." で可変
    width=400,                 # 解像度（ピクセル）
    delay=100,                 # フレーム間隔（ms）
    n_jobs=8,                  # POV レンダリングの並列数
    clean=True,                # 中間ファイル（pov/png ディレクトリ）を自動削除
)

# APNG（GIF より高画質・大ファイル）
traj_to_apng(atoms_list, apng_filepath="anim.png", width=400, delay=100)

個別ステップで制御する場合:

from pfcc_extras.visualize.povray import save_traj_pov, pov_to_png, png_to_gif

save_traj_pov(traj, outdir="pov", width=400, rotation="30x,30y")
pov_to_png(povdir="pov", pngdir="png", n_jobs=16)
png_to_gif(pngdir="png", gif_filepath="anim.gif", delay=100)

• povray が事前にシステムにインストールされている必要があります
• rotation に callable を渡すとフレームごとに回転角を変えられます（例: lambda i, atoms: f"30x,{i}y"）

---

構造加工

SMILES / RDKit 変換（ase_rdkit_converter）

from pfcc_extras.structure.ase_rdkit_converter import (
    smiles_to_atoms, atoms_to_smiles, smiles_to_rdmol, rdmol_to_atoms,
)

atoms = smiles_to_atoms("c1ccccc1", randomSeed=42)   # SMILES → Atoms
smiles = atoms_to_smiles(atoms)                       # Atoms → SMILES

• randomSeed（または random_seed）を固定して再現性を確保してください（デフォルト 1）
• 水素原子は自動付加（AddHs）されます
• 3D 座標の埋め込みに失敗する場合は useRandomCoords=True を指定するか、maxAttempts を増やしてください

atoms = smiles_to_atoms("c1ccccc1", randomSeed=42, useRandomCoords=True, maxAttempts=1000)

配座探索（generate_conformers）

from pfcc_extras.structure.ase_rdkit_converter import generate_conformers

mol, conf_ids = generate_conformers(
    smiles_or_atoms="CC(C)C",   # SMILES 文字列または ASE Atoms
    num_conformers=50,
    pruneRmsThresh=0.1,         # RMS 閾値（低いほど多様な配座を保持）
    energy_tolerance=10.0,      # MMFF エネルギーカットオフ（kcal/mol）
    seed=1234,
)

溶液構造生成（LiquidGenerator）

Packmol または Torch バックエンドで分子をパッキングした溶液系を作成します。

from pfcc_extras.liquidgenerator.liquid_generator import LiquidGenerator

composition = [
    {"smiles": "O",   "number": 100},
    {"smiles": "CCO", "number": 20},
]
gen = LiquidGenerator(engine="packmol", composition=composition, density=1.0, tolerance=2.0)
liquid_atoms = gen.run()

engine="packmol" を使用してください。packmol_bin が存在しない場合は自動インストールされます。エラーが出る場合は、density を小さくしてみてください。

部分占有構造の離散化（PartialOccupancy）

from pfcc_extras.structure.partial_occupancy import PartialOccupancy

po = PartialOccupancy(
    input_structure=atoms,
    csv_path="occupancy.csv",
    occupancy_header="occupancy",
    random_seed=42,
)
po.set_parameters(cell_repeat=(2, 2, 2))
realized_atoms = po.assign_atom_positions()

cell_repeat を大きくすると占有率の整数比近似が改善されます。

分子ラップと分子リスト（wrap_molecule / get_mol_list）

from pfcc_extras.structure.molecule import wrap_molecule, get_mol_list

wrapped = wrap_molecule(atoms)       # 分子単位で PBC ラップ

原子単位で wrap すると分子がセル境界で分断されます。必ず分子単位で適用してください。

合金・元素置換（composition）

from pfcc_extras.structure.composition import make_alloy, make_chemical_formula

formula = make_chemical_formula(atoms, elem_ratio={"Au": 1, "Pt": 3})
alloy_atoms = make_alloy(atoms, chemformula=formula, seed=42)

合金最安定構造探索（select_subset）

ランダム・貪欲法・アニーリング法で目的関数（エネルギー等）を最小化する原子配置を探索します。

from pfcc_extras.structure.select_subset import (
    select_subset_random,
    select_subset_greedy,
    select_subset_annealing,
)
import numpy as np

indices = np.arange(len(atoms))

def objective(subset_indices):
    return get_energy(atoms, subset_indices)

# ランダム法（多数のランダム試行から最良を選択）
best, history, costs = select_subset_random(
    indices, n=20, objective_function=objective, max_iters=500, seed=42, n_jobs=-1,
)

# 貪欲法（1 サイトずつ最良の元素を確定）
best, history, costs = select_subset_greedy(
    indices, n=20, objective_function=objective, seed=42,
)

# アニーリング法（局所最適を脱出）
best, history, costs = select_subset_annealing(
    indices, n=20, objective_function=objective, initial_temp=500, final_temp=100, alpha=0.9,
)

戻り値: (best_subset, subset_history, cost_history)。n_jobs=-1 で joblib 並列実行可能です。

衝突判定（CollisionDetector）

from pfcc_extras.structure.connectivity import CollisionDetector

detector = CollisionDetector(atoms, collision_mult=0.8, connection_mult=1.05)

if detector.is_colliding().any():
    print(detector.get_info_as_dataframe())

clean_atoms = detector.extract_not_colliding_molecules()

• collision_mult=0.8: 共有結合距離 × 0.8 より近ければ「衝突」と判定
• extract_colliding_atoms() / extract_not_colliding_molecules() でクリーニングできます
• 手動配置後や LiquidGenerator 後の構造確認に使用してください

欠陥・格子間サイト生成（fill_interstitial_sites）

from pfcc_extras.structure.defects import fill_interstitial_sites

atoms_with_interstitials, site_list, species, indices = fill_interstitial_sites(
    host_atoms=host,
    insert_species=["Li", "H"],
    mode="pymatgen",   # "pymatgen"（推奨）/ "voronoi" / "random"
    host_min_distance=1.5,
    seed=42,
)

表面スラブの簡易切り出し（makesurface）

ASE の ase.build.surface をベースにした最もシンプルなスラブ生成関数です。Miller 指数・層数・繰り返し・真空層を指定してバルクから 1 枚のスラブを切り出します。

from pfcc_extras.structure.surface import makesurface

slab = makesurface(
    bulk_atoms,
    miller_indices=(1, 1, 1),  # Miller 指数
    layers=6,                  # スラブの層数
    rep=(4, 4, 1),             # 面内の繰り返し
    vacuum=30.0,               # 真空層の厚さ（Å、両側合計）
)

• スラブは Z 軸方向に切り出され、vacuum/2 ずつ上下に真空層が付加されます
• 複数の Miller 面を一括生成したい場合や直交セルが必要な場合は、後述の make_surfaces_pmg / make_rectangular_slab を使用してください
• バルクが切断面でずれて切り出される場合は、事前に原子位置を微小シフトしてください

表面スラブ構築（make_surfaces_pmg / make_rectangular_slab）

from pfcc_extras.structure.surface import make_surfaces_pmg
from pfcc_extras.structure.solid import make_rectangular_slab

# pymatgen ベースのスラブ（複数表面を一括生成）
slabs = make_surfaces_pmg(
    atoms=bulk_atoms, miller_index=(1, 1, 0),
    min_slab_size=10.0, min_vacuum_size=20.0, ab_rep=(2, 2), center_slab=True,
)

# MD 用直交セルスラブ
slab = make_rectangular_slab(
    atoms=bulk_atoms, miller_index=(1, 1, 1),
    min_slab_size=6.0, min_vacuum_size=10.0, max_atoms=3000, min_length=5.0,
)

有機分子結晶の表面構築（make_mol_surface）

バルクの有機分子結晶から表面スラブを構築します。構成分子を mols に渡すと、分子として完結しないフラグメントを自動的に除去します。

from pfcc_extras.structure.surface import make_mol_surface

slab = make_mol_surface(
    atoms=bulk_atoms,          # 有機分子結晶のバルク構造
    mols=[mol_a, mol_b],       # バルクを構成する全分子（Atoms のリスト）
    hkl=(0, 0, 1),             # 表面法線方向（Miller 指数）
    slab_thickness=10,         # スラブ厚さ（Å）
    vacuum=10,                 # 真空層の厚さ（Å）
)

• mols にはバルク構造を構成する全分子を渡してください。漏れがあると表面に欠損が生じます
• 表面に出現するフラグメント（分子として不完全な原子群）は自動除去されます

NPT 用セルの上三角変換（convert_atoms_to_upper）

ASE の NPT モジュールはセルが上三角形式（cell[1,0] == cell[2,0] == cell[2,1] == 0）であることを要求します。この条件を満たさない構造を NPT に渡す前に使用してください。

from pfcc_extras.structure.rotate import convert_atoms_to_upper

atoms_upper = convert_atoms_to_upper(atoms)
# atoms_upper.cell は上三角形式に回転済み

バルク構造の hkl 変換（get_hkl_bulk_structure）

指定した Miller 指数面を Z 軸とするバルク構造に変換します。界面 MD の初期構造生成に使います。

from pfcc_extras.structure.solid import get_hkl_bulk_structure

bulk_list = get_hkl_bulk_structure(atoms=bulk_atoms, miller_index=(1, 1, 1), max_atoms=3000)
hkl_bulk = bulk_list[0]

近傍・結合解析

from pfcc_extras.structure.connectivity import get_neighbors, get_connectivity_matrix

neighbors = get_neighbors(atoms, r=3.0) # r が None であれば、covalent radii を基に計算されます
connectivity = get_connectivity_matrix(atoms, mult=1.05)

cutoff の閾値はワークフロー全体で統一し、結合判定の揺らぎを防いでください。

---

MD スケジューラー

DepositionScheduler（分子堆積）

from pfcc_extras.molecular_dynamics.scheduler import (
    DepositionScheduler, convert_kinetic_energy_to_velocity,
)

scheduler = DepositionScheduler(
    atoms=slab_atoms,
    dyn=dyn,
    molecules=[molecule_atoms],
    fractions=[1.0],
    num_total_steps=10000,
    incident_energy=1.0,     # eV（または incident_velocities で直接指定）
    initial_height=10.0,
    axis=2,
    seed=42,
)
dyn.attach(scheduler, interval=1)

• incident_energy → incident_velocities 変換は convert_kinetic_energy_to_velocity(atoms, energy) を使うとケース間の比較が容易になります
• fractions の総和は自動正規化されます

DeleteMoleculeScheduler（セル外分子の自動削除）

from pfcc_extras.molecular_dynamics.scheduler import DeleteMoleculeScheduler

deleter = DeleteMoleculeScheduler(atoms=atoms, dyn=dyn, axis=2)
dyn.attach(deleter, interval=100)

ElasticVirtualWall（弾性仮想壁）

非周期系の MD でセル境界に弾性壁を設け、原子・分子を反射させます。

from pfcc_extras.molecular_dynamics.scheduler import ElasticVirtualWall

wall = ElasticVirtualWall(
    atoms=atoms, dyn=dyn,
    wall_position=30.0,    # 壁の位置（Å）
    axis=2,
    wall_direction="top",  # "top" または "bottom"
    distance_tol=2.0,      # 分子グループ化の距離閾値（None で原子単位）
    seed=42,
)
dyn.attach(wall, interval=1)

ApplyUniformEfield（一様電場）

from pfcc_extras.molecular_dynamics.uniform_electric_field import ApplyUniformEfield

# charges を渡さない場合：MD ステップごとに atoms.get_charges() を呼び出して動的に更新
efield_constraint = ApplyUniformEfield(atoms=atoms, efield=(0.0, 0.0, 0.01))

# charges を渡す場合：固定値を使用（len(charges) == len(atoms) が必要）
efield_constraint = ApplyUniformEfield(atoms=atoms, efield=(0.0, 0.0, 0.01), charges=[...])

atoms.set_constraint(efield_constraint)

• charges を省略すると各 MD ステップで atoms.get_charges() を呼び出して電荷を動的に取得します。ポテンシャルモデルが電荷を計算できる場合（例: ReaxFF 系）に有効です
• charges を固定する場合は len(charges) == len(atoms) を確認してください

LinearTemperatureScheduler（線形温度スケジュール）

昇温・降温・急冷に使います。estimate_rate / estimate_steps で必要なレートやステップ数を事前に計算できます。

from pfcc_extras.molecular_dynamics.scheduler import (
    LinearTemperatureScheduler, estimate_rate, estimate_steps,
)

# 必要なレート・ステップ数を推定
rate  = estimate_rate(start=300, end=1500, nsteps=10000, timestep_fs=2.0)  # K/fs
steps = estimate_steps(start=300, end=1500, rate=0.12, timestep_fs=2.0)

scheduler = LinearTemperatureScheduler(
    dyn=dyn, temp_start=300, temp_end=1500,
    nsteps=10000,   # または temp_rate=rate で K/fs 指定も可
)
scheduler.attach(interval=1)

CellDeformationScheduler（セル変形スケジュール）

引張・圧縮 MD に使います。

from pfcc_extras.molecular_dynamics.scheduler import CellDeformationScheduler

target_cell = atoms.get_cell().copy()
target_cell[2, 2] *= 1.5   # Z 軸を 1.5 倍に伸長

scheduler = CellDeformationScheduler(
    dyn=dyn, atoms=atoms, target_cell=target_cell,
    nsteps=5000,                    # または strain_rate=1e8（1/s）で指定
    mask=[False, False, True],      # Z 軸のみ変形
)
dyn.attach(scheduler, interval=1)

EarlyStopScheduler（条件付き早期終了）

from pfcc_extras.molecular_dynamics.scheduler import EarlyStopScheduler

def stop_condition(dyn, atoms):
    return atoms.get_temperature() > 1500

stopper = EarlyStopScheduler(
    dyn=dyn, atoms=atoms, func=stop_condition, post_stop_steps=100,
)
dyn.attach(stopper, interval=10)

TemperatureScaleScheduler（温度スケーリング）

from pfcc_extras.molecular_dynamics.scheduler import TemperatureScaleScheduler

scheduler = TemperatureScaleScheduler(atoms, dyn=dyn, temperature=300.0, indices=None, mask=None)
dyn.attach(scheduler, interval=100)

---

物性解析・化学ポテンシャル

イオン伝導パスの等値面計算（IsosurfaceCalculator）

MD 軌跡から特定元素の確率分布グリッドを計算し、VESTA / OVITO / NGLViewer で読み込める Gaussian cube ファイルを出力します。

from pfcc_extras.isosurface.isosurface import IsosurfaceCalculator
from ase.io import Trajectory

iso = IsosurfaceCalculator(Trajectory("md.traj"), grid_size=0.5)
iso.calculate(symbol="Li")
iso.export("Li_isosurface.cube")   # Gaussian cube 形式で出力

grid_size はいずれの格子定数より小さい値を設定してください。

バルク弾性率・状態方程式（calculate_bulk_modulus）

from pfcc_extras.analysis.eos import calculate_bulk_modulus

def get_calc():
    return get_pfp_calculator(calc_mode="r2scan", model_version="v9.0.0")

V0, E0, B = calculate_bulk_modulus(
    atoms=atoms,
    volume_ratio_range=(0.9, 1.1),
    get_calculator=get_calc,
    num_data_points=10,
    fmax=0.005,
    n_jobs=4,           # -1 で全 CPU
)
# V0: 平衡体積（ų）, E0: 最小エネルギー（eV）, B: バルク弾性率（GPa）

get_calculator は毎回新しい calculator を返すファクトリ関数を渡してください。

化学ポテンシャル窓（ChemicalWindow）

Materials Project データと PFP エネルギーを組み合わせ、安定相図上の化学ポテンシャル許容域を計算・可視化します。

from pfcc_extras.chemical_potentials import ChemicalWindow

cw = ChemicalWindow(elements=["Li", "Ni", "O"])

# データの取得（Materials Project からのダウンロード、または自前の PFP 計算エネルギーの読み込み）
cw.download_data_from_materials_project(api_key="YOUR_MP_API_KEY", thermo_types=["GGA_GGA+U"])
# cw.read_csv("energy_per_atoms.csv")   # 代わりに CSV から読み込む場合

# 化学ポテンシャル窓の計算
cw.calculate_chemical_potentials(x_element="Li", y_element="Ni")
cw.get_chemical_potentials_under_constraints(constraints={...})   # 必要に応じて制約を指定
cw.calculate_formation_energy()

# 可視化（plot_type は 'heatmap' / 'contour'）
cw.plot_2d(width=500, height=500, plot_type="contour", title="Chemical window")

モンテカルロシミュレーション（MonteCarlo）

格子 MC（LMC）・オフ格子 MC・グランドカノニカル MC（GCMC）を統一インターフェースで提供します。

from pfcc_extras.monte_carlo.mc import MonteCarlo

mc = MonteCarlo(
    base_str=base_str,
    calculator=calculator,
    total_mc_iterations=10000,
    pressure=1.0,           # atm
    temperature=300.0,      # K
    mc_type_ratios={"lattice": 1.0},   # "lattice" / "off_lattice" / "gcmc" の混合比（合計 1.0）
    random_seed=42,
    output_data_path="output_data",
)

# Lattice MC
mc.setup_lattice_mc(atom_ids_to_swap={"Fe": 0.5, "Ni": 0.5})

# GCMC
mc.setup_gcmc(
    adsorbate_species=adsorbate_species,
    gcmc_move_ratios={"insert": 0.25, "remove": 0.25, "translate": 0.25, "rotate": 0.25},
    mu_TP0=mu_TP0,
)

mc.run()

mc_type_ratios の合計が 1.0 になるよう設定してください。random_seed を固定して再現性を確保してください。

シフトエネルギー補正

PFP のエネルギーを VASP / Gaussian の参照基準に揃えます。pfcc_extras.shift_energies は v0.8.1 以降 deprecated で、代替として Estimator.get_shift_energy_table() を使用してください。

import numpy as np
shift_table = estimator.get_shift_energy_table()   # {原子番号: shift_energy}
shift_energy = np.sum([shift_table[n] for n in atoms.get_atomic_numbers()])
vasp_aligned_energy = atoms.get_potential_energy() + shift_energy

---

吸着・構造探索

Optuna ベース吸着構造探索（adsorption_structure_search）

Optuna のベイズ最適化で吸着分子の位置・姿勢を網羅的に探索します。スラブ・クラスター・多孔質結晶の各バリアントがあります。

from pfcc_extras.adsorption.adsorption_structure_search import (
    adstructure_search_for_slab,
    adstructure_search_for_cluster,
    adstructure_search_for_porus,
    cluster_position_search_on_slab,
)

# スラブへの吸着
study = adstructure_search_for_slab(
    calc_mode="r2scan_plus_d3", model_version="v9.0.0",
    molec_path="molec_opt.traj", slab_path="Slab.traj",
    TH_max_f=5.0, TH_min_f=0.0005, tol=0.5,
    output_path="output/", study_name="slab_study", n_trials=100,
)

# クラスター上への吸着
study = adstructure_search_for_cluster(
    molec_path="opt_molecule.traj", clus_path="opt_cluster.traj",
    fix_ctr_cluster=4.0, output_path="output/", n_trials=100,
)

# 多孔質結晶への吸着
study = adstructure_search_for_porus(
    molec_path="opt_molecule.traj", crystal_path="porus_crystal.traj",
    output_path="output/", n_trials=100,
)

# スラブ上クラスターの位置探索
study = cluster_position_search_on_slab(
    clus_path="opt_cluster.traj", slab_path="Slab.traj",
    output_path="output/", n_trials=100,
)

• TH_max_f / TH_min_f で無効な初期配置を早期スキップし、計算コストを削減できます
• ストレージは JournalFileBackend を使い、中断再開が可能です（load_if_exists=True）
• Optuna の Terminator を使うと、改善が見られない場合に自動停止できます

import optuna
from optuna.terminator import Terminator, TerminatorCallback, BestValueStagnationEvaluator

improvement_evaluator = BestValueStagnationEvaluator(max_stagnation_trials=150)
terminator = Terminator(improvement_evaluator=improvement_evaluator)

study = adstructure_search_for_slab(
    calc_mode="r2scan_plus_d3",
    ...,
    n_trials=1000,                              # 大きめに設定しておく
    sampler=optuna.samplers.TPESampler(),
    callbacks=[TerminatorCallback(terminator)], # 150 回改善なしで自動停止
)

等方圧フィルター（IsotropicFilter）

NPT でセルを等方的に変形させます。剪断成分を除去したい場合に使います。

from pfcc_extras.filters.isotropic_filter import IsotropicFilter
from ase.optimize import LBFGS

opt = LBFGS(IsotropicFilter(atoms))
opt.run(fmax=0.005)

応力テンソルの剪断成分（stress[3:]）を 0 に固定し、対角成分を平均化して等方圧力として扱います。

---

ジョブ実行制御

run_jobs（統一インターフェース）

run_jobs は Notebook ジョブを実行する統一関数です。jobs には Notebook のパス文字列 を渡します（Job オブジェクトではありません）。フラットリスト・グループ化リスト・パラメータスイープの 3 形態に対応します。

from pfcc_extras.job_scheduler.runner import run_jobs

# 1) フラットリスト：複数 Notebook を並列投入
results = run_jobs(
    jobs=["01.ipynb", "02.ipynb", "03.ipynb"],
    max_workers=2,        # 並列投入数
    sequential=False,     # True で各ジョブの完了を待つ
    my_limit=0.4,         # 個人のトークンレート上限（0.0-1.0、None で無効）
    tenant_limit=0.7,     # テナントのトークンレート上限
    polling_interval_sec=5,
    post_submit_wait_sec=5,
    status_check_interval_sec=5,
)

# 2) グループ化リスト：グループ単位で逐次（優先度付き）実行
results = run_jobs(
    jobs=[["01.ipynb", "02.ipynb"], ["03.ipynb"]],  # 前のグループ完了後に次へ
    max_workers=2,
    sequential=True,
)

# 3) パラメータスイープ：同一 Notebook を複数パラメータで実行
results = run_jobs(
    jobs="template.ipynb",          # 単一の Notebook パス
    parameters=[
        {"temperature": 300},
        {"temperature": 500},
    ],
    max_workers=2,
    sequential=False,
)

run_jobs は JobResult のリストを返します。JobResult.status で FAILED と SKIPPED（出力ファイルが既に存在）を分離処理してください。

スケジューラクラスを直接使う

run_jobs を使わず、スケジューラクラスを直接生成して scheduler.run(...) で実行することもできます。共通の引数は my_limit / tenant_limit / mem_limit_mb / cpu_limit_percent / max_workers / polling_interval_sec / post_submit_wait_sec です（resource_limits や monitor_interval、max_concurrent という引数は存在しません）。

from pfcc_extras.job_scheduler.scheduler import (
    ResourceAwareJobScheduler, QueueScheduler, PapermillScheduler,
)

# 並列投入（リソース監視つき）
scheduler = ResourceAwareJobScheduler(
    my_limit=0.4, tenant_limit=0.7,
    max_workers=2, polling_interval_sec=5, post_submit_wait_sec=5,
)
results = scheduler.run(["01.ipynb", "02.ipynb"])

# キュー実行（完了待ち。グループ化リストも可）
scheduler = QueueScheduler(
    my_limit=0.4, tenant_limit=0.7,
    max_workers=2, polling_interval_sec=5, post_submit_wait_sec=5,
    status_check_interval_sec=5,
)
results = scheduler.run(["01.ipynb", "02.ipynb"])

# パラメータスイープ（papermill）
scheduler = PapermillScheduler(
    my_limit=0.4, tenant_limit=0.7,
    max_workers=2, sequential=False,
    polling_interval_sec=5, post_submit_wait_sec=5, status_check_interval_sec=5,
)
results = scheduler.run(
    infile="template.ipynb",
    parameters_list=[{"learning_rate": 0.01}, {"learning_rate": 0.001}],
)

---

LightPFP 向け構造ビルダー

LightPFP 学習データ生成・大規模 MD の初期構造構築向けのユーティリティです。LightPFP 以外の用途でも使えます。

球形・立方体クラスターの切り出し（cut_sphere / cut_cube）

from pfcc_extras.light_pfp.cluster import cut_sphere, cut_cube
from ase.build import bulk

cluster_sphere = cut_sphere(bulk("Fe") * (10, 10, 10), radius=10.0, vaccum=5.0)
cluster_cube   = cut_cube(bulk("Fe") * (10, 10, 10),   length=20.0, vaccum=5.0)

固体-液体界面（solid_molecule_interface）

from pfcc_extras.light_pfp.solid_liquid_interface import solid_molecule_interface
from ase.build import fcc111

atoms = solid_molecule_interface(
    solid=fcc111("Cu", size=(5, 5, 3), vacuum=10.0),
    molecules=["c1ccccc1", "CCO"],    # SMILES または Atoms
    n_molecules=[1, 5],               # 分子比率
    molecule_layer_thickness=15.0,    # 液体層の厚さ（Å）
    molecule_density=0.8,             # 密度（g/cm³）
    spacing=1.5,
)

液体-液体界面（liquid_liquid_interface）

from pfcc_extras.light_pfp.liquid_liquid_interface import liquid_liquid_interface

atoms = liquid_liquid_interface(
    molecules_left=["O", "CCO"],               # 下層
    molecules_right=["CCCCCCC", "c1ccccc1"],   # 上層
    n_molecules_left=[2, 1],
    n_molecules_right=[1, 1],
    xy_length=15.0,
    molecule_layer_thickness_left=10.0,
    molecule_layer_thickness_right=10.0,
)

固体を液体に浸す（soak）

from pfcc_extras.light_pfp.soak import soak

soaked = soak(solid=cluster_atoms, fluid=liquid_atoms, spacing=2.5)

固体-固体界面（solid_solid_interface_random）

from pfcc_extras.light_pfp.solid_solid_interface import solid_solid_interface_random

atoms_gb = solid_solid_interface_random(
    atoms_left=bulk("Fe") * (5, 5, 5),
    atoms_right=bulk("Cu") * (5, 5, 5),
    length=15.0, spacing=1.5,
)

Materials Project からの構造取得・元素置換

from pfcc_extras.light_pfp.solid import search_materials, replace_elements

atoms_list = search_materials(["mp-149", "mp-6930"], api_key="YOUR_KEY")

new_atoms = replace_elements(
    atoms_list[0] * (3, 3, 3),
    replace_scheme={"O": [("N", 0.20), ("F", 0.10)], "Fe": [("Ni", 0.30)]},
)

rNEMD（粘度・熱伝導率計算）

MD 実行中のモメンタム交換（RNEMDExtension）と、終了後のログ解析（get_viscosity / get_thermal_conductivity）がセットになっています。

from pfcc_extras.light_pfp.rnemd_utils import (
    RNEMDExtension,
    VelocityLogExtension,
    TemperatureLogExtension,
    get_viscosity,
    get_thermal_conductivity,
    plot_profile,
)

# MD 中のモメンタム交換 + プロファイルログ記録
rnemd = RNEMDExtension(
    md=md_dynamics,
    rnemd_type="viscosity",          # "viscosity" or "thermal_conductivity"
    n_slab=10,                       # スラブ数（偶数必須）
    n_swap=1, swap_interval=10,
    logfile="rnemd.log",
)
vel_log  = VelocityLogExtension(md_dynamics,   n_slab=10, logfile="velocity.log")
temp_log = TemperatureLogExtension(md_dynamics, n_slab=10, logfile="temperature.log")

md_dynamics.attach(rnemd,    interval=1)
md_dynamics.attach(vel_log,  interval=100)
md_dynamics.attach(temp_log, interval=100)

md_dynamics.run(100000)

# MD 終了後の解析
viscosity = get_viscosity(
    rnemd_log="rnemd.log", profile_log="velocity.log",
    timestep=2.0, init_steps=10000,   # 平衡化ステップを除外
)
print(f"粘度: {viscosity:.4f} mPa·s")

thermal_cond = get_thermal_conductivity(
    rnemd_log="rnemd.log", profile_log="temperature.log",
    timestep=2.0, init_steps=10000,
)
print(f"熱伝導率: {thermal_cond:.4f} W/(m·K)")

# 速度/温度プロファイルの可視化
plot_profile("velocity.log", figname="velocity_profile.png", init_steps=10000)

• n_slab は偶数必須です
• init_steps で平衡化ステップを除外して定常状態のデータのみ使用してください

---

軌跡変換

ASE の軌跡を MD 解析ライブラリ（MDTraj / MDAnalysis）に変換します。

from pfcc_extras.structure.ase_traj_converter import asetraj_to_mdtraj, asetraj_to_mdanalysis

md_traj  = asetraj_to_mdtraj(traj, set_PBC=True, bond_cutoff=1.2)
universe = asetraj_to_mdanalysis(traj, set_PBC=True, bond_cutoff=1.2)

• 全フレームで原子数・元素順を一致させてください
• bond_cutoff は系ごとに調整して過結合・未結合の両方を防いでください

軌跡への MIC 補正（modify_trajectory_by_mic）

PBC 系の MD 軌跡では原子がセル境界をまたぐと座標が不連続に飛びます。modify_trajectory_by_mic は最小像規則（MIC）を各フレーム間に適用し、原子が連続的に移動するように補正します。拡散係数の計算や軌跡の可視化の前処理として使用してください。

from pfcc_extras.structure.boundary import modify_trajectory_by_mic

traj_corrected = modify_trajectory_by_mic(traj)

---

Calculator ユーティリティ

get_pfp_calculator（PFP / EMT フォールバック）

from pfcc_extras.calculators.pfp_calculator import get_pfp_calculator

calc = get_pfp_calculator(calc_mode="r2scan", model_version="v9.0.0", priority=50)

# config dict で一括指定
calc = get_pfp_calculator(config={"calc_mode": "r2scan", "model_version": "v9.0.0"})

# EMT で強制フォールバック（テスト用）
calc = get_pfp_calculator(model_version="emt")

pfp_api_client が利用可能なら PFP を、そうでなければ EMT を返します。ファクトリ関数として他の関数に渡す用途に適しています。

WrappedCalculator と TimeProfileHook

from pfcc_extras.calculators.wrapped_calculator import WrappedCalculator
from pfcc_extras.calculators.hooks.time_profile_hook import TimeProfileHook

wrapped = WrappedCalculator(base_calculator)
hook = TimeProfileHook()
wrapped.register_hook(hook)

atoms.calc = wrapped
atoms.get_potential_energy()

# 計算ステップの所要時間を集計（report() メソッドは存在しない）
print(f"呼び出し回数: {hook.n_call_count()}")
print(f"合計時間: {hook.total_time():.4f} s")
print(f"平均時間: {hook.avg_time():.4f} s")

reset() でフックの計測値をリセットできます。WrappedCalculator 側では reset_hook() で全フックをクリアしてから再登録してください。

---

アルゴリズムユーティリティ

farthest_point_sampling（最遠点サンプリング）

Light-PFP 学習データの多様性確保に使います。距離行列から互いに最も遠い点を貪欲法で選択します。

from pfcc_extras.algorithm.sampling import farthest_point_sampling

selected_indices = farthest_point_sampling(
    distance_matrix=dist_mat,   # (N, N) の距離行列
    min_distance=0.2,
    seed=42,
)
selected_atoms = [all_atoms[i] for i in selected_indices]

opt / opt_cell_size（段階収束型最適化）

収束を監視しながら段階的に maxstep を縮小するラッパー最適化です。

from pfcc_extras.algorithm.optimization import opt, opt_cell_size

atoms = opt(atoms, calculator, sn=10, constraintatoms=[0, 1, 2])
atoms = opt_cell_size(atoms, calculator, sn=10, fix_symmetry=True)

• sn: 最大段階数（各段階で maxstep を 0.9^s 倍に縮小）
• opt_cell_size は FixSymmetry で対称性を保ちながらセル最適化します

opt_with_symmetry（UnitCellFilter + 対称性拘束）

UnitCellFilter ベースのシンプルなセル最適化です。opt_cell_size と異なり、単一ステップで収束まで実行します。

from pfcc_extras.algorithm.optimization import opt_with_symmetry

atoms = opt_with_symmetry(
    atoms_in=atoms,
    calculator=calculator,
    fix_symmetry=True,          # FixSymmetry で対称性を保持
    hydrostatic_strain=False,   # True にすると等方圧縮のみ許可
    fmax=0.001,
)

---

よくあるエラーと対処

エラー / 問題	原因	対処
run_jobs で FAILED になる	Notebook 内のエラー	JobResult の詳細を確認し、Notebook 単体でデバッグしてください
SKIPPED と FAILED の混同	出力ファイルが既に存在	SKIPPED は正常動作（冪等性）です。FAILED とは区別して処理してください
DepositionScheduler で分子が重なる	tol が小さすぎる	calculate_default_distance_tol(molecules) で適切な距離閾値を算出してください
ApplyUniformEfield でエラー	charges の長さが原子数と不一致	len(charges) == len(atoms) を確認してください
部分占有の離散化誤差が大きい	cell_repeat が小さい	cell_repeat を増やして誤差を低減してください
軌跡変換でフレーム数が合わない	原子数・元素順の不一致	全フレームで原子数と元素順が一致しているか確認してください
分子が PBC 境界で分断される	原子単位の wrap	wrap_molecule で分子単位に wrap してください
DeprecationWarning: shift_energy has been removed	pfcc_extras 0.8.1 以降	Estimator().get_shift_energy_table() を使用してください
MC の mc_type_ratios が合計 1.0 にならない	比率の設定ミス	各値の合計が 1.0 になるよう正規化してください
IsosurfaceCalculator で grid_size エラー	グリッドが格子定数より大きい	grid_size を最小格子定数より小さく設定してください
cut_sphere で中心が見つからない	radius がセルに対して大きすぎる	radius を小さくするかスーパーセルを大きくしてください
WrappedCalculator でフックが重複登録される	register_hook の重複呼び出し	reset_hook() でクリアしてから再登録してください

関連ガイド

• 統合ワークフロー (integrated-workflows/SKILL.md): pfcc_extras を使ったエンドツーエンドのパイプライン構築
• バックグラウンドジョブ (background-job/SKILL.md): 長時間ジョブの実行管理
• Light-PFP (light-pfp/SKILL.md): 大規模系での高速推論との組み合わせ