Eighteen years since the release of NumPy 1.0, we are thrilled to announce the launch of NumPy 2.0! This major release marks a significant milestone in the evolution of NumPy, bringing a wealth of enhancements and improvements to users, and setting the stage for future feature development.

NumPy has improved and evolved over the past 18 years, with many old releases bringing significant performance, usability, and consistency improvements. That said, our approach for a long time has been to make only incremental changes while carefully managing backward compatibility. This approach minimizes user breakage, but also limits the scope of improvements that can be made, both to the API and its underlying implementation. Therefore, for this one-off major release, we are breaking backward compatibility to implement significant improvements in NumPy’s type system. The type system is fundamental to NumPy, and major behavioral changes could not be made incrementally without mixing two different type systems, which would be a recipe for disaster.

The journey to an actual 2.0 release has been long, and it was difficult to build the necessary momentum. In part, this may be because, for a time, the NumPy developers associated a NumPy 2.0 release with nothing less than a revolutionary rewrite of significant key pieces of the code base. Many of these rewrites and changes happened over the years, but because of backward compatibility concerns they remained largely invisible to the users. NumPy 2.0 is the culmination of these efforts, allowing us to discard some legacy ABI (Application Binary Interface) that prevented future improvements.

Some major changes to NumPy internals—required for key features in 2.0—have been in the works since 2019 at least. We started concrete plans for the 2.0 release more than a year ago, at a four hour long public planning meeting in April 2023. Many of the key changes were proposed and discussed. The key goals we decided on there were perhaps even larger and more ambitious in scope than some of us expected. This also unlocked some extra energy - which has been great to see. After the meeting and over the course of the last year, NumPy enhancement proposals (NEPs) were written, reviewed, and implemented for each major change.

Some key highlights are:

• Cleaned-up and streamlined Python API (NEP 52): The Python API has undergone a thorough cleanup, making it easier to learn and use NumPy. The main namespace has been reduced by approximately 10%, and the more niche numpy.lib namespace has been reduced by about 80%, providing a clearer distinction between public and private API elements.

• Improved scalar promotion rules: The scalar promotion rules have been updated, as proposed in NEP 50 addressing surprising behaviors in type promotion, e.g. with zero dimensional arrays.

• Powerful new DType API and a new string dtype: NumPy 2.0 introduces a new API for implementing user-defined custom data types as proposed by NEP 41. We used this new API to implement StringDType, offering efficient and painless support for variable length strings which was proposed in NEP 55. And it is our hope that enable future new data types with interesting new capabilities in the PyData ecosystem and in NumPy itself.

• Windows compatibility enhancements: The default 32-bit integer representation on Windows has been updated to 64-bit on 64-bit architectures, addressing one of the most common problems with having NumPy work portably across operating systems.

• Support for the Python array API standard: This is the first release to include full support for the array API standard (v2022.12), made possible by the new promotion rules, APIs, and API cleanup mentioned above. We also aligned existing APIs and behavior with the standard, as proposed in NEP 56.

These are just some of the more impactful changes in behavior and usability. In addition, NumPy 2.0 contains significant performance and documentation improvements, and much more - for an extensive list of changes, see the NumPy 2 release notes.

To adopt this major release, users will likely need to adjust existing code, but we worked hard to strike a balance between improvements and ensuring that the transition to NumPy 2.0 is as seamless as possible. We wrote a comprehensive migration guide, and a ruff plugin that helps to update Python code so it will work with both NumPy 1.x and NumPy 2.x.

While we do require C API users to recompile their projects to support NumPy 2.0, we prepared for this in NumPy 1.25 already. The build process was simplified so that you can now compile with the latest NumPy version, and remain backward compatible. This means that projects build with NumPy 2.x are “magically” compatible with 1.x. It also means that projects no longer need to build their binaries using the oldest supported version of NumPy.

