AI Agents and /aspherix-assistant

Overview

To help with setting up Aspherix cases using an AI harness we have a public skill repository that provides 

 the /aspherix-assistant skill.

You can download the skill from here https://github.com/CFDEMproject/aspherix-assistant.

NOTE: At the moment the skill is built for Claude Code, but we will be adding support for Antigravity, Cursor in the future.

The skill provides the LLM access to our public documentation and our public examples repository and some guidance in setting up cases.

Prerequisites

You will need to install an AI harness on your local system:

• Install Claude Code

You will need Aspherix installed on your system if you want to run the simulation:

• Get a Licence for Aspherix DEM

NOTE: The assistant is capable of running the aspherix executable. For this to work you will need to make sure that the Aspherix environment is loaded and that the executable is in your PATH.

To view results you will need ParaView installed as well:

• A ParaView installer is distributed with the Aspherix installer
• Or you can Download ParaView and install it yourself

Setup

We have a few options for installing the assistant for Claude.

We can install it globally for Claude Code. (Recommended)

This way it will always be available for any project you are working on.

git clone https://github.com/CFDEMproject/aspherix-assistant ~/.claude/skills/aspherix-assistant

git clone https://github.com/CFDEMproject/aspherix-assistant .claude/skills/aspherix-assistant

git submodule add https://github.com/CFDEMproject/aspherix-assistant .claude/skills/aspherix-assistant

NOTE: The assistant can be installed with other AI harnesses -- but each harness uses it's own install location, so you will need to make sure  you use the correct location.

NOTE: Remember to keep the assistant up to date with git update and/or git submodule update.

After launching Claude Code, you can check to see if if the assistant skill is available by using the /skill command.

Usage

With the skill installed you should be able to invoke the agent using the /aspherix-assistant skill command inside of Claude Code.

You will now be able to ask your agent to help you with an Aspherix command:

Please tell me more about the `insertion` command and how I can use it to fill a region.

Please tell me about the `particle_distribution` command and how I can setup a polydisperse distribution.

Please tell me about how to run a simulation until the hopper I filled is empty.

The agent is even able to help you setup a complete input script in mere minutes!

Here are 2 examples you should try:

1. Box Settling

Set up a box-settling test.
Build an open-top rectangular box, 200 mm × 200 mm in plan, 300 mm tall, with rigid walls and a rigid floor.
Use primitive/analytic walls, no mesh geometry needed.
Insert 300 spherical particles, each 10 mm diameter, in a single batch fill of the box's upper region.
Let the particles fall under standard gravity (9.81 m/s²) and settle under particle-particle and particle-wall contact.
Run until the total kinetic energy of the particle system drops below 0.1% of its peak value, indicating the pile has come to rest.
Track the number of particles in the domain and the total kinetic energy over time.

2. Rotating Drum

Set up a rotating drum test.
Build a cylindrical drum as a primitive/analytic geometry, 200 mm inner diameter, 150 mm long, with closed flat end caps, and no mesh file involved.
Orient the drum's axis horizontal.
Insert 400 spherical particles, each 8 mm diameter, filling roughly 30% of the drum's cross-sectional area at the bottom.
Let the particles settle under standard gravity (9.81 m/s²) with the drum stationary.
Once settled, rotate the drum about its axis at a fixed angular velocity of 10 rpm.
Keep gravity active throughout the rotation.
Run for at least 5 full drum revolutions after rotation begins.
Track the particle bed's cross-sectional shape or centroid position over time.

If you give your agent the correct permissions it is even able to run cases and check the output -- iterating and debugging as it goes.

Please run the case and figure out why my particles are dissappearing.

Video Demonstration