circuit-tutor

Imported from zhuoshou111/circuit-tutor (AGENTS.md). Install upstream with npx skills add zhuoshou111/circuit-tutor. Copyright stays with the author.

AGENTS.md

Project Purpose

CircuitTutor is an open-source Python educational toolkit for undergraduate circuit analysis. It should help students understand complex impedance, phasor-domain calculations, and ideal RLC resonance through simple, readable code.

Repository Layout

.
|-- README.md
|-- LICENSE
|-- pyproject.toml
|-- AGENTS.md
|-- src/
|   `-- circuit_tutor/
|       |-- __init__.py
|       |-- impedance.py
|       |-- resonance.py
|       |-- phasor.py
|       |-- visualization.py
|       |-- schematics.py
|       |-- app.py
|       `-- cli.py
|-- examples/
|   |-- series_rlc_demo.py
|   `-- parallel_rlc_demo.py
|-- tests/
|   |-- test_impedance.py
|   `-- test_resonance.py
`-- docs/
    |-- formula_derivation.md
    |-- chinese_user_guide.md
    `-- roadmap.md

Python and Dependencies

• Use Python 3.10 or newer.
• Runtime and test dependencies are declared in pyproject.toml.
• Keep runtime dependencies minimal: numpy and matplotlib.
• Keep test dependencies in the dev optional dependency group; currently this is pytest.
• Keep Streamlit in the app optional dependency group unless a task explicitly changes packaging strategy.
• Do not add heavy dependencies unless the task explicitly requires them.

Local Installation

python -m pip install -e .

For development and tests:

python -m pip install -e ".[dev]"

For the Chinese Streamlit interface:

python -m pip install -e ".[app]"

Running Tests

python -m pytest -q

Running Examples

python examples/series_rlc_demo.py
python examples/parallel_rlc_demo.py

Running the Chinese Interface

streamlit run src/circuit_tutor/app.py

Coding Conventions

• Prefer simple, readable, student-friendly code.
• Use clear function names and docstrings.
• Keep formulas explicit.
• Keep CLI code thin; CLI commands should call package functions.
• Keep Streamlit UI code thin; app screens should call package calculation and plotting functions.
• Keep circuit diagram helpers simple and reusable; prefer Matplotlib over heavier diagram dependencies.
• Chinese educational UI text should be clear, concise, and suitable for undergraduate students.
• Avoid unrelated refactors.

Mathematical Correctness

• Do not silently change formulas.
• Preserve standard phasor conventions:
  • Z_R = R
  • Z_L = j*omega*L
  • Z_C = 1/(j*omega*C)
• Distinguish angular frequency in rad/s from frequency in Hz.
• Every formula implementation should be covered by tests.
• Educational derivations must be checked for mathematical consistency.

Documentation Requirements

• Keep README.md accurate for install, tests, examples, and CLI usage.
• Keep docs/formula_derivation.md consistent with implemented formulas.
• Keep docs/chinese_user_guide.md consistent with the Streamlit interface.
• Keep docs/roadmap.md focused on future work, not completed behavior.

Definition of Done

A task is done when:

• The requested files exist in the expected locations.
• Imports work from the installed package.
• Formula changes have tests.
• Documentation reflects user-facing changes.
• python -m pytest -q passes.
• Relevant examples or CLI commands run when touched.

Constraints

• Do not silently change formulas.
• Do not add unnecessary heavy dependencies.
• Do not create a web app unless explicitly requested.
• Prefer simple, readable, student-friendly code.
• Every formula implementation should be covered by tests.
• Educational derivations must be checked for mathematical consistency.