We knew throughout development that rolling out NumPy 2.0 would be (temporarily) disruptive, because of the backwards-incompatible API and ABI changes. We spent an extraordinary amount of effort communicating these changes, helping downstream projects adapt, tracking compatibility of popular open source projects (see, e.g., numpy#26191), and completing the release process at limited pace to provide time for adoption. No doubt, the next few weeks will bring to light some new challenges, however we fully expect these to be manageable and well worth it in the long run.

The NumPy 2.0 release is the result of a collaborative, largely volunteer, effort spanning many years and involving contributions from a diverse community of developers. In addition, many of the changes above would not have been possible without funders and institutional sponsors allowing several team members to work on NumPy as part of their day jobs. We’d like to acknowledge in particular: the Gordon and Betty Moore Foundation, the Alfred P. Sloan Foundation, NASA, NVIDIA, Quansight Labs, the Chan Zuckerberg Initiative, and Tidelift.

We are excited about future improvements to NumPy, many of which will be possible due to changes in NumPy 2.0. See the NumPy roadmap for some features in the pipeline or on the wishlist. Let’s continue working together to improve NumPy and the scientific Python and PyData ecosystem!

It’s my great pleasure to announce that I’ve finished my book on matplotlib and it is now freely available at www.labri.fr/perso/nrougier/scientific-visualization.html while sources for the book are hosted at github.com/rougier/scientific-visualization-book.

Abstract#

The Python scientific visualisation landscape is huge. It is composed of a myriad of tools, ranging from the most versatile and widely used down to the more specialised and confidential. Some of these tools are community based while others are developed by companies. Some are made specifically for the web, others are for the desktop only, some deal with 3D and large data, while others target flawless 2D rendering. In this landscape, Matplotlib has a very special place. It is a versatile and powerful library that allows you to design very high quality figures, suitable for scientific publishing. It also offers a simple and intuitive interface as well as an object oriented architecture that allows you to tweak anything within a figure. Finally, it can be used as a regular graphic library in order to design non‐scientific figures. This book is organized into four parts. The first part considers the fundamental principles of the Matplotlib library. This includes reviewing the different parts that constitute a figure, the different coordinate systems, the available scales and projections, and we’ll also introduce a few concepts related to typography and colors. The second part is dedicated to the actual design of a figure. After introducing some simple rules for generating better figures, we’ll then go on to explain the Matplotlib defaults and styling system before diving on into figure layout organization. We’ll then explore the different types of plot available and see how a figure can be ornamented with different elements. The third part is dedicated to more advanced concepts, namely 3D figures, optimization & animation. The fourth and final part is a collection of showcases.

Book gallery#

Matplotlib: Revisiting Text/Font Handling

To kick things off for the final report, here’s a meme to nudge about the previous blogs.

About Matplotlib#

Matplotlib is a comprehensive library for creating static, animated, and interactive visualizations, which has become a de-facto Python plotting library.

Much of the implementation behind its font manager is inspired by W3C compliant algorithms, allowing users to interact with font properties like font-size, font-weight, font-family, etc.

However, the way Matplotlib handled fonts and general text layout was not ideal, which is what Summer 2021 was all about.#

By “not ideal”, I do not mean that the library has design flaws, but that the design was engineered in the early 2000s, and is now outdated.

(..more on this later)

About the Project#

(PS: here’s the link to my GSoC proposal, if you’re interested)

Overall, the project was divided into two major subgoals:

1. Font Subsetting
2. Font Fallback

But before we take each of them on, we should get an idea about some basic terminology for fonts (which are a lot, and are rightly confusing)

The PR: Clarify/Improve docs on family-names vs generic-families brings about a bit of clarity about some of these terms. The next section has a linked PR which also explains the types of fonts and how that is relevant to Matplotlib.

Font Subsetting#

An easy-to-read guide on Fonts and Matplotlib was created with PR: [Doc] Font Types and Font Subsetting, which is currently live at Matplotlib’s DevDocs.

Taking an excerpt from one of my previous blogs (and the doc):

Fonts can be considered as a collection of these glyphs, so ultimately the goal of subsetting is to find out which glyphs are required for a certain array of characters, and embed only those within the output.

PDF, PS/EPS and SVG output document formats are special, as in the text within them can be editable, i.e, one can copy/search text from documents (for eg, from a PDF file) if the text is editable.

Matplotlib and Subsetting#

The PDF, PS/EPS and SVG backends used to support font subsetting, only for a few types. What that means is, before Summer ‘21, Matplotlib could generate Type 3 subsets for PDF, PS/EPS backends, but it could not generate Type 42 / TrueType subsets.

With PR: Type42 subsetting in PS/PDF merged in, users can expect their PDF/PS/EPS documents to contains subsetted glyphs from the original fonts.

This is especially beneficial for people who wish to use commercial (or CJK) fonts. Licenses for many fonts require subsetting such that they can’t be trivially copied from the output files generated from Matplotlib.

Font Fallback#

Matplotlib was designed to work with a single font at runtime. A user could specify a font.family, which was supposed to correspond to CSS properties, but that was only used to find a single font present on the user’s system.

Once that font was found (which is almost always found, since Matplotlib ships with a set of default fonts), all the user text was rendered only through that font. (which used to give out “tofu” if a character wasn’t found)

It might seem like an outdated approach for text rendering, now that we have these concepts like font-fallback, but these concepts weren’t very well discussed in early 2000s. Even getting a single font to work was considered a hard engineering problem.

This was primarily because of the lack of any standardization for representation of fonts (Adobe had their own font representation, and so did Apple, Microsoft, etc.)

Previous (notice Tofus) VS After (CJK font as fallback)

To migrate from a font-first approach to a text-first approach, there are multiple steps involved:

Parsing the whole font family#

The very first (and crucial!) step is to get to a point where we have multiple font paths (ideally individual font files for the whole family). That is achieved with either:

• PR: [with findfont diff] Parsing all families in font_manager, or
• PR: [without findfont diff] Parsing all families in font_manager

Quoting one of my previous blogs:

Don’t break, a lot at stake!

My first approach was to change the existing public findfont API to incorporate multiple filepaths. Since Matplotlib has a very huge userbase, there’s a high chance it would break a chunk of people’s workflow:

First PR (left), Second PR (right)

FT2Font Overhaul#

Once we get a list of font paths, we need to change the internal representation of a “font”. Matplotlib has a utility called FT2Font, which is written in C++, and used with wrappers as a Python extension, which in turn is used throughout the backends. For all intents and purposes, it used to mean: FT2Font === SingleFont (if you’re interested, here’s a meme about how FT2Font was named!)

But that is not the case anymore, here’s a flowchart to explain what happens now:

Font-Fallback Algorithm

With PR: Implement Font-Fallback in Matplotlib, every FT2Font object has a std::vector<FT2Font *> fallback_list, which is used for filling the parent cache, as can be seen in the self-explanatory flowchart.

For simplicity, only one type of cache (character -> FT2Font) is shown, whereas in actual implementation there’s 2 types of caches, one shown above, and another for glyphs (glyph_id -> FT2Font).

Note: Only the parent’s APIs are used in some backends, so for each of the individual public functions like load_glyph, load_char, get_kerning, etc., we find the FT2Font object which has that glyph from the parent FT2Font cache!

Multi-Font embedding in PDF/PS/EPS#

Now that we have multiple fonts to render a string, we also need to embed them for those special backends (i.e., PDF/PS, etc.). This was done with some patches to specific backends:

• PR: Implement multi-font embedding for PDF Backend
• PR: Implement multi-font embedding for PS Backend

With this, one could create a PDF or a PS/EPS document with multiple fonts which are embedded (and subsetted!).

Conclusion#

From small contributions to eventually working on a core module of such a huge library, the road was not what I had imagined, and I learnt a lot while designing solutions to these problems.

The work I did would eventually end up affecting every single Matplotlib user.#

…since all plots will work their way through the new codepath!

I think that single statement is worth the whole GSoC project.

Pull Request Statistics#

For the sake of statistics (and to make GSoC sound a bit less intimidating), here’s a list of contributions I made to Matplotlib before Summer ‘21, most of which are only a few lines of diff:

Here’s a list of PRs I opened during Summer'21:

• [Status: ✅] Clarify/Improve docs on family-names vs generic-families
• [Status: ✅] Add parse_math in Text and default it False for TextBox
• [Status: ✅] Type42 subsetting in PS/PDF
• [Status: ✅] [Doc] Font Types and Font Subsetting
• [Status: 🚧] [with findfont diff] Parsing all families in font_manager
• [Status: 🚧] [without findfont diff] Parsing all families in font_manager
• [Status: 🚧] Implement Font-Fallback in Matplotlib
• [Status: 🚧] Implement multi-font embedding for PDF Backend
• [Status: 🚧] Implement multi-font embedding for PS Backend

Acknowledgements#

From learning about software engineering fundamentals from Tom to learning about nitty-gritty details about font representations from Jouni;

From learning through Antony’s patches and pointers to receiving amazing feedback on these blogs from Hannah, it has been an adventure! 💯

Special Mentions: Frank, Srijan and Atharva for their helping hands!

And lastly, you, the reader; if you’ve been following my previous blogs, or if you’ve landed at this one directly, I thank you nevertheless. (one last meme, I promise!)

I know I speak for every developer out there, when I say it means a lot when you choose to look at their journey or their work product; it could as well be a tiny website, or it could be as big as designing a complete library!

I’m grateful to Maptlotlib (under the parent organisation: NumFOCUS), and of course, Google Summer of Code for this incredible learning opportunity.

Farewell, reader! :’)

