Adams Python Model Builder

Common Patterns

Returning a value to CMD from run_python_code

When Python code is executed from CMD via run_python_code(str), the CMD-side return value is always 1 (success) or 0 (failure) — the Python expression's own return value is discarded. To pass a result back to CMD, store it in an Adams design variable using set_dv from the aviewpy library. The CMD macro then reads it directly.

! Inside a CMD macro — run Python and capture the result via set_dv
var set var=$_self.py_str str=                             "from aviewpy.variables import set_dv"
var set var=$_self.py_str str=(eval($_self.py_str)),       "result = my_function()"
var set var=$_self.py_str str=(eval($_self.py_str)),       "set_dv('$_self', 'my_result', result)"
var set var=$_self.tmp_int int=(eval(run_python_code(str_merge_strings("\\n", $_self.py_str))))

! Now the result is stored in the macro's own design variable 'my_result'
if condition=(eval($_self.my_result) > 10)
    ! do something
end

The CMD macro reads the result back with (eval($_self.my_result)).

Key points:

• set_dv(parent, name, value) creates the design variable if it doesn't exist, or updates it. It auto-detects the type (real, integer, string).
• Inside a CMD macro, pass '$_self' as the parent string — Adams substitutes the macro's full dot-path name before Python sees it, so the DV becomes a child of the macro.
• Installation: aviewpy must be installed into the Adams Python environment: path/to/mdi.bat python -m pip install aviewpy.

Common Antipatterns

Using the return value of run_python_code as a result

! WRONG — CMD will see 1 (success), not the Python function's return value
var set var=$_self.my_result int=(eval(run_python_code("my_function()")))

run_python_code returns an exit-code (1 = success, 0 = failure), not the value of the Python expression. See the set_dv pattern above for the correct approach.

Model-Building Workflow

import Adams

# 1. Create model
m = Adams.Models.create(name='my_model')

# 2. Set units
d = Adams.defaults
d.units.length = 'mm'
d.units.mass   = 'kg'
d.units.time   = 'second'
d.units.force  = 'newton'

# 3. Gravity
grav = m.Forces.createGravity(name='GRAVITY')
grav.xyz_component_gravity = [0, -9806.65, 0]

# 4. Access ground part and create reference marker
ground = m.ground_part                                   # ground is always .my_model.ground
gnd_mkr = ground.Markers.create(name='MOUNT_A', location=[0, 0, 0])

# 5. Create a rigid part (part origin placed at its CM for simplicity)
link = m.Parts.createRigidBody(name='link', location=[0, 0, 100])
link.mass = 1.5
link.ixx  = 1200.0
link.iyy  = 1200.0
link.izz  = 50.0

# 6. Create markers on the part
pin_mkr = link.Markers.create(name='pin_mkr', location=[0, 0, 0])   # local coords

# 7. Create a revolute joint
rev = m.Constraints.createRevolute(name='rev_1',
                                   i_marker=pin_mkr,
                                   j_marker=gnd_mkr)

# 8. Add geometry for visualization
link.Geometries.createCylinder(name='rod', center_marker=pin_mkr,
                               length=200, radius=5,
                               angle_extent=360, side_count_for_body=16,
                               segment_count_for_ends=8)

# 9. Run simulation
sim = m.Simulations.create(name='run1', end_time=2.0, number_of_steps=2000)
sim.simulate()

Build order: model → units → gravity → ground markers → parts → part markers → constraints → forces → geometry → data elements → simulation.

Force Selection Guide

Decision guide: matches the CMD skill — the physics is identical, only the syntax differs.

Constraints & Motions

Primitive constraints: createAtPoint(), createInline(), createInPlane(), createOrientation(), createParallel(), createPerpendicular(), createPointPoint()

Motions:

# Apply motion to an existing joint
mo = m.Constraints.createJointMotion(name='drv', joint=rev,
                                     type_of_freedom='rotational',
                                     function='360D * time')

# Free-standing motion (not tied to a joint)
mo2 = m.Constraints.createMotion(name='drv2', i_marker=mkr_i, j_marker=mkr_j,
                                  type_of_freedom='translational',
                                  time_derivative='velocity',
                                  function='100.0')

Geometry

Note: Geometries are created on a part (part.Geometries.createX()) except spring-damper visual and force display, which live on the model (model.Geometries.createX()).

