Skip to content

Configuring simulation settings

Many settings can be tuned before running a simulation. They fall into two categories: solver settings or graphics settings.

Solver settings only affect the solver (that is the part responsible to solve the nonlinear equations, by computing all the equilibrium points), while graphics settings determines what is generated to visualize a result (previously computed by the solver), and how it is going to look like.

All default solver and graphics settings along with useful comments are listed herein below:

show all
default_solver_settings.toml
radius = 0.05
must_be_stable_to_finish_loadstep=false
i_max = 5_000  # max number of increments to reach the prescribed force

detect_critical_points = false
bifurcate_at_simple_bifurcations = false  # only has an effect if 'detect_critical_points' is enabled
critical_point_epsilon = 1e-3  # when detecting critical points, a point is assumed to be critical if the ratio eig_val / initial_stiffness < critical_point_epsilon
# when bifurcating at simple bifurcations, amplitude of the perturbation (relative to the norm of the displacements)
# that multiplies the normalized buckling eigenmode
bifurcation_perturbation_amplitude = 1e-2

show_warnings = false
verbose = true
critical_point_detection_verbose=false
convergence_value = 1e-7
detect_mechanism = true

# herein below, more advanced settings for the arclength method
j_max = 15  # max number of iterations to correct the prediction
alpha = 0.0  # positive and never larger than 0.5
psi_p = 0.0
psi_c = 0.0
show all
default_graphics_settings.toml
[general_options]
generate_model_drawing = true
show_model_drawing = true
generate_fd_plot = true
show_fd_plot = true
show_custom_plot = true
generate_animation = true
show_animation = true

# herein below the desired outputs when scanning parameters
generate_parametric_fd_plots = true
show_parametric_fd_plots = true
show_parametric_custom_plots = true
generate_all_model_drawings = false
show_all_model_drawings = false
generate_all_fd_plots = false
generate_all_animations = false

[plot_options]
show_driven_path = false
driven_path_only = false
loading_sequence = "cycle"
# "loading", "cycle", "loading_unloading"
show_snapping_arrows = true
all_snapping_arrows = false
# if true (when show_snapping_arrow is true), it will show snapping arrow for every possible transition, regardless of the loading sequence,
# else only the snapping arrows encountered during the prescribed loading sequence

snapping_arrow_style = '-'
drive_mode = "none"
# "none" (nothing driven), "force" (force-driven), "displacement" (displacement-driven)

plot_style = 'points' # points, line
# will use points instead of line anyway in case the color mode is different from 'none' or 'stability'

color_mode = "stability"
# is *not* used when showing multiple equilibrium paths after a parameter scan
# "none" (default color), "stability" (by stability), "min_eigval_fd" (by lowest force-driven eig. val.),
# "min_eigval_ud" (by lowest displacement-driven eig. val.), "nb_neg_eigval_fd" (by nb force-driven eig. vals < 0),
# "nb_neg_eigval_ud (by nb displacement-driven eig. val < 0)
show_stability_legend = true
# only has an effect if "color_mode" = "stability"
show_driven_path_legend = true
# only has an effect if "drive_mode" is "force" or "displacement" and "drive_path_only" is false

figure_width = 4
figure_height = 4
axis_box_aspect = 0.75  # aspect ratio of the box defined by the axes' spines
enforce_xlim = false
enforce_ylim = false
xmin = 0.0
ymin = 0.0
xmax = 1.0
ymax = 1.0
transparent = false
dpi = 300

# herein below, colormaps. Must be named colormaps from matplotlib
# (visit https =//matplotlib.org/stable/users/explain/colors/colormaps.html for more info)
range_parameter_scan_colormap = "viridis"
discrete_parameter_scan_colormap = "tab10"
lowest_eigval_colormap = "PuOr"
# used when "color_mode" "min_eigval_fd" or "min_eigval_ud" is used, diverging colormap recommended
nb_negative_eigval_colormap = "plasma"
# used when "color_mode" "nb_neg_eigval_fd" or "nb_neg_eigval_ud" is used
energy_colormap = "viridis"
# used when "color_mode" "energy" is used

max_nb_legend_entries_for_discrete_parameter = 4

default_plot_name = "fd_curve"
default_xlabel = "displacement"
default_ylabel = "force"
default_color = "#a0a0a0"
default_opacity = 1.0
default_marker = "o"
default_markersize = 2.5
default_linewidth = 2.0


