ASCICalculator¶

The main class for ASCI calculations.

Class Definition¶

`ASCICalculator` ¶

Main calculator for Activity-Stability-Cost Index (ASCI).

This class orchestrates the entire ASCI calculation workflow: 1. Load and validate catalyst data 2. Configure reaction-specific parameters 3. Score individual descriptors (activity, stability, cost) 4. Calculate unified ASCI metric 5. Rank and analyze results 6. Export data and statistics

The calculator automatically handles: - HER (Hydrogen Evolution Reaction) - CO2RR-CO (CO2 Reduction to CO) - CO2RR-CHO (CO2 Reduction via CHO pathway) - CO2RR-COCOH (CO2 Reduction via COOH pathway)

ATTRIBUTE	DESCRIPTION
`reaction`	Reaction type ('HER' or 'CO2RR') TYPE: `str`
`pathway`	Reaction pathway (e.g., 'CO', 'CHO', 'COCOH' for CO2RR) TYPE: `str`
`config`	Reaction configuration with optimal energies and parameters TYPE: `ReactionConfig`
`data`	Loaded catalyst data TYPE: `DataFrame or None`
`results`	Calculated ASCI results TYPE: `DataFrame or None`
`scoring_method`	Activity scoring method ('linear' or 'gaussian') TYPE: `str`
`verbose`	Print detailed progress information TYPE: `bool`

Examples:

Basic HER calculation:

>>> from ascicat import ASCICalculator
>>> 
>>> # Initialize for HER
>>> calc = ASCICalculator(reaction='HER', verbose=True)
>>> 
>>> # Load data
>>> calc.load_data('data/HER_clean.csv')
>>> 
>>> # Calculate ASCI with equal weights
>>> results = calc.calculate_asci(w_a=0.33, w_s=0.33, w_c=0.34)
>>> 
>>> # Get top 10 catalysts
>>> top10 = calc.get_top_catalysts(n=10)
>>> print(top10[['symbol', 'ASCI', 'activity_score', 'stability_score', 'cost_score']])

CO2RR calculation with specific pathway:

>>> # Initialize for CO2RR-CO pathway
>>> calc = ASCICalculator(reaction='CO2RR', pathway='CO', verbose=True)
>>> calc.load_data('data/CO2RR_CO_clean.csv')
>>> 
>>> # Calculate with activity-focused weights
>>> results = calc.calculate_asci(w_a=0.5, w_s=0.3, w_c=0.2, method='linear')
>>> 
>>> # Print summary
>>> calc.print_summary(n_top=20)

Comparing multiple pathways:

>>> # Compare different CO2RR pathways
>>> pathways = ['CO', 'CHO', 'COCOH']
>>> for pathway in pathways:
...     calc = ASCICalculator('CO2RR', pathway=pathway)
...     calc.load_data(f'data/CO2RR_{pathway}_clean.csv')
...     results = calc.calculate_asci()
...     print(f"{pathway}: Best ASCI = {results['ASCI'].max():.3f}")

Functions¶

`init(reaction, pathway=None, scoring_method='linear', verbose=True)` ¶

Initialize ASCICalculator.

PARAMETER	DESCRIPTION
`reaction`	Reaction type - must be 'HER' or 'CO2RR' - 'HER': Hydrogen Evolution Reaction (2H⁺ + 2e⁻ → H₂) - 'CO2RR': CO₂ Reduction Reaction (various pathways) TYPE: `str`
`pathway`	Specific reaction pathway (required for CO2RR): - 'CO': CO₂ → CO (ΔE_opt = -0.67 eV) - 'CHO': CO₂ → CH₃OH via CHO (ΔE_opt = -0.48 eV) - 'COCOH': CO₂ → HCOOH via COOH (ΔE_opt = -0.32 eV) For HER, pathway is automatically set to 'H_adsorption' TYPE: `str` DEFAULT: `None`
`scoring_method`	Activity scoring method (default: 'linear') - 'linear': Linear decay from optimum, computationally efficient - 'gaussian': Exponential decay, sharper discrimination TYPE: `(linear, gaussian)` DEFAULT: `'linear'`
`verbose`	Print detailed information during calculations (default: True) TYPE: `bool` DEFAULT: `True`

RAISES	DESCRIPTION
`ValueError`	If reaction is not 'HER' or 'CO2RR' If pathway is required but not provided If scoring_method is invalid

Examples:

