FEKIA — Altair FEKO® Lua Script Generator

AI-powered Altair FEKO® Lua script generator. Describe any antenna in natural language and get a ready-to-run .lua file for CADFEKO®. Runs fully locally — no API costs, no cloud, no internet required during generation.

Additionally, this repository can also serve as a valuable library to find and extract verified Lua scripts for Altair FEKO®, since there are very few publicly available examples online.

Table of Contents

• How it works
• Tested environment
• Installation
• Corpus structure
• Running
• Example prompts
• Generated Example
• Why qwen2.5-coder:32b
• Improving generation quality
• Main files
• Workflow for adding a new antenna type
• Docker — Fully containerized deployment
• Notes
• Disclaimer

---

How it works

---

Tested environment

Component	Value
GPU	NVIDIA RTX 4090 (24 GB VRAM)
RAM	64 GB
Python	3.10+
OS	Ubuntu 24
Ollama	Local service

Other hardware may work. VRAM is the main constraint — qwen2.5-coder:32b in Q4_K_M requires ~18 GB VRAM.

---

Installation

# Clone and create virtual environment
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Pull required Ollama models
ollama pull qwen2.5-coder:32b
ollama pull nomic-embed-text

If Ollama is not installed yet, install it from ollama.com and start the service before running any FEKIA commands.

---

Corpus structure

The RAG system is built from four sources. Populate these folders before indexing:

fekia/
├── luascripts/                    # Verified standalone .lua scripts (gold examples)
├── macro_recordings/              # Syntax snippets recorded directly from CADFEKO®
├── rag_pdfs/                      # Antenna design PDFs (e.g. Balanis Antenna Theory)
└── api_cadfeko_auto_generated/    # CADFEKO® HTML API reference docs

luascripts/

Verified, standalone .lua scripts that run in CADFEKO® without errors. These are the most important source — the RAG system classifies the best ones as gold examples and always includes one in the generation context. Scripts that use require or external utilities are automatically excluded during indexing.

macro_recordings/

Lua snippets recorded directly from CADFEKO® using Home → Scripting → Start Recording. These contain 100% correct API syntax for specific operations (geometry creation, ports, sources, requests, boolean operations). They are indexed as syntax references — the model uses them to verify API patterns without treating them as full antenna templates.

rag_pdfs/

Standard antenna engineering textbooks in PDF format. Used to provide correct design equations and dimensions for complex antenna types (Vivaldi, LPDA, spiral, horn, etc.) where the model's training data alone is insufficient.

api_cadfeko_auto_generated/

CADFEKO® HTML API documentation. Provides object/method signatures as a fallback when neither gold examples nor macro recordings cover a specific API call.

---

Running

Step 1 — Build or update the index

Required on first run, and any time you add files to the corpus folders:

# Full reindex (recommended after adding new files)
python3 rag_generator.py --full-reindex

# Incremental update (only indexes new files)
python3 rag_generator.py

Step 2 — Generate a Lua script

# One-shot mode
python3 main.py "3-element Yagi-Uda antenna at 144 MHz"

# Interactive mode
python3 main.py

Generated scripts are saved to output_lua/ with a timestamped filename.

Debug mode

Shows full RAG retrieval details, context blocks sent to the model, per-attempt validator results, and timing:

python3 main.py --debug "Horn antenna at 10 GHz, TE10 waveguide feed"

---

Example prompts

Half-wave dipole at 2.4 GHz
Quarter-wave monopole at 868 MHz over a 300x300mm ground plane
3-element Yagi-Uda antenna at 144 MHz, optimized for maximum forward gain
5-element Yagi-Uda antenna at 433 MHz
Helical antenna at 2.4 GHz, axial mode, 8 turns
Rectangular microstrip patch antenna at 5.8 GHz on Rogers RO4003C, probe-fed at 50 ohms
2x2 microstrip patch array at 5.8 GHz on Rogers RO4003C, probe-fed, lambda/2 spacing
Horn antenna at 10 GHz, rectangular aperture, TE10 waveguide feed
Log-periodic dipole array at 400 MHz to 1 GHz, 8 elements

---

Generated Example

You can find the generated Lua script for this and other examples in the examples/ folder.

Prompt: "12 element yagi antenna"

CADFEKO® Result

POSTFEKO® Result

---

Why qwen2.5-coder:32b

This project uses a dense 32B model rather than a MoE alternative. For FEKO® Lua generation specifically, the dense model engages all parameters per token, which produces more consistent API syntax and better repair loop behavior. Earlier iterations tested Qwen3 35B-A3B (MoE, ~3.5B active parameters per token) and found it less reliable for long, technically precise scripts.

To change the model, update OLLAMA_MODEL in main.py.

---

Improving generation quality

Quality depends on three things, in order of importance:

1. Corpus quality The most impactful lever. Add more verified .lua scripts to luascripts/ and re-run --full-reindex. Each new gold example improves generation for that antenna family. Use CADFEKO®'s macro recording feature to capture verified API syntax for new geometry types or operations.

2. Validator rules lua_validator.py contains forbidden patterns (wrong API paths, invented classes) and required patterns (NewProject, SaveAs, GlobalFrequency). When a new CADFEKO® error is discovered, add a corresponding rule and it will be caught in future repair loops.

3. System prompt main.py contains a detailed system prompt with verified API syntax for all major geometry types, ports, sources, and requests. When new correct syntax is discovered via macro recording, add it to the relevant section.