# herein below colors to indicate the stability of an equilibrium point,
# only used when "color_mode" "stability" is used.
color_for_stable_points = "#86a7fc"
color_for_stabilizable_points = "#ffdd95"
color_for_unstable_points = "#dd9843"

# herein below colors to indicate the stability of equilibrium branches
# only used when 'plot_style=line'
style_for_stable_branches = '-'
style_for_stabilizable_branches = '--'
style_for_unstable_branches = ':'

# herein below labels used to indicate the stability of equilibrium branches
label_for_stable_points = 'stable'
label_for_stabilizable_points = 'stabilizable'
label_for_unstable_points = 'unstable'

driven_path_color = "#444444"
size_for_driven_path = 0.4
# scaling of the default markersize for driven path
snapping_arrow_color_loading = "#ff0000"
snapping_arrow_color_unloading = "#0000ff"
# only has an effect if "show_snapping_arrow" is true
snapping_arrow_opacity = 1.0
# only has an effect if "show_snapping_arrow" is true
snapping_arrow_width = 1.75
# only has an effect if "show_snapping_arrow" is true
snapping_arrow_headwidth = 0.2
# only has an effect if "show_snapping_arrow" is true
snapping_arrow_headlength = 0.4
# only has an effect if "show_snapping_arrow" is true


# herein below scaling of the markersize to indicate stability,
# has no effect in case the "color_mode" "min_eigval_fd", "min_eigval_ud", "nb_neg_eigval_fd" or "nb_neg_eigval_ud is used
size_for_stable_points = 1
size_for_stabilizable_points = 0.66
size_for_unstable_points = 0.33

stylesheet = "default"
# one of the style names of matplotlib (see https://matplotlib.org/stable/gallery/style_sheets/style_sheets_reference.html)
# or the path/url to a stylesheet, such as "my_style_sheets/my_favorite_style.mplstyle" (see https://matplotlib.org/stable/users/explain/customizing.html#defining-your-own-style)
spine_offset = 10
show_top_spine = false
show_bottom_spine = true
show_left_spine = true
show_right_spine = false
hide_ticklabels = false

[animation_options]
fps = 25
nb_frames = 50
dpi = 200
drive_mode = "none"
# "none" (nothing driven), "force" (force-driven), "displacement" (displacement-driven)
cycling = false
default_animation_name = "animation"
save_as_mp4 = false  # can only save as mp4 if ffmpeg is installed and is 'in the PATH'
save_as_transparent_mov = false # can only save as mov if ffmpeg is installed and is 'in the PATH'
save_as_gif = true
save_frames_as_png = false
side_plot = true
stylesheet = "default"
# one of the style names of matplotlib (see https://matplotlib.org/stable/gallery/style_sheets/style_sheets_reference.html)
# or the path/url to a stylesheet, such as "my_style_sheets/my_favorite_style.mplstyle" (see https://matplotlib.org/stable/users/explain/customizing.html#defining-your-own-style)
animated_equilibrium_point_color = "#ff0000"
animated_equilibrium_point_size= 10
animation_width = 8
animation_height = 4.5

