RingDecomposerLib.h

Go to the documentation of this file.

/*
 * This file is part of the RingDecomposerLib, licensed
 * under BSD New license (see LICENSE in the root directory).
 * Copyright (c) 2016
 * University of Hamburg, ZBH - Center for Bioinformatics
 * Niek Andresen, Florian Flachsenberg, Matthias Rarey
 * 
 * Please cite:
 * 
 * Kolodzik, A.; Urbaczek, S.; Rarey, M.
 * Unique Ring Families: A Chemically Meaningful Description
 * of Molecular Ring Topologies.
 * J. Chem. Inf. Model., 2012, 52 (8), pp 2013-2021
 * 
 * Flachsenberg, F.; Andresen, N.; Rarey, M.
 * RingDecomposerLib: An Open-Source Implementation of
 * Unique Ring Families and Other Cycle Bases.
 * J. Chem. Inf. Model., 2017, 57 (2), pp 122-126
 */

#ifndef RING_DECOMPOSER_LIB_H
#define RING_DECOMPOSER_LIB_H

#if (defined( _WIN32 ) && defined( _MSC_VER ) )
    /* Win32 & MS VC ++ */
    #define RDL_API __declspec(dllexport)
#elif __GNUC__ >= 4 || defined(__clang__)
    #define RDL_API __attribute__((visibility("default")))
#else
    #define RDL_API
#endif

