SuperAPI AI Directory

edu-physics

General & other

View repository

Updated 10-15 20:05

About this skill

Physics → Interactive Teaching Webpage

What this skill produces

A single-page HTML (three columns) that can be opened directly in a browser:

  • Left column: problem statement + dynamic console — one variable-parameter slider (such as time t / angle θ / velocity v / temperature T) drives real-time recomputed physics quantities (position, velocity, acceleration, energy, momentum…), as well as an "identity indicator" (conservation law) or "state determination".
  • Middle column: step-by-step analysis (formulas use KaTeX), can be collapsed with one click to give the space to the board.
  • Right column: 2D Canvas dynamic physics board (trajectory trace + particle + vector arrows + waveform + light rays + electric field lines + grid coordinate axes), overlaid with a brush doodle toolbar.

Division of labor between edu-physics (2D) and edu-physics-3d

This skill (edu-physics) coversphysics scenarios that a 2D plane is sufficient to display. Whenever the physics quantities/directions/trajectories involvethree-dimensional space, or need to be observed from any angle, please use the separate edu-physics-3d skill (Three.js 3D board).

Scenario Skill to use Reason
Projectile motion, simple harmonic motion, waves edu-physics 2D is completely sufficient
Inclined plane block, collisions, circular motion edu-physics Motion within a plane
Electric field lines, equipotential surfaces, circuits edu-physics Planar field distribution
Gas state changes, thermodynamic cycles edu-physics PV diagram plane
Lorentz force F=qv×B edu-physics-3d The cross product direction is perpendicular to the plane, must be 3D
Right-hand rule visualization edu-physics-3d The force direction is perpendicular to the plane of v and B
Atomic orbital shapes edu-physics-3d s/p/d orbitals are three-dimensional spatial distributions
Crystal structure/lattice edu-physics-3d Three-dimensional spatial arrangement
Rigid body rotation/angular momentum edu-physics-3d The rotation axis is in three-dimensional space
Electromagnetic wave E/B orthogonal edu-physics-3d The two fields propagate orthogonally in three-dimensional space
Magnetic field (solenoid) edu-physics-3d Field lines are distributed in three-dimensional space

edu-physics outputs a 2D Canvas single-page HTML; edu-physics-3d outputs a Three.js 3D single-page HTML. The data island formats of the two differ (board vs board3d), see their respective SKILL.md for details.

Dependencies

No external dependencies(no physics engine needed, no sympy needed). The template engine template/board.html is a self-contained single-page HTML. As long as you can use Python 3 (the standard library is enough) for string replacement, that works, or you can directly inject JSON manually.

Workflow

Step 1: Determine the problem specification

Clarify:

  • Physics scenario: projectile motion/collision/oscillation/wave/refraction/electric field/gas change, etc.
  • Variable parameters: time t, angle θ, velocity v, temperature T, etc., determine the range and step size
  • Physical laws: equations of motion, Newton's laws, conservation of energy/momentum, gas state equation, etc.
  • Interaction paradigm: sliders control time/angle/parameters, observe changes in physical quantities + trajectory/vector/conservation verification
  • Language: output language follows the prompt language (Chinese/English)

Step 2: Design the physical system

This is the most critical step. Choose convenient system coordinates and write the parameterized expressions of the physical quantities.

Coordinate placement tips:

  • For projectile motion, use the launch point as the origin, with x horizontal to the right and y vertical upward
  • For simple harmonic motion, use the equilibrium position as the origin
  • For light refraction, place the interface on the x-axis
  • For an inclined plane, align it along the x-axis

Physical quantity construction patterns:

Scenario Coordinate scheme scalars sequence
Projectile motion Origin at the launch point vx=v₀cosθ, vy=v₀sinθ-gt, x=vx·t, y=vy·t-½gt²
Simple harmonic motion Equilibrium position at the origin x=A·cos(ωt+φ), v=-Aω·sin(ωt+φ), a=-Aω²·cos(ωt+φ)
Block on an inclined plane Inclined plane along the x-axis a=g(sinθ-μcosθ), v=at, s=½at²
Conservation of momentum Along the same straight line v1'=(m1-m2)v1/(m1+m2), v2'=2m1v1/(m1+m2)

Verify physical correctness(mental check):

  • Initial conditions: whether position, velocity, and energy are correct at t=0
  • Conservation check: whether mechanical energy Eₖ+Eₚ is constant
  • Boundary conditions: whether vy=0 at the highest point and x is correct when y=0 at the landing point

viewport range: leave a 10-15% margin to ensure the complete motion trajectory is visible on the canvas.

Step 3: Assemble the data and inject it into the template

