crate documentation

[haguettaz]

Here's the expanded documentation for the crate, including usage examples, code snippets, best practices, and common pitfalls:

//! This crate provides tools for simulating spiking neural networks (SNNs) in Rust.
//!
//! # Creating Networks
//!
//! To create a spiking neural network, you can use the `Network` struct from the `core` module.
//! Here's an example of building a simple network with neurons and connections:
//!
//! ```rust
//! use rusty_snn::core::{Network, Connection};
//!
//! fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     // Define connections between neurons
//!     let connections = vec![
//!         Connection::build(0, 1, 0.8, 1.0)?, // from neuron 0 to neuron 1
//!         Connection::build(1, 2, 0.5, 0.5)?, // from neuron 1 to neuron 2
//!     ];
//!
//!     // Create the network from the connections
//!     let mut network = Network::new(connections);
//!
//!     // Optionally, save the network to a file
//!     network.save_to("network.json")?;
//!
//!     Ok(())
//! }
//! ```
//!
//! **Best Practices:**
//! - **Validate Parameters:** Always handle potential errors when building connections to ensure parameters like weight and delay are valid.
//! - **Logical Structuring:** Assign meaningful IDs to neurons and maintain a logical structure for easier debugging and extension.
//!
//! **Common Pitfalls:**
//! - **Missing Neurons:** Forgetting to include all necessary neurons can lead to incomplete networks.
//! - **Invalid Delays:** Negative delay values are invalid and will cause errors.
//!
//! # Simulating Networks
//!
//! Once you have a network, you can simulate it using the `run` method. This requires defining a `SimulationInterval` and providing a random number generator:
//!
//! ```rust
//! use rusty_snn::core::{Network, SimulationInterval};
//! use rand::rngs::StdRng;
//! use rand::SeedableRng;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     // Load the network from a file
//!     let mut network = Network::load_from("network.json")?;
//!
//!     // Create a random number generator
//!     let mut rng = StdRng::seed_from_u64(42);
//!
//!     // Define the simulation interval
//!     let simulation_interval = SimulationInterval::build(0.0, 10.0, 0.0, vec![])?;
//!
//!     // Run the simulation
//!     network.run(simulation_interval, &mut rng).await?;
//!
//!     Ok(())
//! }
//! ```
//!
//! **Best Practices:**
//! - **Seeded RNG:** Use a seeded random number generator for reproducible results.
//! - **Async Execution:** Remember to use the `#[tokio::main]` macro for asynchronous execution.
//!
//! **Common Pitfalls:**
//! - **Ignoring Futures:** Forgetting to `await` the `run` method will result in the simulation not executing.
//! - **Error Handling:** Not properly handling errors can cause the simulation to terminate unexpectedly.
//!
//! # Optimizing Networks
//!
//! The crate offers optimization capabilities through the `optimizer` module. While specifics may vary, here is a general approach:
//!
//! ```rust
//! use rusty_snn::optimizer::NetworkOptimizer;
//! use rusty_snn::core::Network;
//!
//! fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     // Load or create a network
//!     let mut network = Network::load_from("network.json")?;
//!
//!     // Create an optimizer instance
//!     let mut optimizer = NetworkOptimizer::new();
//!
//!     // Optimize the network parameters
//!     optimizer.optimize(&mut network)?;
//!
//!     // Save the optimized network
//!     network.save_to("optimized_network.json")?;
//!
//!     Ok(())
//! }
//! ```
//!
//! **Best Practices:**
//! - **Parameter Tuning:** Experiment with different optimization parameters for better results.
//! - **Monitor Performance:** Regularly evaluate the network's performance during optimization.
//!
//! **Common Pitfalls:**
//! - **Overfitting:** Be cautious of overfitting the network to a specific dataset.
//! - **Resource Intensive:** Optimization may be computationally intensive; ensure adequate resources.
//!
//! # Additional Notes
//!
//! - **Examples and Tutorials:** Check the `examples` directory in the repository for more detailed use cases.
//! - **Documentation:** Refer to the module-level documentation for detailed descriptions of functions and structs.
//! - **Community Support:** If you encounter issues, consider opening an issue on GitHub or joining the discussion forums.

Feel free to integrate this documentation into your code. Let me know if you need further assistance!

_Originally posted by @coderabbitai[bot] in https://github.com/haguettaz/rusty-snn/pull/11#discussion_r1837849895_