Consider contributing to Matplotlib (Open Source in general) ❤️

NOTE: This blog post is also available at my personal website.#

“Matplotlib, I want 多个汉字 in between my text.”

Let’s say you asked Matplotlib to render a plot with some label containing 多个汉字 (multiple Chinese characters) in between your English text.

Or conversely, let’s say you use a Chinese font with Matplotlib, but you had English text in between (which is quite common).

Assumption: the Chinese font doesn’t have those English glyphs, and vice versa

With this short writeup, I’ll talk about how does a migration from a font-first to a text-first approach in Matplotlib looks like, which ideally solves the above problem.

Have the fonts?#

Logically, the very first step to solving this would be to ask whether you have multiple fonts, right?

Matplotlib doesn’t ship CJK (Chinese Japanese Korean) fonts, which ideally contains these Chinese glyphs. It does try to cover most grounds with the default font it ships with, however.

So if you don’t have a font to render your Chinese characters, go ahead and install one! Matplotlib will find your installed fonts (after rebuilding the cache, that is).

Parse the fonts#

This is where things get interesting, and what my previous writeup was all about..

Parsing the whole family to get multiple fonts for given font properties

FT2Font Magic!#

To give you an idea about how things used to work for Matplotlib:

1. A single font was chosen at draw time (fixed: re previous writeup)
2. Every character displayed in your document was rendered by only that font (partially fixed: re this writeup)

FT2Font is a matplotlib-to-font module, which provides high-level Python API to interact with a single font’s operations like read/draw/extract/etc.

Being written in C++, the module needs wrappers around it to be converted into a Python extension using Python’s C-API.

It allows us to use C++ functions directly from Python!

So wherever you see a use of font within the library (by library I mean the readable Python codebase XD), you could have derived that:

FT2Font === SingleFont

Things are be a bit different now however..

Designing a multi-font system#

FT2Font is basically itself a wrapper around a library called FreeType, which is a freely available software library to render fonts.

In my initial proposal.. while looking around how FT2Font is structured, I figured:

Oh, looks like all we need are Faces!

If you don’t know what faces/glyphs/ligatures are, head over to why Text Hates You. I can guarantee you’ll definitely enjoy some real life examples of why text rendering is hard. 🥲

Anyway, if you already know what Faces are, it might strike you:

If we already have all the faces we need from multiple fonts (let’s say we created a child of FT2Font.. which only tracks the faces for its families), we should be able to render everything from that parent FT2Font right?

As I later figured out while finding segfaults in implementing this design:

Each FT2Font is linked to a single FT_Library object!

If you tried to load the face/glyph/character (basically anything) from a different FT2Font object.. you’ll run into serious segfaults. (because one object linked to an FT_Library can’t really access another object which has it’s own FT_Library)

// face is linked to FT2Font; which is
// linked to a single FT_Library object
FT_Face face = this->get_face();
FT_Get_Glyph(face->glyph, &placeholder); // works like a charm

// somehow get another FT2Font's face
FT_Face family_face = this->get_family_member()->get_face();
FT_Get_Glyph(family_face->glyph, &placeholder); // segfaults!

Realizing this took a good amount of time! After this I quickly came up with a recursive approach, wherein we:

1. Create a list of FT2Font objects within Python, and pass it down to FT2Font
2. FT2Font will hold pointers to its families via a
   std::vector<FT2Font *> fallback_list
3. Find if the character we want is available in the current font
   1. If the character is available, use that FT2Font to render that character
   2. If the character isn’t found, go to step 3 again, but now iterate through the fallback_list
4. That’s it!

A quick overhaul of the above piece of code^

bool ft_get_glyph(FT_Glyph &placeholder) {
	FT_Error not_found = FT_Get_Glyph(this->get_face(), &placeholder);
	if (not_found) return False;
	else return True;
}

// within driver code
for (uint i=0; i<fallback_list.size(); i++) {
	// iterate through all FT2Font objects
	bool was_found = fallback_list[i]->ft_get_glyph(placeholder);
	if (was_found) break;
}

With the idea surrounding this implementation, the Agg backend is able to render a document (either through GUI, or a PNG) with multiple fonts!

Python C-API is hard, at first!#

I’ve spent days at Python C-API’s argument doc, and it’s hard to get what you need at first, ngl.

But, with the help of some amazing people in the GSoC community (@srijan-paul, @atharvaraykar) and amazing mentors, blockers begone!

So are we done?#

Oh no. XD

Things work just fine for the Agg backend, but to generate a PDF/PS/SVG with multiple fonts is another story altogether! I think I’ll save that for later.