📍 Output location & unique artifact: deliver to the useronly one .html, write tocurrent working directory (Path.cwd()). Do not leave any other files in cwd—build scripts (.py)、__pycache__, screenshots, etc. put temporary files all in /tmp or delete them after use. Also never write into the skill's own directory.

Data format(three-part JSON, see schema in template/board.html data island __LESSON_DATA__):

{
  "lesson": {
    "language": "zh-CN",
    "title": "页面标题",
    "problem": "<p>题面 HTML,公式用 $…$ / $$…$$</p>",
    "answer": "$E_k+E_p = \\text{const}$"
  },
  "steps": [
    { "title": "步骤一", "content": "<p>解析内容...</p>" },
  ],
  "board": {
    "view": { "xRange": [-1, 10], "yRange": [-1, 6] },
    "points": {
      "O": [0, 0],
      "P": ["v0*cos(theta*PI/180)*t", "v0*sin(theta*PI/180)*t-0.5*g*t*t"],
      // 速度矢量箭头末端 = 当前位置 + 速度方向(缩放),用表达式点驱动
      "Vtip": ["x+vx*0.3", "y+vy*0.3"]
    },
    "param": {
      "name": "t",
      "label": "时间 $t$ (s)",
      "min": 0, "max": 5, "step": 0.05,
      "value": 0, "unit": "s",
      "ticks": ["0", "2.5", "5"]
    },
    "scalars": [
      { "name": "v0", "expr": "10" },
      { "name": "theta", "expr": "45" },
      { "name": "g", "expr": "9.8" },
      { "name": "vx", "expr": "v0*cos(theta*PI/180)" },
      { "name": "vy", "expr": "v0*sin(theta*PI/180)-g*t" },
      { "name": "x", "expr": "vx*t" },
      { "name": "y", "expr": "vy*t-0.5*g*t*t" },
      { "name": "Ek", "expr": "0.5*(vx*vx+vy*vy)" },
      { "name": "Ep", "expr": "g*y" },
      { "name": "E", "expr": "Ek+Ep" }
    ],
    "derived": [
      // 质点 P(points 里定义的点默认按浅灰渲染;这里用 vector 叠加箭头更醒目)
      // 位移矢量:从原点指向质点
      { "type": "vector", "name": "r_vec", "from": "O", "to": "P", "color": "vecA", "label": "$\\vec{r}$" },
      // 速度矢量:从质点 P 指向 Vtip(随速度方向变化的箭头)
      { "type": "vector", "name": "v_vec", "from": "P", "to": "Vtip", "color": "vec", "label": "$\\vec{v}$" },
    ],
    "readouts": [
      { "id": "x", "label": "水平位移 $x$", "type": "expr", "expr": "x", "digits": 2, "color": "vecA" },
      { "id": "y", "label": "竖直位移 $y$", "type": "expr", "expr": "y", "digits": 2, "color": "vecB" },
      { "id": "vx", "label": "$v_x$", "type": "expr", "expr": "vx", "digits": 2, "color": "vecA" },
      { "id": "vy", "label": "$v_y$", "type": "expr", "expr": "vy", "digits": 2, "color": "vecB" },
      { "id": "Ek", "label": "$E_k = \\frac{1}{2}mv^2$", "type": "expr", "expr": "Ek", "digits": 2 },
      { "id": "Ep", "label": "$E_p = mgy$", "type": "expr", "expr": "Ep", "digits": 2 },
      { "id": "E", "label": "$E = E_k+E_p$", "type": "expr", "expr": "E", "digits": 4, "highlight": true }
    ],
    // 定值指示(机械能守恒)—— of 指向上面 readouts 里真实存在的 id "E"
    "constant": { "of": "E", "label": "$E_k+E_p \\equiv \\text{常数}$" },
    // trace 轨迹
    "trace": { "of": "P", "color": "locus" },
    // 图例
    "legend": [
      { "color": "locus", "text": "轨迹" },
      { "color": "vec", "text": "速度 $\\vec{v}$" },
    ]
  }
}

Build script method(Python, recommended): Place the build script in /tmp, directly perform string replacement:

#!/usr/bin/env python3
import json, sys
from pathlib import Path
sys.dont_write_bytecode = True

SKILL_DIR = Path(".claude/skills/edu-physics")
TEMPLATE = SKILL_DIR / "template" / "board.html"
PLACEHOLDER = "__LESSON_DATA__"

data = {
    "lesson": { ... },
    "steps": [ ... ],
    "board": { ... }
}

template = TEMPLATE.read_text(encoding="utf-8")
out_path = Path.cwd() / "solution-xxx.html"
out_path.write_text(
    template.replace(PLACEHOLDER, json.dumps(data, ensure_ascii=False)),
    encoding="utf-8"
)
print("written:", out_path)
python3 -B /tmp/build.py && rm -f /tmp/build.py

