Real-time design and visualization of Maxwell simulations in Blender 3D, with multi-solver support.

Go to file

Sofus Albert Høgsbro Rose c9936b8942 feat: big refactor to fight fundamental crashes Some rather foundational things were fundamentally broken, especially related to the initialization procedures of fields / cached properties. - We completely revamped `bl_cache`, fixing many to-be-discovered bugs. - We completely streamlined `BLField` property logic into reusable `bl_cache.BLProp` and `bl_cache.BLPropType`. - We implemented `BLInstance` superclass to handle ex. deterministic persistance of dynamic enum items, and other nuanced common functionality that was being duplicated raw. - We implemented inter `cached_bl_property` / `BLField` dependency logic, including the ability to invalidate dynamic enums without @on_value_changed logic. This greatly simplifies a vast quantity of nodes that were traditionally very difficult to get working due to the sharp edges imposed by needing manual invalidation logic. - We gave `ExprSocket` a significant usability upgrade, including thorough parsing logic in the `SocketDef`. It's not that existing nodes are as such broken, but their existing bugs are now going to cause problems a lot faster. Which is a good thing. BREAKING CHANGE: Closes #13. Closes #16. Big work on #64. Work on #37.		2024-05-15 12:37:38 +02:00
doc	refactor: Huge simplifications from ExprSocket	2024-04-30 18:42:46 +02:00
src	feat: big refactor to fight fundamental crashes	2024-05-15 12:37:38 +02:00
.editorconfig	refactor: applied tooling for predictable lint/fmt/commits	2024-05-04 20:08:33 +02:00
.gitattributes	docs: Added README.md and LICENSE	2024-03-14 12:33:49 +01:00
.gitignore	feat: Completely revamped dependency system.	2024-03-20 12:55:40 +01:00
.pre-commit-config.yaml	docs: added license headers to all files	2024-05-04 22:29:40 +02:00
.python-version	feat: Completely revamped dependency system.	2024-03-20 12:55:40 +01:00
CHANGELOG.md	bump: version 0.0.1 → 0.1.0	2024-05-04 20:09:16 +02:00
FUTURE.md	refactor: Fixes and movement.	2024-04-17 18:14:14 +02:00
LICENSE.txt	packaging: Initialize virtual 'rye' project.	2024-03-14 13:37:30 +01:00
LICENSE_header.txt	docs: added license headers to all files	2024-05-04 22:29:40 +02:00
README.md	doc: Updated line about instability	2024-03-21 18:54:53 +01:00
TODO.md	refactor: applied tooling for predictable lint/fmt/commits	2024-05-04 20:08:33 +02:00
pyproject.toml	fix: fix import and remove some TODOs	2024-05-05 09:51:17 +02:00
requirements-dev.lock	refactor: applied tooling for predictable lint/fmt/commits	2024-05-04 20:08:33 +02:00
requirements.lock	refactor: applied tooling for predictable lint/fmt/commits	2024-05-04 20:08:33 +02:00

README.md

Blender Maxwell

A tool for fast, intuitive, and real-time design and visualization of Maxwell PDE Simulations in Blender 3D.

WARNING: This is very alpha software. It says "version 0.0.1" for a reason: Expect janky untest installation; expect obvious bugs, lacking documentation, and jankiness; expect breaking changes without warning. Here be dragons, growl growl...

Blender Maxwell is a tool for creating and analyzing electromagnetic PDE simulations, with a particular focus on nano-/micro-scale phenomena. In particular, this tool seeks to make working with FDTD ("Finite-Difference Time-Domain") intuitive and fun:

