Defining the Project

A numerical project begins with a question, not with a collection of code. This lesson defines a noisy-line investigation and divides it into visible stages whose inputs, outputs, and responsibilities can be checked separately.

The project begins with a concrete question:

If measurements come from a line with some added noise, can a program recover a reasonable estimate of the line's slope?

This question is small enough to inspect from beginning to end. It also contains the main parts of a larger numerical project: create or obtain data, perform a calculation, inspect the evidence, and report a conclusion.

Begin with the question, not the code

A numerical project uses computation to answer a question about numbers. Code is part of the method, but writing code is not itself the goal.

For this project, choose input values x, generate measured values y, and fit a line of the form:

predicted y = slope * x

The data will contain noise: small variations that move measured values away from the exact line. For example, a line with slope 2 gives these clean values:

x:       0    1    2    3
clean y: 0    2    4    6

Measurements with noise might instead be:

x:        0.0    1.0    2.0    3.0
measured: 0.1    1.8    4.2    5.9

No measured point except the first needs to lie exactly on the line. The project therefore cannot test a candidate slope by asking whether every prediction is equal to every measurement. It needs a numerical measure of how far the predictions are from the measurements. A later lesson will use mean squared error for that comparison.

State what the project receives and produces

Before choosing functions, separate the values known before the run from the values produced by it.

The main inputs are:

  • the random seed;
  • the number of data points;
  • the true slope used to generate the synthetic data;
  • the amount of noise;
  • the candidate slopes to compare.

The main results are:

  • the generated x and y arrays;
  • the fitted slope;
  • the loss of the fitted slope;
  • a plot comparing measurements with predictions;
  • a saved summary of the run.

The true slope and fitted slope have different roles. The true slope is an input that defines the artificial data. The fitted slope is an estimate computed from the noisy measurements. Because this is synthetic data, the known true slope lets us check how close the estimate came to its target.

Divide the work into visible stages

The project follows this sequence:

question
   ↓
configuration
   ↓
data generation
   ↓
fitting
   ↓
inspection
   ↓
recorded result

Configuration collects choices made before the run. Data generation creates the measurements. Fitting compares candidate slopes. Inspection checks the result numerically and visually. The recorded result preserves the settings, fitted value, and evidence needed to understand the run later.

Each stage should have one clear responsibility. A function name can state that responsibility:

These calls are a plan, not yet a complete program. Their names show what each stage receives and produces without exposing every implementation detail.

Keep the configuration in one record

A dataclass can collect the choices that define one run:

The decorator @dataclass creates a small record class from the listed fields. The option frozen=True prevents code from assigning a different value to a field after the record is created. This makes the original run settings easier to preserve.

One configuration is then visible in one place:

A reader can now see the intended run without searching through several functions for separate constants.

Let main show the complete workflow

The main function coordinates the stages:

This code does not hide the order inside one large function. It shows the project at two levels:

  • main shows the overall investigation;
  • the called functions contain the details of individual stages.

The familiar main guard can start the workflow when the file is run as a script:

Run a small project skeleton

The following program uses temporary implementations so the complete flow can run before the real numerical methods are added. Edit the configuration and observe which printed values change.

Run the project stages in order

The helper functions are deliberately simple. Their return values make the data flow through main visible.

Ready to run.

The current data contains no noise, and the fitting function does not yet compare candidates. Those limitations are intentional and visible. The remaining lessons will replace one temporary stage at a time while preserving the overall workflow.

Separate coordination from calculation

The main function should coordinate the project rather than contain every calculation. This separation makes several useful questions easier to answer:

  • Which settings produced this result?
  • Where is the data created?
  • Which function selects the fitted slope?
  • Where is the plot produced?
  • What information is saved?

A single long block of code can produce the same number, but it makes these questions harder to answer and individual stages harder to test.

Exercise: Place the project stages in order

Which sequence matches the numerical project developed in this chapter?

Choose the project sequence

Select one choice, then check.

HintSeparate choices from results

Configuration is known before the run. A fitted value and report exist only after the data has been generated and analysed.

SolutionMove from configuration to a recorded result

The sequence is configuration → data generation → fitting → inspection → recorded result. Each stage receives information produced or selected by an earlier stage.

Exercise: Identify the project question

Which question best describes this project?

Choose the central question

Select one choice, then check.

HintName the unknown result

The true slope creates the synthetic data. The program must estimate that slope from measurements that do not lie exactly on the line.

SolutionEstimate the slope behind noisy measurements

The central question is whether the program can recover a reasonable line slope from noisy measurements. Generating arrays and noise supports that investigation but is not the final purpose.

Exercise: Separate an input from a result

Which value is produced by the project rather than chosen in its configuration?

Choose the produced value

Select one choice, then check.

HintUse the before-and-after distinction

The seed and noise scale are selected before the run begins.

SolutionThe fitted slope is a result

The fitted slope is computed from the noisy data. The seed and noise scale belong to configuration because they define how that data is generated.

Exercise: Choose one function responsibility

Which function call has one clear responsibility and makes its required values visible?

Choose the clearest function call

Select one choice, then check.

HintRead the name and arguments together

A reader should be able to infer the stage and see its main inputs from the call.

SolutionMake the fitting inputs explicit

fit_slope(x, y, candidate_slopes) names one calculation and exposes the measurements and candidates it uses. do_everything() hides both the stages and their data flow, while fit_slope() hides its dependencies.

Exercise: Complete the project coordinator

Complete main so it creates the data before fitting and passes the fitted result to the report. The finished program must print:

data points: 4
fitted slope: 2.0

Connect the project stages

Ready to run.

HintFollow the data dependencies

fit_slope needs the two values returned by make_data. report_result needs x and the value returned by fit_slope.

SolutionCoordinate the three stages in main

First unpack x and y from make_data(). Then compute fitted_slope from those arrays and pass x with the fitted value to report_result. The order follows the information needed by each function.

Keep the project question visible

When a numerical program becomes difficult to follow, return to four questions:

  1. What question is the program trying to answer?
  2. Which values are chosen before the run?
  3. Which stages transform those values into evidence?
  4. Which results and settings must be preserved?

These questions keep the code connected to the investigation. The next lesson will make the inputs, outputs, and checks of each stage more precise.