Note: if at runtime it prompts template/board.html the path is incorrect, please use an absolute path or derive it from Path(__file__) .

Step 4: Self-check and delivery

  • Physical correctness: verify the initial conditions at t=0, that conserved quantities remain constant, and that boundary conditions are correct
  • Browser preview: start a local static server, check that there are no console errors, KaTeX works properly, and slider interaction is smooth
    • When the slider is dragged, the particle moves along the expected trajectory
    • The trace trajectory curve is correct (parabola for projectile motion, sine wave for SHM, etc.)
    • Vector direction/magnitude changes correctly with parameters
    • The constant indicator remains constant throughout
  • Close the port: stop the local server immediately after preview ends
  • Cleanup: delete /tmp temporary scripts in , confirm that cwd contains only .html

Data Format Reference (Core Fields)

Key board Field Descriptions

Field Type Description
view {xRange, yRange} Mathematical coordinate viewport
points {name: [x,y] 或 {xy,color,label}} Key position coordinates
param {name, min, max, step, value, label, unit, ticks} Slider definitions
scalars [{name, expr}] Physical quantities derived from param
derived Construction sequence point / vector / segment / polygon, etc.
readouts [{id, label, type, ...}] Real-time physical quantity values
constant {of, label} Conservation law indicators
trace {of, color} Trajectory sampling (160 steps)
legend [{color, text}] Legend

Common readouts types

type Field Displayed content
expr expr, digits Any physical quantity expression
distance a,b (point) Distance between two points
coord of (point) Coordinates
status expr, rhs, okText, badText Boolean state determination (e.g. "overweight"/"weightless")

Common derived types

Note: After a particle position is defined in points , it is automatically rendered (default light gray); if you need to change the color/label, declare it in points using the {xy, color, label} form, rather than using derived's point(this type is not implemented). When velocity/force vectors change with the particle, a common approach: define an "arrow endpoint" point in points (coordinates using expressions), then use vector to point from the particle to it (see Vtip)。

type Field Effect
segment name, a, b, color, dashed Segment (light ray/electric field line/boundary)
vector name, from, to, color, label Displacement/force/field strength vector (name required)
polygon pts, color, stroke Semi-transparent fill (energy bar/region)
midpoint name, a, b Midpoint
line_through_points name, a, b, color Line through two points
line_through_slope name, point, slope, color Line through one point with slope

Color semantic names

curve(golden yellow) · line(cyan) · aux(gray auxiliary) · ptA(red) · ptB(blue) · point(light gray) · given(purple) · fixed(emerald green) · vecA(red) · vecB(blue) · locus(trajectory purple-red) · area(cyan semi-transparent). You can also write hex directly:#f87171 or rgba(248,113,113,0.25)。

Expression engine

Coordinate values/scalars in the expr supports:+ - * / ^ sqrt cbrt abs sin cos tan asin acos atan atan2 exp log pow min max sign floor ceil hypot PI Trigonometric functions useradians(angles must be converted first:theta*PI/180). Parameter names must be valid JS identifiers (e.g. t/v0/theta, cannot use θ and other non-identifiers).

KaTeX Formula Notes

KaTeX formulas in the course text (lesson.problem、steps[].content) and legend (legend[].text) use $...$(inline) or $$...$$(block) wrapping.

Known incompatible commands:

  • \\prescript — KaTeX does not support the mathtools package's \\prescript command. ✅ Use instead {}^{<上标>}_{<下标>}\\text{<基>}, e.g.: $\\left({}^{4}_{2}\\text{He}^{2+}\\right)$ → $\left({}^{4}_{2}\text{He}^{2+}\right)$

trace Trajectory System

After configuring board in trace: { of: "点名称", color: "颜色" } , the engine samples the [min, max] interval of param uniformly over 160 steps and draws the trajectory path for the specified point. Suitable for:

  • Parabolic trajectory of projectile motion
  • x-t curve of simple harmonic motion (horizontal axis time, vertical axis displacement)
  • Wave envelope

constant value indicator

Configuration constant: { of: "读数id", label: "标签" } Afterward, when the read value changes with the slider and remains constant as a fixed value, the page displays a green banner prompt. Applicable to:

  • Conservation of mechanical energy (Eₖ+Eₚ constant)
  • Conservation of momentum (m₁v₁+m₂v₂ constant)
  • Pythagorean theorem (a²+b²-c²≡0)
  • Other identities

Table of contents

  • template/board.html — Data-driven template (generic 2D renderer + parameter engine + data island __LESSON_DATA__)
  • references/conventions.md — Physics interaction paradigms, construction patterns, self-check checklist
  • examples/ — Example reference