Crate gorder

Source
Expand description

§gorder: Everything you will ever need for lipid order calculations

A crate for calculating lipid order parameters from Gromacs simulations. gorder can calculate atomistic, coarse-grained, as well as united-atom lipid order parameters.

It is recommended to first read the gorder manual to understand the capabilities of gorder and then refer to this documentation for details about the Rust API.

§Usage

Run:

$ cargo add gorder

Import the crate in your Rust code:

use gorder::prelude::*;

gorder is also available as a command-line tool. You can install it using:

$ cargo install gorder

§Quick examples

Basic analysis of atomistic lipid order parameters:

use gorder::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // Construct the analysis
    let analysis = Analysis::builder()
        .structure("system.tpr")                   // Structure file
        .trajectory("md.xtc")                      // Trajectory file to analyze
        .output("order.yaml")                      // Output YAML file
        .analysis_type(AnalysisType::aaorder(      // Type of analysis to perform
            "@membrane and element name carbon",   // Selection of heavy atoms
            "@membrane and element name hydrogen", // Selection of hydrogens
        ))
        .build()?;                                 // Build the analysis

    // Activate colog for logging (requires the `colog` crate)
    colog::init();

    // Run the analysis and write the output
    analysis.run()?.write()?;

    Ok(())
}

Basic analysis of coarse-grained lipid order parameters:

use gorder::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // Construct the analysis
    let analysis = Analysis::builder()
        .structure("system.tpr")                   // Structure file
        .trajectory("md.xtc")                      // Trajectory file to analyze
        .output("order.yaml")                      // Output YAML file
        .analysis_type(AnalysisType::cgorder(      // Type of analysis to perform
            "@membrane",                           // Selection of beads
        ))
        .build()?;                                 // Build the analysis

    // Activate colog for logging (requires the `colog` crate)
    colog::init();

    // Run the analysis and write the output
    analysis.run()?.write()?;

    Ok(())
}

Basic analysis of united-atom lipid order parameters:

use gorder::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // Construct the analysis
    let analysis = Analysis::builder()
        .structure("system.tpr")                   // Structure file
        .trajectory("md.xtc")                      // Trajectory file to analyze
        .output("order.yaml")                      // Output YAML file
        .analysis_type(AnalysisType::uaorder(      // Type of analysis to perform
            Some("element name carbon and not name C15 C34 C24 C25"),  // Selection of satured carbons
            Some("name C24 C25"),                  // Selection of unsaturated carbons
            None,                                  // Selection of atoms to ignore
        ))
        .build()?;                                 // Build the analysis

    // Activate colog for logging (requires the `colog` crate)
    colog::init();

    // Run the analysis and write the output
    analysis.run()?.write()?;

    Ok(())
}

The Analysis structure includes many optional fields.

use gorder::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // Construct the analysis
    let analysis = Analysis::builder()
        .structure("system.tpr")                   // Structure file
        .bonds("bonds.bnd")                        // Topology file containing bonds (not needed with TPR structure file)
        .trajectory("md.xtc")                      // Trajectory file to analyze
        .index("index.ndx")                        // Input NDX file
        .output_yaml("order.yaml")                 // Output YAML file
        .output_tab("order.tab")                   // Output table file
        .output_xvg("order.xvg")                   // Pattern for output XVG files
        .output_csv("order.csv")                   // Output CSV file
        .analysis_type(AnalysisType::cgorder(      // Type of analysis to perform
            "@membrane",                           // Selection of beads
        ))
        .membrane_normal(Axis::Z)                  // Membrane normal
        .begin(100_000.0)                          // Start time of analysis
        .end(200_000.0)                            // End time of analysis
        .step(5)                                   // Analyze every Nth frame
        .min_samples(100)                          // Minimum required samples
        .n_threads(4)                              // Number of threads to use
        .leaflets(                                 // Calculate order for individual leaflets
            LeafletClassification::global(         // Method for classifying lipids into leaflets
                "@membrane",                       // Lipids for membrane center
                "name PO4"                         // Lipid heads selection
            )
            .with_frequency(Frequency::once())     // Frequency of classification
        )
        .ordermaps(                                // Construct maps of order parameters
            OrderMap::builder()
                .output_directory("ordermaps")     // Directory for order maps
                .dim([                             // Dimensions of the map
                    GridSpan::Manual {             // X-dimension span
                        start: 5.0,                // Start at 5 nm
                        end: 10.0,                 // End at 10 nm
                    },
                    GridSpan::Auto,                // Auto span for Y-dimension
                ])
                .bin_size([0.05, 0.2])             // Grid bin size
                .min_samples(30)                   // Minimum samples per bin
                .plane(Plane::XY)                  // Orientation of the map
                .build()?
        )  
        .estimate_error(EstimateError::new(        // Estimate error for calculations
            Some(10),                              // Number of blocks for averaging
            Some("convergence.xvg")                // Output file for convergence
        )?)
        .geometry(Geometry::cylinder(              // Only consider bonds inside a cylinder
            "@protein",                            // Reference position for the cylinder
            3.0,                                   // Radius of the cylinder
            [-2.0, 2.0],                           // Span of the cylinder relative to reference
            Axis::Z                                // Orientation of the main cylinder axis
        )?)               
        .handle_pbc(true)                          // Handle periodic boundary conditions?
        .build()?;                                 // Build the analysis

    // Activate colog for logging (requires the `colog` crate)
    colog::init();

    // Run the analysis and write the output
    analysis.run()?.write()?;

    Ok(())
}

