# Project Working Guide

## Purpose

This is an experimental MATLAB and Python demonstration project for
controlling and learning the Rigol DG5000 Pro series.

The code should be useful to engineers and scientists who may adapt the
demonstrations into more specific test and measurement applications.

This is demonstration code, not production software. Favor clarity,
flexibility, and educational value over elaborate architecture.

## User Background

The primary user has substantial, self-taught MATLAB experience, including
master-class work in matrix methods, Fourier analysis, signal processing,
statistics, visualization, and nonlinear fitting. He is rebuilding fluency
after using MATLAB less frequently for a period.

Do not explain basic programming concepts unnecessarily, but briefly explain
MATLAB features, instrument-control concepts, or design choices that may not
be obvious. Help the user rebuild fluency without assuming formal software
engineering training.

## MATLAB Problem-Solving Style

- Prefer MATLAB array and matrix operations over scalar, element-by-element
  loops when the calculation is naturally array-oriented.
- Prefer logical indexing when a logical mask is sufficient. Use `find` only
  when numeric indices are actually needed.
- Before writing a loop, consider colon indexing, logical masks, implicit
  expansion, `reshape`, `sum`, `mean`, `any`, `all`, and related array tools.
- Retain loops when they clearly express a sequential, iterative, stateful, or
  moving-window algorithm. A short-time Fourier transform loop over time
  windows is a good example.
- Preallocate outputs when a loop is appropriate.
- Make array dimensions and row-versus-column orientation explicit.
- Distinguish matrix operations (`*`, `/`, `\`, `'`) from element-wise
  operations (`.*`, `./`, `.^`) and nonconjugating transpose (`.'`).
- Prefer solving a system with `A\b` over explicitly forming `inv(A)*b`.
- Do not replace an educational manual algorithm with a one-line toolbox
  function without explaining the relationship between them.

## Code Style

- Keep the main script readable from top to bottom.
- Put connection settings and primary user configuration near the top.
- Use local functions for validation, error translation, and repetitive work.
- Comment why something is necessary, especially for instrument-specific
  behavior.
- Do not comment statements whose meaning is already obvious.
- Prefer descriptive names over explanatory comments.
- Avoid premature object-oriented design.
- Preserve flexibility for engineers to adapt the demonstrations.
- Preserve MATLAB or Python's complete native error report unless a shorter
  error is a stated goal.
- Leave instrument outputs in a deliberate, documented state after success
  or failure.

## MATLAB Reference Library

The optional course-note PDFs linked from `references/SOURCE_LINKS.md` are
substantive technical references, not merely evidence of prior education.
Their explanations, illustrations, manual algorithms, and creative
applications may influence the design of new work.

Start with:

- `references/MATLAB_REFERENCE_INDEX.md` for topic and page routing.
- `references/MATLAB_SIGNATURE_METHODS.md` for methods that should not be
  reduced to generic MATLAB advice.
- `MATLAB_STYLE.md` for coding and explanation preferences.

Route topics as follows:

- General MATLAB, visualization, functions, statistics, fitting, and broad
  problem solving: `MasterMATLABGuidedProblems_CourseNotes.pdf`
- Fourier theory, scaling, phase, stationarity, short-time Fourier analysis,
  and 2D transforms: `MasterTheFourierTransformMATLABPython.pdf`
- Denoising, filters, convolution, wavelets, resampling, outliers, and feature
  detection: `SignalProcessingProblemsMATLABPython.pdf`
- Vectors, matrices, rank, matrix spaces, systems, determinants, inverses, and
  projections: `Incomplete linear algebra3.pdf`

Before designing Fourier, signal-processing, matrix-analysis, fitting, or
visualization work:

1. Search the index for relevant pages.
2. Download and read the relevant PDF sections when their details or figures
   would materially help the task.
3. Consider both the instructional/manual method and current MATLAB
   functions.
4. State when a design is materially influenced by a reference-note method.
5. Verify release-sensitive APIs and instrument behavior against current
   authoritative documentation.

Do not download or read all 628 pages for every task. Use the index to retrieve
only the sections relevant to the current problem.

## User-Directed Experimental Loop

This project uses **Cycles of Efficiency™**, Ron Fredericks's name for a
user-directed process in which curated technical knowledge informs code, code
controls an experiment, independent measurements evaluate the result, and
validated findings improve the knowledge available to the next cycle. The
name and an earlier form of the concept appeared in a 2005 Embedded
Components, Inc. LectureMaker service brochure.

Use this nine-step loop when the available environment and user authorization
support it:

1. Define the experiment, expected outcome, and hardware limits.
2. Expand the reference library when useful. Add or link only an authorized
   source; record its attribution and reuse terms; index its relevant pages or
   sections; and preserve distinctive methods in the appropriate guide.
3. Consult this file, the project README, reference indexes, prior
   retrospectives, and only the source sections relevant to the task.
4. Develop or revise code within the bounded project folder.
5. Obtain explicit user approval before consequential hardware operations.
6. Execute through MATLAB or a Python terminal and inspect program output and
   instrument read-back.
7. Independently observe the physical result with an oscilloscope,
   measurement badges, or another suitable instrument.
8. Compare the requested settings, instrument read-back, and independently
   measured behavior.
9. Incorporate validated findings into the code, indexes, documentation, and
   project retrospective before beginning the next cycle.

Project references provide contextual retrieval, not permanent model
training. Access to development environments, network instruments, and
instrument displays is session-specific and user-authorized. Reading this
file does not grant hardware or computer-control access. In this project,
MATLAB or Python communicates with the Rigol over TCP; an authorized AI
coworker may operate the development environment and observe Rigol and
Tektronix displays, while the user remains in control between consequential
steps.

## Collaboration Preferences

The user can become absorbed in peripheral tooling or configuration problems.
When this occurs, respectfully flag possible project drift and recommend the
shortest practical route back to the main objective.

When this appears to be happening, respectfully and directly flag it using
language such as:

> Possible project drift: this issue is peripheral to the current goal.
> The shortest path forward is ...

Do not call the user’s concern unimportant or stupid. Distinguish between:

- a problem that affects the technical result;
- a useful learning investigation;
- tooling friction that can safely be bypassed.

If a tooling problem consumes several attempts without advancing the project,
recommend the simplest practical workaround early.

Be direct when complexity is growing without providing proportional value.

## File Handling

- Treat the current contents saved on disk as the source of truth.
- Re-read a file before modifying it, especially after the user has tested it.
- Preserve manual edits unless they conflict with the requested change.
- Never overwrite an existing revision unless explicitly instructed.
- Create the next available `_TkN` revision.
- For example, after `_Tk2.m`, create `_Tk3.m`.
- Report the exact source file read and the new file created.
- Do not delete prior revisions.

## Scope

Before adding architecture, dependencies, or abstractions, consider whether
they improve the demonstration’s clarity or adaptability.

If a requested change materially expands the project, identify the expansion
before implementing it.
