Documentation

1. Purpose

LIMES (Limit-based Intelligent Machining Expert System) is research software that supports the preparation of CNC milling programmes. From a part model (STL, STEP or IGES), a workpiece material and a machine, it produces a process plan and an ISO 6983 G-code programme. Each cutting-data value comes with the physical limit that determined it, so a planner can see why a value was chosen and what would allow a more productive regime.

It is intended for process planners, students and researchers in manufacturing engineering, and for evaluators of the underlying PhD research. It is not a replacement for CAM verification on the target machine.

2. Architecture

The deployment has three parts behind one Nginx reverse proxy on a single domain:

• Website (/) – static HTML/CSS pages built from site/src.
• Tool (/app/) – a Streamlit application (frontend/app.py) that imports the engine directly.
• API (/api/) – a FastAPI service (backend/) exposing the same engine for programmatic use.

The Python packages are engine/ (physics models, principled selection, planning, toolpaths, G-code, simulation, optimization), geometry/ (STL parsing, STEP/IGES conversion and feature extraction), models/ (optional ML models), common/ (security and logging helpers shared by the tool and the API) and data/ (material, machine and tool databases).

3. Technology stack

4. Installation

Local development

git clone <repository-url> advisorai && cd advisorai
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env            # then edit .env
./scripts/run_local.sh          # API on :8000, tool on :8501/app
python3 site/build.py           # website into site/dist/

Open http://localhost:8501/app/ for the tool. To preview the website, run python3 -m http.server 8080 -d site/dist. The Launch the tool links point to /app/, which only works behind Nginx or the Docker set-up.

Docker

cp .env.example .env
docker compose -f docker/docker-compose.yml up --build

The compose file starts the API, the tool and an Nginx container on http://localhost:8080. Only Nginx publishes a port, and only to the loopback interface.

Production server

See docs/DEPLOYMENT.md in the repository. A single script installs everything behind Nginx with HTTPS on your domain.

5. Configuration

All settings come from environment variables. On the server they live in /etc/advisorai/advisorai.env, readable only by root (systemd passes the values to the services at start-up). The file .env.example documents every variable. No secret is stored in the source code.

6. Using the tool

1. Upload. Choose a 3D model in millimetres – STL, STEP (.step, .stp) or IGES (.igs, .iges), limit 25 MB – open one from My files, or click Use sample block. The tool, including the sample block and the examples, is used with a free account (see Accounts and My files). The file is checked for type, size and content before it is read; STEP and IGES models are converted to a triangle mesh by Open CASCADE in a separate, time-limited process (the chordal deviation is shown), and the exact volume of the solid is kept.
2. Features. Review the detected surfaces, pockets, holes and thin walls.
3. Configure. Select the material and the machine. The selection determines the speed and feed bands, the specific cutting force, the spindle power and the machine's rigidity.
4. Process plan. Check the operations and the Governing limit column. Open Predicted process values for force, power, temperature, tool life and roughness per operation.
5. Physics, G-code, Validate. Inspect the detailed analysis, the generated programme and the simulation along the toolpath.
6. Export. Download the programme (.nc), the report and the JSON data.

Reading the governing limit

Checking your own G-code