#ifdef __cplusplus
extern "C" {
#endif

typedef struct RDL_data RDL_data;

typedef struct RDL_graph RDL_graph;

typedef unsigned RDL_node;

typedef RDL_node RDL_edge[2];

typedef enum RDL_ERROR_LEVEL {
  RDL_DEBUG,
  RDL_WARNING,
  RDL_ERROR,
  RDL_INITIALIZE_OUTPUT
} RDL_ERROR_LEVEL;

/*
 * @brief output function for writing errors/warnings
 *
 * @param level `RDL_ERROR_LEVEL` specifying the level of the message
 * @param m message associated with the event
 */
typedef void (*RDL_outputFunction) (RDL_ERROR_LEVEL level, const char* m, ...);

RDL_API extern RDL_outputFunction RDL_outputFunc;

RDL_API
void RDL_setOutputFunction(RDL_outputFunction func);

RDL_API
void RDL_writeToStderr(RDL_ERROR_LEVEL level, const char* fmt, ...);

RDL_API
void RDL_writeNothing(RDL_ERROR_LEVEL level, const char* fmt, ...);

RDL_API extern const unsigned RDL_INVALID_RESULT;
RDL_API extern const unsigned RDL_DUPLICATE_EDGE;
RDL_API extern const unsigned RDL_NO_RINGSYSTEM;
RDL_API extern const double RDL_INVALID_RC_COUNT;

RDL_API
RDL_graph *RDL_initNewGraph(unsigned nof_nodes);

RDL_API
void RDL_deleteGraph(RDL_graph *graph);

RDL_API
unsigned RDL_addUEdge(RDL_graph *graph, RDL_node node1, RDL_node node2);

RDL_API
RDL_data *RDL_calculate(RDL_graph *input_graph);

RDL_API
void RDL_deleteData(RDL_data *data);

RDL_API
unsigned RDL_getNofURF(const RDL_data *data);

RDL_API
unsigned RDL_getNofRCF(const RDL_data *data);

RDL_API
unsigned RDL_getWeightForURF(const RDL_data *data, unsigned index);

RDL_API
unsigned RDL_getWeightForRCF(const RDL_data *data, unsigned index);

RDL_API
unsigned RDL_getNodesForURF(const RDL_data *data, unsigned index,
                            RDL_node **RDL_node_array_ptr);

RDL_API
unsigned RDL_getEdgesForURF(const RDL_data *data, unsigned index,
                            RDL_edge **RDL_edge_array_ptr);

RDL_API
unsigned RDL_getNodesForRCF(const RDL_data *data, unsigned index,
                            RDL_node **RDL_node_array_ptr);

RDL_API
unsigned RDL_getEdgesForRCF(const RDL_data *data, unsigned index,
                            RDL_edge **RDL_edge_array_ptr);

RDL_API
unsigned RDL_getNofURFContainingNode(const RDL_data *data, RDL_node node);

RDL_API
unsigned RDL_getNofURFContainingEdge(const RDL_data *data, RDL_node node1,
                                     RDL_node node2);

RDL_API
unsigned RDL_getNofRCFContainingNode(const RDL_data *data, RDL_node node);

RDL_API
unsigned RDL_getNofRCFContainingEdge(const RDL_data *data, RDL_node node1,
                                     RDL_node node2);

RDL_API
unsigned RDL_getURFsContainingNode(const RDL_data *data, RDL_node node,
                                   unsigned **RDL_ids_ptr);

RDL_API
unsigned RDL_getURFsContainingEdge(const RDL_data *data, RDL_node node1,
                                   RDL_node node2, unsigned **RDL_ids_ptr);

RDL_API
unsigned RDL_getRCFsContainingNode(const RDL_data *data, RDL_node node,
                                   unsigned **RDL_ids_ptr);

RDL_API
unsigned RDL_getRCFsContainingEdge(const RDL_data *data, RDL_node node1,
                                   RDL_node node2, unsigned **RDL_ids_ptr);

typedef struct RDL_cycle {
    RDL_edge *edges;
    unsigned weight;
    unsigned urf;
    unsigned rcf;
} RDL_cycle;

RDL_API
void RDL_deleteCycle(RDL_cycle *cycle);

typedef struct RDL_cycleIterator RDL_cycleIterator;

RDL_API
RDL_cycleIterator* RDL_cycleIteratorNext(RDL_cycleIterator* it);

RDL_API
RDL_cycle* RDL_cycleIteratorGetCycle(RDL_cycleIterator* it);

RDL_API
int RDL_cycleIteratorAtEnd(RDL_cycleIterator* it);
RDL_API
void RDL_deleteCycleIterator(RDL_cycleIterator* it);

RDL_API
unsigned RDL_getRCyclesForURF(const RDL_data *data, unsigned index,
                              RDL_cycle ***RDL_cycle_array_ptr);

RDL_API
RDL_cycleIterator* RDL_getRCyclesForURFIterator(const RDL_data *data, unsigned index);

RDL_API
unsigned RDL_getRCyclesForRCF(const RDL_data *data, unsigned index,
                              RDL_cycle ***RDL_cycle_array_ptr);

RDL_API
RDL_cycleIterator* RDL_getRCyclesForRCFIterator(const RDL_data *data, unsigned index);

RDL_API
unsigned RDL_getRCycles(const RDL_data *data, RDL_cycle ***RDL_cycle_array_ptr);

RDL_API
RDL_cycleIterator* RDL_getRCyclesIterator(const RDL_data *data);

RDL_API
double RDL_getNofRCForURF(const RDL_data *data, unsigned index);

RDL_API
double RDL_getNofRCForRCF(const RDL_data *data, unsigned index);

RDL_API
double RDL_getNofRC(const RDL_data *data);

RDL_API
unsigned RDL_getSSSR(const RDL_data *data, RDL_cycle ***RDL_cycle_array_ptr);

RDL_API
unsigned RDL_getRCPrototypes(const RDL_data *data,
                             RDL_cycle ***RDL_cycle_array_ptr);

RDL_API
void RDL_deleteCycles(RDL_cycle **cycles, unsigned number);

RDL_API
unsigned RDL_translateCycArray(const RDL_data *data,
                               RDL_cycle **old_array,
                               unsigned number,
                               char ***RDL_cycle_array_ptr);

RDL_API
void RDL_deleteEdgeIdxArray(char **cycles, unsigned number);

RDL_API
unsigned RDL_getEdgeArray(const RDL_data *data, RDL_edge **RDL_edge_array_ptr);

RDL_API
unsigned RDL_getNofEdges(const RDL_data *data);

RDL_API
unsigned RDL_getEdgeId(const RDL_data *data, unsigned from, unsigned to);

RDL_API
unsigned RDL_getNofRingsystems(const RDL_data* data);

RDL_API
unsigned RDL_getNofNodesForRingsystem(const RDL_data *data, unsigned idx);

RDL_API
unsigned RDL_getNofEdgesForRingsystem(const RDL_data *data, unsigned idx);

RDL_API
unsigned RDL_getEdgesForRingsystem(
    const RDL_data *data, unsigned idx, RDL_edge** edges);

RDL_API
unsigned RDL_getNodesForRingsystem(
    const RDL_data *data, unsigned idx, RDL_node** nodes);

RDL_API
unsigned RDL_getRingsystemForEdge(
    const RDL_data* data, unsigned from, unsigned to);

#ifdef __cplusplus
} /* extern "C" */
#endif

#endif