Data Elements

# Spline (1D or 2D lookup table)
spl = m.DataElements.createSpline(name='road_profile',
                                  x=[0, 10, 20, 30],
                                  y=[0, 5, 3, 8],
                                  linear_extrapolate=True)

# Design variable (parametric)
dv = m.DesignVariables.createReal(name='SPRING_K', value=5000.0)
spring.stiffness = Adams.expression(dv.full_name)

# State variable (for FUNCTION= feedback)
sv = m.DataElements.createStateVariable(name='load_sensor',
                                        function='FZ(.model.axle.cm, .model.ground.ref, .model.ground.ref)')

# Material
mat = m.Materials.create(name='steel',
                          youngs_modulus=2.07e5, poissons_ratio=0.29, density=7.8e-6)
link.material_type = mat

Simulation

# Simple transient run
sim = m.Simulations.create(name='run1',
                           end_time=5.0,
                           number_of_steps=500,
                           initial_static=False)
sim.simulate()

# With initial static equilibrium
sim2 = m.Simulations.create(name='run2', end_time=2.0, number_of_steps=200,
                            initial_static=True)
sim2.simulate()

# Scripted — inline ACF solver commands
sim3 = m.Simulations.create(name='run3',
                            script_type='solver_commands',
                            script=['simulate/transient,duration=10,dtout=0.01',
                                    'linear/statemat,file=model.mat'])
sim3.simulate()

# Scripted — by CMD language commands
sim4 = m.Simulations.create(name='run4',
                            script_type='commands',
                            script='simulation single_run transient type=auto_select '
                                   'end_time=5.0 number_of_steps=500 model_name=.my_model')
sim4.simulate()

script_type options: 'simple' (default), 'commands' (CMD language), 'solver_commands' (ACF).

Post-processing

# Access analysis results after simulate()
analysis = m.Analyses[sim.name]          # or m.Analyses['run1']

# Browse result components (OrderedDict)
print(analysis.results.keys())           # top-level groups
component = analysis.results['PART_1']['CM Position']['X']
values = component.values                # List[float], one per time step

# Create a measure (tracked during simulation)
meas = m.Measures.createObject(name='link_angle',
                               object=rev,
                               characteristic='ax_ay_az_projection_angles',
                               component='z_component')

# Function measure (arbitrary FUNCTION= expression)
fm = m.Measures.createFunction(name='spring_force',
                               function='DM(.model.link.pin_mkr, .model.ground.mount_a)')

FUNCTION= Expressions Quick Reference

Runtime expressions are identical between CMD and Python — they're always passed as plain strings to .function properties. The Adams Solver evaluates them at each timestep.

spring.function = 'STEP(TIME, 0.0, 0.0, 1.0, 500.0)'
motion.function = '360D * TIME'
sforce.function = 'IMPACT(DZ(.model.body.cm, .model.ground.ref), VZ(.model.body.cm, .model.ground.ref, .model.ground.ref), 0.0, 1e5, 1.5, 50.0, 0.1)'
sforce.function = 'AKISPL(DX(.model.body.cm, .model.ground.ref), 0, .model.road_profile, 0)'

Full expression reference: references/function-expressions.md

Key Reference Files

Submit a Lesson Learned

If during your work you discover something useful that other Adams users would benefit from — a non-obvious behaviour, a reliable workaround, a better approach — do the following:

1. Draft the lesson:

   {
     "skill": "adams-python-model-builder",
     "summary": "One-sentence description",
     "detail": "Full explanation with enough context to be actionable",
     "adams_version": "<version if relevant, else omit>",
     "os": "<windows/linux if relevant, else omit>"
   }
   

2. Always append it to lessons-learned.md in the skill folder (create the file if it doesn't exist). Use this format:

   ## <summary>
   **Date:** <YYYY-MM-DD>  
   **Submitted:** <yes/no>
   
   <detail>
   

3. Show it to the user and ask: "I've recorded this locally — want me to also submit it anonymously to the skill maintainer?"
4. If yes, POST it:

   POST https://adams-skills-api.bthorn191.workers.dev/lessons
   Content-Type: application/json
   <lesson JSON>
   

   Then update the Submitted: field in lessons-learned.md to yes.
5. If the POST fails, tell the user and move on — do not retry. Leave Submitted: no in the local file.