# FeynCalc Migration Guide

This guide is for FeynCalc users moving QFT algebra, Feynman-rule, loop
integral, and amplitude workflows to Kalika.

Official source references used while preparing this guide:

- FeynCalc overview: <https://feyncalc.github.io/>
- FeynCalc `FeynAmpDenominator`:
  <https://feyncalc.github.io/FeynCalcBookDev/FeynAmpDenominator.html>
- FeynCalc `DiracSimplify`:
  <https://feyncalc.github.io/FeynCalcBook/DiracSimplify.html>
- FeynCalc `OneLoop`: <https://feyncalc.github.io/FeynCalcBookDev/OneLoop.html>

## Workflow Translation

| FeynCalc Workflow                          | Kalika Workflow                                                                                   | Notes                                                                      |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Mathematica expressions with QFT heads     | Typed QFT data structures and functions                                                           | Keep amplitudes as structured data as long as possible.                    |
| `GA`, `GAD`, `GS`, `GSD` gamma/slash heads | `gamma`, `slash`, `gamma5`, `diracChain`                                                          | Dimension and gamma5 scheme are explicit options.                          |
| `DiracTrace`, `DiracSimplify`              | `diracTrace`, `simplifyDiracChain`                                                                | Trace results report whether the expression was fully evaluated.           |
| `SUNSimplify`, color traces                | `suNColorAlgebra`, `colorTrace`, `colorTraceEvaluate`                                             | Color algebra lives beside QFT, not in a global Mathematica namespace.     |
| `FAD`, `SFAD`, `FeynAmpDenominator`        | `oneLoopScalarIntegral`, `scalarA0/B0/C0/D0`, `feynmanParameterPolynomial`                        | Kalika represents scalar integral families directly.                       |
| `OneLoop` / `TID`                          | `passarinoVeltmanReduce`, scalar integral evaluators, IBP helpers                                 | `OneLoop`-style monolithic evaluation is split into inspectable stages.    |
| FeynArts/FeynRules model path              | `createGaugeTheoryModel`, field definitions, `deriveFeynmanRules`, `toFeynRulesGaugeDeclarations` | Kalika can export declarations but keeps model construction in TypeScript. |
| Diagram display                            | `renderFeynmanDiagram`                                                                            | Rendering is in `@kalika/renderer`.                                        |

## Quick Mapping

| FeynCalc                      | Kalika Target                                                   | Notes                                                     |
| ----------------------------- | --------------------------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------- |
| `GA[mu]`, `GAD[mu]`           | `gamma("mu", "4"                                                | "D")`                                                     | Dimension is an argument instead of a separate head. |
| `GS[p]`, `GSD[p]`             | `slash("p", "4"                                                 | "D")`                                                     | Use consistent dimension choices through the chain.  |
| `GA[5]`                       | `gamma5()`                                                      | Gamma5 scheme is passed to simplification/trace calls.    |
| Noncommutative dot chains     | `diracChain([...])`                                             | Chains are explicit arrays of factors.                    |
| `DiracTrace[expr]`            | `diracTrace(chain, options)`                                    | Results include notes and `evaluated`.                    |
| `DiracSimplify[expr]`         | `simplifyDiracChain(chain, options)`                            | Use options for scheme and dimension symbol.              |
| `FAD[{q, m}]`                 | `scalarB0`, `oneLoopScalarIntegral`, or integral-family helpers | Choose scalar family by topology.                         |
| `TID[amp, q]`                 | `passarinoVeltmanReduce(integral)`                              | Tensor reduction is an explicit stage.                    |
| `FeynRule[...]` / model rules | `deriveFeynmanRules(model)`                                     | Use `createGaugeTheoryModel` and field definitions first. |
| Feynman diagram graphics      | `renderFeynmanDiagram(...)`                                     | Render after topology/model construction.                 |

## Dirac Algebra Pattern

```ts
import {
  diracChain,
  diracTrace,
  gamma,
  gamma5,
  simplifyDiracChain,
  slash,
} from '@kalika/quantum-field-theory';

const chain = diracChain([
  slash('p', 'D'),
  gamma('mu', 'D'),
  gamma5(),
  gamma('nu', 'D'),
]);
const simplified = simplifyDiracChain(chain, {
  scheme: 'BMHV',
  dimensionSymbol: 'd',
});
const trace = diracTrace(simplified, { scheme: 'BMHV', dimensionSymbol: 'd' });

console.log(trace.expression, trace.evaluated, trace.notes);
```

## Loop Integral Pattern

```ts
import {
  feynmanParameterPolynomial,
  oneLoopScalarIntegral,
  oneLoopTensorIntegral,
  passarinoVeltmanReduce,
  pvPropagator,
  scalarB0,
} from '@kalika/quantum-field-theory';

const b0 = scalarB0('p^2', 'm^2', 'm^2', { expansionOrder: 0 });
const scalar = oneLoopScalarIntegral('B0', ['p^2'], ['m^2', 'm^2']);
const polynomial = feynmanParameterPolynomial(scalar);

const tensor = oneLoopTensorIntegral({
  loopMomentum: 'q',
  propagators: [pvPropagator('q', 'm^2'), pvPropagator('q-p', 'm^2')],
  externalMomenta: ['p'],
  lorentzIndices: ['mu'],
});
const pv = passarinoVeltmanReduce(tensor);

console.log(b0.expression, polynomial, pv.expression);
```

## Model and Diagram Pattern

```ts
import {
  assignGaugeRepresentations,
  createGaugeTheoryModel,
  createLagrangianBuilder,
  defineDiracSpinor,
  deriveFeynmanRules,
  fundamentalRepresentation,
  productGaugeGroup,
  suGroup,
  u1Group,
  u1ChargeRepresentation,
  toFeynRulesGaugeDeclarations,
} from '@kalika/quantum-field-theory';
import { renderFeynmanDiagram } from '@kalika/renderer';

const em = u1Group('U1EM', 'e');
const color = suGroup(3, { name: 'SU3C', coupling: 'g_s' });
const gaugeGroup = productGaugeGroup('QED-plus-color', [em, color]);
const psi = defineDiracSpinor({ name: 'psi', symbol: 'psi', mass: 'm' });

const gaugeModel = createGaugeTheoryModel('QED-like model', gaugeGroup, [
  assignGaugeRepresentations(psi, [
    u1ChargeRepresentation(em, -1),
    fundamentalRepresentation(color),
  ]),
]);

const declarations = toFeynRulesGaugeDeclarations(gaugeModel, {
  U1EM: 'A',
  SU3C: 'G',
});
const lagrangian = createLagrangianBuilder('Dirac toy model')
  .addField(psi)
  .addMassTerm(psi)
  .build();

const rules = deriveFeynmanRules(lagrangian);
const diagram = renderFeynmanDiagram({
  vertices: [{ id: 'v1', x: 0, y: 0 }],
  edges: [],
});

console.log(declarations, rules, diagram.svg);
```

## Migration Checklist

- Split monolithic FeynCalc notebooks into model construction, algebra,
  reduction, evaluation, rendering, and phenomenology stages.
- Make dimensional regularization and gamma5 choices explicit in every Dirac
  algebra call.
- Preserve loop integral topology data before reducing to scalar expressions.
- Use `@kalika/hep-phenomenology` for PDG data, spectra, flavor, and observable
  comparisons after symbolic QFT work.
- Use `@kalika/typesetting` and `@kalika/notebooks` for publication exports
  rather than relying on Mathematica notebook formatting.