Corpus audit

Check for inconsistent patterns across the corpus:

python3 audit_corpus.py

Normalize known bad patterns automatically:

python3 normalize_corpus.py

Check which scripts are classified as gold examples:

python3 check_gold.py

---

Main files

File	Purpose
main.py	Main CLI — retrieves context, generates Lua, validates, repairs, saves
rag_generator.py	Indexes all corpus sources into ChromaDB
lua_validator.py	Deterministic FEKO® Lua validation and repair prompt builder
debug_logger.py	Debug mode output — RAG details, generation attempts, timing
audit_corpus.py	Detects inconsistent API patterns across luascripts/
normalize_corpus.py	Auto-corrects known bad patterns in luascripts/
inspect_pattern.py	Searches the Lua corpus for specific regex patterns to inspect API usage context
check_bulk_lua_headless.py	Headless batch validator that runs all scripts in CADFEKO® and reports success/error statistics
check_gold.py	Lists all documents classified as gold examples in ChromaDB
generate_dataset.py	Generates fine-tuning dataset for a FEKO® Lua judge model
test_rag.py	Retrieval smoke test for FEKO-related queries
generation_benchmark.py	End-to-end generation benchmark with pass rate report
requirements.txt	Python dependencies
generation_runs.jsonl	Append-only log of all generation runs with RAG debug info

---

Workflow for adding a new antenna type

1. Build the antenna manually in CADFEKO.
2. Record the macro: Home → Scripting → Start Recording → build → Stop Recording.
3. Save the macro to macro_recordings/ with a descriptive name.
4. If the full script works end-to-end, save it to luascripts/ as a gold example.
5. Run python3 rag_generator.py --full-reindex.
6. Add any new API patterns discovered to the system prompt in main.py.
7. Add any new forbidden patterns to lua_validator.py.

---

Docker — Fully containerized deployment

If you prefer not to install anything on the host except Docker, FEKIA supports a fully containerized deployment that runs both Ollama and the FEKIA app inside Docker containers.

1. Build and start the stack:

docker compose up --build

2. Model pulling (automatic)

The docker-compose.yml includes an ollama-init one-shot service that pulls the required models into the shared Ollama volume when you run docker compose up --build. In most cases you do not need to run any manual commands — the init service populates the volume for you.

Note: Ollama and the AI model are installed automatically inside the Docker container. No local installation required.

3. Run the generator (examples):

One-shot:

docker compose run --rm fekia "3-element Yagi-Uda antenna at 144 MHz"

Interactive:

docker compose run --rm fekia

Debug mode (writes debug log file into the mounted debug folder):

docker compose run --rm fekia --debug "Horn antenna at 10 GHz, TE10 waveguide feed"

4. Custom output/debug folders

Use environment variables and host mounts to choose folders on the host:

docker compose run --rm \
  -e FEKIA_OUTPUT_DIR=/data/my_lua \
  -e FEKIA_DEBUG_DIR=/data/my_debug \
  -v "$PWD/my_lua:/data/my_lua" \
  -v "$PWD/my_debug:/data/my_debug" \
  fekia --debug "Half-wave dipole at 2.4 GHz"

Or with CLI flags:

docker compose run --rm fekia \
  --output-dir /data/my_lua \
  --debug-dir /data/my_debug \
  "Quarter-wave monopole at 868 MHz"

Notes:

• The first model load may take time while Ollama initializes and the model is loaded.
• The RAG index in feko_db is mounted into the container; regenerate it with rag_generator.py --full-reindex when you change corpus files.

Automatic GPU and PC Resources Access

By default, the docker-compose.yml file is configured to automatically request and bridge all available PC resources (GPUs, CPU, RAM) into the containers. You do not need to append any special flags when you run the docker compose commands.

However, your host machine must have the NVIDIA drivers and the Docker GPU toolkit (nvidia-container-toolkit) installed for the container to utilize the graphics card.

Automatic Setup (Debian/Ubuntu): We've included an automatic setup script for your host PC. Run this configuration script once:

sudo ./setup_host.sh

Alternative: Manual Setup: If you prefer not to use the script, install the nvidia-container-toolkit following the official NVIDIA documentation and restart Docker (sudo systemctl restart docker).

Once the host configuration is done (or if you already use Docker with GPUs on your machine), everything else is completely automatic. Just use exactly the same commands:

# GPUs and CPU are automatically linked!
docker compose run --rm fekia "3-element Yagi-Uda antenna at 144 MHz"

Notes

• Scripts in luascripts/ that use require or local lfs are test suite scripts from Altair and are automatically excluded during indexing — they are not standalone and confuse the model.
• generation_runs.jsonl logs every run including RAG debug info, validator errors, and repair attempts. Useful for diagnosing quality regressions.
• The fine-tuning pipeline in generate_dataset.py and finetune_judge.py supports training a small local judge model to replace the rule-based validator with a learned one.

---

Disclaimer

Note: This project is still a work in progress. Errors or hallucinatory syntax in generated scripts may happen occasionally. System reliability, the model prompting, and the RAG retrieval will continue to improve over time as more verified examples are added to the corpus and modifications are made to the main code.

Generated Lua scripts should be reviewed in CADFEKO® before use in production simulation workflows. Always verify geometry, port placement, and solver settings match the intended design.