>>> # HER calculation (pathway automatic)
>>> calc_her = ASCICalculator(reaction='HER')
>>> 
>>> # CO2RR-CO calculation (pathway required)
>>> calc_co = ASCICalculator(reaction='CO2RR', pathway='CO')
>>> 
>>> # With Gaussian scoring and quiet mode
>>> calc = ASCICalculator('HER', scoring_method='gaussian', verbose=False)

`load_data(file_path, validate=True)` ¶

Load catalyst data from CSV file.

Loads and validates catalyst database containing DFT descriptors and material properties. Automatically handles both HER and CO2RR data formats with appropriate validation.

PARAMETER DESCRIPTION

file_path

Path to CSV file containing catalyst data Required columns: - 'DFT_ads_E': Adsorption energy (eV) - activity descriptor - 'surface_energy': Surface energy (J/m²) - stability descriptor - 'Cost': Material cost ($/kg) - economic descriptor - 'symbol': Catalyst identifier - 'AandB': Detailed catalyst composition - 'reaction_type': Reaction name - 'optimal_energy': Sabatier optimum for this reaction - 'activity_width': Scoring width parameter

TYPE: str

validate

Perform data quality validation (default: True) Checks for: - Missing values - Out-of-range descriptors - Duplicate entries - Physical validity

TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
`DataFrame`	Loaded and validated catalyst data

RAISES	DESCRIPTION
`FileNotFoundError`	If data file doesn't exist
`ValueError`	If required columns are missing If data validation fails

Notes

Data Quality Checks: - Adsorption energies: |ΔE| < 10 eV (sanity check) - Surface energies: 0 < γ < 15 J/m² (physical bounds) - Costs: $0.01 < C < $1M per kg (reasonable range) - No missing values in critical columns - No duplicate catalysts

For HER data: Expected format includes bimetallic catalysts with various surface facets (111, 100, 110, etc.)

For CO2RR data: Expected format includes pathway-specific intermediates (CO*, CHO*, COOH*) with corresponding binding energies

Examples:

>>> # Load HER data
>>> calc = ASCICalculator('HER')
>>> data = calc.load_data('data/HER_clean.csv')
>>> print(f"Loaded {len(data)} HER catalysts")

>>> # Load CO2RR-CO data
>>> calc = ASCICalculator('CO2RR', pathway='CO')
>>> data = calc.load_data('data/CO2RR_CO_clean.csv')
>>> print(f"Loaded {len(data)} CO2RR-CO catalysts")

>>> # Load without validation (faster, but risky)
>>> data = calc.load_data('data/HER_clean.csv', validate=False)

`calculate_asci(w_a=0.33, w_s=0.33, w_c=0.34, method=None, show_progress=True)` ¶

Calculate Activity-Stability-Cost Index for all catalysts.

This is the MAIN CALCULATION METHOD that orchestrates: 1. Activity scoring (Sabatier principle) 2. Stability scoring (surface energy) 3. Cost scoring (economic viability) 4. Weighted integration into unified ASCI metric

PARAMETER	DESCRIPTION
`w_a`	Activity weight [0, 1] (default: 0.33) Higher values prioritize catalytic performance TYPE: `float` DEFAULT: `0.33`
`w_s`	Stability weight [0, 1] (default: 0.33) Higher values prioritize electrochemical durability TYPE: `float` DEFAULT: `0.33`
`w_c`	Cost weight [0, 1] (default: 0.34) Higher values prioritize economic viability Constraint: w_a + w_s + w_c must equal 1.0 TYPE: `float` DEFAULT: `0.34`
`method`	Activity scoring method (default: use initialized method) Override the method specified during initialization TYPE: `(linear, gaussian)` DEFAULT: `'linear'`
`show_progress`	Display progress bar during calculation (default: True) TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`DataFrame`	Results DataFrame with columns: - All original columns from input data - 'activity_score': Activity scores [0, 1] - 'stability_score': Stability scores [0, 1] - 'cost_score': Cost scores [0, 1] - 'ASCI': Combined ASCI scores [0, 1] - 'rank': Ranking (1 = best) Sorted by ASCI in descending order

RAISES	DESCRIPTION
`ValueError`	If data not loaded (call load_data first) If weights invalid or don't sum to 1

Notes

Weight Selection Guidelines:

Equal Weights (0.33, 0.33, 0.34) - DEFAULT
Unbiased exploratory screening
Recommended for initial surveys
Treats all objectives equally
Activity-Focused (0.5, 0.3, 0.2)
Performance-critical applications
Research/fundamental studies
When activity is limiting factor
Stability-Focused (0.3, 0.5, 0.2)
Long-term operation required
Harsh conditions (acidic/oxidizing)
Industrial durability emphasis
Cost-Focused (0.3, 0.2, 0.5)
Large-scale deployment
Earth-abundant materials priority
Economic viability critical

