Volco

VOLCO (VOLume COnserving) is a model capable of simulating the 3D printing process. It simulates the printing process in a voxelized space and it is capable of predicting the final shape of a 3D printed material.

• Inputs

  • gcode

• Outputs

  • voxel 3D-matrix or .stl file

Example of the .stl file generated by VOLCO:

Support open source work

Help us continue to share work open source:

• Cite the papers listed at the bottom of this readme

• Involve us in academic research/papers (a.gleadall@lboro.ac.uk)

• Contibute improvements to this repo via pull requests

• Tell people about this repo

Papers

[1] - VOLCO: A predictive model for 3D printed microarchitecture

[2] - VOLCO-X: Numerical simulation of material distribution and voids in extrusion additive manufacturing

Running locally

• See detailed usage instructions and examples:

  • examples/jupyter_example.ipynb

  • examples/example.py

• VOLCO was tested using python 3.8, 3.9 and 3.10

• Installing dependencies

  • It is recommended to install dependencies in a virtual environment. Please, follow this guide to create a virtual environment. After the virtual environment is initialized, install the dependencies:

    pip3 install -r requirements.txt

• Simulating 3D printing

  python volco.py --gcode=examples/gcode_example.gcode --sim=examples/simulation_settings.json --printer=examples/printer_settings.json

Using in Jupyter Notebooks

VOLCO can be used directly in Jupyter notebooks, allowing for more interactive experimentation and visualization:

from volco import run_simulation

# Run simulation using file paths
# Note: When running from the examples directory, use '../' prefix for paths
output = run_simulation(
    gcode_path='examples/gcode_example.gcode',
    printer_config_path='examples/printer_settings.json',
    sim_config_path='examples/simulation_settings.json'
)

# Or use Python variables instead of file paths
output = run_simulation(
    gcode=gcode_content,  # G-code as a string
    printer_config=printer_config_dict,  # Printer config as a dictionary
    sim_config=sim_config_dict  # Simulation config as a dictionary
)

# Working with the output
output.export_mesh_to_stl()

# Visualize the mesh (in Jupyter notebooks)
fig = output.visualize_mesh(visualizer='plotly', color_scheme='cyan_blue')
fig.show()

Example of the plotly plot in a jupyter notebook:

Using in Python Scripts

The same functionality available in Jupyter notebooks can be used in regular Python scripts:

from volco import run_simulation

# Example Python script
def process_gcode(gcode_file):
    output = run_simulation(
        gcode_path=gcode_file,
        printer_config_path='examples/printer_settings.json',
        sim_config_path='examples/simulation_settings.json'
    )
    
    # Process the results
    print(f"Simulation complete. Voxel dimensions: {output.voxel_space.dimensions}")
    
    # Export to STL
    stl_path = output.export_mesh_to_stl()
    print(f"STL exported to: {stl_path}")
    
if __name__ == "__main__":
    process_gcode('examples/gcode_example.gcode')

Configuration Parameters

VOLCO uses two configuration files: simulation settings and printer settings. Below is an explanation of each parameter and its recommended default value.

Simulation Configuration

Parameter	Description	Default Value
voxel_size	Size of each voxel in mm. Smaller values increase accuracy but require more memory and computation time.	0.1
step_size	Distance between simulation steps in mm. Smaller values increase accuracy but slow down simulation.	0.2
x_offset, y_offset	Padding added to the voxel space boundaries in x and y directions.	5 × nozzle_diameter
z_offset	Additional space above the maximum z-coordinate in the G-code.	0
sphere_z_offset	Distance to offset the sphere center below the nozzle. Controls material deposition position.	0.5 × nozzle_diameter
x_crop, y_crop, z_crop	Cropping boundaries for the final output. Use ["all", "all"] to include everything.	["all", "all"]
radius_increment	Increment for sphere radius in the bisection method.	0.1
solver_tolerance	Tolerance for volume conservation in the bisection method.	0.0001
consider_acceleration	Whether to consider acceleration in volume distribution.	false
stl_ascii	Whether to export STL in ASCII format (true) or binary (false).	false

Printer Configuration

Parameter	Description	Default Value
nozzle_diameter	Diameter of the printer nozzle in mm.	0.4
feedstock_filament_diameter	Diameter of the input filament in mm.	1.75
nozzle_jerk_speed	Maximum instantaneous speed change for nozzle in mm/s.	8.0
extruder_jerk_speed	Maximum instantaneous speed change for extruder in mm/s.	5.0
nozzle_acceleration	Acceleration of the nozzle in mm/s².	500.0
extruder_acceleration	Acceleration of the extruder in mm/s².	1000.0

Parameter Relationships

• sphere_z_offset: Controls how far below the nozzle the center of each deposited sphere is placed. A value of half the nozzle diameter is typically appropriate, as it places the sphere center at the bottom of the nozzle.

• x_offset and y_offset: These provide space around the print in the voxel grid. Larger values ensure the entire print is captured but increase memory usage.

• z_offset: Set to 0 as material cannot be deposited above the nozzle height.

• consider_acceleration: When true, the simulation accounts for acceleration and deceleration, which can provide more accurate results but increases computation time.

Finite Element Analysis (FEA)

VOLCO includes a Finite Element Analysis (FEA) module that enables structural analysis of the simulated 3D printed parts. With just one line of code, you can analyze the structural behavior of your VOLCO simulation results:

from volco_fea import analyze_voxel_matrix, Surface

# Define boundary conditions
boundary_conditions = {
    'constraints': {
        Surface.MINUS_Z: "fix",  # Fix bottom surface
        Surface.PLUS_Z: [None, None, -0.1, None, None, None]  # Apply displacement on top
    }
}

# Run analysis
results = analyze_voxel_matrix(voxel_matrix, voxel_size, boundary_conditions=boundary_conditions)

For detailed documentation and examples, see app/postprocessing/fea/README.md.

LLM Reference Guide

For developers using large language models (LLMs) for code editing and development, we provide comprehensive reference documents:

• llm_ref.md - A structured overview of the repository designed to minimize context needed for LLM code editing
• llm_ref_fea.md - Detailed documentation of the FEA module structure and functionality

These reference documents should be updated as the repository evolves to ensure they remain accurate and useful.

Running tests

• Running tests

pytest

Running with docker-compose

• Building image

make build

• Simulating 3D printing inside container

make run-volco GCODE=examples/gcode_example.gcode SIM=examples/simulation_settings.json PRINTER=examples/printer_settings.json

• Running tests

make test