1 /** 2 * @file SBMLLevel1Version1Converter.h 3 * @brief Definition of SBMLLevel1Version1Converter. 4 * @author Frank Bergmann 5 * 6 * <!-------------------------------------------------------------------------- 7 * This file is part of libSBML. Please visit http://sbml.org for more 8 * information about SBML, and the latest version of libSBML. 9 * 10 * Copyright (C) 2020 jointly by the following organizations: 11 * 1. California Institute of Technology, Pasadena, CA, USA 12 * 2. University of Heidelberg, Heidelberg, Germany 13 * 3. University College London, London, UK 14 * 15 * Copyright (C) 2019 jointly by the following organizations: 16 * 1. California Institute of Technology, Pasadena, CA, USA 17 * 2. University of Heidelberg, Heidelberg, Germany 18 * 19 * Copyright (C) 2013-2018 jointly by the following organizations: 20 * 1. California Institute of Technology, Pasadena, CA, USA 21 * 2. EMBL European Bioinformatics Institute (EMBL-EBI), Hinxton, UK 22 * 3. University of Heidelberg, Heidelberg, Germany 23 * 24 * Copyright (C) 2009-2013 jointly by the following organizations: 25 * 1. California Institute of Technology, Pasadena, CA, USA 26 * 2. EMBL European Bioinformatics Institute (EMBL-EBI), Hinxton, UK 27 * 28 * Copyright (C) 2006-2008 by the California Institute of Technology, 29 * Pasadena, CA, USA 30 * 31 * Copyright (C) 2002-2005 jointly by the following organizations: 32 * 1. California Institute of Technology, Pasadena, CA, USA 33 * 2. Japan Science and Technology Agency, Japan 34 * 35 * This library is free software; you can redistribute it and/or modify it 36 * under the terms of the GNU Lesser General Public License as published by 37 * the Free Software Foundation. A copy of the license agreement is provided 38 * in the file named "LICENSE.txt" included with this software distribution 39 * and also available online as http://sbml.org/software/libsbml/license.html 40 * ------------------------------------------------------------------------ --> 41 * 42 * @class SBMLLevel1Version1Converter 43 * @sbmlbrief{core} Whole-document SBML Level/Version converter. 44 * 45 * @htmlinclude libsbml-facility-only-warning.html 46 * 47 * This SBML converter takes an SBML document having one SBML Level+Version 48 * combination, and attempts to convert it to an SBML document having a 49 * different Level+Version combination. This converter 50 * (SBMLLevel1Version1Converter) converts models to SBML Level 1 51 * Version 1, to the extent possible by the limited features of 52 * that Level/Version combination of SBML. 53 * 54 * @section SBMLLevel1Version1Converter-usage Configuration and use of SBMLLevel1Version1Converter 55 * 56 * SBMLLevel1Version1Converter is enabled by creating a ConversionProperties 57 * object with the option @c "convertToL1V1", and passing this 58 * properties object to SBMLDocument::convert(@if java 59 * ConversionProperties@endif). The target SBML Level and Version 60 * combination are determined by the value of the SBML namespace set on the 61 * ConversionProperties object (using 62 * ConversionProperties::setTargetNamespaces(SBMLNamespaces *targetNS)). 63 * 64 * In addition, this converter offers the following options: 65 * 66 * @li @c "changePow": Mathematical expressions for exponentiation of 67 * the form <code>pow(s1, 2)</code> will be converted to the expression 68 * <code>s1^2</code>. 69 * 70 * @li @c "inlineCompartmentSizes": Back in the days of SBML Level 1 71 * Version 1, many software tools assumed that the "kinetic laws" of 72 * SBML were written in terms of units of 73 * <em>concentration</em>/<em>time</em>. These tools would not expect (and 74 * thus not handle) rate expressions such as 75 * <code>CompartmentOfS1 * k * S1</code>. 76 * When the option @c "inlineCompartmentSizes" is enabled, libSBML will 77 * replace the references to compartments (such as @c "CompartmentOfS1" in 78 * this example) with their initial sizes. This is not strictly correct in 79 * all cases; in particular, if the compartment volume varies during 80 * simulation, this conversion will not reflect the expected behavior. 81 * However, many models do not have time-varying compartment sizes, so this 82 * option makes it easy to get modern SBML rate expressions into a form that 83 * old software tools may better understand. 84 * 85 * @copydetails doc_section_using_sbml_converters 86 */ 87 88 #ifndef SBMLLEVEL1VERSION1CONVERTER_H 89 #define SBMLLEVEL1VERSION1CONVERTER_H 90 91 #include <sbml/SBMLNamespaces.h> 92 #include <sbml/conversion/SBMLConverter.h> 93 #include <sbml/conversion/SBMLConverterRegister.h> 94 95 96 #ifdef __cplusplus 97 98 99 LIBSBML_CPP_NAMESPACE_BEGIN 100 101 102 class LIBSBML_EXTERN SBMLLevel1Version1Converter : public SBMLConverter 103 { 104 public: 105 106 /** @cond doxygenLibsbmlInternal */ 107 /** 108 * Register with the ConversionRegistry. 109 */ 110 static void init(); 111 112 /** @endcond */ 113 114 115 /** 116 * Creates a new SBMLLevel1Version1Converter object. 117 */ 118 SBMLLevel1Version1Converter (); 119 120 121 /** 122 * Copy constructor; creates a copy of an SBMLLevel1Version1Converter 123 * object. 124 * 125 * @param obj the SBMLLevel1Version1Converter object to copy. 126 */ 127 SBMLLevel1Version1Converter(const SBMLLevel1Version1Converter& obj); 128 129 130 /** 131 * Destroys this object. 132 */ 133 virtual ~SBMLLevel1Version1Converter (); 134 135 136 /** 137 * Assignment operator for SBMLLevel1Version1Converter. 138 * 139 * @param rhs the object whose values are used as the basis of the 140 * assignment. 141 */ 142 SBMLLevel1Version1Converter& operator=(const SBMLLevel1Version1Converter& rhs); 143 144 145 /** 146 * Creates and returns a deep copy of this SBMLLevel1Version1Converter 147 * object. 148 * 149 * @return a (deep) copy of this converter. 150 */ 151 virtual SBMLLevel1Version1Converter* clone() const; 152 153 154 /** 155 * Returns @c true if this converter object's properties match the given 156 * properties. 157 * 158 * A typical use of this method involves creating a ConversionProperties 159 * object, setting the options desired, and then calling this method on 160 * an SBMLLevel1Version1Converter object to find out if the object's 161 * property values match the given ones. This method is also used by 162 * SBMLConverterRegistry::getConverterFor(@if java ConversionProperties@endif) 163 * to search across all registered converters for one matching particular 164 * properties. 165 * 166 * @param props the properties to match. 167 * 168 * @return @c true if this converter's properties match, @c false 169 * otherwise. 170 */ 171 virtual bool matchesProperties(const ConversionProperties &props) const; 172 173 174 /** 175 * Perform the conversion. 176 * 177 * This method causes the converter to do the actual conversion work, 178 * that is, to convert the SBMLDocument object set by 179 * SBMLConverter::setDocument(@if java SBMLDocument@endif) and 180 * with the configuration options set by 181 * SBMLConverter::setProperties(@if java ConversionProperties@endif). 182 * 183 * @copydetails doc_returns_success_code 184 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 185 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 186 * @li @sbmlconstant{LIBSBML_CONV_INVALID_TARGET_NAMESPACE, OperationReturnValues_t} 187 * @li @sbmlconstant{LIBSBML_CONV_PKG_CONVERSION_NOT_AVAILABLE, OperationReturnValues_t} 188 * @li @sbmlconstant{LIBSBML_CONV_INVALID_SRC_DOCUMENT, OperationReturnValues_t} 189 */ 190 virtual int convert(); 191 192 193 /** 194 * Returns the default properties of this converter. 195 * 196 * A given converter exposes one or more properties that can be adjusted 197 * in order to influence the behavior of the converter. This method 198 * returns the @em default property settings for this converter. It is 199 * meant to be called in order to discover all the settings for the 200 * converter object. 201 * 202 * @return the ConversionProperties object describing the default properties 203 * for this converter. 204 */ 205 virtual ConversionProperties getDefaultProperties() const; 206 207 208 /* Convenience functions for this converter */ 209 210 211 private: 212 /** @cond doxygenLibsbmlInternal */ 213 /* 214 * Predicate returning true if compartment sizes in kinetic laws should 215 * be inlined with their values. 216 */ 217 bool inlineCompartmentSizes(); 218 219 /* 220 * Predicate returning true if calls to pow should be replaced with the hat notation. 221 */ 222 bool shouldChangePow(); 223 224 /** @endcond */ 225 }; 226 227 228 LIBSBML_CPP_NAMESPACE_END 229 230 #endif /* __cplusplus */ 231 232 233 #ifndef SWIG 234 235 LIBSBML_CPP_NAMESPACE_BEGIN 236 BEGIN_C_DECLS 237 238 239 END_C_DECLS 240 LIBSBML_CPP_NAMESPACE_END 241 242 #endif /* !SWIG */ 243 #endif /* SBMLLEVEL1VERSION1CONVERTER_H */ 244 245