M08 — Macros, files, and debugging · Learn to Program Ansys APDL Simulations

In M07, the model already builds, solves, and validates against theory. That still does not make it a tool: it remains a monolithic script. In M08, we will refactor it into a reusable driver with arguments, submacros, and debugging evidence, preparing the M09 parametric sweep.

Your mission

You will separate inputs, construction, solution, and results; invoke the same macro for two heights with mesh_h as an argument; and generate a CSV that can pass or fail each case without touching the GUI.

Guiding question: can you reproduce the same result from a clean directory?

Objectives

After completing M08, you will be able to:

Separate an FEA workflow into callable phases using /INPUT.
Pass and validate an argument contract with *USE and ARGx.
Write reproducible evidence with *CFOPEN and *VWRITE.
Diagnose faults with /STATUS, the .out file, and counts.
Run two verifiable cases without rewriting the M07 physics.
Document a symptom → check → cause → solution table.

Prerequisites and downloads

M07: the base case passes deflection, interior stress, and equilibrium.
M02: components must not depend on residual selections.
M01: analytical references travel with the input parameters.

08_start.mac — starting point.
08_macro_debug.mac — audited driver.
08_build.mac — construction.
08_solve.mac — solution.
08_extract.mac — validation and CSV.
08_bug_hunt.mac — five reuse faults.
08_challenge.mac — two-case challenge.
08_expected_results.csv — self-check contract.
macro-call-tree.svg — driver architecture.
debug-flow.svg — debugging flow.

How to use this lesson

Path	Duration	Coverage
First win	25–30 min	Prediction, driver invocation, and first run with CSV.
Complete	60–65 min	Also: submacros, debugging, and the two-clean-directory challenge.

Recommendation: define the ARG contract before writing code. A macro without early validation turns an input error into an hour of later debugging.

Session map

Mission: objectives, downloads, and prediction for two heights.
Mental model: contract before code.
Demonstration: invocation, submacros, and CSV evidence.
Bug hunt: paths, arguments, and incorrectly propagated KEYOPT.
Challenge: reproducibility between two clean directories.
Mastery: final test before the M09 automated project.

Prediction — Two heights, one law

With b = 0.05 m, L = 1 m, E = 210 GPa, and F = −1000 N:

I = b·h³/12
uy_ref = F·L³/(3·E·I)
sigma_ref(x=0.2L) = F·(0.8L)·(h/2)/I

Case	h (m)	mesh_h (m)	uy_ref (m)	sigma_ref (Pa)	Topology
1	0.10	0.05	−3.80952381E−4	9.60000E6	126 nodes / 40 elems
2	0.08	0.04	−7.44047619E−4	1.50000E7	156 nodes / 50 elems

When the height is reduced from 0.10 to 0.08, the moment of inertia falls with h³ and theoretical deflection increases by approximately 95%. If the driver is properly encapsulated, that change only requires new arguments.

Mental model — Contract before code

Driver that validates arguments and calls build, solve, and extract — Figure 1. One public macro orchestrates three private phases with explicit failures.

M08 introduces no new physics. It changes the software's form: validated inputs, separated phases, file output, and systematic diagnosis. Without that contract, the M09 sweep would only multiply hidden errors.

Step 1 — Invoke with an explicit contract

/CLEAR,START
*USE,08_macro_debug.mac,0.10,-1000,0.05,1

*USE loads the macro and assigns ARG1…ARG4. The driver translates those arguments into named parameters and rejects invalid values before building anything:

beam_h=ARG1
tip_force=ARG2
mesh_h=ARG3
case_id=ARG4

*IF,beam_h,LE,0,THEN
  /COM,ERROR: ARG1 beam_h must be positive
  /STATUS,PARM
  /EOF
*ENDIF

Do not run /CLEAR inside the driver. It would clear the database and macro stack. Clean the session before calling *USE.

Step 2 — Separate construction, solution, and extraction

/INPUT,08_build,mac,,,,1
/INPUT,08_solve,mac,,,,1
/INPUT,08_extract,mac,,,,1

Each phase assumes and checks preconditions. 08_build.mac creates geometry, mesh, and components; 08_solve.mac applies D/F and solves; 08_extract.mac activates the set, validates against theory, and writes the CSV.

Mesh divisions are calculated with NINT(dim/mesh_h). Thus mesh_h is a real contract argument, not a hardcoded value in the monolith. Construction sets KEYOPT(2)=3 on SOLID185: with KEYOPT(2)=0, bending stress is artificially low (~22%) on this mesh.

Step 3 — Write evidence, not just messages

