Introduction of pfcc-extras v0.13.0

---

Table of Contents

• Summary
• How to Install
• Introduction of major functions

---

Summary

pfcc-extras is a library package that gathers convenient tools for tasks such as modeling and result visualization.

Please note that since this is provided as an experimental library package, compatibility with new features is not guaranteed and may be changed or removed without prior notice.

This library has been tested with the latest Python 3.13.8 and ASE 3.27.0.

(2026.2 note)

As of February 13, 2026, pfcc-ase-extras is no longer available.

For alternative solutions, please refer to the February 13, 2026 release notes.

The functions in pfcc and the path to sample scripts were summarized as below.

Category	Functions	Scripts	Ver
Modeling	collision detector	collision_detector/Collision Detector Example.ipynb	>0.10.0
Modeling	Extraction from MaterialsProject (data)	materials_project.ipynb	>0.5.0
Modeling	liquid generator	liquid_generator/liquidgenerator_example.ipynb	>0.8.0
Modeling	make_mol_surface	make_mol_surface/make_mol_surface.ipynb	>0.5.0
Modeling	partial_occupancy	partial_occupancy/ partial_occupancy_treatment_example_XX.ipynb	>0.9.0
Modeling	modeling related modules (structure)   ase_rdkit_converter composition connectivity molecule surface solid	composition RandomElementSequenceGenerator.ipynb	>0.8.0
Modeling	solid_solid_interface	solid_solid_interface/make_solid_solid_interface.ipynb	>0.5.0
Modeling	get_hkl_bulk_structure	solid/convert_bulk_hkl_structure.ipynb	>=0.11.0
Modeling	Select alloy structure (select_subset)	alloy_atom_configurations/configuration_search_method_GaN-AlN.ipynb alloy_atom_configurations/volume_expansion_XRD_Al-Mg.ipynb	>=0.12.0
Modeling	Find interstitial sites (find_interstitial_sites)	defects/find_interstitials_pymatgen.ipynb defects/optimize_with_cutoff_radii.ipynb defects/analyze_neighbors.ipynb	>=0.12.0
Modeling	Find conformers (generate_conformers)	generate_conformers/generate_conformers.ipynb	>=0.12.0
Modeling	Initial structure construction (lihgtpfp_utils)	light-pfp-utils/light-pfp-initial-structures.ipynb	>=0.13.0
Calculation	adsorption_structure_search	adsorption_structure_serch adsorption_structure_search_for_cluster.ipynb adsorption_structure_search_for_porus.ipynb adsorption_structure_search_for_slab.ipynb cluster_on_slab.ipynb	>0.6.0
Calculation	chemical_window	chemical_window/ calculate_chemical_window_CZTS.ipynb	>0.7.0
Calculation	monte_carlo(MC)   GCMC Lattice MC	monte-carlo gcmc/gcmc.ipynb lmc/lmc.ipynb lmc/lmc_vac.ipynb	>0.5.0
Calculation	uniform_electric_field	molecular_dynamics/uniform_electric_field/ uniform_electric_field_en.ipynb	>=0.11.0
Calculation	MD schdedulers for deposition (deposition_scheduler)	molecular_dynamics/deposition/deposition_SiH4_on_Si001.ipynb	>=0.12.0
Calculation	general MD scheduler (scheduler)	molecular_dynamics/scheduler/*.ipynb	>=0.13.0
Calculation	Virtual wall	molecular_dynamics/virtual_wall/CH4_gas.ipynb	>=0.12.0
Visualization	isosurface	isosurface/isosurface.ipynb	>0.5.0
Visualization	povray animation	povray_to_gjf/povray_animation.ipynb	>0.5.0
Visualization	visualization modules   view_ngl SurfaceEditor	visualization/visualization.ipynb	>0.5.0
Visualization	Editor for molecules (addEditor)	visualization/addeditor_GUI_for_modeling	>=0.12.0
Visualization	wrap_molecule	wrap_molecule/wrap_molecule.ipynb	>0.5.0
Others	isotropic_filter	ー	>0.5.0
Others	jupyter_run	jupyter_notebook/run_all_notebooks.ipynb	>0.10.0
Others	math   gaussian_broadening linalg	ー	>0.10.0
Others	Interpolate NEB images (reaction_path_MIC)	reaction_path/modify_trajectory_by_mic.ipynb	>=0.12.0
Others	Convert trajectory (MDTraj, MDAnalysis)	structure/*.ipynb	>=0.13.0
depricated	shift_energy	ー	>0.5.0

* The all script paths only represents the relative path after "/pfcc-extras-v0.x.0/examples/".  tests are also informative if the ipynb file nots exist.

Return to Top⏎

How to install

1. Open Package Launcher and move to the bottom to find pfcc-extras package.
   
   
    
2. Copy to the directry as zip format
   
   
    
3. Right click the file and select “Extract Archive”
   
    

4. Open /pfcc-extras-v0.x.0/examples/install.ipynb, and run the cell below

   !pip install ..

   If you add -e option, the package will be installed in editable mode.
   
   
    

5. After install command, please restart the kernel.
   
   Please confirm the completion of the installation as below.
   • How to restart kernel
     • Kernel > Restart Kernel...
       
        
     • Click "Restart the kernel" button
        

   • Output example in v0.6.0

     import pfcc_extras
     
     print("pfcc_extras version: ", pfcc_extras.__version__)

     pfcc_extras version: 0.6.0

Return to Top⏎

Introduction of major functions

■ adsorption_structure_search

By using Optuna^TM , the black box optimization OSS, the optimization of adsorption structure will be conducted.

There are 4 examples in pfcc-extras.

file name	adsorbent	adsorbate
adsorption_structure_search_for_slab	Ru(111) slab	acrolein
adsorption_structure_search_for_porous	SiO2 zeolite	H2O
adsorption_structure_search_for_cluster	AuCu cluster	2-Propen-1-thiol
cluster_on_slab	CeO2 slab	Co half cluster

• Adsorption of acrolein on Ru(111) slab
• Adsorption of H2O in the porous SiO₂
• Adsorption of 2-Propen-1-thiol on AuCu cluster
• Adsorption of Co cluster on CeO₂ slab

Return to Top⏎

■ chemical_window

Using the chemical potentials of constituent elements as variables, we calculate the range of chemical potentials where the target material can stably exist.
When different phases precipitate experimentally, the relationship between the precipitate phase and the chemical potentials becomes clear.
This allows us to estimate the values of chemical potentials necessary to evaluate the energy of structures deviating from stoichiometric compositions, such as crystal defects or surfaces.

Return to Top⏎

■ collision_detector

The function judges whether the collision atoms (the pair of short distance atoms) exist in the system.

It make easy to find the collision atoms in PBC conditions or manually generated structures.

Return to Top⏎

■ data

The function can extract structure information form Materials Project through mp_api

NOTE) It needs the API key to access Materials Project.

Return to Top⏎

■ get_hkl_bulk_structure

Convert bulk structure into the structure with set miller index

　=>　

Return to Top⏎

■ isotropic_filter

The filter can convert the stress to the isotropic stress.

Return to Top⏎

■ isosurface

Creates a Gaussian cube file to visualize the diffusion path of specific elements from trajectory data.

The cube file can be loaded into applications such as OVITO, VESTA, and NGLViewer.

How to use:

1. Prepare trajectory file as trj.

2. Execute the codes as below.

   　iso = IsosurfaceCalculator(trj, grid_size = 0.5) ) 
   　iso.calculate(symbol = ‘Li’) x 
   　iso.export(‘./output.cube’) 

Return to Top⏎

■ jupyter_run

The script can execute another notebooks one by one.

Please use this if you want to separate and execute the steps sequentially.

From v0.13.0, jobscheduler  that allows for more complex execution control have been added. Please see the notebook for details.

Return to Top⏎

■ liquid_generator

The function can generate liquid system by packing molecules in the cell.

Return to Top⏎

■ math

gaussian_broadening

The function convert the graph by gaussian broadening method.

Return to Top⏎

■ make_mol_surface

Create the surface strucutre of organic molecules

How to use：

1.  Prepare the crystal structure
2. Define the components (molecule)
3. Execute make_mol_surface function

(a) anthracene, (b) graphene, (c) SiO₂, (d) CH₃, NH₃, Pbl₃

Return to Top⏎

■ monte_carlo

GCMC

The scripts can conduct Groud canonical Monte Carlo, GCMC

In the example, adsorption of CO2 molecules in Metal-organic-framework (MOFs) was introduced.

Return to Top⏎

Lattice MC

The scripts can conduct Lattice Monte Carlo, LMC.

In the example, the structure search of metal slab with Pt₃Au case.

Return to Top⏎

■ partial_occupancy

The example can create the structure from CIF file with occupancy is not 1.

Return to Top⏎

■ povray_animation

Create video files from trajectory file.

The format below can be obtained.

• .gif
• .png

Return to Top⏎

■ shift_energy(deprecated)

Converts the reference value of energy used in Matlantis to the reference value of energy used in VASP.

Since calculation is now possible using `estimator.get_shift_energy_table()` in the pfp-api-client, this feature is deprecated.

Return to Top⏎

■ structure

composition

Creates an alloy with arbitrary ratios or a crystal structure with partial element substitution.

Return to Top⏎

■ solid_solid_interface

Make a solid-solid interface model.
* requires "pymatgen" 

Procedure: 

1. Prepare two different bulk structures
2. Each cut into rectangular ("make_rectangular_slab")
3. Calculate multiplier that minimizes cell size gap when stacked. ("make_similar_lattice_const_slabs")
4. The two are stacked to create an interface structure. ("surface_stack")
5. Extract unit cell. ("make_primitive")
6. Save

Return to Top⏎

■ select_subset

An algorithm has been added that searches for the most stable structure of an alloy using random substitution, greedy algorithms, and annealing methods.

The greedy algorithm is used to search for stable configurations of alloys. This is effective for creating initial configurations for the Monte Carlo method and for simple screening.

Return to Top⏎

■find_interstitial_sites

Find interstitial sites within a crystal structure and insert atoms into them. This is useful for simulating doping and diffusion, and for exploring new compounds.

Return to Top⏎

■generate_conformers

For the input smiles or atoms, you can get a conformer in atoms type. Detailed argument settings are also possible depending on the purpose.

Return to Top⏎

■ deposition_scheduler

A function has been added to perform MD such as adding and deleting molecules from the calculation system.

• DepositionScheduler: A scheduler that adds molecules to the system during MD calculation.
• DeleteMoleculeScheduler: A scheduler that deletes molecules that have been thrown out of the system during MD calculation.
• TemperatureScaleScheduler: A scheduler that controls the temperature of specified atoms with simple temperature scaling.

Return to Top⏎

■virtual_wall

Added the function to elastically reflect molecules at cell boundaries in MD calculations of non-periodic systems.

Return to Top⏎

■ uniform_electric_field

Conduct MD with uniform electric field

Return to Top⏎

■ visualization

view_ngl

view_ngl is a light-weight visualization tool, quickly allows you to inspect your structure.

Some useful features:

• Change color scheme and ball size
• Save images
• Display force and charge*
• View trajectory file

* Displaying force and charge requires setting calculator. 

Return to Top⏎

SurfaceEditor

SurfaceEditor is a versatile editor/visualization tool. (Setting calculator is required)

Some useful features:

• Change color scheme and ball size
• Change view direction
• Select atom to apply changes
  • Delete and replace
  • Move and rotate
• Check energy and max force
• Perform a quick optimization
• Save images
• Display forces and xyz axes
• Displays atom ID and coordinates (w/Hovering mouse cursor over an atom)

Return to Top⏎

■addEditor

The functionality of the SurfaceEditor has been expanded, and an AddEditor has been added that allows for molecular shaping on a GUI.
Operations can be easily undone (Undo, Redo), carbon chain extension at the clicked index, and hydrogen coverage on the catalyst surface.

Return to Top⏎

■ wrap_molecule

• wrap_molecule() … wrap a molecule that crosses a periodic boundary without splitting it.
• get_mol_index() … Index numbering and labeling for each molecule
• get_mol_list() … Split the Atoms object into separate molecules.

eg.: wrap_molecule()

Return to Top⏎

■reaction_path_MIC

When creating the initial configuration for NEB calculations, if an atom crosses a periodic boundary between images, the atomic position is corrected using the minimum image convention (MIC).

In the example below, the atom in the slab at [1,0,0] is determined to be located across the periodic boundary at [1,1,0], which can cause the interpolation structure to be incorrect. In such cases, it is possible to correctly select atoms within the periodic boundary and interpolate.

Return to Top⏎

■general scheduler

General-purpose functions for controlling the computational system have been added.

• CellDeformationScheduler: A scheduler that controls cell deformation.
• LinerTemperatureScheduler: A scheduler that controls temperature changes.
• EarlyStopScheduler: A scheduler that allows you to set termination conditions to terminate MD early.

Return to Top⏎

■ convert trajectory

A function to convert ASE Trajectory objects to MDTraj and MDAnalysis object formats have been added.

Return to Top⏎

■initial structure construction

To simplify the construction of initial structures in LightPFP, we have added various scripts for creating initial structures.

Return to Top⏎