Rapid Node-Based Simulation Design and Visualization: Rapidly create and visualize complex FDTD simulations with a novel visual programming language, implemented within Blender's (https://www.blender.org/) Python API.
Deep Tidy3D Integration: Submit, run, monitor, and retrieve FDTD simulation results from the high-performance, state-of-the-art commercial FDTD solver "Tidy3D" (https://www.flexcompute.com/tidy3d/solver/), leveraging their Python client library tidy3d.

Development of this tool is made possible with support from the Technical University of Denmark / DTU Electro / Metamaterials Department. They provided the opportunity to develop the tool as part of the author's BSc Eng thesis, and provided funding for a professional Tidy3D license.

Key Features

Parametric Design: Leverage Blender's parametric, non-destructive geometry generator: "Geometry Nodes". https://docs.blender.org/manual/en/latest/modeling/geometry_nodes/introduction.html).
Live Processing and Visualization: Quickly understand the nature of data flowing through the node graph, be it a simulation input or output, with the help of (soft-)real-time 2D plots and 3D visualizations tailored to each node.
Prioritization of UX: Much work has gone into node graphs and workflows feeling and acting "right". Here, "right" is an ideal of optimizing for clarity, responsiveness, and features, in roughly that order.

"Free" in License and Spirit

Blender Maxwell is free (as in freedom) software (aka. open source). It endeavors to discourage lock-in:

All simulation components and results are easily imported and exported as open formats, .json, .hdf, .png for plots, etc.. This is especially possible thanks to the fully open-source tidy3d client.
Simulation .blend files can be freely shared and used by absolutely anyone (with the sole exception of running new simulations on the Tidy3D cloud, which requires a Tidy3D license + API Key). This is possible because Blender (and its file format .blend) is free (as in freedom) software, meaning the design and results of your work will never be locked up.
The entire simulation workspace is scriptable. This makes it easy to write custom scripts to fitting experimental material properties from specialized formats, auto-generating simulation node graphs for educational purposes, and more.
The license (see License section) enables anyone to ex. to make their own nodes, examine the way certain operations are implemented, audit the source code (to comply with ex. institutional security policies), and/or make similar software by copy-pasting any useful parts of this program.

We hope you'll consider saying hello in an Issue, reporting bugs, and/or contributing any changes you find useful!

Simulator Support

Only Tidy3D is supported, via the tidy3d client.

tidy3d was chosen as the "lingua franca" client for declarative FDTD simulation definition, in large part because it is "just that good". Other simulators are theoretically possible to integrate; however, this would involve writing a translation layer from the tidy3d.

Why Tidy3D?

FDTD simulation can easily take days, be very complex to design, and fail in intricate ways.

As what might be the fastest FDTD simulator on the market today, Tidy3D is the "secret sauce" of the rapid iteration loops that Blender Maxwell attempts to help realize. It turns days into minutes when running useful, real-world simulation tasks. Moreover, Tidy3D provides a very well-made and -documented open-source Python client library, tidy3d, which is a massively helpful resource when developing such a tool.

Due to its quality, performance, and lack of "lock-in", I believe Tidy3D is an ideal and future-proof choice of simulator integration for this project.

License

This software is provided under the terms of the "AGPL software license", as specified in the LICENSE file. If you would like a different license, please contact the author(s).

In general (not legal advice), AGPL means you can use, modify, redistribute, and even sell (copies of) this project (or simulation node graphs made with it) for any reason, so long as you also provide these same kinds of freedoms to anyone you share it (copies) with (including stating any changes you made).

If you wish to contribute, you must also agree to do so under the terms of this license. For more information on AGPL, see (https://www.gnu.org/licenses/gpl-faq.html) or seek legal advice.

Do's and Don'ts

It can sometimes be a bit confusing to figure out exactly what you're allowed to do with a piece of software. If in doubt, don't hesitate to ask.

Do: Anything you want with exported simulation output, ex. plots, images, arrays/fields (as ex. HDF, OpenVDB, text, etc.), renders, and so on. To be very clear, and to dispel a common misunderstanding: AGPL doesn't apply to exported results; exported results are NOT subject to AGPL(-compatible) terms. In general, when you share something you made using Blender Maxwell, AGPL DOESN'T apply; if you share something you made including part (or all) of Blender Maxwell, AGPL DOES apply.

Don't: Share .blend files containing a Blender Maxwell node graph without an AGPL(-compatible) license. Since node graphs are source code (visual code is also code) for software that includes part of Blender Maxwell, sharing a node graph requires sharing a part of Blender Maxwell. Therefore, the AGPL applies.

Do: Take a moment to explore the dependencies, including Blender and tidy3d of course, but also numpy, sympy, xarray, networkx, pydantic, jax etc.! They are not only fantastic pieces of engineering, but are themselves licensed under similar "open source" terms that made this tool possible.

Don't: Worry about whether your .blend file is licensed correctly. By default, Blender Maxwell should include license information in the node graph (feel free to change the license, just mind that your choice is AGPL-compatible). When you do share simulation .blends, it's probably a good idea to briefly communicate the terms anyway, just to everyone's on the same page.