jkitchin Electronic Lab Notebook (ELN) Skill
This skill provides expert guidance for maintaining professional electronic lab notebooks using org-mode, following best practices for scientific documentation, reproducibility, and research integrity.
When to Use This Skill
Use this skill when:
- Creating or updating lab notebook entries
- Documenting experiments, calculations, or analyses
- Recording hypotheses and experimental design
- Documenting computational workflows
- Summarizing results and drawing conclusions
- Organizing research notes chronologically
- Creating cross-references between related work
- Preparing documentation for publications or reports
- Ensuring reproducibility of scientific work
- Maintaining professional research records
Core Principles of Scientific Documentation
1. Chronological Organization
Entries are organized by date in a hierarchical structure:
notebook/
├── 2025/
│ ├── 01-January/
│ │ ├── 2025-01-15.org
│ │ └── 2025-01-20.org
│ └── 02-February/
│ └── 2025-02-03.org
2. Complete Documentation
Each entry should contain:
- What was done: Detailed description of work
- Why it was done: Hypothesis, motivation, reasoning
- How it was done: Methods, procedures, parameters
- What was observed: Results, data, observations
- What it means: Analysis, interpretation, conclusions
- Next steps: Follow-up work, questions raised
3. Reproducibility
Documentation should enable anyone (including future you) to:
- Understand the reasoning behind decisions
- Reproduce the work exactly
- Access all data and code used
- Follow the chain of logic
4. Professional Standards
- Write clearly and professionally
- Be honest about failures and unexpected results
- Date and timestamp all entries
- Never delete or modify past entries (make corrections with new entries)
- Include sufficient detail for independent reproduction
Org-Mode ELN Structure
File Organization
Date-Based Files
Each day's work goes in a dated file:
2025-01-15.org # Single day's work
Directory Structure
research-notebook/
├── 2025/
│ ├── 01-January/
│ │ ├── 2025-01-15.org
│ │ ├── 2025-01-16.org
│ │ └── data/
│ │ └── 2025-01-15/
│ │ ├── experiment_results.csv
│ │ └── analysis.png
│ └── 02-February/
├── templates/
│ ├── experiment-template.org
│ └── calculation-template.org
├── index.org # Master index
└── README.org # Project overview
Entry Template Structure
#+TITLE: Lab Notebook - 2025-01-15
#+AUTHOR: Your Name
#+DATE: [2025-01-15 Wed]
#+FILETAGS: :experiment:catalyst:
#+STARTUP: overview
* Daily Summary
Brief overview of what was accomplished today.
* Entry 1: Hypothesis Testing - CO Adsorption on Pt
:PROPERTIES:
:ID: 2025-01-15-001
:PROJECT: Catalyst_Screening
:STATUS: In_Progress
:RELATED: [[file:2025-01-10.org::*Previous Results]]
:END:
** Objective
What are you trying to accomplish and why?
** Hypothesis
Clear statement of what you expect and the reasoning.
** Background/Context
- Why is this important?
- What previous work led to this?
- What are the key questions?
** Methods
*** Computational Setup
Detailed description of how the work was performed.
#+BEGIN_SRC python
# Include actual code used
from ase.build import fcc111
slab = fcc111('Pt', size=(4,4,4), vacuum=10.0)
#+END_SRC
*** Parameters
- DFT functional: PBE
- Energy cutoff: 400 eV
- k-points: 4×4×1
- Convergence: 0.05 eV/Å
** Results
*** Observations
What actually happened? Include data, figures, output.
#+BEGIN_SRC python :results file
# Analysis code
import matplotlib.pyplot as plt
# ... plotting code ...
plt.savefig('data/2025-01-15/adsorption_energy.png')
return 'data/2025-01-15/adsorption_energy.png'
#+END_SRC
#+RESULTS:
[[file:data/2025-01-15/adsorption_energy.png]]
*** Data
| Metal | E_ads (eV) | Site |
|-------+------------+-------|
| Pt | -1.82 | fcc |
| Cu | -0.95 | hcp |
| Au | -0.45 | ontop |
** Analysis
*** Interpretation
What do these results mean?
*** Comparison with Literature
How do results compare with expected values?
*** Unexpected Findings
Anything surprising or anomalous?
** Conclusions
- Key findings
- Hypothesis supported/rejected
- Confidence level in results
** Issues/Problems
Document any problems encountered and how they were resolved.
** Next Steps
- [ ] Validate with different functional
- [ ] Test larger surface models
- [ ] Calculate reaction barriers
** References
- Previous work: [[file:2025-01-10.org::*Initial Screening]]
- Literature: Smith et al. (2024) DOI:10.1021/xxxxx
- Code: [[file:~/projects/catalyst-screening/run_calculations.py]]
* Entry 2: Another Task
...
Essential Org-Mode Features for ELN
1. Properties Drawer
:PROPERTIES:
:ID: unique-identifier
:PROJECT: Project_Name
:STATUS: Planning|In_Progress|Complete|On_Hold
:STARTED: [2025-01-15 Wed]
:COMPLETED: [2025-01-15 Wed]
:RELATED: [[link-to-related-entry]]
:DATA: [[file:./data/2025-01-15/results.csv]]
:END:
2. Tags
Use tags for categorization and filtering:
#+FILETAGS: :experiment:simulation:catalyst:DFT:
* Entry Title :important:urgent:
Common tag categories:
- Type: :experiment:, :simulation:, :analysis:, :literature:, :meeting:
- Topic: :catalyst:, :materials:, :synthesis:, :characterization:
- Status: :todo:, :in_progress:, :done:, :failed:
- Priority: :urgent:, :important:, :routine:
3. Links
# Internal links
[[file:2025-01-10.org::*Previous Results]]
[[id:2025-01-15-001]]
# External links
[[file:~/data/experiment_001.csv][Data file]]
[[https://doi.org/10.1021/xxxxx][Smith et al. 2024]]
# Code links
[[file:~/projects/analysis/plot_results.py]]
4. Code Blocks
#+BEGIN_SRC python :results output :session analysis :exports both
import pandas as pd
import matplotlib.pyplot as plt
# Reproducible analysis code
data = pd.read_csv('data/2025-01-15/results.csv')
print(f"Mean energy: {data['energy'].mean():.3f} eV")
#+END_SRC
#+RESULTS:
: Mean energy: -1.234 eV
5. Tables
| Parameter | Value | Units | Notes |
|----------------+-----------+-------+--------------------|
| Temperature | 300 | K | Room temperature |
| Pressure | 1 | atm | Standard |
| Coverage | 0.25 | ML | 1/4 monolayer |
#+TBLFM: @2$4=Calculated from geometry
6. TODO Items and Checkboxes
** Next Steps
- [ ] Run convergence test for k-points
- [ ] Compare with experimental data from Lee et al.
- [X] Calculate adsorption energy
- [ ] Write up results for group meeting
** TODO Validate results with different functional
DEADLINE: <2025-01-20 Fri>
:PROPERTIES:
:EFFORT: 2h
:END:
7. Timestamps
# Active timestamps (appear in agenda)
* Meeting with advisor
<2025-01-20 Fri>
# Inactive timestamps (documentation only)
Calculation started [2025-01-15 Wed]
# Date ranges
Project duration: <2025-01-10 Mon>--<2025-01-30 Mon>
Common Entry Types
1. Experimental/Computational Work
* DFT Calculation - Surface Relaxation
:PROPERTIES:
:ID: 2025-01-15-001
:PROJECT: Catalyst_Screening
:TYPE: Calculation
:STATUS: Complete
:END:
** Objective
Optimize the geometry of clean Pt(111) surface.
** Methods
- Calculator: VASP
- Functional: PBE
- ENCUT: 400 eV
- k-points: 6×6×1 Monkhorst-Pack
- Convergence: Forces < 0.05 eV/Å
#+BEGIN_SRC bash
# Command used
vasp_std > vasp.out
#+END_SRC
** Results
- Final energy: -123.45 eV
- Relaxation time: 2.5 hours
- Converged in 45 ionic steps
[[file:./data/2025-01-15/surface_relaxation.png]]
** Analysis
Surface atoms relaxed inward by 0.03 Å (0.8% contraction).
This agrees with literature values (Smith 2023: 0.02-0.04 Å).
** Conclusion
Surface structure validated. Ready for adsorbate calculations.
** Next Steps
- [ ] Add CO adsorbate at FCC site
- [ ] Calculate adsorption energy
2. Literature Review Entry
* Literature Review - CO Oxidation Mechanisms
:PROPERTIES:
:ID: 2025-01-15-002
:TOPIC: Catalysis
:STATUS: Complete
:END:
** Paper
Smith, J. et al. (2024) "CO Oxidation on Platinum Surfaces"
J. Phys. Chem. C, DOI: 10.1021/xxxxx
** Key Findings
- CO adsorption energy on Pt(111): -1.5 to -1.8 eV (experimental)
- Preferred site: FCC hollow
- Barrier for CO → CO₂: 0.8 eV
** Relevance to Our Work
Their experimental values provide validation targets for our DFT calculations.
Our predicted -1.82 eV is in excellent agreement.
** Questions Raised
- How does coverage affect binding energy?
- What about stepped surfaces?
** References to Follow Up
- [ ] Lee et al. (2023) - Coverage effects
- [ ] Zhang et al. (2024) - Step sites
3. Data Analysis Entry
* Analysis - Comparing Different Functionals
:PROPERTIES:
:ID: 2025-01-15-003
:PROJECT: Method_Validation
:STATUS: Complete
:END:
** Objective
Compare PBE, PBE+D3, and RPBE for CO adsorption energies.
** Data Sources
- PBE: [[file:2025-01-10.org::*PBE Results]]
- PBE+D3: [[file:2025-01-12.org::*Dispersion Results]]
- RPBE: [[file:2025-01-14.org::*RPBE Calculations]]
** Analysis Code
#+BEGIN_SRC python :results file
import pandas as pd
import matplotlib.pyplot as plt
# Compile results
data = {
'Functional': ['PBE', 'PBE+D3', 'RPBE'],
'E_ads': [-1.82, -2.15, -1.45],
'Experiment': [-1.6, -1.6, -1.6]
}
df = pd.DataFrame(data)
# Plot
plt.figure(figsize=(8, 5))
plt.bar(df['Functional'], df['E_ads'], alpha=0.7, label='Calculated')
plt.axhline(y=-1.6, color='r', linestyle='--', label='Experiment')
plt.ylabel('Adsorption Energy (eV)')
plt.legend()
plt.tight_layout()
plt.savefig('data/2025-01-15/functional_comparison.png', dpi=300)
return 'data/2025-01-15/functional_comparison.png'
#+END_SRC
#+RESULTS:
[[file:data/2025-01-15/functional_comparison.png]]
** Findings
| Functional | E_ads (eV) | Error vs Expt (eV) |
|------------+------------+--------------------|
| PBE | -1.82 | -0.22 |
| PBE+D3 | -2.15 | -0.55 |
| RPBE | -1.45 | 0.15 |
#+TBLFM: $3=$2-(-1.6);%.2f
** Conclusions
- PBE gives reasonable agreement (within 0.22 eV)
- PBE+D3 overbinds significantly
- RPBE underestimates binding
- **Decision**: Use PBE for production calculations
** Impact on Previous Work
Need to note that PBE tends to overbind slightly when reporting results.
4. Meeting Notes
* Group Meeting - Project Discussion
:PROPERTIES:
:ID: 2025-01-15-004
:TYPE: Meeting
:ATTENDEES: Prof. Smith, Jane Doe, John Smith
:END:
** Agenda
1. Progress updates
2. Results discussion
3. Next steps
** My Update
Presented CO adsorption results on Pt(111):
- E_ads = -1.82 eV (PBE)
- Good agreement with experiment (-1.6 eV)
** Feedback
- Prof. Smith: Test with larger surface to check size effects
- Jane: Compare with her experimental values (coming next week)
- Need to include dispersion for comparison
** Action Items
- [ ] Run calculations with 6×6×4 slab
- [ ] Prepare summary for Jane's experimental comparison
- [ ] Read paper Prof. Smith suggested: Zhang et al. 2024
** Next Meeting
<2025-01-22 Wed 10:00>
5. Problem/Debugging Entry
* Troubleshooting - VASP SCF Convergence Issues
:PROPERTIES:
:ID: 2025-01-15-005
:TYPE: Problem
:STATUS: Resolved
:END:
** Problem
VASP calculation not converging after 100 SCF steps.
Error message:
#+BEGIN_EXAMPLE
WARNING: Sub-Space-Matrix is not hermitian in DAV
#+END_EXAMPLE
** Attempted Solutions
1. Increased NELM to 200 - Still failed
2. Changed ALGO from Fast to Normal - No improvement
3. Reduced SIGMA from 0.2 to 0.1 - Failed
4. **Solution**: Used ISMEAR=0 (Gaussian smearing) instead of ISMEAR=1
** Root Cause
System has a band gap. Methfessel-Paxton smearing (ISMEAR=1) is inappropriate.
Gaussian smearing (ISMEAR=0) is better for molecules and systems with gaps.
** Resolution
Changed INCAR:
#+BEGIN_EXAMPLE
ISMEAR = 0
SIGMA = 0.05
#+END_EXAMPLE
Calculation converged in 45 SCF steps.
** Lessons Learned
- Always check if system has a gap before choosing smearing
- For molecules/insulators: Use ISMEAR=0 or ISMEAR=-5
- For metals: ISMEAR=1 or 2 is appropriate
** References
- VASP Wiki: [[https://www.vasp.at/wiki/index.php/ISMEAR]]
Best Practices
1. Daily Summaries
Start each file with a brief summary:
* Daily Summary
Today focused on validating DFT functional choice for catalyst project.
Compared PBE, PBE+D3, and RPBE against experimental data. Concluded
that PBE gives best agreement. Started large-scale screening of FCC
metals.
Key accomplishment: Validated methodology for production runs.
Main challenge: VASP convergence issues with molecular systems (resolved).
2. Honest Documentation
** Results
Expected: E_ads ≈ -1.5 eV
**Observed: E_ads = -0.45 eV**
This is significantly different from literature values.
** Analysis of Discrepancy
Possible causes:
1. Wrong adsorption site? → Checked: FCC is correct
2. Insufficient k-points? → Tested 8×8×1: -0.46 eV (no change)
3. Functional issue? → Literature used PBE, we used PBE
4. **Surface coverage?** → Our 1/16 ML vs literature 1/4 ML
** Resolution
Rerun with higher coverage to match literature conditions.
Original calculation still valid for low-coverage limit.
3. Version Control Integration
** Computational Details
Code version: catalyst-tools v2.3.1
Git commit: a3f5e2b
#+BEGIN_SRC bash
git log -1 --oneline
#+END_SRC
#+RESULTS:
: a3f5e2b Fix convergence criteria in optimizer
4. Data Management
** Data Files
- Raw output: [[file:./data/2025-01-15/OUTCAR]]
- Processed data: [[file:./data/2025-01-15/results.csv]]
- Analysis notebook: [[file:./data/2025-01-15/analysis.ipynb]]
- Archived: ~/archives/2025/january/calculation_001.tar.gz
MD5 checksums:
- OUTCAR: 5d41402abc4b2a76b9719d911017c592
- results.csv: 7d793037a0760186574b0282f2f435e7
5. Cross-Referencing
** Related Work
- Background: [[file:2025-01-05.org::*Literature Review]]
- Previous attempt: [[file:2025-01-12.org::*Failed Calculation]] (explains why approach changed)
- Follow-up: [[file:2025-01-18.org::*Extended Analysis]]
- Project overview: [[file:../index.org::*Catalyst Screening Project]]
6. Reproducibility Checklist
Every computational entry should enable reproduction:
** Reproducibility Information
- [X] Software versions documented
- [X] Input files included or linked
- [X] Random seeds specified (if applicable)
- [X] Computational environment described
- [X] Data processing code included
- [X] Analysis scripts provided
- [X] Key outputs archived
Environment:
- VASP: 6.4.2
- Python: 3.11.4
- ASE: 3.23.0
- NumPy: 1.24.3
Search and Retrieval
Using Org-Mode Search
# Search by tag
C-c / m # Match tags
Search: experiment+DFT-failed
# Search by TODO
C-c / t # Show TODOs
# Search by text
C-c / r # Regex search
# Org-agenda
C-c a s # Search across all agenda files
Creating Index File
#+TITLE: Research Notebook Index
#+STARTUP: overview
* Projects
** [[file:2025/01-January/2025-01-15.org::*Catalyst Screening][Catalyst Screening Project]]
Started: [2025-01-05]
Status: Active
** Method Validation
Started: [2025-01-10]
Status: Complete
* Key Results
** [[file:2025/01-January/2025-01-15.org::*Functional Comparison][Best DFT Functional for CO Adsorption]]
Result: PBE preferred (error < 0.25 eV)
* Important Techniques
** [[file:2025/01-January/2025-01-12.org::*Convergence Testing][How to Test k-point Convergence]]
Templates
Quick Entry Template
* Short Description
:PROPERTIES:
:ID: YYYY-MM-DD-NNN
:END:
** What I Did
** Why
** Results
** Next Steps
Full Research Entry Template
* Project - Specific Task
:PROPERTIES:
:ID: YYYY-MM-DD-NNN
:PROJECT: Project_Name
:STATUS: In_Progress
:END:
** Objective
** Hypothesis
** Methods
** Results
** Analysis
** Conclusions
** Next Steps
Integration with Computational Workflows
Embedding Code
#+BEGIN_SRC python :results output :session :exports both
from ase.build import molecule
from ase.optimize import BFGS
mol = molecule('H2O')
# ... calculation code ...
print(f"Optimized energy: {mol.get_potential_energy():.3f} eV")
#+END_SRC
Capturing Output
#+BEGIN_SRC bash :results output
cd ~/calculations/calc_001
grep "energy" OUTCAR | tail -1
#+END_SRC
#+RESULTS:
: free energy = -123.456789 eV
Including Figures
#+CAPTION: CO adsorption energy vs coverage
#+NAME: fig:ads_energy
#+ATTR_ORG: :width 400
[[file:./data/2025-01-15/adsorption_plot.png]]
See Figure [[fig:ads_energy]] for trends.
Professional Writing Guidelines
1. Clarity
- Write complete sentences
- Use past tense for work done
- Use present tense for conclusions
- Avoid ambiguous pronouns
2. Precision
- Include units: "300 K" not "300"
- Specify parameters: "PBE functional" not "DFT"
- Quantify: "decreased by 15%" not "decreased significantly"
3. Organization
- Use hierarchical structure
- One concept per section
- Chronological within day
- Logical grouping across days
4. Completeness
- Include negative results
- Document failed attempts
- Explain unexpected outcomes
- Preserve troubleshooting notes
Response Patterns
When helping with ELN:
- Suggest appropriate structure for the entry type
- Ask clarifying questions about what was done, why, and outcomes
- Recommend org-mode features that fit the task
- Ensure reproducibility - check if enough detail provided
- Encourage cross-referencing to related work
- Format code and data properly
- Include metadata (properties, tags, timestamps)
- Maintain professional tone while being helpful
- Prompt for conclusions and next steps
- Suggest organizational improvements when appropriate
Common Scenarios
Starting New Project
* Project Initiation - Catalyst Screening Study
:PROPERTIES:
:ID: 2025-01-15-001
:PROJECT: Catalyst_Screening
:STATUS: Planning
:END:
** Project Goal
Identify optimal catalyst for CO oxidation through computational screening.
** Background
[Literature review, motivation]
** Approach
1. Validate methodology with Pt(111) benchmark
2. Screen FCC metals (Cu, Ag, Au, Pt, Pd, Ni)
3. Analyze trends using d-band model
4. Validate top candidates with experiments
** Success Criteria
- Identify 2-3 promising candidates
- Error < 0.3 eV vs experiment
- Complete by [2025-02-28]
** Initial Tasks
- [ ] Set up calculation framework
- [ ] Run Pt(111) benchmark
- [ ] Compare functionals
Documenting Failure
* Failed Attempt - NEB Calculation
:PROPERTIES:
:ID: 2025-01-15-006
:STATUS: Failed
:END:
** Objective
Calculate CO diffusion barrier on Pt(111).
** Approach
NEB with 7 images, climbing image method.
** Problem
Images diverged after 20 steps. Final image forces > 5 eV/Å.
** Analysis
Initial path guess was poor - CO moved through bulk instead of surface.
** Lessons Learned
- Need better initial path interpolation
- Check geometry of intermediate images before optimization
- Use more images (9-11) for surface diffusion
** Next Attempt
Will use improved path generation script and verify geometries.
Scheduled for [[file:2025-01-16.org][tomorrow]].
Archiving and Long-Term Storage
End-of-Month Summary
#+TITLE: January 2025 Summary
#+DATE: [2025-01-31]
* Overview
Completed validation of DFT methodology for catalyst project.
Screened 6 FCC metals for CO adsorption. Identified Pt and Pd as
most promising candidates.
* Key Accomplishments
- Validated PBE functional (error < 0.25 eV)
- Completed metal screening
- Resolved VASP convergence issues
* Data Generated
- 24 DFT calculations
- 180 GB raw data (archived to ~/archives/2025/january/)
- 6 publications figures prepared
* Next Month Goals
- Begin reaction barrier calculations
- Compare with experimental data from collaborators
- Draft results section for paper
Year-End Review
Create comprehensive summaries for easy retrieval and reporting.