I'm pleased to announce that in the coming months I am going to be doing some work on Avogadro on a paid freelance basis.

The work will be in the region of 10–11 hours per calendar month, and I'll be tackling specific tasks, one at a time.

Getting paid for these blocks of focused work makes it feasible for me to dedicate the time for them, which I couldn't otherwise justify or afford. The work will be entirely independent of my usual, routine contributions to the project – e.g. the maintenance of the Flatpak and the development of the xtb and CREST plugins – which I'll continue to do on a voluntary basis.

A further motivation, from the project's perspective, is that it allows for prioritization of some things that are important for the project but might not otherwise get done, such as documentation.

I'll be undertaking the work in close communication with @ghutchis, via the forum as well as occasional conference calls. I'll keep the community updated on the things I've tackled and the progress made here on the forum.

About me

I've been contributing to the project in various ways over the past four years, initially with translations but later particularly to the general UI/UX design, the documentation, the port to Qt6, the maintenance of the Linux Flatpak, and the architecture and design of the new Python plugin API, as well as the development of the popular xtb/CREST plugin.

I'd describe my programming skills as being good with Python, competent with Rust, and rudimentary (for now) when it comes to C++. Over the years though I have become fairly well acquainted with the Avogadro codebase, have reasonable familiarity with Qt, and I've successfully made small contributions to Avogadro's C++ code in the past. As such, C++/Qt work features amongst the proposed tasks, along with non-coding things like documentation and housekeeping bits and bobs.

Potential tasks

Below is a list of things that seem like good candidates for me to work on. Suggestions of other ideas, or requests for certain things to be prioritized, are more than welcome!

In November I'm going to tackle adding a settings menu/dialog (phases 1 and 2), as it'll be a pretty big UX upgrade and it's a bit of a blocker for a few other things, including accessibility improvements.

Subsequently, I think the documentation is probably the priority.

Overview

With links to corresponding GitHub issues:

Application

  1. Settings menu/dialog (see also the avogadroapp issue)
  2. Declarative tool pane interfaces
  3. Built-in, customizable plotting with matplotlib

Documentation

  1. User guide
  2. Enforced documentation maintenance
  3. Offline documentation
  4. Plugin API documentation
  5. Contribution guides

Plugins

  1. Binary plugins
  2. Citations

Application

Settings menu

As the number of options available to users with which to customize Avogadro has grown, so has the need for a single place to configure them. A settings/preferences dialog is a long-requested and long-planned feature, but has yet to be implemented.

This work would be done in phases:

  1. Design a new settings dialog and implement it in an extensible fashion
  2. Bring the existing options into the single new dialog from other parts of the UI
  3. Add new settings and options that have been suggested in the past

(3) would include adding preferred units of energy and length, which would then need to be respected in many other places in the UI, making it necessary to touch many other parts of the codebase. As such, it is more of a stretch goal.

Declarative tool pane interfaces

Currently, the functionality of Avogadro's tool widgets is fairly tightly coupled to the Qt Widgets implementation of their UI elements. As mooted in a forum thread, reducing this coupling would be useful for builds of Avogadro with non-Qt frontends, such as the ongoing effort to create a webassembly build.

The suggested strategy to achieve this is to have the tools themselves inform the interface code what UI options they require, in a declarative fashion. The frontend would serve the options to the user without needing any semantic knowledge, and would simply pass any changes in state on to the respective tool.

Avogadro already has prior art for this within its codebase, as plugins are able to define a dialog for themselves in such a fashion. The task would be to expand and polish this protocol, extend it to the tools, and port the existing tools over to use it.

The task can be broken down into a number of steps:

  1. Appraise the protocol as currently implemented for plugins, make any revisions or extensions to the design as necessary to fully support the tools' configuration options
  2. Implement code in the frontend to interpret the declarative syntax and display appropriate widgets in the UI
  3. Adapt the code for the tool widgets to use the declarative syntax

An open question is whether the declarative JSON should be generated dynamically at runtime or stored in static form, and if the latter, whether it should be in the C++ source files in-line or in separate JSON files.

Built-in, customizable plotting with matplotlib

While the plotting library used by Avogadro, JKQtPlotter, is excellent, the user's capacity to customize a plotted graph is restricted to the options made explicitly available through the UI. Much can already be customized, but there are many requests for additional options, and inevitably users reach a point where they have to export the data and plot it externally to get what they want. This particularly applies if the user requires a publication-quality graphic, something that is a recurring feature request.

matplotlib is the predominant library for creating publication-quality scientific plots in Python. Combining this with the high rate of Python usage amongst user survey respondents and the heavily research-skewed population of the survey sample, it can be assumed that a good proportion of advanced (i.e. likely to fill out the survey) Avogadro users also have some familiarity with matplotlib.

An ambitious way to harness this would be to replace the JKQtPlotter plotting backend with one powered by matplotlib, and then not only provide GUI controls to change the plot options, but also give the user the power to directly view and edit the matplotlib script that generates the plot from within the Avogadro UI, somewhat like a Jupyter Notebook. Both the data and the script would be exportable, making the plot entirely reproducible independently of Avogadro.

Notably, Qt is one of the options for the rendering backend when displaying matplotlib plots.

The scope of this task is not of full implementation but rather a proof of concept and an assessment of the technical feasibility.

Documentation

User guide

One of the more important tasks is to continue the work to improve the state of the documentation for users, hosted in the Guide section of the website at https://avogadro.cc/docs/.

Various existing sections of the user documentation will be updated to reflect the current builds, expanded, or generally improved, such as:

  • Display Types
  • Panes
  • Tutorials – in particular, ensuring things are cross-linked to the reference sections appropriately
  • Settings

