Expand description


This crate provides the CAMINOS simulator as a library. This is the Cantabrian Adaptable and Modular Interconnection Open Simulator.


This crate is caminos-lib. To use it add caminos-lib to your dependencies in your project’s Cargo.toml.

caminos-lib = "0.4"

Alternatively, consider whether the binary crate caminos fits your intended use.

Breaking changes

[0.4.0] to

  • Added the function server_state to the Traffic trait.
  • Functions on the output module now use ExperimentFiles instead of Path.

[0.3.0] to [0.4.0]

  • Added path argument to config::{evaluate,reevaluate}.
  • File create_output and similar now receive in its results argument also the experiment indices.
  • routings now return RoutingNextCandidates. In addition to the vector of candidates it contains an idempotent field to allow some checks and optimizations.
  • Added requirement VirtualChannelPolicy: Debug.
  • The file_main function now receives a free_args parameter. Free arguments of the form path=value are used to override the configuration.

[0.2.0] to [0.3.0]

  • Added parameter cycle to Traffic::should_generate.

[0.1.0] to [0.2.0]

  • Added methods to Routing and Router traits to gather statistics.
  • Added method Routing::performed_request to allow routings to make decisions when the router makes a request to a candidate.
  • Added ConfigurationValue::NamedExperiments(String,Vec<ConfigurationValue>).
  • Removed surrounding quotes from the config LitStr and Literal.
  • Now neighbour_router_iter must always be used instead of 0..degree() to check ports to other routers. Note that degree does not give valid ranges when having non-connected ports, as in the case of some irregular topologies as the mesh.
  • Plugs now include a stages attribute.
  • Removed from the Topology interfaz the never used methods num_arcs, average_distance, distance_distribution.

Public Interface

caminos-lib provides the functions directory_main and file_main, intended to use the file version when the final binary calls with a configuration file argument and the directory version when it is called with a directory argument.

The directory_main function receives a &Path assumed to contain a main.cfg, main.od, optionally remote, plus any generated files and subdirectories.

  • main.cfg contains the definition of the experiment to perform, expected to unfold into multiple simulations.
  • main.od contains the definition of what outputs are desired. For example csv files or (pdf,latex)-plots.
  • remote allows to define a remote from which to pull result files.
  • journaltracks the actions performed on the experiment. It is specially useful to track what execution are currently launched in what slurm jobs.
  • runs/job<action_index>/launch<experiment_index> are the scripts launched to slurm. action_index is number of the current action. experiment_index is expected to be the experiment index of one of the experiments included in the slurm job.
  • runs/job<action_index>/launch<experiment_index>-<slurm_index>.{out,err} are the outputs from scripts launched to slurm. The slurm_index is the job id given by slurm.
  • runs/run<experiment_index>/local.cfg is the configuration exclusive to the simulation number experiment_index.
  • runs/run<experiment_index>/local.result will contain the result values of the simulation number experiment_index after a successful simulation.

The directory_main receives also an Action. In the crate caminos this is done via its --action=<method> falg.

  • local_and_output runs all the remaining simulations locally and generates the outputs.
  • local runs all the simulations locally, without processing the results afterwards.
  • output processes the currently available results and generates the outputs.
  • slurm launches the remaining simulations onto the slurm system.
  • check just shows how many results we got and how many are currently in slurm.
  • pull brings result files from the defined remote host.
  • remote_check performs a check action in the remote host.
  • push compares the local main.cfg with the host remote.cfg. It reports discrepancies and create the remote path if missing.
  • slurm_cancel executes a scancel with the job ids found in the journal file.
  • shell creates the experiment folder with default configuration files. Alternatively, when receiving --source=another_experiment it copies the configuration of the other experiment into this one.
  • pack forces the creation of a binary.results file and erases the verbose raw results files. In some extreme cases it can reduce a decent amount of space and sped up computations.

Configuration Syntax

The configuration files are parsed using the gramatica crate. These files are parsed as a ConfigurationValue defined as following.