*CFOPEN,m08_results,csv
*VWRITE
('case_id,beam_h,tip_force,mesh_h,n_nodes,n_elements,...,passes')
*VWRITE,case_id,beam_h,tip_force,mesh_h,n_nodes,n_elements,...,passes
(...format...)
*CFCLOS

The CSV must contain inputs, topology, FE results, analytical references, relative errors, and passes. An on-screen /COM helps debugging; the file is evidence that survives the session.

Step 4 — Always diagnose with the same method

Debugging cycle: symptom, evidence, cause, and correction — Figure 2. Each fault is closed with a minimum correction and a clean rerun.

/STATUS,PARM
/COM,Inspect the .out for file paths, empty selections and missing sets

If passes=0, do not relax tolerances. Ask in this order: is the argument contract valid? Are the submacros in the working directory? Do the components contain nodes? Does a result set exist before extraction?

CSV acceptance contract

Compare your output with 08_expected_results.csv:

Case 1: 126 nodes, 40 elements, uy_ref=−3.80952381E−4.
Case 2: 156 nodes, 50 elements, uy_ref=−7.44047619E−4.
Deflection error < 5%, interior stress < 10%, equilibrium < 0.5%.
passes=1 in both cases.

Common pitfalls

Calling *USE without also copying 08_build, 08_solve, and 08_extract.
Forgetting ALLSEL,ALL between regions and carrying a residual selection.
Extracting displacements when n_sets=0.
Changing the physics or tolerance to “make” an incorrectly invoked case pass.

Bug hunt

Open 08_bug_hunt.mac. It contains five deliberate defects. Complete the table for each one:

Error	Symptom	Check	Cause	Minimum fix
1	Immediate `/EOF`	`/STATUS,PARM`	`ARG1 ≤ 0`	Correct the `*USE` contract
2	Macro not found	`.out` / path	Incorrect name or folder	Copy all four `.mac` files to the cwd
3	Zero load	`n_tip=0`	Empty component	Review `CM` and `SELTOL`
4	Nonsensical equilibrium	Active selection	Residual selection	`ALLSEL` between phases
5	Garbage values	`n_sets`	Extraction without `SET`	Activate the set before `*GET`

Verifiable challenge — Two clean directories

Run the driver for both cases from an empty directory. Then repeat the pair of runs from a second clean directory. The CSV files must match numerically and must not depend on residual selections from another session.

/CLEAR,START
*USE,08_macro_debug.mac,0.10,-1000,0.05,1

/CLEAR,START
*USE,08_macro_debug.mac,0.08,-1000,0.04,2

Check	Case 1	Case 2
Topology	126 / 40	156 / 50
uy_ref	−3.80952381E−4 m	−7.44047619E−4 m
sigma_ref	9.60000E6 Pa	1.50000E7 Pa
passes	1	1

Self-assessment

Why does the driver validate arguments before building?

Because an invalid argument must fail explicitly and early. Building on a broken contract produces misleading evidence.

What does separating build / solve / extract provide?

It lets you debug in blocks, reuse phases, and avoid a monolith that cannot be orchestrated from M09.

When is /COM enough, and when is a CSV required?

The message helps in the current session. The CSV is evidence that can be compared across runs, directories, and reviews.

What do you check if tip_nodes is empty?

Check beam_l, the SELTOL tolerance, and that the component was created after meshing rather than from an incorrect prior selection.

Learning evidence

08_macro_debug.mac driver callable with four arguments.
08_build, 08_solve, and 08_extract submacros.
m08_results.csv for both cases with passes=1.
.out log and, if applicable, /STATUS output from a diagnosed fault.
Bug-hunt diagnosis table.
Reproducibility test between two clean directories.

Exit checklist

☐ I validate ARG1…ARG4 before building.
☐ I separated construction, solution, and extraction.
☐ Each phase fails explicitly when preconditions are missing.
☐ I write a CSV with inputs, FE results, references, and passes.
☐ I diagnose with /STATUS, .out, and counts.
☐ I ran both contract cases.
☐ I repeated the test from a clean directory.
☐ I did not relax M07 tolerances to force a pass.

Technical traceability

This lesson uses the 2024 R1 Command Reference for *USE, ARG1–ARGn, /INPUT, *CFOPEN, *VWRITE, /STATUS, and /EOF, and the APDL Guide for macro and file organization. The physics and validation tolerances are inherited from M07.

Next step: M09

With a verifiable driver, M09 can sweep several heights using *DO, consolidate a decision CSV, and select the acceptable design with the smallest section without manual intervention.

Save your progress

Macros, files, and debugging