1. Open Digital twin → Check my G-code. Choose Optimise my program or Compare programs.
2. Upload the part as STL, STEP or IGES (the finished part, in millimetres) and one to three programs (.nc, .tap, .gcode, .ngc, .cnc, .txt; up to 10 MB each), or load one of the examples.
3. If the program comes from SOLIDWORKS CAM, choose the post processor you used (the list matches the SOLIDWORKS CAM machine dialog); LIMES then reads the right G-code dialect – ISO/Fanuc/Haas, Siemens Sinumerik, Fagor, Brother or Okuma – and suggests a machine. Otherwise leave it on Detect from the program.
4. Select the machine and the material. Under Setup as in your CAM you can set what you defined in your CAM system before generating the toolpath: the stock (detected from the program by default: if the program never faces the top or machines the outside, the stock is the part's bounding box), the part orientation, the program zero, and the target roughness and allowed remaining stock.
5. Click Read programs. LIMES detects the type (3-axis, 3+2 or turning), fits the toolpath to the part to find the part orientation (for example a SolidWorks model saved with +Y up) and the program zero, and lists the tools it found in the comments (Fusion 360, Mastercam, SolidWorks CAM / CAMWorks, ISO insert codes). Correct any tool marked assumed: gouge and leftover results depend on the tool sizes. If the detected zero is not how the part was set up, choose another detected option or type it in.
6. Click Optimise or Compare. The verdict, a side-by-side table, time and power charts, a map of remaining stock and gouges, and the findings with line numbers are shown. Re-tuned and LIMES programs can be downloaded.

The re-tuned program keeps every coordinate, comment and block number; only F and S words change, and finishing moves never get a larger chip load than in your program. The LIMES program uses generic raster strategies: it is a safe independent benchmark, but a well-written contour program is often faster on simple prismatic parts, and the verdict says so.

Experiments and calibration of the models

The page Experiments & Calibration processes the measurements of the experimental programme (dissertation, Chapter 4) with exactly the model formulation used by the rest of the tool, so the coefficients it finds can be used without conversion. It is prepared for the aviation titanium alloys Ti-6Al-4V (VT6) and VT22 but works for every metal with a physics model.

1. Download the CSV templates, fill them in with the test results, and upload them. The synthetic demo data show the format and the output.
2. Force tests (Section 4.4): mean main cutting force from a dynamometer, or the net cutting power at the spindle (load meter or clamp-on power meter), at five feeds per tooth with three replications. Result: kc1.1 and mc with 95 % confidence intervals, R² ≥ 0.95 check, the single-insert (fly-cutting) check of the multi-tooth engagement and the force-component ratios.
3. Temperature tests (Section 4.5): the secondary-zone coefficient K_cal of the two-zone thermal model.
4. Tool-life tests (Section 4.6, ISO 8688-1): tool life from the flank-wear curve at VB = 0.3 mm, then C, n, a and b of the extended Taylor equation, with the physical-admissibility check a > 0, b > 0.
5. Roughness (Section 4.7): the built-up-edge and vibration factor K_bue.

For each quantity the agreement between calculation and experiment is reported as MAPE, MPE and R² against the acceptance criteria of Table 4.4, with the provisional and the calibrated coefficients side by side; rows marked set = verification give an independent check. The page also shows how the assigned cutting data and the governing limit change for a reference face-milling operation. The result is a calibration record (JSON) and the protocol tables for Sections 4.11–4.12 (CSV). The record takes effect only after it is reviewed and added to data/calibrations.json; uploads on the public site never change the coefficients used by others.

Accounts and My files

Create a free account on the sign-in page with your e-mail address and a password (you receive a 6-digit confirmation code by e-mail) or with Continue with Google. The tool and the API are used signed in. Signed in, you can also upload your own 3D models (STL, STEP, IGES) and G-code programs in the tool, and the My account page shows:

• Profile: name, e-mail, organisation and role, date of registration and last sign-in; edit them, change the password, sign out on all devices, or delete the account with all files.
• My files: the models and programs you uploaded in the tool (while Keep a copy of my uploads is on), uploaded on the page, or saved from the tool with Save to My files (generated and re-tuned G-code). Each file can be opened in the tool, downloaded, renamed or deleted. Storage per account is limited (default 200 MB, 200 files).

In the tool, the upload areas offer Or open from My files. Signing in or out happens on the website; the tool picks it up when the page is reloaded. What is stored and for how long is described in Privacy & security.

7. API overview

The API is served under /api/ on the same domain and is rate-limited. Every endpoint except sign-in, sign-up and /health needs a signed-in session (the cookie set by the sign-in page); requests without one receive 401. Interactive documentation is disabled in production.

8. Reproducing the results

The tables and figures on the Results page come from two scripts in research/:

cd research
python3 case_study_models.py     # six-material case study
python3 p1s_comparison.py        # symmetric rule vs sequential rule P1-S

9. Security measures

A summary is given on the Privacy & security page. The full list and the threat model are in SECURITY.md in the repository.

10. Limitations

• No experimental validation yet. All predictions use provisional coefficients. The ISO 8688-1 calibration programme on Ti-6Al-4V (VT6) and VT22 is designed and the calibration module is ready, but the tests have not been carried out, so absolute values of force, temperature and tool life are indicative only. The VT22 record in particular carries provisional cutting data (kc1.1 and the recommended bands are estimated from Ti-6Al-4V).
• Tool life is very sensitive to its constants. A 10 % error in the Taylor constant changes predicted tool life by about 50 %. Compare regimes rather than trusting absolute minutes.
• Single thermal threshold. The same homologous-temperature limit applies to all material groups. Aluminium alloys are therefore often thermally limited, although their real limit is adhesion and built-up edge.
• Material coverage. Physics-based selection covers steels, stainless steels, cast irons, aluminium, titanium and nickel alloys. Other materials use handbook bands.
• Drilling uses handbook values; thrust force and torque are not modelled.
• Stability is a conservative estimate; stability lobes need a measured frequency response.
• G-code uses the basic ISO 6983 word set with FANUC-style reference return (G28). Always post-process and verify on the target controller before cutting.
• G-code check. ISO / Fanuc / Haas dialect only; no simultaneous 4/5-axis, macros, cutter-radius compensation in the control, or holder and fixture collisions. Height-map resolution is 0.2–0.4 mm (3-axis), voxels 0.35–1 mm (3+2) and 0.05 mm axially (turning); results near walls are accurate to about one cell. Tool data missing from the program are assumed and must be checked.
• Indicative costs only. Cost figures use generic hourly rates from the machine database (default USD 80/h) and catalogue tool prices. Economic tool life is not optimised; use shop-specific rates for real quotations.

11. Troubleshooting

• “This does not look like an STL file” – export again as STL (binary or ASCII), or upload the model as STEP or IGES.
• “The STEP model could not be converted …” – the model is very complex or the file is damaged; simplify it, export it again, or export it as STL.
• “The model has … triangles; the limit is …” – simplify or decimate the mesh in your CAD system.
• “Model larger than 10 m” – the file was probably exported in micrometres or inches; re-export in millimetres.
• An error with a reference code – the details are in the server log under that code. Quote it when you contact the project.