NOTE: This blog post is also available at my personal website.#

“Well? Did you get it working?!”

Before I answer that question, if you’re missing the context, check out my previous blog’s last few lines.. promise it won’t take you more than 30 seconds to get the whole problem!

With this short writeup, I intend to talk about what we did and why we did, what we did. XD

Ostrich Algorithm#

Ring any bells? Remember OS (Operating Systems)? It’s one of the core CS subjects which I bunked then and regret now. (╥﹏╥)

The wikipedia page has a 2-liner explanation if you have no idea what’s an Ostrich Algorithm.. but I know most of y’all won’t bother clicking it XD, so here goes:

Ostrich algorithm is a strategy of ignoring potential problems by “sticking one’s head in the sand and pretending there is no problem”

An important thing to note: it is used when it is more cost-effective to allow the problem to occur than to attempt its prevention.

As you might’ve guessed by now, we ultimately ended up with the not-so-clean API (more on this later).

What was the problem?#

The highest level overview of the problem was:

❌ fontTools -> buffer -> ttconv_with_buffer
✅ fontTools -> buffer -> tempfile -> ttconv_with_file

The first approach created corrupted outputs, however the second approach worked fine. A point to note here would be that Method 1 is better in terms of separation of reading the file from parsing the data.

1. fontTools handles the Type42 subsetting for us, whereas ttconv handles the embedding.
2. ttconv_with_buffer is a modification to the original ttconv_with_file; that allows it to input a file buffer instead of a file-path

You might be tempted to say:

“Well, ttconv_with_buffer must be wrongly modified, duh.”

Logically, yes. ttconv was designed to work with a file-path and not a file-object (buffer), and modifying a codebase written in 1998 turned out to be a larger pain than we anticipated.

It came to a point where one of my mentors decided to implement everything in Python!#

He even did, but the efforts to get it to production / or to fix ttconv embedding were ⋙ to just get on with the second method. That damn ostrich really helped us get out of that debugging hell. 🙃

Font Fallback - initial steps#

Finally, we’re onto the second subgoal for the summer: Font Fallback!

To give an idea about how things work right now:

1. User asks Matplotlib to use certain font families, specified by:

matplotlib.rcParams["font-family"] = ["list", "of", "font", "families"]

2. This list is used to search for available fonts on a user’s system.
3. However, in current (and previous) versions of Matplotlib:

   As soon as a font is found by iterating the font-family, all text is rendered by that and only that font.

You can immediately see the problems with this approach; using the same font for every character will not render any glyph which isn’t present in that font, and will instead spit out a square rectangle called “tofu” (read the first line here).

And that is exactly the first milestone! That is, parsing the entire list of font families to get an intermediate representation of a multi-font interface.

Don’t break, a lot at stake!#

Imagine if you had the superpower to change Python standard library’s internal functions, without consulting anybody. Let’s say you wanted to write a solution by hooking in and changing, let’s say str("dumb") implementation by returning:

>>> str("dumb")
["d", "u", "m", "b"]

Pretty “dumb”, right? xD

For your usecase it might work fine, but it would also mean breaking the entire Python userbase’ workflow, not to mention the 1000000+ libraries that depend on the original functionality.

On a similar note, Matplotlib has a public API known as findfont(prop: str), which when given a string (or FontProperties) finds you a font that best matches the given properties in your system.

It is used throughout the library, as well as at multiple other places, including downstream libraries. Being naive as I was, I changed this function signature and submitted the PR. 🥲

Had an insightful discussion about this with my mentors, and soon enough raised the other PR, which didn’t touch the findfont API at all.

One last thing to note: Even if we do complete the first milestone, we wouldn’t be done yet, since this is just parsing the entire list to get multiple fonts..

We still need to migrate the library’s internal implementation from font-first to text-first!

But that’s for later, for now:

NOTE: This blog post is also available at my personal website.#

"Aitik, how is your GSoC going?"

Well, it’s been a while since I last wrote. But I wasn’t spending time watching Loki either! (that’s a lie.)

During this period the project took on some interesting (and stressful) curves, which I intend to talk about in this small writeup.

New Mentor!#

The first week of coding period, and I met one of my new mentors, Jouni. Without him, along with Tom and Antony, the project wouldn’t have moved an inch.

It was initially Jouni’s PR which was my starting point of the first milestone in my proposal, Font Subsetting.

What is Font Subsetting anyway?#

As was proposed by Tom, a good way to understand something is to document your journey along the way! (well, that’s what GSoC wants us to follow anyway right?)

Taking an excerpt from one of the paragraphs I wrote here:

Font Subsetting can be used before generating documents, to embed only the required glyphs within the documents. Fonts can be considered as a collection of these glyphs, so ultimately the goal of subsetting is to find out which glyphs are required for a certain array of characters, and embed only those within the output.

Now this may seem straightforward, right?

Wrong.#

The glyph programs can call their own subprograms, for example, characters like ä could be composed by calling subprograms for a and ¨; or → could be composed by a program that changes the display matrix and calls the subprogram for ←.

Since the subsetter has to find out all such subprograms being called by every glyph included in the subset, this is a generally difficult problem!

Something which one of my mentors said which really stuck with me:

Matplotlib isn’t a font library, and shouldn’t try to be one.

It’s really easy to fall into the trap of trying to do everything within your own project, which ends up rather hurting itself.

Since this holds true even for Matplotlib, it uses external dependencies like FreeType, ttconv, and newly proposed fontTools to handle font subsetting, embedding, rendering, and related stuff.

PS: If that font stuff didn’t make sense, I would recommend going through a friendly tutorial I wrote, which is all about Matplotlib and Fonts!

Unexpected Complications#

Matplotlib uses an external dependency ttconv which was initially forked into Matplotlib’s repository in 2003!

ttconv was a standalone commandline utility for converting TrueType fonts to subsetted Type 3 fonts (among other features) written in 1995, which Matplotlib forked in order to make it work as a library.

Over the time, there were a lot of issues with it which were either hard to fix, or didn’t attract a lot of attention. (See the above paragraph for a valid reason)

