<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/">
  <channel>
    <title>Kanu, notes</title>
    <link>https://erickdonado.com/notes/</link>
    <description>Erick Donado's notes: machine learning, systems, and whatever I'm studying.</description>
    <language>en</language>
    <atom:link href="https://erickdonado.com/feed.xml" rel="self" type="application/rss+xml"/>
    <lastBuildDate>Mon, 02 Nov 2026 12:00:00 GMT</lastBuildDate>
    <item>
      <title>Learning to code when AI can write it for you</title>
      <link>https://erickdonado.com/notes/learning-to-code-when-ai-can-write-it/</link>
      <guid isPermaLink="true">https://erickdonado.com/notes/learning-to-code-when-ai-can-write-it/</guid>
      <pubDate>Mon, 02 Nov 2026 12:00:00 GMT</pubDate>
      <category>programming</category>
      <category>learning</category>
      <category>ai</category>
      <description>AI isn't replacing programmers, but it does change how you should learn. Pick a language for a reason, loop between syntax and projects, build without AI first, and use it as a tutor instead of a ghostwriter.</description>
      <content:encoded><![CDATA[<p>AI is not replacing software engineers overnight. It's a tool, and a very good one: it takes the repetitive parts of the job, the boilerplate and the clean-up, off people who already know what they're doing.</p><p>That last part is the catch. Ask an AI for something in a language you've never touched, and when the code it hands you is broken, you won't know where. So you paste the error back, it guesses again, and the two of you go in circles. Nobody in that conversation can read the code.</p><p>When you can program, three things change:</p><ul><li>you know what to ask for, so the AI actually speeds you up</li><li>you can tell when what it gave you is nonsense</li><li>you're not stuck when it's down, or when your credits run out</li></ul><p>Often the bug is so small that reading the code yourself is faster than three rounds with a chatbot. You created two objects in the wrong order, and you can see it in ten seconds. The AI can't, because it's focused on the task and doesn't know everything you know about how you want it done.</p><p>Someone who can code and uses AI well beats both the person who refuses to use it and the person who uses it blindly.</p><h2 id="pick-a-language-for-a-reason">Pick a language for a reason</h2><p>Before choosing a language, decide why you want to program. The field is huge, and different parts of it use different languages.</p><p>There's no bad language. There are languages that fit a job and languages that don't. For machine learning and data science that means Python: the libraries are there, and it's quick to try ideas in. You wouldn't write a neural network pipeline in C, and you wouldn't write an operating system in Python.</p><p>Ignore anyone who tells you their favorite language is the best one. Best for what?</p><h2 id="the-loop">The loop</h2><p>Learning to program is a loop with two steps:</p><ol><li><strong>Learn some syntax.</strong></li><li><strong>Build something with it.</strong></li></ol><p>Then back to step 1. There's no secret beyond that.</p>
<p><em><a href="https://erickdonado.com/notes/learning-to-code-when-ai-can-write-it/">Live figure, open the note to see it</a>: The whole method. Every pass around the loop, the projects get a little harder.</em></p>
<h3 id="learning-syntax">Learning syntax</h3><p>Syntax is the rules of a language: how you write a loop, a function, a class. Every language has its own, so even someone who knows five languages has to learn the rules of a sixth. What they have is speed. If you know Python, JavaScript comes easier, because both are scripting languages. If you know what a pointer is from C++, Rust's smart pointers make sense sooner.</p><p>Use a free site with exercises, like W3Schools or Codecademy, or just play with the language in your editor. You're ready to move on when you can declare functions, create objects, join strings and use the basic data structures without looking at a tutorial.</p><p>Learning a language is also learning:</p><ul><li><strong>what it's for</strong> (TypeScript for web apps, Rust for engines and operating systems)</li><li><strong>why it's built the way it is</strong> (one runs on an engine that interprets it, the other compiles down to the machine's own instructions)</li><li><strong>what that costs</strong> (what's fast, what's slow, and when it matters)</li></ul><p>If you commit to a language, look under the hood too: how function calls use the stack, why global variables cause trouble, how memory gets handed out and taken back. It's optional, and it will quietly make you better, because you'll notice when you're writing something wasteful. It's why computer science courses teach theory before building.</p><h3 id="building-projects">Building projects</h3><p>Don't know what to build? This is a great thing to ask an AI:</p><pre><code>For Python, give me 3 project ideas at each level: beginner,
intermediate and advanced. For each one, list the features
to build and the concepts I'll learn.</code></pre><p>You'll get nine projects, each with its features and what it teaches. The start of the answer looks something like this:</p>
<p><em><a href="https://erickdonado.com/notes/learning-to-code-when-ai-can-write-it/">Live figure, open the note to see it</a>: The answer names the project, what to build and what you'll learn from it. That last line is what makes it a study plan.</em></p>
<p>Build all nine, start to finish.</p><p>And here's the rule that matters: <strong>build them without AI help.</strong> The industry does lean on AI to write code now, and companies want more output than ever. That's exactly why you need the habit of thinking for yourself first. An AI is only as good as the person steering it.</p><p>When you get stuck, these have an answer for almost everything:</p><ul><li><strong>W3Schools</strong>: syntax with exercises</li><li><strong>GeeksforGeeks</strong>: an explanation of nearly every concept</li><li><strong>Stack Overflow</strong>: someone already asked your question, and got a blunt answer</li><li><strong>Codecademy</strong>: guided, step by step</li></ul><h2 id="if-you-do-use-ai-while-learning">If you do use AI while learning</h2><p>I teach programming, and I see the same thing every time: a student with an AI open finishes the exercise and still can't write the next one alone. The code got done; the learning didn't. A few rules keep that from happening.</p><p><strong>Try first, then ask.</strong> A broken attempt shows you exactly what you don't understand, and that makes your question good.</p><p><strong>Ask for explanations, not solutions.</strong> &quot;Why does this loop never end?&quot; teaches. &quot;Write me a loop that does X&quot; doesn't. Try telling it: &quot;don't give me the code, give me a hint.&quot;</p><p><strong>Give the bug twenty minutes.</strong> Read the error from the bottom up, print the values, shrink the problem. Most of the time you'll find it.</p><p><strong>The line-by-line test.</strong> Before keeping any code, explain every line out loud. If there's a line you can't explain, you're not done.</p><h2 id="things-to-remember">Things to remember</h2><ul><li><strong>Impostor syndrome is normal.</strong> Everyone feels it. Learning the next thing is what quiets it, for a while.</li><li><strong>It's your path.</strong> Don't measure yourself against other people's.</li><li><strong>Ask the small questions.</strong> An AI is a tutor that's awake at 3 a.m. and never gets tired of &quot;why?&quot;.</li><li><strong>Don't slide into copy and paste.</strong> The moment you're pasting code you don't understand, you've stopped learning.</li><li><strong>Find people.</strong> A community of others who are learning pulls you up with it.</li></ul><h2 id="the-short-version">The short version</h2><p>Use AI like a tutor while you learn, and like a colleague once you can check its work. Never like a ghostwriter for things you're supposed to understand.</p>]]></content:encoded>
    </item>
    <item>
      <title>Why machine learning needs maths</title>
      <link>https://erickdonado.com/notes/why-machine-learning-needs-maths/</link>
      <guid isPermaLink="true">https://erickdonado.com/notes/why-machine-learning-needs-maths/</guid>
      <pubDate>Mon, 02 Nov 2026 12:00:00 GMT</pubDate>
      <category>machine learning</category>
      <category>maths</category>
      <category>learning</category>
      <description>A scary formula is usually a few simple steps written very compactly. Here's why the maths is worth learning, what statistics, linear algebra and calculus each do in machine learning, and the ideas behind PCA and gradient descent without the jargon.</description>
      <content:encoded><![CDATA[<p>Show this to someone who has just learned Pythagoras and they'll want to close the book:</p><div class="note-math"><span class="katex"><math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><mi>D</mi><mo stretchy="false">(</mo><mi>x</mi><mo separator="true">,</mo><mi>y</mi><mo stretchy="false">)</mo><mo>=</mo><msup><mrow><mo fence="true">(</mo><munderover><mo>∑</mo><mrow><mi>i</mi><mo>=</mo><mn>1</mn></mrow><mi>n</mi></munderover><mi mathvariant="normal">∣</mi><msub><mi>x</mi><mi>i</mi></msub><mo>−</mo><msub><mi>y</mi><mi>i</mi></msub><msup><mi mathvariant="normal">∣</mi><mi>p</mi></msup><mo fence="true">)</mo></mrow><mfrac><mn>1</mn><mi>p</mi></mfrac></msup></mrow><annotation encoding="application/x-tex">D(x, y) = \left( \sum_{i=1}^{n} |x_i - y_i|^p \right)^{\frac{1}{p}}</annotation></semantics></math></span></div><p>It's the Minkowski distance. Now say the same thing as steps:</p><ol><li>Take two points and subtract them, one coordinate at a time. For 7 and 3, the gap is 4.</li><li>Raise each gap to a power. With a power of 2, a gap of 4 becomes 16, and a gap of 1 stays 1. Big gaps get punished much more than small ones.</li><li>Add up all the punished gaps.</li><li>Undo the power at the end, so the answer is a distance again and not an inflated number.</li></ol><p>Nothing in there is harder than school arithmetic. With a power of 2 it's exactly Pythagoras. The formula only looks scary because it packs four steps into one line.</p><p>That's the point of this note. Maths notation is compression. Once you can read it, a line of symbols is easier than a paragraph of words, and the advanced ideas stop looking like a wall.</p><h2 id="nobody-is-born-good-at-this">Nobody is born good at this</h2><p>I don't believe in &quot;maths people&quot;. Some pick things up faster, but what separates people is practice, and the fact that maths is stacked: every idea stands on earlier ones.</p><p>Take this integral:</p><div class="note-math"><span class="katex"><math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><mo>∫</mo><mfrac><mn>1</mn><msup><mi>x</mi><mn>3</mn></msup></mfrac><mtext> </mtext><mi>ln</mi><mo>⁡</mo><mi>x</mi><mtext>  </mtext><mi>d</mi><mi>x</mi></mrow><annotation encoding="application/x-tex">\int \frac{1}{x^3} \, \ln x \; dx</annotation></semantics></math></span></div><p>To solve it you need fractions, exponent rules, rewriting an expression in an equivalent form, what a function is, what the natural logarithm is, what a derivative is, and integration by parts. If one of those is shaky, the whole question feels impossible, and it's easy to decide you're just bad at it. You're not. You're missing a step underneath.</p><p>How deep you go depends on where you're headed. For research you'll spend more time with maths than with code. For building and shipping models, you won't solve triple integrals at work; you need to understand what the tools are doing.</p><h2 id="the-three-branches">The three branches</h2><p>Almost all of machine learning sits on three kinds of maths. In order of how much you'll use them:</p><ul><li><strong>Statistics</strong>: whether what the model learned can be trusted</li><li><strong>Linear algebra</strong>: how the data is represented and transformed</li><li><strong>Calculus</strong>: how the model learns</li></ul><h2 id="statistics-can-i-trust-this">Statistics: can I trust this?</h2><p>Real data is messy, and statistics is the toolbox for getting something trustworthy out of it. It answers questions like:</p><ul><li>Where does my data come from, and how well does it represent the real world?</li><li>Is my model good, or was the test I gave it too easy?</li><li>Is the difference between two models real, or noise?</li></ul><p>You'll hear the phrase <strong>ground truth</strong> constantly: the answers we treat as correct, which everything else is measured against. A lot of the work is making human data fit for maths: balanced, numerical, and clean enough to feed into a function.</p><p>Language models are statistics too. ChatGPT, Claude and Gemini are, in the end, very large probability machines. They don't read words the way you do. They work with chunks called tokens and have learned which chunks tend to follow which. Mention &quot;car&quot; and &quot;engine&quot; in your question and &quot;truck&quot; becomes far more likely to come next than &quot;water&quot;. The answer you get is the most probable continuation.</p><h3 id="untangling-a-mix-ica">Untangling a mix: ICA</h3><p>Sometimes what you measured is several things blended together. Picture three friends singing at once at a karaoke bar, with three microphones in the room. Every microphone records all three voices, at different volumes. Each recording is a tangle.</p>
<p><em><a href="https://erickdonado.com/notes/why-machine-learning-needs-maths/">Live figure, open the note to see it</a>: Three voices go in mixed. ICA works out which part of the tangle belongs to whom.</em></p>
<p><strong>Independent component analysis</strong> (ICA) takes those tangled recordings and gives you back each voice on its own. Nobody tells it who was singing where, which is why it's also called blind source separation.</p><p>The trick is statistical. When you mix many independent things, the result tends towards the bell curve, the most ordinary shape data can take. A single voice is less ordinary: it has spikes and flat stretches of its own. ICA looks for the directions in the data that look least like a bell curve, and those turn out to be the original voices.</p>
<p><em><a href="https://erickdonado.com/notes/why-machine-learning-needs-maths/">Live figure, open the note to see it</a>: The bell curve: most values crowd around the average. A mix of many things looks like this; a single voice doesn't.</em></p>
<h2 id="linear-algebra-the-shape-of-the-data">Linear algebra: the shape of the data</h2><p>A model only understands numbers, and the numbers need structure. A house with 3 bedrooms, 2 bathrooms, 1,200 square feet and a price of 250,000 becomes a list:</p><div class="note-math"><span class="katex"><math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><mtext>house</mtext><mo>=</mo><mrow><mo fence="true">[</mo><mtable rowspacing="0.16em" columnalign="center" columnspacing="1em"><mtr><mtd><mstyle scriptlevel="0" displaystyle="false"><mn>3</mn></mstyle></mtd></mtr><mtr><mtd><mstyle scriptlevel="0" displaystyle="false"><mn>2</mn></mstyle></mtd></mtr><mtr><mtd><mstyle scriptlevel="0" displaystyle="false"><mn>1200</mn></mstyle></mtd></mtr><mtr><mtd><mstyle scriptlevel="0" displaystyle="false"><mn>250000</mn></mstyle></mtd></mtr></mtable><mo fence="true">]</mo></mrow></mrow><annotation encoding="application/x-tex">\text{house} = \begin{bmatrix} 3 \\ 2 \\ 1200 \\ 250000 \end{bmatrix}</annotation></semantics></math></span></div><p>That's a <strong>vector</strong>. Stack many houses and you get a table, with a row per house and a column per thing you measured. That's a <strong>matrix</strong>. So from the very first step, your data is linear algebra.</p>
<p><em><a href="https://erickdonado.com/notes/why-machine-learning-needs-maths/">Live figure, open the note to see it</a>: Three houses as a matrix: each row is a house, each column is something we measured.</em></p>
<p>The core of a neural network is one line:</p><div class="note-math"><span class="katex"><math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><mi>z</mi><mo>=</mo><mrow><mo fence="true">(</mo><munderover><mo>∑</mo><mrow><mi>i</mi><mo>=</mo><mn>1</mn></mrow><mi>n</mi></munderover><msub><mi>x</mi><mi>i</mi></msub><mo>×</mo><msub><mi>w</mi><mi>i</mi></msub><mo fence="true">)</mo></mrow><mo>+</mo><mi>b</mi></mrow><annotation encoding="application/x-tex">z = \left( \sum_{i=1}^{n} x_i \times w_i \right) + b</annotation></semantics></math></span></div><p>Read it piece by piece. Each <span class="katex"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><msub><mi>x</mi><mi>i</mi></msub></mrow><annotation encoding="application/x-tex">x_i</annotation></semantics></math></span> is one of the house's attributes. Each <span class="katex"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><msub><mi>w</mi><mi>i</mi></msub></mrow><annotation encoding="application/x-tex">w_i</annotation></semantics></math></span> is a <strong>weight</strong>, a number that says how much that attribute matters. <span class="katex"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>b</mi></mrow><annotation encoding="application/x-tex">b</annotation></semantics></math></span> is the <strong>bias</strong>, one more number added at the end. The <span class="katex"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mo>∑</mo></mrow><annotation encoding="application/x-tex">\sum</annotation></semantics></math></span> just means: do the multiplication for every attribute and add the results. Do that for many attributes and many houses at once and it's a matrix multiplication. A neural network is a long chain of them.</p><p>Multiplying by a matrix transforms data: it stretches it, squashes it, turns it. A model keeps transforming the data until it lands on something useful, like a class, a price, or the next token of a sentence.</p><h3 id="keeping-what-matters-pca">Keeping what matters: PCA</h3><p>Real tables often say the same thing twice. Height and weight are a good example: taller people are usually heavier, so the two columns mostly move together. Why store two columns when one direction, &quot;bigger person&quot;, explains most of it?</p>
<p><em><a href="https://erickdonado.com/notes/why-machine-learning-needs-maths/">Live figure, open the note to see it</a>: Height and weight for two groups. Both lines say the same thing: as one goes up, so does the other.</em></p>
<p>That's <strong>principal component analysis</strong> (PCA). It finds the directions along which the data spreads out the most, and lets you describe everything using those directions. The first direction carries the most information. The second carries the leftover wiggle the first couldn't explain, and so on.</p>
<p><em><a href="https://erickdonado.com/notes/why-machine-learning-needs-maths/">Live figure, open the note to see it</a>: The data already points in a direction; PCA just finds it. PC1 runs along the cloud, PC2 across it.</em></p>
<p>How does it find them? With an idea that sounds worse than it is: <strong>eigendecomposition</strong>. You know that <span class="katex"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mn>12</mn><mo>=</mo><mn>2</mn><mo>×</mo><mn>2</mn><mo>×</mo><mn>3</mn></mrow><annotation encoding="application/x-tex">12 = 2 \times 2 \times 3</annotation></semantics></math></span>, its prime factors. A matrix can be broken down into building blocks too:</p><ul><li><strong>Eigenvectors</strong>: the core directions built into the matrix</li><li><strong>Eigenvalues</strong>: how strong each of those directions is</li></ul><p>Multiplying a vector by a matrix normally stretches it and turns it. An eigenvector is a direction the matrix refuses to turn. It only gets longer or shorter, and the eigenvalue is by how much.</p><p>PCA builds a table of how every pair of columns moves together (the covariance matrix) and breaks it down this way. The eigenvector with the largest eigenvalue is the direction of largest spread. Keep the few biggest and drop the rest, and you have a smaller dataset that still says almost everything the big one did.</p><p>PCA and ICA are easy to confuse, and they do different jobs:</p>
<p><em><a href="https://erickdonado.com/notes/why-machine-learning-needs-maths/">Live figure, open the note to see it</a></em></p>
<p>In practice PCA often runs first, as a clean-up step before ICA.</p><h2 id="calculus-how-the-model-learns">Calculus: how the model learns</h2><p>Say the network makes a prediction and it's wrong. How do we tell it to be less wrong?</p><p>First we need to measure how wrong. That's the <strong>loss function</strong>: it takes the model's prediction and the real answer and returns one number. The bigger the number, the worse the prediction. It's the same idea as the distance at the top of this note, with the prediction and the ground truth as the two points.</p><p>Now picture the loss as a landscape. Every possible setting of the weights is a place, and its height is how wrong the model is there. Training is walking downhill.</p><p>On a straight line like <span class="katex"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>y</mi><mo>=</mo><mi>m</mi><mi>x</mi><mo>+</mo><mi>b</mi></mrow><annotation encoding="application/x-tex">y = mx + b</annotation></semantics></math></span> the slope is the same everywhere: it's <span class="katex"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>m</mi></mrow><annotation encoding="application/x-tex">m</annotation></semantics></math></span>. On a curve like <span class="katex"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>y</mi><mo>=</mo><mi>a</mi><msup><mi>x</mi><mn>2</mn></msup><mo>+</mo><mi>b</mi><mi>x</mi><mo>+</mo><mi>c</mi></mrow><annotation encoding="application/x-tex">y = ax^2 + bx + c</annotation></semantics></math></span> it changes at every point, and calculus is the maths of that kind of continuous change.</p>
<p><em><a href="https://erickdonado.com/notes/why-machine-learning-needs-maths/">Live figure, open the note to see it</a></em></p>
<p>The <strong>derivative</strong> is the slope where you're standing. It tells you which way is down.</p><p>So training is a loop:</p><ol><li>Compute the slope where you are.</li><li>Take a small step the opposite way.</li><li>Repeat.</li></ol><p>That's <strong>gradient descent</strong>: descending, using the gradient.</p>
<p><em><a href="https://erickdonado.com/notes/why-machine-learning-needs-maths/">Live figure, open the note to see it</a>: Each square is one step. The steeper the slope, the bigger the step, so the steps shrink as it gets close to the bottom.</em></p>
<p>Written as a formula, one step is:</p><div class="note-math"><span class="katex"><math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><mi>w</mi><mo>←</mo><mi>w</mi><mo>−</mo><mi>η</mi><mo>⋅</mo><mfrac><mrow><mi mathvariant="normal">∂</mi><mi>L</mi></mrow><mrow><mi mathvariant="normal">∂</mi><mi>w</mi></mrow></mfrac></mrow><annotation encoding="application/x-tex">w \leftarrow w - \eta \cdot \frac{\partial L}{\partial w}</annotation></semantics></math></span></div><p><span class="katex"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>L</mi></mrow><annotation encoding="application/x-tex">L</annotation></semantics></math></span> is the loss, <span class="katex"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mfrac><mrow><mi mathvariant="normal">∂</mi><mi>L</mi></mrow><mrow><mi mathvariant="normal">∂</mi><mi>w</mi></mrow></mfrac></mrow><annotation encoding="application/x-tex">\frac{\partial L}{\partial w}</annotation></semantics></math></span> is the slope of the loss for the weight <span class="katex"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>w</mi></mrow><annotation encoding="application/x-tex">w</annotation></semantics></math></span>, and <span class="katex"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>η</mi></mrow><annotation encoding="application/x-tex">\eta</annotation></semantics></math></span> (the learning rate) is how big a step to take. The code says the same thing:</p><pre data-lang="python"><code>w = 0.0
for step in range(100):
    gradient = 2 * (w - 3)       # slope of the error (w - 3)²
    w = w - 0.1 * gradient       # one small step downhill
print(w)                         # ends very close to 3</code></pre><p>A real model doesn't have one weight; it has millions, so the landscape isn't a curve but a surface with far more dimensions than we can draw. In three it looks like this:</p>
<p><em><a href="https://erickdonado.com/notes/why-machine-learning-needs-maths/">Live figure, open the note to see it</a>: With more than one weight the curve becomes a surface. Going downhill can end in a shallow valley and never find the deepest one, which is why where you start and how big your steps are both matter.</em></p>
<p>We can't change the inputs. The weights and the bias are the only numbers we're allowed to move, so those are what the loop adjusts.</p><p>Two names come up together here, and they do different jobs:</p><ul><li><strong>Backpropagation</strong> works out how much each weight was responsible for the error.</li><li><strong>Gradient descent</strong> uses that to move each weight to a better value.</li></ul><p>Backpropagation rests on the chain rule. If the output depends on a value through several layers, the slope of the whole thing is the slopes of each layer multiplied together:</p><div class="note-math"><span class="katex"><math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><mfrac><mrow><mi>d</mi><mi>L</mi></mrow><mrow><mi>d</mi><mi>x</mi></mrow></mfrac><mo>=</mo><mfrac><mrow><mi>d</mi><mi>L</mi></mrow><mrow><mi>d</mi><mi>z</mi></mrow></mfrac><mo>⋅</mo><mfrac><mrow><mi>d</mi><mi>z</mi></mrow><mrow><mi>d</mi><mi>y</mi></mrow></mfrac><mo>⋅</mo><mfrac><mrow><mi>d</mi><mi>y</mi></mrow><mrow><mi>d</mi><mi>x</mi></mrow></mfrac></mrow><annotation encoding="application/x-tex">\frac{dL}{dx} = \frac{dL}{dz} \cdot \frac{dz}{dy} \cdot \frac{dy}{dx}</annotation></semantics></math></span></div><p>That's what lets a network with millions of weights learn at all.</p><h2 id="start-from-the-ground-up">Start from the ground up</h2><p>All of this is why I'd rather you build the maths from the bottom than skip ahead. If you can't multiply powers, the power rule of calculus won't make sense, and you'll blame calculus.</p><p>Take your time and be patient with yourself. Go back to the unit tests on Khan Academy every so often so what you learned stays fresh. That's how people become &quot;good at maths&quot;.</p><p>If a formula still won't click, write it as a loop and run it. That's often the fastest way in.</p>]]></content:encoded>
    </item>
    <item>
      <title>How dither-moon draws the Moon</title>
      <link>https://erickdonado.com/notes/how-dither-moon-draws-the-moon/</link>
      <guid isPermaLink="true">https://erickdonado.com/notes/how-dither-moon-draws-the-moon/</guid>
      <pubDate>Sat, 31 Oct 2026 12:00:00 GMT</pubDate>
      <category>graphics</category>
      <category>astronomy</category>
      <category>javascript</category>
      <description>The moon on my home page isn't a picture. It's worked out from where the Sun and the Moon are right now, wrapped in NASA's map, and drawn one on-or-off pixel at a time. Here's how, step by step.</description>
      <content:encoded><![CDATA[<p>The moon on my home page isn't an image. A few times a second, a small program works out where the Sun and the Moon are right now, lights a ball to match, wraps NASA's map of the Moon around it, and then decides for every pixel whether it's on or off. I packaged it as <a href="https://github.com/KanuSaru/dither-moon" target="_blank" rel="noopener noreferrer">dither-moon</a> so anyone can put it on their own page.</p><p>This note goes through it one step at a time. Every moon below is live: it shows the date written under it, and you can drag it to turn it.</p><h2 id="1-where-the-moon-is-in-its-cycle">1. Where the Moon is in its cycle</h2><p>A phase is just geometry. The Sun always lights half of the Moon; what changes is how much of that lit half faces us. That depends on the angle between the Sun and the Earth as seen from the Moon, called the <strong>phase angle</strong>. At 0° we see the whole lit side (full moon); at 180° we see none of it (new moon).</p><p>To get that angle, the library computes where the Sun and the Moon are in the sky for the given moment, using the classic low-precision series from Jean Meeus's <em>Astronomical Algorithms</em>. The Sun needs a mean position plus a correction for Earth's elliptical orbit. The Moon needs more: its mean position plus the largest wobbles caused by its own tilted, stretched orbit and by the Sun pulling on it. The biggest of those terms alone moves it by more than 6°. From the two positions comes the phase angle, and from that the lit fraction:</p><pre><code>lit fraction = (1 + cos(phase angle)) / 2</code></pre><p>I checked it against eclipses, which are the most precisely timed new and full moons there are: it lands within about five minutes. A fixed 29.5-day cycle can be off by up to about half a day, because the real month speeds up and slows down.</p>
<p><em><a href="https://erickdonado.com/notes/how-dither-moon-draws-the-moon/">Live figure, open the note to see it</a>: The same code on four dates this November: a 16% crescent, first quarter, 87% gibbous and full moon.</em></p>
<p>One detail about names: new, first quarter, full and last quarter are instants, not days. So the library only uses those names within about a day of the exact moment, and the in-between names (&quot;waxing gibbous&quot;, &quot;waning crescent&quot;…) the rest of the time.</p><h2 id="2-a-ball-lit-from-the-side">2. A ball, lit from the side</h2><p>The drawing itself starts small: a square canvas about a hundred pixels across. For each pixel, if it falls inside the circle, the program finds the matching point on the front of a sphere. On a sphere of radius 1, that point is also the direction the surface faces there (its <em>normal</em>), which is everything we need to light it.</p><p>The obvious way to shade a ball is Lambert's law: brightness follows the cosine of the angle between the surface and the light, so a ball darkens toward its edges. The Moon doesn't do that. A full moon looks like a flat, evenly bright disc, because its dusty soil scatters light back toward the Sun. That behavior is closer to the <strong>Lommel–Seeliger</strong> law, which also accounts for the angle you're looking from:</p><pre><code>brightness ∝ μ₀ / (μ₀ + μ)
μ₀ = cos(angle to the Sun), μ = cos(angle to the viewer)</code></pre><p>On top of that goes a tone curve that keeps most of the lit side solid and leaves the gradient near the shadow line, where it matters most in 1-bit.</p>
<p><em><a href="https://erickdonado.com/notes/how-dither-moon-draws-the-moon/">Live figure, open the note to see it</a>: Only the lighting: a plain white ball under the Sun's real angle on November 21. Notice how evenly lit it stays all the way to its right edge.</em></p>
<h2 id="3-wrapping-nasa-s-map-around-it">3. Wrapping NASA's map around it</h2><p>Next comes the surface. NASA's Scientific Visualization Studio publishes the <a href="https://svs.gsfc.nasa.gov/4720" target="_blank" rel="noopener noreferrer">CGI Moon Kit</a>, a color map and an elevation map of the whole Moon built from Lunar Reconnaissance Orbiter data, free for anyone to use.</p><p>Each point of the sphere becomes a latitude and a longitude, and those become a position on the map. The map was prepared ahead of time: turned into grays, shrunk to 512 × 256, slightly blurred, and pushed toward two tones. The dark seas (<em>maria</em>) sit around one level and the bright highlands around another, and at this size it reads best when highlands come out almost solid and the seas as an even dot pattern. Fine detail like small craters and bright rays only turns into noise when there are this few pixels.</p><p>Both maps travel inside the library, about 33 KB, so it never has to fetch anything from another site.</p>
<p><em><a href="https://erickdonado.com/notes/how-dither-moon-draws-the-moon/">Live figure, open the note to see it</a>: With NASA's map, no relief yet. The dark seas are the shapes people see as a face or a rabbit.</em></p>
<h2 id="4-craters-that-catch-the-light">4. Craters that catch the light</h2><p>Elevation isn't drawn as height. Instead, for each point the library looks at the elevation map just east and west, and just north and south, to get the <strong>slope</strong> there. It tilts the surface normal by that slope before lighting it, so a crater wall facing the Sun gets brighter and the one facing away gets darker.</p><p>This barely shows on a full moon, because the light comes from straight behind us. It matters most along the shadow line (the <em>terminator</em>), where sunlight arrives low and every slope casts a difference. It's the same reason the Moon looks most textured through binoculars around first quarter.</p><p>The tilt is worked out in the Moon's own frame and then turned back to the view. That way the craters stay lit from the correct side even while the Moon sways or you drag it around.</p>
<p><em><a href="https://erickdonado.com/notes/how-dither-moon-draws-the-moon/">Live figure, open the note to see it</a>: First quarter, with relief. Look along the straight shadow line: that's where the craters show.</em></p>
<h2 id="5-on-or-off-ordered-dithering">5. On or off: ordered dithering</h2><p>At this point every pixel has a brightness between 0 and 1, but the moon is drawn in one color on nothing: each pixel is either ink or empty. The simplest rule is a threshold: on if the brightness is over one half. It throws away everything in between.</p><p><strong>Ordered dithering</strong> gives each pixel its own threshold instead, taken from a small grid that repeats across the image. dither-moon uses the 4 × 4 <strong>Bayer matrix</strong>: the numbers 0 to 15, arranged so that consecutive thresholds land as far apart as possible.</p>
<p><em><a href="https://erickdonado.com/notes/how-dither-moon-draws-the-moon/">Live figure, open the note to see it</a>: The 4 × 4 Bayer matrix. Each pixel is compared with the cell it falls on, as (value + 0.5) / 16. Brighter cells mean a higher threshold.</em></p>
<p>So a 50% gray turns into a checkerboard, 25% into one dot every other pixel and row, and so on: sixteen levels of gray out of pure on and off.</p>
<p><em><a href="https://erickdonado.com/notes/how-dither-moon-draws-the-moon/">Live figure, open the note to see it</a>: The same left-to-right ramp three ways.</em></p>
<p>Why not error diffusion, like Floyd–Steinberg, which usually looks more natural? Because the moon moves. Error diffusion passes each pixel's rounding error on to its neighbors, so a tiny change anywhere reshuffles the dots across the image, and an animation shimmers. With an ordered grid the pattern stays pinned to the screen, each pixel is decided on its own, and a slowly swaying moon stays calm. It's also very cheap: one comparison per pixel.</p><p>The night side isn't completely empty either. It keeps 5% of the surface brightness, which is just enough for the brightest highlands to cross the lowest thresholds as sparse dots, a little like earthshine.</p><h2 id="6-pixels-stars-and-turning-it-by-hand">6. Pixels, stars and turning it by hand</h2><p>The small canvas is shown 2 or 3 times bigger with <code>image-rendering: pixelated</code>, so every moon pixel becomes a crisp square instead of a blur. It redraws about nine times a second. A low frame rate suits the pixel look and barely uses any battery.</p><p>The rest is atmosphere:</p><ul><li><strong>Sway</strong>: the moon wobbles a few degrees side to side and up and down, a nod to <em>libration</em>, the real slow wobble that lets us see a bit more than half of the Moon over a month.</li><li><strong>Stars</strong>: placed with a hash so they're the same on every visit, each one fading in and out at its own pace.</li><li><strong>Dragging</strong>: a drag across the whole moon turns it about half a turn, so you can look at the far side. Six seconds after you let go, it eases back to the side that always faces Earth.</li></ul>
<p><em><a href="https://erickdonado.com/notes/how-dither-moon-draws-the-moon/">Live figure, open the note to see it</a>: Today's moon. Drag it to see the far side; it comes back on its own.</em></p>
<h2 id="use-it">Use it</h2><p>It works on any page with one script tag, or as a React component:</p><pre data-lang="html"><code>&lt;script src=&quot;https://cdn.jsdelivr.net/npm/dither-moon@1/dist/dither-moon.js&quot;&gt;&lt;/script&gt;
&lt;dither-moon info style=&quot;width: 240px; color: #e7e2d6&quot;&gt;&lt;/dither-moon&gt;</code></pre><pre data-lang="bash"><code>npm install dither-moon</code></pre><p>The phase math is also there on its own (<code>moonPhase()</code>, <code>nextFullMoon()</code>), with no dependencies. The code is on <a href="https://github.com/KanuSaru/dither-moon" target="_blank" rel="noopener noreferrer">GitHub</a> and the package is on <a href="https://www.npmjs.com/package/dither-moon" target="_blank" rel="noopener noreferrer">npm</a>.</p><h3 id="sources">Sources</h3><ul><li>Jean Meeus, <em>Astronomical Algorithms</em>, 2nd ed. (Willmann-Bell, 1998): positions of the Sun and the Moon, and the phase angle.</li><li>NASA Scientific Visualization Studio, <a href="https://svs.gsfc.nasa.gov/4720" target="_blank" rel="noopener noreferrer">CGI Moon Kit</a>, from Lunar Reconnaissance Orbiter (LROC and LOLA) data.</li><li>Bryce E. Bayer, &quot;An optimum method for two-level rendition of continuous-tone pictures&quot; (1973): the threshold matrix.</li></ul>]]></content:encoded>
    </item>
  </channel>
</rss>
