diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index eb7508a..0e700d2 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -21,6 +21,26 @@ This is a work-in-progress (WIP) educational resource. Copilot is intended to he - **Data Directories**: `data/`, `psp/` contain supporting data files - **Configuration**: `anphon/` and related files for phonon calculations +### Book Branch + +The book branch contains a comprehensive LaTeX manuscript that provides the theoretical foundation for the course: + +- **LaTeX Source Files**: + - `book/main.tex` - Main manuscript file (246KB, ~4200 lines) containing comprehensive theoretical content + - `book/methods-old.tex` - Legacy manuscript file + +- **Supporting Figures and Diagrams**: + - Crystal structure diagrams: `crystal.pdf`, `lattice.pdf`, `brillouin.pdf` + - Material-specific examples: `BaTiO3.pdf` (barium titanate), `Fe2SiO4-1.pdf` and `Fe2SiO4-2.pdf` (iron orthosilicate), `FeSe.pdf` (iron selenide) + - Methodology illustrations: `diagram.pdf`, `gap-hyb.pdf` (hybrid functionals), `pseudopots-new.pdf` (pseudopotentials), `rare-earths.pdf`, `usp.pdf` (ultrasoft pseudopotentials) + - Other assets: `Jacob.jpg`, `Fxs.png` + +- **Book Content Structure**: + - **Introduction**: Historical development of DFT and ab initio methods, from Schrödinger equation to modern density functional theory + - **Chapter 1 - Electron Interactions**: Fundamental quantum mechanics, Hartree-Fock approximation, electronic correlations, homogeneous electron gas, hydrogen molecule example (Heitler-London method) + - **Chapter 2 - Stany elektronowe w krysztale** (Electronic States in Crystals, in Polish): Crystal lattices, Bravais lattices, reciprocal space, Bloch's theorem, band structure theory + - Additional chapters covering DFT theory, electronic structure methods, orbital-dependent functionals, insulators/semiconductors, electric polarization, van der Waals interactions, and many-body effects + ## Key Technologies - **Python 3**: Primary programming language @@ -28,6 +48,8 @@ This is a work-in-progress (WIP) educational resource. Copilot is intended to he - **ASE (Atomic Simulation Environment)**: Framework for atomic simulations - **NumPy/SciPy/Matplotlib**: Scientific computing and visualization libraries - **ABINIT**: Ab initio computational materials science calculator +- **LaTeX**: Document preparation system for the textbook manuscript +- **Quarto** (migration target): Modern publishing system for unified scientific content (notebooks and manuscripts) ## Coding Guidelines @@ -54,6 +76,15 @@ This is a work-in-progress (WIP) educational resource. Copilot is intended to he - Document any new dependencies clearly - Ensure compatibility with JupyterLab/Binder environments +### LaTeX Guidelines +- Follow standard LaTeX best practices for academic manuscripts +- Maintain consistency in mathematical notation throughout the document +- Use descriptive labels for equations, figures, and sections (e.g., `\label{eq:schrodinger}`, `\label{fig:crystal}`) +- Ensure all references and citations are properly formatted using BibTeX +- Keep figure files organized in the `book/` directory +- Use comments to mark sections requiring review (e.g., `% **[REVIEW NEEDED]**: Description of issue`) +- Preserve multi-language content structure (English and Polish sections), except when translating consecutive chapters by user request + ## What Copilot Should Help With ✅ **Technical tasks Copilot should assist with:** @@ -65,10 +96,16 @@ This is a work-in-progress (WIP) educational resource. Copilot is intended to he - Build and deployment configurations - Testing and validation scripts - Integration with JupyterLab/Binder environments +- LaTeX formatting and structure improvements +- Cross-referencing between notebooks and book content +- Figure and diagram organization in the book directory +- Build scripts for LaTeX compilation (if needed) +- Migration to Quarto-based publishing system (unify content where sensible, but not forcefully) ❌ **Academic tasks Copilot should NOT modify unless directly requested:** - Lecture content in PDF files - Physics equations and theoretical derivations +- Mathematical proofs and derivations in `main.tex` - Scientific conclusions or interpretations - Bibliography and references - Academic authorship information @@ -79,6 +116,8 @@ This is a work-in-progress (WIP) educational resource. Copilot is intended to he - Verify that computational examples produce expected physical results - Ensure backward compatibility with existing notebooks - Check that notebooks run successfully in Binder environment +- Verify LaTeX compilation succeeds without errors (for book branch) +- Ensure all figures referenced in LaTeX are present in book directory ## Special Considerations @@ -86,6 +125,22 @@ This is a work-in-progress (WIP) educational resource. Copilot is intended to he - **Reproducibility**: Random seeds and computational parameters should be documented - **Educational Value**: Changes should enhance learning, not just optimize code - **Environment**: Must work in both local JupyterLab and cloud Binder environments +- **Multi-language Content**: The book manuscript contains sections in English and Polish (Polish sections start at Chapter 2/Rozdział 2) +- **Branch Structure**: Main branch focuses on interactive materials; book branch adds comprehensive textbook manuscript +- **Figure Management**: Keep book figures organized and ensure LaTeX references are correct +- **Quarto Migration Goal**: The repository aims to migrate to a Quarto-based solution for unified publishing. Prioritize approaches that facilitate this transition and unify content structure where it makes sense, but avoid forced unification that compromises existing functionality + +## Branch-Specific Notes + +### Main Branch +- Focus: Interactive Jupyter notebooks and lecture PDFs +- Target: Hands-on computational exercises + +### Book Branch +- Focus: Comprehensive LaTeX textbook manuscript with supporting materials +- Target: Theoretical foundation and detailed methodology +- Key File: `book/main.tex` (main manuscript source) +- Build Process: LaTeX compilation to PDF (build system TBD) ## Contact and Context diff --git a/.github/workflows/README.md b/.github/workflows/README.md new file mode 100644 index 0000000..7f53d3d --- /dev/null +++ b/.github/workflows/README.md @@ -0,0 +1,70 @@ +# GitHub Actions Workflows + +## Build Book PDF + +The `build-book-pdf.yml` workflow automatically builds the LaTeX book manuscript into a PDF. + +### How it works + +1. **Triggers**: The workflow runs when: + - Changes are pushed to the `book` branch in the `book/` directory + - Pull requests target the `book` branch with changes in `book/` directory + - Manually triggered from the Actions tab + +2. **Build process**: + - Checks out the repository + - Uses the `xu-cheng/latex-action@v3` to compile the LaTeX document + - Runs `latexmk` which automatically handles multiple pdflatex passes for cross-references + - Compiles `book/main.tex` into `book/main.pdf` + +3. **Output**: + - The generated PDF is uploaded as a GitHub Actions artifact + - Artifacts are available for download from the Actions tab for 90 days + - Each workflow run creates a `book-pdf` artifact containing `main.pdf` + +### Accessing the PDF + +After a successful build: + +1. Go to the **Actions** tab in the GitHub repository +2. Click on the workflow run you're interested in +3. Scroll down to the **Artifacts** section +4. Download the `book-pdf` artifact (will be a .zip file containing main.pdf) + +### Manual triggering + +You can manually trigger a build: + +1. Go to **Actions** tab +2. Select **Build Book PDF** workflow +3. Click **Run workflow** button +4. Select the `book` branch +5. Click **Run workflow** + +### LaTeX packages + +The workflow uses a full TeX Live distribution that includes all required packages: +- graphicx, epsfig (for figures) +- amsmath (for mathematical notation) +- hyperref (for hyperlinks and cross-references) +- geometry (for page layout) +- longtable, dcolumn (for tables) +- bm (for bold math) +- And many more standard packages + +### Troubleshooting + +If the build fails: +1. Check the workflow logs in the Actions tab for error messages +2. Common issues: + - Missing figures: Ensure all PDF/PNG files referenced in main.tex are in the book/ directory + - LaTeX syntax errors: Check the error log for line numbers + - Missing bibliography: The workflow expects inline bibliography (using `\begin{thebibliography}`) + +### Future enhancements + +Possible improvements to consider: +- Add automatic release creation for tagged versions +- Generate and upload build logs +- Cache TeX Live packages for faster builds +- Add PDF validation/linting diff --git a/.github/workflows/build-book-pdf.yml b/.github/workflows/build-book-pdf.yml new file mode 100644 index 0000000..d3df582 --- /dev/null +++ b/.github/workflows/build-book-pdf.yml @@ -0,0 +1,56 @@ +name: Build Book PDF + +# Trigger the workflow on pushes and pull requests to the book branch +on: + push: + branches: + - book + paths: + - 'book/**' + pull_request: + branches: + - book + paths: + - 'book/**' + # Allow manual triggering from Actions tab + workflow_dispatch: + +jobs: + build-pdf: + runs-on: ubuntu-latest + + permissions: + contents: read + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Compile LaTeX document + uses: xu-cheng/latex-action@v3 + with: + root_file: main.tex + working_directory: book + # Use latexmk for automatic handling of multiple passes + args: -pdf -file-line-error -interaction=nonstopmode + latexmk_use_lualatex: false + latexmk_use_xelatex: false + latexmk_shell_escape: false + + - name: Check PDF was created + run: | + if [ -f book/main.pdf ]; then + echo "✓ PDF successfully created" + ls -lh book/main.pdf + else + echo "✗ PDF was not created" + exit 1 + fi + + - name: Upload PDF artifact + if: success() + uses: actions/upload-artifact@v4 + with: + name: book-pdf + path: book/main.pdf + retention-days: 90