Scoring Details:

For HER (ΔE_opt = -0.27 eV): - Perfect binding at -0.27 eV → S_a = 1.0 - Too weak (ΔE > -0.12 eV) → S_a approaches 0 - Too strong (ΔE < -0.42 eV) → S_a approaches 0

For CO2RR-CO (ΔE_opt = -0.67 eV): - Perfect CO binding at -0.67 eV → S_a = 1.0 - Ag/Au typically near optimum

For CO2RR-CHO (ΔE_opt = -0.48 eV): - Optimal for methanol production - Cu-based catalysts often favorable

For CO2RR-COCOH (ΔE_opt = -0.32 eV): - Optimal for formic acid production - Sn/Pb-based catalysts perform well

Examples:

>>> # Basic HER calculation with equal weights
>>> calc = ASCICalculator('HER')
>>> calc.load_data('data/HER_clean.csv')
>>> results = calc.calculate_asci()  # Uses defaults
>>> print(f"Best ASCI: {results['ASCI'].max():.3f}")

>>> # CO2RR-CO with activity focus
>>> calc = ASCICalculator('CO2RR', pathway='CO')
>>> calc.load_data('data/CO2RR_CO_clean.csv')
>>> results = calc.calculate_asci(w_a=0.5, w_s=0.3, w_c=0.2)
>>> 
>>> # Get top catalyst
>>> top = results.iloc[0]
>>> print(f"Top catalyst: {top['symbol']}")
>>> print(f"  ASCI: {top['ASCI']:.3f}")
>>> print(f"  Activity: {top['activity_score']:.3f}")
>>> print(f"  Stability: {top['stability_score']:.3f}")
>>> print(f"  Cost: {top['cost_score']:.3f}")

>>> # Compare different weight scenarios
>>> scenarios = [
...     (0.33, 0.33, 0.34, 'Equal'),
...     (0.5, 0.3, 0.2, 'Activity'),
...     (0.3, 0.2, 0.5, 'Cost')
... ]
>>> for w_a, w_s, w_c, name in scenarios:
...     results = calc.calculate_asci(w_a, w_s, w_c)
...     top_cat = results.iloc[0]['symbol']
...     print(f"{name:10s}: {top_cat}")

`get_top_catalysts(n=10)` ¶

Get top N catalysts by ASCI score.

PARAMETER	DESCRIPTION
`n`	Number of top catalysts to return (default: 10) TYPE: `int` DEFAULT: `10`

RETURNS	DESCRIPTION
`DataFrame`	Top N catalysts sorted by ASCI score

RAISES	DESCRIPTION
`ValueError`	If results not calculated (call calculate_asci first)

Examples:

>>> calc = ASCICalculator('HER')
>>> calc.load_data('data/HER_clean.csv')
>>> calc.calculate_asci()
>>> top10 = calc.get_top_catalysts(n=10)
>>> print(top10[['rank', 'symbol', 'ASCI']])

`get_statistics()` ¶

Get statistical summary of results.

RETURNS	DESCRIPTION
`dict`	Statistics dictionary containing: - n_catalysts: Total number of catalysts - weights: Applied weights (w_a, w_s, w_c) - method: Scoring method used - asci: ASCI statistics (mean, std, min, max, median) - activity: Activity score statistics - stability: Stability score statistics - cost: Cost score statistics

Examples:

>>> stats = calc.get_statistics()
>>> print(f"Mean ASCI: {stats['asci']['mean']:.3f}")
>>> print(f"Best ASCI: {stats['asci']['max']:.3f}")

`print_summary(n_top=10)` ¶

Print comprehensive summary of results.

PARAMETER	DESCRIPTION
`n_top`	Number of top catalysts to display (default: 10) TYPE: `int` DEFAULT: `10`

Examples:

>>> calc.calculate_asci()
>>> calc.print_summary(n_top=20)

Quick Reference¶

Initialization¶

from ascicat import ASCICalculator

# For HER
calc = ASCICalculator(reaction='HER', verbose=True)

# For CO2RR with specific pathway
calc = ASCICalculator(reaction='CO2RR', pathway='CO')

# With custom configuration
from ascicat.config import create_custom_config
config = create_custom_config(name='OER', optimal_energy=1.6)
calc = ASCICalculator(config=config)

Parameters¶