§Detailed usage

It is recommended to first read the gorder manual to understand the capabilities of gorder and then refer to this documentation for details about the Rust API.

Performing lipid order parameter calculations using the gorder crate consists of three main steps:

  1. Constructing the Analysis structure.
  2. Running the analysis.
  3. Inspecting the results.

§Step 1: Constructing the Analysis structure

Start by including the prelude of the gorder crate:

use gorder::prelude::*;

The Analysis structure is constructed using the “builder” pattern. First, initiate the builder:

Analysis::builder()

Then, add your options to it:

.structure("system.tpr")
.trajectory("md.xtc")
.analysis_type(AnalysisType::aaorder(
    "@membrane and element name carbon",
    "@membrane and element name hydrogen")
)

When using the gorder application, specifying the output YAML file is mandatory. However, when you are using gorder as a crate, specifying the output file is optional, as you might not require any output to be generated.

Finally, assemble the Analysis:

.build()?;

Alternatively, you can construct the Analysis using an input YAML file that is also used by the CLI version of gorder:

let analysis = Analysis::from_file("analysis.yaml")?;

See the gorder manual for the format of this input YAML file.

To learn more about the various input parameters for Analysis, refer to:

  1. AnalysisBuilder for an overview of the builder.
  2. AnalysisType for the types of analysis.
  3. OrderMapBuilder and OrderMap for specifying order parameter maps.
  4. LeafletClassification for leaflet classification.
  5. MembraneNormal, Axis, and DynamicNormal for membrane normal specification.
  6. EstimateError for error estimation.
  7. Geometry for geometry selection.

§Step 2: Running the analysis

Once the Analysis structure is ready, running the analysis is straightforward:

let results = analysis.run()?;

It is also recommened to initialize some logging crate, if you want to see information about the progress of the analysis.

colog::init();
let results = analysis.run()?;

The Analysis::run method returns an AnalysisResults enum containing the results.

§Step 3: Inspecting the results

The simplest way to inspect results is by writing output files. These files must be specified during the construction of the Analysis structure:

  1. AnalysisBuilder::output_yaml for YAML file,
  2. AnalysisBuilder::output_csv for CSV file,
  3. AnalysisBuilder::output_xvg for XVG files,
  4. AnalysisBuilder::output_tab for files in “table” format.

To write the output files, call:

results.write()?;

Alternatively, results can be extracted programmatically. Match the AnalysisResults enum to access the results:

let aa_results = match results {
    AnalysisResults::AA(aa_results) => aa_results,
    _ => panic!("Expected atomistic results."),
};

Then, inspect the results as needed. Refer to:

  1. AAOrderResults for atomistic results.
  2. CGOrderResults for coarse-grained results.
  3. UAOrderResults for united-atom results.

Modules§

errors
This module contains error types that can be returned by the gorder crate.
input
This module contains structures and methods for specifying parameters of the analysis.
prelude
This module contains re-exported public structures of the gorder crate.
presentation
This module contains structures and methods for presenting the results of the analysis.

Macros§

colog_info
Log colored info message.
colog_warn
Log colored warning message.

Enums§

Leaflet
Specifies the leaflet a lipid is in.

Constants§

GORDER_VERSION
Version of the gorder crate.