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.
[dependencies]
caminos-lib = "0.4"Alternatively, consider whether the binary crate caminos fits your intended use.
- Added the function
server_stateto theTraffictrait. - Functions on the output module now use ExperimentFiles instead of Path.
- Added a server argument to
Traffic::try_consume. - Added phit to
RequestInfo.
- Added
pathargument toconfig::{evaluate,reevaluate}. - File
create_outputand similar now receive in itsresultsargument also the experiment indices. - routings now return
RoutingNextCandidates. In addition to the vector of candidates it contains anidempotentfield to allow some checks and optimizations. - Added requirement
VirtualChannelPolicy: Debug. - The
file_mainfunction now receives afree_argsparameter. Free arguments of the formpath=valueare used to override the configuration.
- Added parameter
cycletoTraffic::should_generate.
- Added methods to
RoutingandRoutertraits to gather statistics. - Added method
Routing::performed_requestto 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
LitStrandLiteral. - Now
neighbour_router_itermust always be used instead of0..degree()to check ports to other routers. Note thatdegreedoes not give valid ranges when having non-connected ports, as in the case of some irregular topologies as the mesh. Plugsnow include astagesattribute.- Removed from the
Topologyinterfaz the never used methodsnum_arcs,average_distance,distance_distribution.
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.cfgcontains the definition of the experiment to perform, expected to unfold into multiple simulations.main.odcontains the definition of what outputs are desired. For examplecsvfiles or (pdf,latex)-plots.remoteallows 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_indexis number of the current action.experiment_indexis 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. Theslurm_indexis the job id given by slurm.runs/run<experiment_index>/local.cfgis the configuration exclusive to the simulation numberexperiment_index.runs/run<experiment_index>/local.resultwill contain the result values of the simulation numberexperiment_indexafter a successful simulation.
The directory_main receives also an Action. In the crate caminos this is done via its --action=<method> falg.
local_and_outputruns all the remaining simulations locally and generates the outputs.localruns all the simulations locally, without processing the results afterwards.outputprocesses the currently available results and generates the outputs.slurmlaunches the remaining simulations onto the slurm system.checkjust shows how many results we got and how many are currently in slurm.pullbrings result files from the defined remote host.remote_checkperforms acheckaction in the remote host.pushcompares the local main.cfg with the host remote.cfg. It reports discrepancies and create the remote path if missing.slurm_cancelexecutes ascancelwith the job ids found in the journal file.shellcreates the experiment folder with default configuration files. Alternatively, when receiving--source=another_experimentit copies the configuration of the other experiment into this one.packforces 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.
The configuration files are parsed using the gramatica crate. These files are parsed as a ConfigurationValue defined as following.
pub enum ConfigurationValue
{
Literal(String),
Number(f64),
Object(String,Vec<(String,ConfigurationValue)>),
Array(Vec<ConfigurationValue>),
Experiments(Vec<ConfigurationValue>),
NamedExperiments(String,Vec<ConfigurationValue>),
True,
False,
Where(Rc<ConfigurationValue>,Expr),
Expression(Expr),
}
- An
Objectos typedName { key1 : value1, key2 : value2, [...] }. - An
Arrayis typed[value1, value2, value3, [...]]. - An
Experimentsis 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 typedusername![value1, value2, value3, [...]]. Its size must match otherNamedExperiments 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
Numbercan be written like 2 or 3.1. Stored as af64. - A
Literalis a double-quoted string. Trueis writtentruea andFalseis writtenfalse.Expressionis typed=expr, useful in output descriptions.- The
Whereclause is not yet implemented.
An example of main.cfg file is
Configuration
{
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.
delay:1,
},
//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.
Slurm
{
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.
},
],
}
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.
Plotkind{
//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.
Plotkind{
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",
},
},
Plots
{
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.