One major utility which is still used is convert_ttf_to_ps, which takes a font path as input and converts it into a Type 3 or Type 42 PostScript font, which can be embedded within PS/EPS output documents. The guide I wrote (link) contains decent descriptions, the differences between these type of fonts, etc.

So we need to convert that font path input to a font buffer input.#

Why do we need to? Type 42 subsetting isn’t really supported by ttconv, so we use a new dependency called fontTools, whose ‘full-time job’ is to subset Type 42 fonts for us (among other things).

It provides us with a font buffer, however ttconv expects a font path to embed that font

Easily enough, this can be done by Python’s tempfile.NamedTemporaryFile:

with tempfile.NamedTemporaryFile(suffix=".ttf") as tmp:
    # fontdata is the subsetted buffer
    # returned from fontTools
    tmp.write(fontdata.getvalue())

    # TODO: allow convert_ttf_to_ps
    # to input file objects (BytesIO)
    convert_ttf_to_ps(
        os.fsencode(tmp.name),
        fh,
        fonttype,
        glyph_ids,
    )

But this is far from a clean API; in terms of separation of *reading* the file from *parsing* the data.

What we ideally want is to pass the buffer down to convert_ttf_to_ps, and modify the embedding code of ttconv (written in C++). And here we come across a lot of unexplored codebase, which wasn’t touched a lot ever since it was forked.

Funnily enough, just yesterday, after spending a lot of quality time, me and my mentors figured out that the whole logging system of ttconv was broken, all because of a single debugging function. 🥲

This is still an ongoing problem that we need to tackle over the coming weeks, hopefully by the next time I write one of these blogs, it gets resolved!

Again, thanks a ton for spending time reading these blogs. :D

NOTE: This blog post is also available at my personal website.#

The day of result, was a very, very long day.

With this small writeup, I intend to talk about everything before that day, my experiences, my journey, and the role of Matplotlib throughout!

About Me#

I am a third-year undergraduate student currently pursuing a Dual Degree (B.Tech + M.Tech) in Information Technology at Indian Institute of Information Technology, Gwalior.

During my sophomore year, my interests started expanding in the domain of Machine Learning, where I learnt about various amazing open-source libraries like NumPy, SciPy, pandas, and Matplotlib! Gradually, in my third year, I explored the field of Computer Vision during my internship at a startup, where a big chunk of my work was to integrate their native C++ codebase to Android via JNI calls.

To actuate my learnings from the internship, I worked upon my own research along with a friend from my university. The paper was accepted in CoDS-COMAD’21 and is published at ACM Digital Library. (Link, if anyone’s interested)

During this period, I also picked up the knack for open-source and started glaring at various issues (and pull requests) in libraries, including OpenCV [contributions] and NumPy [contributions].

I quickly got involved in Matplotlib’s community; it was very welcoming and beginner-friendly.

Fun fact: Its dev call was the very first I attended with people from all around the world!

First Contributions#

We all mess up, my very first PR to an organisation like OpenCV went horrible, till date, it looks like this:

In all honesty, I added a single commit with only a few lines of diff.

However, I pulled all the changes from upstream master to my working branch, whereas the PR was to be made on 3.4 branch.

I’m sure I could’ve done tons of things to solve it, but at that time I couldn’t do anything - imagine the anxiety!

At this point when I look back at those fumbled PRs, I feel like they were important for my learning process.

Fun Fact: Because of one of these initial contributions, I got a shiny little badge [Mars 2020 Helicopter Contributor] on GitHub!

Getting started with Matplotlib#

It was around initial weeks of November last year, I was scanning through Good First Issue and New Feature labels, I realised a pattern - most Mathtext related issues were unattended.

To make it simple, Mathtext is a part of Matplotlib which parses mathematical expressions and provides TeX-like outputs, for example:

I scanned the related source code to try to figure out how to solve those Mathtext issues. Eventually, with the help of maintainers reviewing the PRs and a lot of verbose discussions on GitHub issues/pull requests and on the Gitter channel, I was able to get my initial PRs merged!

Learning throughout the process#

Most of us use libraries without understanding the underlining structure of them, which sometimes can cause downstream bugs!

While I was studying Matplotlib’s architecture, I figured that I could use the same ideology for one of my own projects!

Matplotlib uses a global dictionary-like object named as rcParams, I used a smaller interface, similar to rcParams, in swi-ml - a small Python library I wrote, implementing a subset of ML algorithms, with a switchable backend.

Where does GSoC fit?#

It was around January, I had a conversation with one of the maintainers (hey Antony!) about the long-list of issues with the current ways of handling texts/fonts in the library.

After compiling them into an order, after few tweaks from maintainers, GSoC Idea-List for Matplotlib was born. And so did my journey of building a strong proposal!

About the Project#

Proposal Link: Google Docs (will stay alive after GSoC), GSoC Website (not so sure)#

Revisiting Text/Font Handling#

The aim of the project is divided into 3 subgoals:

1. Font-Fallback: A redesigned text-first font interface - essentially parsing all family before rendering a “tofu”.

   (similar to specifying font-family in CSS!)

2. Font Subsetting: Every exported PS/PDF would contain embedded glyphs subsetted from the whole font.

   (imagine a plot with just a single letter “a”, would you like it if the PDF you exported from Matplotlib to embed the whole font file within it?)

3. Most mpl backends would use the unified TeX exporting mechanism

Mentors Thomas A Caswell, Antony Lee, Hannah.

Thanks a lot for spending time reading the blog! I’ll be back with my progress in subsequent posts.

NOTE: This blog post is also available at my personal website!#

Google Summer of Code 2020 is completed. Hurray!! This post discusses about the progress so far in the three months of the coding period from 1 June to 24 August 2020 regarding the project Baseline Images Problem under matplotlib organisation under the umbrella of NumFOCUS organization.

Project Details:#

This project helps with the difficulty in adding/modifying tests which require a baseline image. Baseline images are problematic because