pub enum ConfigurationValue
  • An Object os typed Name { key1 : value1, key2 : value2, [...] }.
  • An Array is typed [value1, value2, value3, [...]].
  • An Experiments is typed ![value1, value2, value3, [...]]. These are used to indicate several simulations in a experiment. This is, the set of simulations to be performed is the product of all lists of this kind.
  • A NamedExperimentsis typed username![value1, value2, value3, [...]]. Its size must match other NamedExperiments with the same name. Thus if there is {firstkey: alpha![value1, value2, value3],secondkey: alpha![other1,other2,other3]}, then the simulations will include {firstkey:value1, secondkey:other1} and {firstkey:value3,secondkey:other3} but it will NOT include {firstkey:value1,secondkey:other3}.
  • A Number can be written like 2 or 3.1. Stored as a f64.
  • A Literal is a double-quoted string.
  • True is written truea and False is written false.
  • Expression is typed =expr, useful in output descriptions.
  • The Where clause is not yet implemented.

Experiment example

An example of main.cfg file is

	random_seed: ![42,43,44],//Simulate each seed
	warmup: 20000,//Cycles to warm the network
	measured: 10000,//Cycles measured for the results
	topology: RandomRegularGraph//The topology is given as a named record
		servers_per_router: 5,//Number of host connected to each router
		routers: 500,//Total number of routers in the network
		degree: 10,//Number of router ports reserved to go to other routers
		legend_name: "random 500-regular graph",//Name used on generated outputs
	traffic: HomogeneousTraffic//Select a traffic. e.g., traffic repeating a pattern continously.
		pattern: ![//We can make a simulation for each of several patterns.
			Uniform { legend_name:"uniform" },
			RandomPermutation { legend_name:"random server permutation" },
		servers: 2500,//Servers involved in the traffic. Typically equal to the total of servers.
		//The load offered from the servers. A common case where to include many simulation values.
		load: ![0.05, 0.1, 0.15, 0.2, 0.25, 0.3, 0.35, 0.4, 0.45, 0.5, 0.55, 0.6, 0.65, 0.7, 0.75, 0.8, 0.85, 0.9, 0.95, 1.0],
		message_size: 16,//The size in phits of the messages created by the servers.
	maximum_packet_size: 16,//Messages of greater length will be broken into several packets.
	router: Basic//The router is another object with a large description
		//The number of virtual channels. The basic router sets a buffer for each virtual channel in each port, both at input and output.
		virtual_channels: 8,
		//Policies that filter the candidate routes given by the routing algorithm. They may be used to break deadlock or to give preference to some choices.
		//EnforceFlowControl must be included to actually use flow control restrictions.
		virtual_channel_policies: [ EnforceFlowControl, WideHops{width:1}, LowestSinghWeight{extra_congestion:0, extra_distance:0, aggregate_buffers:true, use_internal_space:true}, Random ],
		delay: 0,//not actually implemted in the basic router. In the future it may be removed or actually implemented.
		buffer_size: 64,//phits available in each input buffer
		bubble: false,//to enable bubble mechanism in Cartesian topologies.
		flit_size: 16,//set to maximum_packet_size to have Virtual Cut-Through.
		intransit_priority: false,//whether to give preference to transit over injection.
		allow_request_busy_port: true,//whether to allow input buffer to make requests to ports that are transmitting
		output_buffer_size:32,//Available phits in each output_buffer.
		output_priorize_lowest_label: true,//whether arbiters give priority to requests with lowest label.
	routing: ![//Algorithm to provide candidate exit ports.
		Shortest { legend_name: "shortest" },
		Valiant {
			//The meta-routing by Valiant in which we sent shortest to a random middle router
			//And then shortest from the middle to the destination.
			first: Shortest,//We can change the sub-routing in either the first or second segment.
			second: Shortest,//If we do not have arguments we only put the object name. No need for braces.
			legend_name: "generic Valiant",
	link_classes: [
		//We can set the delays of different class of links. The number of classes depends on the topology.
		LinkClass {
			//In random regular graphs all router--router links have the same class.
		//The last class always correspond to the links between server and router
		LinkClass { delay: 1},
		//In a dragonfly topology we would have 0=server, 1=routers from same group, 2=routers from different groups.
	launch_configurations: [
		//We may put here options to send to the SLURM system.
			job_pack_size: 2,//number of simulations to go in each slurm job.
			time: "1-11:59:59",//maximum time allocated to each slurm job.

Example output description

An example of output decription main.od is

	CSV//To generate a csv with a selection of fields
		fields: [=configuration.traffic.pattern.legend_name, =configuration.traffic.load, =result.accepted_load, =result.average_message_delay, =configuration.routing.legend_name, =result.server_consumption_jain_index, =result.server_generation_jain_index, =result.average_packet_hops, =result.average_link_utilization, =result.maximum_link_utilization],
		filename: "results.csv",
	Plots//To plot curves of data.
		selector: =configuration.traffic.pattern.legend_name,//Make a plot for each value of the selector
		kind: [
			//We may create groups of figures.
			//In this example. For each value of pattern we draw three graphics.
				//The first one is accepted load for each offered load.
				//Simulations with same parameter, here offered load, are averaged together.
				parameter: =configuration.traffic.load,
				abscissas: =configuration.traffic.load,
				label_abscissas: "offered load",
				ordinates: =result.accepted_load,
				label_ordinates: "accepted load",
				min_ordinate: 0.0,
				max_ordinate: 1.0,
			//In this example we draw message delay against accepted load, but we
			//continue to average by offered load. The offered load is also used for
			//the order in which points are joined by lines.
				parameter: =configuration.traffic.load,
				abscissas: =result.accepted_load,
				label_abscissas: "accepted load",
				ordinates: =result.average_message_delay,
				label_ordinates: "average message delay",
				min_ordinate: 0.0,
				max_ordinate: 200.0,
		legend: =configuration.routing.legend_name,
		prefix: "loaddelay",
		backend: Tikz
			//We use tikz to create the figures.
			//We generate a tex file easy to embed in latex document.
			//We also generate apdf file, using the latex in the system.
			tex_filename: "load_and_delay.tex",
			pdf_filename: "load_and_delay.pdf",
		selector: =configuration.traffic.pattern.legend_name,//Make a plot for each value of the selector
		//We can create histograms.
		kind: [Plotkind{
			label_abscissas: "path length",
			label_ordinates: "amount fo packets",
			histogram: =result.total_packet_per_hop_count,
			min_ordinate: 0.0,
			//max_ordinate: 1.0,
		legend: =configuration.routing.legend_name,
		prefix: "hophistogram",
		backend: Tikz
			tex_filename: "hop_histogram.tex",
			pdf_filename: "hop_histogram.pdf",

Fot the tikz backend to work it is necessary to have a working LaTeX installation that included the pgfplots package. It is part of the texlive-pictures package in some linux distributions.


Both entries directory_main and file_main receive a &Plugs argument that may be used to provide the simulator with new implementations. This way, one can make a copy of the main in the caminos crate and declare plugs for their implemented Router, Topology, Routing, Traffic, Pattern, and VirtualChannelPolicy.


The file main.od contains the description of the outputs to be generated by executing the Output action in an experiment.

A Pattern defines the way elements select their destinations.

A policy defined to what output queue/port to request among the ones returned as possible by the routing function. Policies are designed to be applied in sequence so that there remains at most a single candidate.

A Routing defines the ways to select a next router to eventually reach the destination.

A Topology defines the way routers and servers are connected.

A Traffic defines the way load is generated by the servers.


Description of common properties of sets of links. For example, the links to servers could have a different delay. The topologies can set additional classes. For example, a mesh/torus can diffentiate horizontal/vertical links. And a dragonfly topology can differentiate local from global links.

An application message, broken into packets

An instantiated network, with all its routers and servers.

A portion of a message. They are divided into phits. All phits must go through the same queues without phits of other packets in between.

Minimal unit to be processed by the network. Not to be confused with flits.

The objects that create and consume traffic to/from the network.

The object represeting the whole simulation.

default() generates an empty measurement, invoked on each reset. begin_cycle must be set on resets.

All the global statistics captured.


Main when passed a directory as path path must be a directory containing a main.cfg. plugs constains the plugged builder functions. action is the action to be performed in the experiment. For example running the simulations or drawing graphics. options encapsulate other parameters such as restricting the performed action to a range of simulations.

Main when passed a configuration file as path file must be a configuration file with the experiment to simulate. plugs constains the plugged builder functions. result_file indicates where to write the results. free_args are free arguments. Those of the form path=value are used to override configurations.

Get an identifier of the git commit. It is of little use to someone using a forzen public version. The value is fixed in the build script.

Get the number currently written in the Cargo.toml field version. In public version this is more useful than get_git_id.

Derive Macros