[assembly_appearance]
drawing_fig_width = 3
drawing_fig_height = 3
enforce_xlim = false
enforce_ylim = false
xmin = 0.0
ymin = 0.0
xmax = 1.0
ymax = 1.0
drawing_dpi = 300
show_axes = false
stylesheet = "default"  # only used when drawing the model, not used for the animation
transparent = false  # used when saving the model drawing or saving animation as PNG frames
coloring_mode = "generalized_force"
# "none", "energy", "generalized_force", "generalized_stiffness"
color_elements = true
color_forces = false
colormap="coolwarm"
# Colormap to color the elements and the forces. Must be a named colormap from matplotlib
# (visit https =//matplotlib.org/stable/users/explain/colors/colormaps.html for more info)
show_state_of_hysterons = true # it true, label with a state number will be shown at the center of the element
hysteron_state_label_size = 10
hysteron_state_bg_color = "#e0e0e0"
hysteron_state_txt_color = "#101010"
show_forces = true
hide_low_preloading_forces = false  # low forces are defined by parameter 'low_preloading_force_threshold'
low_preloading_force_threshold = 0.0  # preloading load with magnitude below this value will not be depicted if 'hide_low_preloading_forces' is true.
force_vector_scaling = 1.0
spring_style = "simple"  # "simple", "elegant", "line"
spring_nb_coils = 4  # has no effect if "spring_style" = "line"
spring_aspect = 0.4  # is only used when "spring_style" = "elegant"
spring_linewidth = 2
spring_width_scaling = 1.0
spring_default_opacity = 1.0
spring_default_color = "#cecece"
angular_spring_style = "line"  # "elegant", "line"
angular_spring_nb_coils = 6  # has no effect if "angular_spring_style" = "line"
angular_spring_radii_ratio = 6  # ratio between the angular spring radius and the coil radius. Is only used when "angular_spring_style" = "elegant"
angular_spring_aspect = 0.4  # is only used when "angular_spring_style" = "elegant"
angular_spring_linewidth = 2
angular_spring_radius_scaling = 1.0
angular_spring_default_opacity = 1.0
angular_spring_default_color = "#cecece"
area_spring_default_opacity = 0.5
area_spring_default_color = "#cecece"
path_spring_linewidth = 2
path_spring_default_opacity = 1.0
path_spring_default_color = "#cecece"
path_spring_dot_color = "#ffffff"
path_spring_dot_opacity = 1.0
distance_spring_linestyle = '-'  # any linestyle from matplotlib, in particular 'none' if you dont want to show the distance line
distance_spring_linewidth = 1.0
distance_spring_default_opacity = 1.0
distance_spring_default_color = '#cecece'
distance_spring_line_linestyle = '--'  # any linestyle from matplotlib, in particular 'none' if you dont want to show the line from which the distance is measured
distance_spring_line_linewidth = 1.0
distance_spring_line_default_color = '#CECECE'
paint_distance_spring_line_with_default_color = false
# if true, the line from which the distance is measured will be depicted with its default color, if false its color will match the one from the distance line
node_style = "elegant"  # "minimalist", "simple", "elegant"
node_size = 5.
node_color = "#101010"
node_edgecolor = "#101010"
node_edgewidth = 1.0
show_node_numbers = false
node_nb_color = "#cecece"
node_nb_shift_x = 5
node_nb_shift_y = 5
node_nb_fontsize = 10
force_vector_style = 'basic'
preload_force_opacity = 0.65
preload_force_default_color = '#cecece'
force_default_color = '#000000'
force_vector_length_scaling = 1.0
force_vector_connection = "tail"
force_vector_linewidth = 1.0  # only has an effect if 'force_vector_style' is 'basic'

When you wish to change a setting (let's say a solver setting), create a TOML file, that is a text file saved with extension .toml. You can use the NotePad (Windows) or TextEdit (MacOS) to do that, for example. The file will look similar to this:

custom_solver_settings.toml
radius = 0.01

A lower value for radius can be used to refine the solution, at the cost of increasing the solving duration. Default value is 0.05.

To use these custom solver settings, use the path to custom_solver_settings.toml as an extra argument of the ss.simulate_model() function, as follows:

my_first_simulation.py
"""
Python script example to learn how to use the package springable
"""
import springable.simulation as ss

ss.simulate_model(model_path='my_spring_model.csv',
                  save_dir='my_simulation_result',
                  solver_settings='custom_solver_settings.toml')

Similarly, when you wish to modify a graphics setting, create another TOML file and include the settings you wish to modify

custom_graphics_settings.toml
[animation_options]
nb_frames = 240
fps = 60

[plot_options]
show_snapping_arrows = true
drive_mode = "force"

Animation settings nb_frames and fps determine the number of frames and the frame rate (in frame per second) of the animation showing the spring assembly deforming. Plot settings show_snapping_arrows = true combined with drive_mode = "force" means that you want to indicate with arrows the (potential) snapping transitions under controlled force in the force-displacement plot. To indicate, snapping transitions under controlled displacement use show_snapping_arrows = true combined with drive_mode = "displacement" instead.

To use these custom graphics settings, use the path to custom_graphics_settings.toml as an extra argument of the ss.simulate_model() function, as follows:

my_first_simulation.py
"""
Python script example to learn how to use the package springable
"""
import springable.simulation as ss

ss.simulate_model(model_path='my_spring_model.csv',
                  save_dir='my_simulation_result',
                  solver_settings='custom_solver_settings.toml',
                  graphics_settings='custom_graphics_settings.toml')

Additional notes

  • A custom settings file does not need to contain all the possible settings; just include the one you wish to modify.
  • Graphics settings are divided into 4 sections of settings (indicated by [...] in TOML files):
    • general options (determines what should be generated and directly shown (drawing, animation, plot))
    • plot options (determines how plots will look like)
    • animation options (determines how animations will look like)
    • assembly appearance (determines how the spring assembly will be depicted)