• Baseline images cause the repo size to grow rather quickly.
• Baseline images force matplotlib contributors to pin to a somewhat old version of FreeType because nearly every release of FreeType causes tiny rasterization changes that would entail regenerating all baseline images (and thus cause even more repo size growth).

So, the idea is to not store the baseline images in the repository, instead to create them from the existing tests.

Creation of the matplotlib_baseline_images package#

We had created the matplotlib_baseline_images package. This package is involved in the sub-wheels directory so that more packages can be added in the same directory, if needed in future. The matplotlib_baseline_images package contain baseline images for both matplotlib and mpl_toolkits. The package can be installed by using python3 -mpip install matplotlib_baseline_images.

Creation of the matplotlib baseline image generation flag#

We successfully created the generate_missing command line flag for baseline image generation for matplotlib and mpl_toolkits in the previous months. It was generating the matplotlib and the mpl_toolkits baseline images initially. Now, we have also modified the existing flow to generate any missing baseline images, which would be fetched from the master branch on doing git pull or git checkout -b feature_branch.

Now, the image generation on the time of fresh install of matplotlib and the generation of missing baseline images works with the python3 -pytest lib/matplotlib matplotlib_baseline_image_generation for the lib/matplotlib folder and python3 -pytest lib/mpl_toolkits matplotlib_baseline_image_generation for the lib/mpl_toolkits folder.

Documentation#

We have written documentation explaining the following scenarios:

1. How to generate the baseline images on a fresh install of matplotlib?
2. How to generate the missing baseline images on fetching changes from master?
3. How to install the matplotlib_baseline_images_package to be used for testing by the developer?
4. How to intentionally change an image?

Links to the work done#

• Issue
• Pull Request
• Blog Posts

Mentors#

• Thomas A Caswell
• Hannah
• Antony Lee

I am grateful to be part of such a great community. Project is really interesting and challenging :)

Thanks Thomas, Antony and Hannah for helping me to complete this project.

Google Summer of Code 2020’s second evaluation is completed. I passed!!! Hurray! Now we are in the mid way of the last evaluation. This post discusses about the progress so far in the first two weeks of the third coding period from 26 July to 9 August 2020.

Completion of the modification logic for the matplotlib_baseline_images package#

We successfully created the matplotlib_baseline_image_generation command line flag for baseline image generation for matplotlib and mpl_toolkits in the previous months. It was generating the matplotlib and the matplotlib toolkit baseline images successfully. Now, we modified the existing flow to generate any missing baseline images, which would be fetched from the master branch on doing git pull or git checkout -b feature_branch.

We initially thought of creating a command line flag generate_baseline_images_for_test "test_a,test_b", but later on analysis of the approach, we came to the conclusion that the developer will not know about the test names to be given along with the flag. So, we tried to generate the missing images by generate_missing without the test names. This worked successfully.

Adopting reusability and Do not Repeat Yourself (DRY) Principles#

Later, we refactored the matplot_baseline_image_generation and generate_missing command line flags to single command line flag matplotlib_baseline_image_generation as the logic was similar for both of them. Now, the image generation on the time of fresh install of matplotlib and the generation of missing baseline images works with the python3 -pytest lib/matplotlib matplotlib_baseline_image_generation for the lib/matplotlib folder and python3 -pytest lib/mpl_toolkits matplotlib_baseline_image_generation for the lib/mpl_toolkits folder.

Writing the documentation#

We have written documentation explaining the following scenarios:

1. How to generate the baseline images on a fresh install of matplotlib?
2. How to generate the missing baseline images on fetching changes from master?
3. How to install the matplotlib_baseline_images_package to be used for testing by the developer?
4. How to intentionally change an image?

Refactoring and improving the code quality before merging#

Right now, we are trying to refactor the code and maintain git clean history. The current PR is under review. I am working on the suggested changes. We are trying to merge this :)

Daily Meet-ups#

Monday to Thursday meeting initiated at 11:00pm IST via Zoom. Meeting notes are present at HackMD.

I am grateful to be part of such a great community. Project is really interesting and challenging :) Thanks Thomas, Antony and Hannah for helping me so far.

Google Summer of Code 2020’s second evaluation is about to complete. Now we are about to start with the final coding phase. This post discusses about the progress so far in the last two weeks of the second coding period from 13 July to 26 July 2020.

Modular approach towards removal of matplotlib baseline images#

We have divided the work in two parts as discussed in the previous blog. The first part is the generation of the baseline images discussed below. The second part is the modification of the baseline images. The modification part will be implemented in the last phase of the Google Summer of Code 2020.

Generation of the matplotlib baseline images#

Now, we have started removing the use of the matplotlib_baseline_images package. After the changes proposed in the previous PR, the developer will have no baseline images on fresh install of matplotlib. So, the developer would need to generate matplotlib baseline images locally to get started with the testing part of the mpl. The images can be generated by the image comparison tests with use of matplotlib_baseline_image_generation flag from the command line. Once these images are generated for the first time, then they can be used as the baseline images for the later times for comparison. This is the main principle adopted.

Completion of the generation of images for the matplotlib directory#

We successfully created the matplotlib_baseline_image_generation flag in the beginning of the second evaluation but images were not created in the baseline images directory inside the matplotlib and mpl_toolkits directories, instead they were created in the result_images directory. So, we implemented this functionality. The images are created in the lib/matplotlib/tests/baseline_images directory directly now in the baseline image generation step. The baseline image generation step uses python3 -mpytest lib/matplotlib --matplotlib_baseline_image_generation command. Later on, running the pytests with python3 -mpytest lib/matplotlib will start the image comparison.

Right now, the matplotlib_baseline_image_generation flag works for the matplotlib directory. We are trying to achieve the same functionality for the mpl_toolkits directory.

Future Goals#

Once the generation of the baseline images for mpl_toolkits directory is completed in the current PR, we will move to the modification of the baseline images in the third coding phase. The addition of new baseline image and deletion of the old baseline image will also be implemented in the last phase of GSoC. Modification of baseline images will be further divided into two sub tasks: addition of new baseline image and the deletion of the previous baseline image.