Parameter	Type	Default	Description
`reaction`	str	Required	Reaction type ('HER', 'CO2RR')
`pathway`	str	None	Pathway for CO2RR ('CO', 'CHO', 'COCOH')
`config`	ReactionConfig	None	Custom configuration
`scoring_method`	str	'linear'	'linear' or 'gaussian'
`verbose`	bool	True	Print progress messages

Methods¶

load_data¶

Load catalyst data from file or DataFrame.

# From CSV file
calc.load_data('data/HER_clean.csv')

# From DataFrame
import pandas as pd
df = pd.read_csv('data/HER_clean.csv')
calc.load_data(df)

Parameters:

Parameter	Type	Description
`data_source`	str or DataFrame	Path to CSV or DataFrame

Returns: None (data stored in calc.data)

calculate_asci¶

Calculate ASCI scores for all catalysts.

results = calc.calculate_asci(
    w_a=0.33,      # Activity weight
    w_s=0.33,      # Stability weight
    w_c=0.34,      # Cost weight
    show_progress=True
)

Parameters:

Parameter	Type	Default	Description
`w_a`	float	0.33	Activity weight
`w_s`	float	0.33	Stability weight
`w_c`	float	0.34	Cost weight
`show_progress`	bool	True	Show progress bar

Returns: pd.DataFrame with columns:

Original data columns
activity_score - Activity score S_a
stability_score - Stability score S_s
cost_score - Cost score S_c
ASCI - Combined ASCI score
Sorted by ASCI (descending)

get_top_catalysts¶

Get top-ranked catalysts.

top10 = calc.get_top_catalysts(n=10)
top100 = calc.get_top_catalysts(n=100)

Parameters:

Parameter	Type	Default	Description
`n`	int	10	Number of top catalysts

Returns: pd.DataFrame with top n rows

get_statistics¶

Get summary statistics.

stats = calc.get_statistics()
print(stats['asci']['mean'])
print(stats['activity']['std'])

Returns: dict with nested dictionaries:

{
    'asci': {'mean', 'std', 'min', 'max', 'median'},
    'activity': {'mean', 'std', 'min', 'max', 'median'},
    'stability': {'mean', 'std', 'min', 'max', 'median'},
    'cost': {'mean', 'std', 'min', 'max', 'median'}
}

print_summary¶

Print formatted summary to console.

calc.print_summary(n_top=10)

Parameters:

Parameter	Type	Default	Description
`n_top`	int	10	Number of top catalysts to show

Properties¶

data¶

Access loaded data:

df = calc.data
print(f"Loaded {len(df)} catalysts")

config¶

Access reaction configuration:

print(calc.config.optimal_energy)
print(calc.config.activity_width)

results¶

Access latest calculation results:

results = calc.results  # Same as calculate_asci() return

Example Usage¶

from ascicat import ASCICalculator

# Initialize
calc = ASCICalculator(reaction='HER', verbose=True)

# Load data
calc.load_data('data/HER_clean.csv')

# Calculate with equal weights
results = calc.calculate_asci(w_a=0.33, w_s=0.33, w_c=0.34)

# Analyze
stats = calc.get_statistics()
print(f"Mean ASCI: {stats['asci']['mean']:.3f}")

# Get top catalysts
top20 = calc.get_top_catalysts(n=20)
print(top20[['symbol', 'ASCI', 'activity_score']])

# Print summary
calc.print_summary()

# Access data
print(f"Dataset size: {len(calc.data)}")
print(f"Optimal energy: {calc.config.optimal_energy} eV")

ASCICalculator¶

Class Definition¶

ASCICalculator ¶

Functions¶

__init__(reaction, pathway=None, scoring_method='linear', verbose=True) ¶

load_data(file_path, validate=True) ¶

calculate_asci(w_a=0.33, w_s=0.33, w_c=0.34, method=None, show_progress=True) ¶

get_top_catalysts(n=10) ¶

get_statistics() ¶

print_summary(n_top=10) ¶

Quick Reference¶

Initialization¶

Parameters¶

Methods¶

load_data¶

calculate_asci¶

get_top_catalysts¶

get_statistics¶

print_summary¶

Properties¶

data¶

config¶

results¶

Example Usage¶

`ASCICalculator` ¶

`init(reaction, pathway=None, scoring_method='linear', verbose=True)` ¶

`load_data(file_path, validate=True)` ¶

`calculate_asci(w_a=0.33, w_s=0.33, w_c=0.34, method=None, show_progress=True)` ¶

`get_top_catalysts(n=10)` ¶

`get_statistics()` ¶

`print_summary(n_top=10)` ¶