CLAUDE

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is an Obsidian vault focused on CERN accelerator physics research, specifically hysteresis modeling for the SPS (Super Proton Synchrotron). The vault follows a PARA-inspired organizational system with numbered areas and MOC (Maps of Content) structure.

Vault Organization System

Core Structure

• 00-System/ - Infrastructure files, templates, inbox, attachments, archive
• 01-Projects/ - Active research projects with deadlines
• 02-Areas/ - Ongoing research areas (A.00-A.05 naming convention)
• 03-Meetings/ - Meeting notes and discussions
• 04-Resources/ - Reference materials and documentation

Key Research Areas (02-Areas/)

• A.00 - Hysteresis Modeling/ - Neural network models for magnetic hysteresis prediction
• A.01 - Magnetic Measurements/ - Experimental validation and measurement campaigns
• A.02 - SPS Operations/ - Accelerator operations and beam studies
• A.03 - MDs/ - Machine Development sessions and beam time studies
• A.04 - Compensation Infrastructure/ - Real-time control systems
• A.05 - Python/ - Development tools and scripts

Critical File Patterns

MOC (Maps of Content) Files

• MOC - Hysteresis Modeling.md - Central hub for all ML/physics modeling work
• MOC - Machine Development.md - Central hub for beam studies and MD sessions
• These files use Dataview queries to dynamically link related content

Dataset Organization

• Multiple dataset versions (v3-v9) with evolutionary improvements
• Dipole datasets v9.md is the current production version
• Individual MBI (Main Bending magnet I) dataset files follow pattern: MBI Dataset - [CYCLE_A]___[CYCLE_B].md
• 148+ individual dataset files organized by supercycle transitions

Model Naming Convention

• Neural network models: TFT-6, TFLSTM-15, TFTMBI-176 (increasing numbers indicate newer versions)
• Models stored in 02-Areas/A.00 - Hysteresis Modeling/A.00.1 - experiments/Models/

Machine Development (MD) Sessions

• Pattern: Dedicated MD YYYY-MM-DD.md or Parallel MD YYYY-MM-DD.md
• Planning → Execution → Results → Lessons Learned structure
• Associated datasets: Dataset MD YYYY-MM-DD.md

Development Workflows

Adding New Research Content

1. Use appropriate templates from 00-System/Templates/
2. Follow frontmatter conventions with tags, dates, and status
3. Update relevant MOC files with new content links
4. Add attachments to 00-System/Attachments/ with descriptive names

Dataset Management

• Current datasets live in 02-Areas/A.00 - Hysteresis Modeling/A.00.4 - Data/Datasets/
• Archive old versions rather than deleting them
• Use descriptive names rather than generic “Untitled” or “Pasted image”

Experimental Documentation

• Document model experiments in A.00.1 - experiments/ with version numbers
• Include hyperparameters, training data, and results in frontmatter
• Link to relevant datasets and MD sessions

File Naming Conventions

Standard Patterns

• Daily notes: YYYY-MM-DD.md
• MD sessions: [Type] MD YYYY-MM-DD.md
• Datasets: Dataset [Description] v[N].md or Dataset MD YYYY-MM-DD.md
• Models: [Architecture][Identifier]-[Version].md
• MOC files: MOC - [Topic].md

Attachment Naming

• Use descriptive names: fig_hysteresis_prediction_2024_07.png
• Avoid generic names: “Untitled.png”, “Screenshot.png”, “Pasted image.png”
• Include dates for time-sensitive content

Dataview Integration

The vault extensively uses Dataview plugin for dynamic content:

• MOC files contain automated lists of related content
• Task management through Dataview queries
• Filtering by status, tags, and creation dates
• Examples in Home.md and MOC files

Inbox Processing

• 00-System/Inbox/ contains unprocessed items (typically 40+ files)
• Weekly processing recommended to move items to appropriate areas
• Use tags and frontmatter to categorize before moving

Archive Strategy

Active Archiving

• Archive old dataset versions to 00-System/Archive/datasets/
• Archive completed daily notes older than 6 months
• Archive superseded model versions while preserving training history

Version Control

• Keep current version as primary file
• Archive old versions rather than deleting
• Document evolution and key changes in primary file

Physics Domain Context

Core Research Focus

• Hysteresis Modeling: Neural networks (TFT, LSTM) for magnetic field prediction
• SPS Operations: Super Proton Synchrotron beam dynamics and control
• Magnetic Measurements: Physical validation of computational models
• Real-time Compensation: Operational deployment of ML models

Key Technical Concepts

• Supercycles: Beam acceleration patterns (SFT→LHC, AWAKE, HiRadMat)
• MBI/MQ: Main Bending/Quadrupole magnets with hysteresis effects
• BCT/BPM: Beam Current Transformers/Beam Position Monitors
• MD Sessions: Machine Development time for experimental validation

External Dependencies

• NXCALS data acquisition system
• LSA (LHC Software Architecture) integration
• FESA (Front-End Software Architecture) for real-time control
• Various Python packages: transformertf, hysteresis-scripts, pyda-nxcals

Special Considerations

Data Sensitivity

• Some content may contain operational parameters for CERN accelerators
• Maintain appropriate confidentiality for unpublished research
• Archive rather than delete historical measurement data

Cross-linking Strategy

• Heavy use of [[wiki-style]] links between related content
• MOC files serve as navigational hubs
• Dataview queries provide dynamic relationship discovery

Maintenance Schedule

• Weekly: Process inbox, update active MOCs
• Monthly: Archive completed work, update project status
• Quarterly: Review organizational structure, consolidate versions

This vault represents active physics research with iterative model development, experimental validation, and operational deployment cycles.

• use math for any greek characters, never use unicode characters over latex for mathematical expressions.