Appearance

Common Troubleshooting Tips ​

Every researcher gets stuck sometimes — that’s just part of the process. What matters is how you approach a problem. At Avkalan Labs, we recommend following this simple workflow whenever you hit an issue:

Query checklist

Spend 15–20 minutes investigating the issue yourself, then share it with full context — including screenshots, error messages, and a short description of what you’ve tried. This helps others help you faster.

Read the Error Carefully ​

When you see an error, don’t panic — read the traceback slowly from bottom to top. The last line usually tells you what went wrong and where.

For example:

python
Traceback (most recent call last):
  File "main_solver.py", line 45, in <module>
    u = project(expr, V)
RuntimeError: Unable to project, dimension mismatch between function and space

Here, the message clearly points to a dimension mismatch, meaning your function space doesn’t match the variable shape. Once you understand that, you can check your function space definitions.

A quick mindset shift — from “it crashed” to “what is it trying to tell me?” — will save hours over time.

Quick First Checks ​

Before diving deep, check the simple things. Most errors come from something small being overlooked:

  • Did you save your file before running?
  • Are you in the right directory?
  • Is the mesh file named correctly?
  • Are you using the correct Python or FEniCS environment?

You can confirm paths quickly using:

bash
pwd        # shows current working directory
ls *.med   # check if your mesh file exists
which python3

Or in Python:

python
import os
print(os.getcwd())  # confirm where the script is running

Fixing these basics often resolves more issues than you’d expect.

Minimal Reproducible Example (MRE) ​

When a script feels overwhelming, simplify it. Try to isolate just the part that breaks.

Example:

python
from dolfin import *
mesh = UnitSquareMesh(8, 8)
V = FunctionSpace(mesh, "Lagrange", 1)

u = TrialFunction(V)
v = TestFunction(V)
a = inner(grad(u), grad(v))*dx
L = Constant(1.0)*v*dx
solve(a == L, Function(V))

If this basic setup works, but your full simulation doesn’t, then the issue lies in your added complexity — maybe in your boundary conditions or mesh imports. Keep trimming your code until it runs. That “minimal version” gives you a clean reference to rebuild from.

Units, Scaling, and Stability ​

Sometimes everything “runs” — but the results explode or make no sense. That usually means there’s a unit mismatch or your system is numerically unstable.

Example:

python
dt = 1e-3   # time step
v = u_n + dt * a   # update equation

If your mesh is in meters but your velocity is in mm/s, or if your time step is too large, you’ll see oscillations or divergence. Start by checking all units (stick to SI) and gradually reduce the time step:

python
dt = 1e-4  # smaller, more stable

If stability improves, the issue was likely with scaling or CFL limits.

I/O and XDMF Specifics ​

If your simulation finishes but nothing appears in ParaView, it’s often just a file writing or viewing issue.

  • Make sure you’re writing to disk properly:

    python
    with XDMFFile("results.xdmf") as file:
    file.write(u)

  • Always click “Apply” in ParaView after opening the file.

  • If the screen looks blank, hit Reset Camera or Rescale to Data Range.

  • Check if your variable is being saved with the correct name (u, E, T, etc.).

If the file loads but looks empty, open it in a text editor — sometimes you’ll see that no time steps or data arrays were written at all.

Summary ​

Troubleshooting isn’t about fixing errors quickly — it’s about learning to listen to what the program is telling you. Read carefully, start small, check your basics, and be systematic.

Most importantly, document what you tried. Share the error, the fix, and a short note in your daily log or Slack channel. That habit not only helps your teammates — it builds your own understanding over time.