Daily Meet-ups#

Monday to Thursday meeting initiated at 11:00pm IST via Zoom. Meeting notes are present at HackMD.

I am grateful to be part of such a great community. Project is really interesting and challenging :) Thanks Thomas, Antony and Hannah for helping me so far.

Google Summer of Code 2020’s first evaluation is completed. I passed!!! Hurray! Now we are in the mid way of the second evaluation. This post discusses about the progress so far in the first two weeks of the second coding period from 30 June to 12 July 2020.

Completion of the matplotlib_baseline_images package#

We successfully created the matplotlib_baseline_images package. It contains the matplotlib and the matplotlib toolkit baseline images. Symlinking is done for the baseline images, related changes for Travis, appvoyer, azure pipelines etc. are functional and tests/test_data is created as discussed in the previous blog. PR is reviewed and suggested work is done.

Modular approach towards removal of matplotlib baseline images#

We have divide the work in two parts. The first part is the generation of the baseline images discussed below. The second part is the modification of the baseline images which happens when some baseline images gets modified due to git push or git merge. Modification of baseline images will be further divided into two sub tasks: addition of new baseline image and the deletion of the previous baseline image. This will be discussed in the second half of the second phase of the Google Summer of Code 2020.

Generation of the matplotlib baseline images#

After the changes proposed in the previous PR, the developer will have no baseline images on fresh install of matplotlib. The developer would need to install the sub-wheel matplotlib_baseline_images package to get started with the testing part of the mpl. Now, we have started removing the use of the matplotlib_baseline_images package. It will require two steps as discussed above. The images can be generated by the image comparison tests. Once these images are generated for the first time, then they can be used as the baseline images for the later times for comparison. This is the main principle adopted. The images are first created in the result_images directory. Then they will be moved to the lib/matplotlib/tests/baseline_images directory. Later on, running the pytests will start the image comparison.

Created commandline flags for baseline images creation#

I learned about the pytest hooks and fixtures. I build a command line flag matplotlib_baseline_image_generation which will create the baseline images in the result_images directory. The full command will be python3 pytest --matplotlib_baseline_image_generation. In order to do this, we have done changes in the conftest.py and also added markers to the image_comparison decorator.

Learning more about the Git and virtual environments#

I came to know about the git worktree and the scenarios in which we can use it. I also know more about virtual environments and their need in different scenarios.

Future Goals#

Once the generation of the baseline images is completed in the current PR, we will move to the modification of the baseline images in the second half of the second coding phase.

Daily Meet-ups#

Monday to Thursday meeting initiated at 11:00pm IST via Zoom. Meeting notes are present at HackMD.

I am grateful to be part of such a great community. Project is really interesting and challenging :) Thanks Thomas, Antony and Hannah for helping me so far.

Google Summer of Code 2020’s first evaluation is about to complete. This post discusses about the progress so far in the last two weeks of the first coding period from 15 June to 30 June 2020.

Completion of the demo package#

We successfully created the demo app and uploaded it to the test.pypi. It contains the main and the secondary package. The main package is analogous to the matplotlib and secondary package is analogous to the matplotlib_baseline_images package as discussed in the previous blog.

Learning more about the Git and mpl workflow#

I came across another way to merge the master into the branch to resolve conflicts is by rebasing the master. I understood how to create modular commits inside a pull request for easy reviewal process and better understandability of the code.

Creation of the matplotlib_baseline_images package#

Then, we implemented the similar changes to create the matplotlib_baseline_images package. Finally, we were successful in uploading it to the test.pypi. This package is involved in the sub-wheels directory so that more packages can be added in the same directory, if needed in future. The matplotlib_baseline_images package contain baseline images for both matplotlib and mpl_toolkits. Some changes were required in the main matplotlib package’s setup.py so that it will not take information from the packages present in the sub-wheels directory.

Symlinking the baseline images#

As baseline images are moved out of the lib/matplotlib and lib/mpl_toolkits directory. We symlinked the locations where they are used, namely in lib/matplotlib/testing/decorator.py, tools/triage_tests.py, lib/matplotlib/tests/__init__.py and lib/mpl_toolkits/tests/__init__.py.

Creation of the tests/test_data directory#

There are some test data that is present in the baseline_images which doesn’t need to be moved to the matplotlib_baseline_images package. So, that is stored under the lib/matplotlib/tests/test_data folder.

Understanding Travis, Appvoyer and Azure-pipelines#

I came across the Continuous Integration tools used at mpl. We tried to install the matplotlib followed by matplotlib_baseline_images package in all three travis, appvoyer and azure-pipeline.

Future Goals#

Once the current PR is merged, we will move to the Proposal for the baseline images problem.

Daily Meet-ups#

Everyday meeting initiated at 11:00pm IST via Zoom. Meeting notes are present at HackMD.

I am grateful to be part of such a great community. Project is really interesting and challenging :) Thanks Antony and Hannah for helping me so far.

I Sidharth Bansal, was waiting for the coding period to start from the March end so that I can make my hands dirty with the code. Finally, coding period has started. Two weeks have passed. This blog contains information about the progress so far from 1 June to 14 June 2020.

Movement from mpl-test and mpl packages to mpl and mpl-baseline-images packages#

Initially, we thought of creating a mpl-test and mpl package. Mpl-test package would contain the test suite and baseline images while the other package would contain parts of repository other than test and baseline-images related files and folders. We changed our decision to creation of mpl and mpl-baseline-images packages as we don’t need to create separate package for entire test suite. Our main aim was to eliminate baseline_images from the repository. Mpl-baseline-images package will contain the data[/baseline images] and related information. The other package will contain files and folders other than baseline images. We are now trying to create the following structure for the repository:

mpl/
  setup.py
  lib/mpl/...
  lib/mpl/tests/...  [contains the tests .py files]
  baseline_images/
    setup.py
    data/...  [contains the image files]

It will involve:

• Symlinking baseline images out.
• Creating a wheel/sdist with just the baseline images; uploading it to testpypi (so that one can do pip install mpl-baseline-images).