Various new sections will be added, such as:

  • Interface overview
  • Toolbars – to match the sections for the other UI elements e.g. Menus, Tools, Panes
  • Supported file formats
  • How To
  • FAQ
  • Tips and Tricks

The requests in the user survey for missing features that are actually already implemented demonstrates that discoverability is an issue and that it is often not clear how to perform common tasks. One way to improve this situation is through better documentation, in particular guides and tutorials. The latter sections listed above (How To, FAQ, Tips and Tricks) are envisaged as being particularly helpful for answering quick user queries, something that long-form tutorials are perhaps not so good at.

A further proposed change is to reorganize the manual into two overarching parts according to approach:

  1. A guide

    • Natural home for the What's New, Getting Started, Building Molecules, Optimizing Geometry, and Tutorials sections
    • Contents oriented around achieving specific tasks
    • Answers "How do I do X"

  2. A reference

    • Comprehensive details of how interface elements behave
    • Organized by UI section
    • Answers "What does X do"

The long term goal would be to have documentation in the reference for every element in every part of the UI, and to fully cross-reference from the guide to the reference to enable users to easily find more detail for items mentioned in the guide.

This split approach is very commonly seen in other projects, both applications (e.g. Krita) and libraries (e.g. matplotlib, polars).

Finally, the many build warnings that are currently raised will be addressed.

Enforced documentation maintenance

Once high quality documentation has been attained, it is important that it remains accurate and up-to-date. An approach taken by many projects is to require any merge request that would change user-facing behaviour to be accompanied by appropriate updates to the documentation.

This task would see the application of this approach to Avogadro, enforced as part of the CI workflow, with PR merge blocked in the absence of either a corresponding docs PR or an exemption from a reviewer (e.g. for non-user-facing changes).

Offline documentation

It may be helpful for some users to have access to the user guide directly from the desktop application's UI without requiring an internet connection. The possibility of bundling the documentation in HTML form with the binary releases will be investigated.

Plugin API documentation

While some documentation of the plugin API, to assist plugin authors in writing one, was added in time for the 2.0 release, it should be far more comprehensive. Moreover, there are additional changes in 2.1 that need to be documented.

Additionally, if Geoff doesn't beat me to it, a tutorial will be written that walks the reader through writing a simple minimal plugin.

This documentation will be added to the Develop section of the website.

Contribution guides

It is currently not always clear how newcomers to the project should go about contributing, as demonstrated by the answers to the respective question of the 2026 community survey. To help with this, the different guides to contribution found in various places will be expanded and updated.

The organization of the documentation for contributors on the https://avogadro.cc website needs some improvement; in particular, several pages appear in the wrong place in the table of contents trees.

The documentation for contributors on the website needs to cover:

  • how to get started with contributing from a technical perspective
  • what tasks are suitable for newcomers (this may include a list of good first issues scraped from the GitHub repositories)
  • information of the project's existing codebase/website source etc.
  • what styles should be followed and what standards need to be upheld in the codebase/website source

Additionally, many of the project's repositories also contain a CONTRIBUTING.md file, which may repeat some of the information found on the website. The different guides should be harmonized to avoid contradiction and, where possible, refer to a single central reference (the website) rather than reproduce the same thing.

Most of the information will be added to the Contribute section to the website, with some appearing under Develop.

Plugins

Binary plugins

Communication between the Avogadro desktop application and plugins consists primarily of data in JSON format passed over the standard I/O streams, and plugin metadata is expressed in TOML files. These were deliberate choices and ensure that the plugin API is entirely language agnostic.

However, the process of running a plugin in a subprocess, handled by the application's plugin backend, is not language agnostic as it stands – the program is set up only to run plugins written in Python, as calls to a Python interpreter.

Though Python is by far the language with the most widespread proficiency amongst Avogadro users, extending support to other languages would enable additional use-cases and is a long-term goal. Support for other interpreted languages would require machinery of similar complexity to the existing backend for Python plugins and is thus not an immediate priority. On the other hand, it would be fairly trivial to enable Avogadro to interface with compiled binaries that can be called directly and respond in accordance with the plugin API.

Support for binary plugins opens up many possibilities:

  1. Users can write plugins in not just a single additional language but indeed any compiled language
  2. Plugins that execute computationally expensive procedures can be written in a compiled language to take advantage of the performance benefits
  3. Any binary executable can expose functionality as a plugin for Avogadro simply by conforming to Avogadro's plugin API and supplying appropriate metadata, even if the program is not solely a plugin
  4. Avogadro could bundle plugins compiled from C++ code without having to worry about Python being available on a user's system

The aim of this task is to implement support in Avogadro for installing, running, and managing plugins in compiled binary form (with accompanying metadata).

Distribution of plugins in binary form is out of scope at this time. As well as the additional work that this would entail – the online plugin infrastructure is also set up specifically for Python packages – taking submissions of arbitrary binary executables and presenting them to users in the in-app plugin manager for download opens a large attack vector and would require safety mitigation. However, even exclusively local usage of binary plugins is a significant capability worth having.

Citations

This would see the implementation of the idea, discussed by Geoff on the forum earlier this year, of reporting all relevant citation information for a plugin to the user in a convenient form, to make it significantly easier to cite any appropriate papers and hopefully improve citation rates.

An initial step will be the assessment of the different formats and packages used to report this information, to determine which is most appropriate for Avogadro.

Implementation requires several pieces, including in the hosted plugin infrastructure and processing scripts, the plugin backend of the application, and the application interface.



Discuss this on our forum.