Following prototype modelling#

I am creating a prototype first with two packages - main package and sub-wheel package. Once the demo app works well on Test PyPi, we can do similar changes to the main mpl repository. The structure of demo app is analogous to the work needed for separation of baseline-images to a new package mpl-baseline-images as given below:

testrepo/
  setup.py
  lib/testpkg/__init__.py
  baseline_images/setup.py
  baseline_images/testdata.txt

This will also include related MANIFEST files and setup.cfg.template files. The setup.py will also contain logic for exclusion of baseline-images folder from the main mpl-package.

Following Enhancements over iterations#

After the current PR is merged, we will focus on eliminating the baseline-images from the mpl-baseline-images package. Then we will do similar changes for the Travis CI.

Bi weekly meet-ups scheduled#

Every Tuesday and every Friday meeting is initiated at 8:30pm IST via Zoom. Meeting notes are present at HackMD.

I am grateful to be part of such a great community. Project is really interesting and challenging :) Thanks Antony and Hannah for helping me so far.

When I, Sidharth Bansal, heard I got selected in Google Summer of Code(GSOC) 2020 with Matplotlib under Numfocus, I was jumping and dancing. In this post, I talk about my past experiences, how I got selected for GSOC with Matplotlib, and my project details. I am grateful to the community :)

About me:#

I am currently pursuing a Bachelor’s in Technology in Software Engineering at Delhi Technological University, Delhi, India. I started my journey of open source with Public Lab, an open-source organization as a full-stack Ruby on Rails web developer. I initially did the Google Summer of Code there. I built a Multi-Party Authentication System which involves authentication of the user through multiple websites linked like mapknitter.org and spectralworkbench.org with OmniAuth providers like Facebook, twitter, google, and Github. I also worked on a Multi-Tag Subscription project there. It involved tag/category subscription by the user so that users will be notified of subsequent posts in the category they subscribe to earlier. I have also mentored there as for Google Code-In and GSoC last year. I also worked there as a freelancer.

Apart from this, I also successfully completed an internship in the Google Payments team at Google, India this year as a Software Engineering Intern. I built a PAN Collection Flow there. PAN(Taxation Number) information is collected from the user if the total amount claimed by the user through Scratch cards in the current financial year exceeds PAN_LIMIT. Triggered PAN UI at the time of scratching the reward. Enabled Paisa-Offers to uplift their limit to grant Scratch Cards after crossing PAN_LIMIT. Used different technologies like Java, Guice, Android, Spanner Queues, Protocol Buffers, JUnit, etc.

I also have a keen interest in Machine Learning and Natural Language Processing and have done a couple of projects at my university. I have researched on Query Expansion using fuzzy logic. I will be publishing it in some time. It involves the fuzzification of the traditional wordnet for query expansion.

Our paper Experimental Comparison & Scientometric Inspection of Research for Word Embeddings got accepted in ESCI Journal and Springer LNN past week. It explains the ongoing trends in universal embeddings and compares them.

Getting started with matplotlib#

I chose matplotlib as it is an organization with so much cool stuff relating to plotting. I have always wanted to work on such things. People are really friendly, always eager to help!

Taking Baby steps:#

The first step is getting involved with the community. I started using the Gitter channel to know about the maintainers. I started learning the different pieces which tie up for the baseline image problem. I started with learning the system architecture of matplotlib. Then I installed the matplotlib, learned the cool tech stack related to matplotlib like sphinx, python, pypi etc.

Keep on contributing and keep on learning:#

Learning is a continuous task. Taking guidance from mentors about the various use case scenarios involved in the GSoC project helped me to gain a lot of insights. I solved a couple of small issues. I learned about the code-review process followed here, sphinx documentation, how releases work. I did some PRs. It was a great learning experience.

About the Project:#

The project is about the generation of baseline images instead of downloading them. The baseline images are problematic because they cause the repo size to grow rather quickly by adding more baseline images. Also, the baseline images force matplotlib contributors to pin to a somewhat old version of FreeType because nearly every release of FreeType causes tiny rasterization changes that would entail regenerating all baseline images. Thus, it causes even more repository size growth. The idea is not to store the baseline images at all in the Github repo. It involves dividing the matplotlib package into two separate packages - mpl-test and mpl-notest. Mpl-test will have test suite and related information. The functionality of mpl plotting library will be present in mpl-notest. We will then create the logic for generating and grabbing the latest release. Some caching will be done too. We will then implement an analogous strategy to the CI.

Mentor Antony Lee

Thanks a lot for reading….having a great time coding with great people at Matplotlib. I will be right back with my work progress in subsequent posts.

As has been discussed in detail in Nadia Eghbal’s Roads and Bridges, the CZI EOSS program announcement, and in the NumFocus sustainability program goals, much of the critical software that science and industry are built on is maintained by a primarily volunteer community. While this has worked, it is not sustainable in the long term for the health of many projects or their contributors.

We are happy to announce that we have hired Elliott Sales de Andrade (QuLogic) as the Matplotlib Software Research Engineering Fellow supported by the Chan Zuckerberg Initiative Essential Open Source Software for Science effective March 1, 2020!

Elliott has been contributing to a broad variety of Free and Open Source projects for several years. He is an active Matplotlib contributor and has had commit rights since October 2015. In addition to working on Matplotlib, Elliott has contributed to a wide range of projects in the Scientific Python software stack, both downstream and upstream of Matplotlib, including Cartopy, ObsPy, and NumPy. Outside of Python, Elliott is a developer on the Pidgin project and a packager for Fedora Linux. In his work on Matplotlib, he is interested in advancing science through reproducible workflows and more accessible libraries.

We are already seeing a reduction in the backlog of open issues and pull requests, which we hope will make the library easier to contribute to and maintain long term. We also benefit from Elliott having the bandwidth to maintain a library wide view of all the on-going work and open bugs. Hiring Elliott as an RSEF is the start of ensuring that Matplotlib is sustainable in the long term.

Looking forward to all the good work we are going to do this year!