001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 3.0.7 004 * 005 * Do not make changes to this file unless you know what you are doing--modify 006 * the SWIG interface file instead. 007 * ----------------------------------------------------------------------------- */ 008 009package org.sbml.libsbml; 010 011/** 012 * <span class="pkg-marker pkg-color-comp"><a href="group__comp.html">comp</a></span> 013 'Flattens' a model, removing composition. 014 <p> 015 * <p style='color: #777; font-style: italic'> 016This class of objects is defined by libSBML only and has no direct 017equivalent in terms of SBML components. It is a class used in 018the implementation of extra functionality provided by libSBML. 019</p> 020 021 <p> 022 * This converter translates a hierarchical model defined with the SBML 023 * Level 3 Hierarchical Model Composition package to a so-called 024 * 'flattened' version of the same model. A 'flattened' model is one that 025 * results from interpreting the hierarchical structure and creating an 026 * equivalent model that does not use any Hierarchical Model Composition 027 * package constructs; all of the mathematics of the model remain as 028 * intended, but the hierarchical structure is removed. 029 * {@link CompFlatteningConverter} achieves this by performing the following actions 030 * on a model: 031 * <ol> 032 * <li> Each submodel is instantiated; that is, a copy of every {@link Model} object 033 * referenced by every {@link Submodel} object is created. This is a recursive 034 * process: if the instantiated {@link Model} itself has {@link Submodel} children, they are 035 * also instantiated. 036 <p> 037 * <li> The identifier of every component object in every {@link Model} that is 038 * instantiated is modified by prepending a prefix to it, to make the 039 * identifier unique in the overall flattened SBML model. The prefix 040 * consists of the {@link Submodel} object identifier, plus a small integer if 041 * necessary to ensure uniqueness, plus two underscore characters 042 * (<code>'__'</code>). Typically, this results in a final identifier of the 043 * form <span 044 * class='code-placeholder'>SubmodelIdentifier__</span><span 045 * class='code-placeholder2-nospace'>ObjectIdentifier</span>, where <span 046 * class='code-placeholder2'>ObjectIdentifier</span> is the object's original 047 * identifier and <span 048 * class='code-placeholder'>SubmodelIdentifier__</span> is 049 * the prefix. The same process is applied to <em>metaid</em> (meta-identifier) 050 * values of every component object as well. 051 <p> 052 * <li> All deleted elements are removed from the model and all instantiated 053 * submodels. 054 <p> 055 * <li> All replaced elements are removed from the model and all instantiated 056 * submodels. 057 <p> 058 * <li> All references to replaced elements are changed to point to the 059 * replacement element instead. 060 <p> 061 * <li> All remaining elements are placed in a single {@link Model} object; this {@link Model} 062 * object is made the new child of the {@link SBMLDocument} container. The original 063 * {@link Model}, {@link ModelDefinition}, and {@link ExternalModelDefinition} objects are all 064 * deleted. 065 <p> 066 * </ol> 067 <p> 068 * Note an implication of this process is that if conversion is successful, 069 * all old pointers to the {@link SBMLDocument} object's {@link Model} object as well as all 070 * of its children, will be rendered obsolete, and will no longer work. 071 <p> 072 * <h2>Summary of options for {@link CompFlatteningConverter}</h2> 073 <p> 074 * <p> 075 * {@link CompFlatteningConverter} is enabled by creating a {@link ConversionProperties} 076 * object with the option <em>'flatten</em> comp', and passing this 077 * {@link ConversionProperties} object to {@link SBMLDocument#convert(ConversionProperties)}. The {@link CompFlatteningConverter} converter 078 * accepts numerous options influencing its behavior. The following list 079 * briefly summarizes the options: 080 * <ul> 081 * <li> <em>'flatten comp'</em>: Possible values are <code>'true'</code> or <code>'false'.</code> 082 * Setting the option to <code>true</code> (the default) means enable the flattening 083 * converter. 084 <p> 085 * <li> <em>'abortIfUnflattenable'</em>: Possible values are <code>'all'</code>, @c 086 * 'requiredOnly' (the default), or <code>'none'.</code> Controls what happens upon 087 * encountering an SBML Level 3 package with no flattener 088 * implementation. 089 <p> 090 * <li> <em>'stripUnflattenablePackages'</em>: Possible values are <code>'true'</code> or @c 091 * 'false' (the default). Controls whether the constructs of Level 3 092 * packages with no flattener implementation are stripped from the output. 093 <p> 094 * <li> <em>'stripPackages'</em>: The value must be a string representing a 095 * comma-separated list of SBML Level 3 packages to be stripped before 096 * conversion. (Default value: empty string, meaning, no packages.) 097 <p> 098 * <li> <em>'basePath'</em>: The value must be a string representing the path where 099 * the converter should search for any {@link ExternalModelDefinition} objects. 100 * (Default value: '.', meaning, the current directory.) 101 <p> 102 * <li> <em>'leavePorts'</em>: Possible values are <code>'true'</code> or <code>'false'</code> (the 103 * default). Controls what happens to {@link Port} constructs in the output. 104 <p> 105 * <li> <em>'listModelDefinitions'</em>: Possible values are <code>'true'</code> or @c 106 * 'false' (the default). Controls what happens to {@link ModelDefinition} and 107 * {@link ExternalModelDefinition} objects in the final output. 108 <p> 109 * <li> <em>'performValidation'</em>: Possible values are <code>'true'</code> (the default) 110 * or <code>'false'.</code> Controls whether whether libSBML validates the model 111 * before attempting to flatten it. 112 * </ul> 113 <p> 114 * <h2>Detailed explanation of available options</h2> 115 <p> 116 * The following sections examine in detail the options understood by 117 * {@link CompFlatteningConverter} and their effects on the flattening process. 118 <p> 119 * <h3>Options for handling Level 3 packages</h3> 120 <p> 121 * If other SBML Level 3 packages are used in the {@link SBMLDocument}, the same 122 * rules apply to each package's constructs if an implementation of the 123 * flattener exists for that Level 3 package. If no implementation 124 * exists, the behavior of this {@link CompFlatteningConverter} depends on the values 125 * of the options <em>'abortIfUnflattenable'</em> and <em></em> 126 * 'stripUnflattenablePackages'. Specifically: 127 * <ul> 128 <p> 129 * <li> The option <em>'abortIfUnflattenable'</em> controls whether the flattening 130 * process is abandoned. The following are the possible values for this 131 * option and their meanings: 132 * <ul style='list-style-type: circle'> 133 <p> 134 * <li> If the <em>'abortIfUnflattenable'</em> option is set to <code>'all'</code>, then if any 135 * construct is found for a package that has no flattening algorithm 136 * available, the converter will abort, return failure, and avoid 137 * changing the original {@link SBMLDocument} object. 138 <p> 139 * <li> If <em>'abortIfUnflattenable'</em> is set to <code>'requiredOnly'</code> (the default), 140 * then if any SBML Level 3 package construct is found for a package 141 * that is labeled <code>'required=true'</code> and for which no flattening 142 * algorithm is available, the converter will abort, return failure, and 143 * avoid changing the original {@link SBMLDocument} object. SBML Level 3 144 * package constructs from packages set <code>'required=false'</code> for which no 145 * flattening algorithm is implemented will be ignored and the constructs 146 * will be kept or removed depending on the value of the <em></em> 147 * 'stripUnflattenablePackages' option described below. 148 <p> 149 * <li> If <em>'abortIfUnflattenable'</em> is set to <code>'none'</code>, constructs from all 150 * unflattenable SBML Level 3 packages will be ignored, and their 151 * constructs will be kept or removed depending on the value of the <em></em> 152 * 'stripUnflattenablePackages' option. 153 <p> 154 * </ul> 155 <p> 156 * <li> The option <em>'stripUnflattenablePackages'</em> controls whether SBML 157 * Level 3 package constructs are removed from the final flattened 158 * model. The following are the possible values for this option and their 159 * meanings: 160 * <ul style='list-style-type: circle'> 161 <p> 162 * <li> If the option <em>'stripUnflattenablePackages'</em> is set to <code>'true'</code>, and 163 * the option <em>'abortIfUnflattenable'</em> has the value <code>'requiredOnly'</code> 164 * or <code>'none'</code>, then {@link CompFlatteningConverter} will remove all constructs 165 * belonging to packages that lack a flattening converter. The XML 166 * namespace declaration for unflattenable SBML Level 3 packages 167 * will also be removed. 168 <p> 169 * <li> If the option <em>'stripUnflattenablePackages'</em> is set to <code>'false'</code> 170 * (the default), {@link CompFlatteningConverter} will leave any package 171 * constructs that cannot be flattened due to the lack of a flattening 172 * implementation. These Level 3 package constructs will remain in 173 * the final model. Note that any package constructs from an 174 * instantiated {@link Submodel} object that was <em>not</em> a child of a retained 175 * component will be lost (because the SBML component where it was 176 * located was removed from the final, flattened model). 177 <p> 178 * </ul> 179 <p> 180 * <li> The option <em>'stripPackages'</em> controls whether SBML Level 3 181 * package information is stripped from a model before conversion. 182 * Regardless of the above options, if an SBML package is listed in this 183 * comma-separated list, all constructs from that package will be removed 184 * from the model before the flattening algorithm is applied. This happens 185 * whether a flattening algorithm exists for that package or not, and applies 186 * to all referenced models, both local and external. In addition, the 187 * removal takes place before any validation is performed by libSBML. 188 <p> 189 * </ul> 190 <p> 191 * <h3>Additional general conversion options for {@link CompFlatteningConverter}</h3> 192 <p> 193 * The following are other, general options offered by CompFlatteningConverter: 194 <p> 195 * <ul> 196 * <li> <em>'basePath'</em>: if there are {@link ExternalModelDefinition} objects that are to 197 * be instantiated in a flattened {@link Submodel}, the <em>'basePath'</em> option may 198 * be set to a location where those external models may be found. The 199 * default is the working directory (<code>'.'</code>). 200 <p> 201 * <li> <em>'leavePorts'</em>: if this option is set to <code>'false'</code> (the default), the 202 * flattened model will have no {@link Port} objects in it. Conversely, if <em></em> 203 * 'leavePorts' is set to <code>'true'</code>, any {@link Port} objects not referenced by any 204 * Replacement or {@link Deletion} will be left in the resulting flattened {@link Model}. 205 <p> 206 * <li> <em>'listModelDefinitions'</em>: If this option is set to <code>'false'</code> (the 207 * default), no {@link ModelDefinition} or {@link ExternalModelDefinition} objects will 208 * be present in the flattened {@link SBMLDocument}. If <em>'listModelDefinitions'</em> 209 * is set to <code>'true'</code>, they will remain, although they will no longer be 210 * referenced by any {@link Submodel} in the flattened {@link Model} child of the 211 * {@link SBMLDocument}. 212 <p> 213 * <li> <em>'performValidation'</em>: if this option is set to <code>'true'</code> (the 214 * default), the {@link SBMLDocument} will first be validated before flattening 215 * is attempted. If there are any validation errors, those errors will 216 * be logged with the {@link SBMLDocument}, which will remain otherwise 217 * unchanged, and the conversion process will return a failure code. 218 * Similarly, if the flattened {@link Model} is not valid, those validation 219 * errors will be added to the {@link SBMLDocument}, which will remain otherwise 220 * unchanged, and the conversion attempt will return failure. 221 * Conversely, if the option <em>'performValidation'</em> is set to @c 222 * 'false', the {@link SBMLDocument} will be flattened regardless of any 223 * validation errors. The conversion may yet fail if insurmountable 224 * errors are encountered in the course of trying to flatten the model 225 * (for instance, if an element is replaced by something that does not 226 * exist), but no separate validation steps are performed. 227 * 228 * </ul> <p> 229 * Note that if both the option <em>'leavePorts'</em> and <em>'listModelDefinitions'</em> 230 * are set to <code>'false'</code> (which they are by default), the Hierarchical Model 231 * Composition namespace will be removed from the resulting {@link SBMLDocument}. 232 <p> 233 * <h2>Complete example of invoking {@link CompFlatteningConverter}</h2> 234 <p> 235 * In this section, we present a complete example of a program that can take 236 * an SBML model containing Level 3 Hierarchical Model Composition 237 * constructs and flatten it to a plain SBML Level 3 model. 238 * A version of this program is available in the libSBML distribution's 239 * <code>examples/java/comp</code> directory as the 240 * program named 241 * <code>'flattenModel.java'</code>. The example 242 * XML models shown below are the same models as given in sections 243 * 4.1–4.2 in the specification document for SBML Level 3 244 * Hierarchical Model Composition. 245 <p> 246 * <h3>Example program</h3> 247 <p> 248 * For brevity, we do not give the general scaffolding that a real program 249 * would have (such as inclusion of header files, command-line argument 250 * checks, additional error checks throughout the code, and so on), and focus 251 * instead on the parts relevant to an application using the libSBML 'comp' 252 * extension. 253 <p> 254 * First, our program checks that this copy of libSBML has the 'comp' 255 * extension available. The process for doing that simply involves a call to 256 * the extension registry in libSBML: 257 258<p> 259<pre class='fragment'> 260if (! {@link SBMLExtensionRegistry}.isPackageEnabled('comp')) 261{ 262 System.out.println('This copy of libSBML does not contain the 'comp' extension'); 263 System.out.println('Unable to proceed with flattening the model.'); 264 System.exit(1); 265} 266</pre> 267<p> 268 * Next, we read the SBML input file. For this example, we simply 269 * assume that the path to the file is given as the first argument 270 * to the program; a real program would perform more sophisticated 271 * command-line argument processing and error checking. 272 273<p> 274<pre class='fragment'> 275{@link SBMLReader} reader = new {@link SBMLReader}(); 276{@link SBMLDocument} doc = reader.readSBML(args[0]); 277if (doc.getErrorLog().getNumFailsWithSeverity(libsbml.LIBSBML_SEV_ERROR) > 0) 278{ 279 doc.printErrors(); 280 System.exit(1); 281} 282</pre> 283<p> 284 * Continuing, we set up options for the call to the converter. 285 * The use of {@link ConversionProperties} and the general scheme behind 286 * conversion options is explained further below; for the purposes 287 * of this example, it is enough to know that the following are the 288 * basic lines of code needed to obtain a copy of a libSBML 289 * converter object that will invoke CompFlatteningConverter: 290 291<p> 292<pre class='fragment'> 293{@link ConversionProperties} props = new {@link ConversionProperties}(); 294props.addOption('flatten comp', true); 295</pre> 296<p> 297 * Now comes the actual invocation of {@link CompFlatteningConverter}. 298 * As always, it is critical to check for possible errors by 299 * checking the status code returned by the call; we do this 300 * in the code below too. 301 302<p> 303<pre class='fragment'> 304if (doc.convert(props) != libsbml.LIBSBML_OPERATION_SUCCESS) 305{ 306 doc.printErrors(); 307 System.exit(1); 308} 309</pre> 310<p> 311 * If successful, we simply write out the resulting flattened model 312 * to an output file which, for the purposes of this simple example, 313 * we assume is indicated by the second argument handed to the program 314 * on the command line by the user. 315 316<p> 317<pre class='fragment'> 318{@link SBMLWriter} writer = new {@link SBMLWriter}(); 319writer.writeSBML(doc, args[1]); 320</pre> 321<p> 322 * <h3>Example use of the program</h3> 323 <p> 324 * What is the result of the above on an actual model? Suppose we 325 * have the following SBML Level 3 model stored in a file named 326 * <code>'enzyme_model.xml':</code> 327 <p> 328 * <div class="highlight"><pre class="fragment"><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span> 329<span class="nt"><sbml</span> <span class="na">xmlns=</span><span class="s">"http://www.sbml.org/sbml/level3/version1/core"</span> <span class="na">level=</span><span class="s">"3"</span> <span class="na">version=</span><span class="s">"1"</span> 330 <span class="na">xmlns:comp=</span><span class="s">"http://www.sbml.org/sbml/level3/version1/comp/version1"</span> <span class="na">comp:required=</span><span class="s">"true"</span><span class="nt">></span> 331 332 <span class="nt"><model</span> <span class="na">id=</span><span class="s">"aggregate"</span><span class="nt">></span> 333 <span class="nt"><comp:listOfSubmodels></span> 334 <span class="nt"><comp:submodel</span> <span class="na">comp:id=</span><span class="s">"submod1"</span> <span class="na">comp:modelRef=</span><span class="s">"enzyme"</span><span class="nt">/></span> 335 <span class="nt"><comp:submodel</span> <span class="na">comp:id=</span><span class="s">"submod2"</span> <span class="na">comp:modelRef=</span><span class="s">"enzyme"</span><span class="nt">/></span> 336 <span class="nt"></comp:listOfSubmodels></span> 337 <span class="nt"></model></span> 338 <span class="nt"><comp:listOfModelDefinitions></span> 339 <span class="nt"><comp:modelDefinition</span> <span class="na">id=</span><span class="s">"enzyme"</span> <span class="na">name=</span><span class="s">"enzyme"</span><span class="nt">></span> 340 <span class="nt"><listOfCompartments></span> 341 <span class="nt"><compartment</span> <span class="na">id=</span><span class="s">"compartment"</span> <span class="na">spatialDimensions=</span><span class="s">"3"</span> <span class="na">size=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">/></span> 342 <span class="nt"></listOfCompartments></span> 343 <span class="nt"><listOfSpecies></span> 344 <span class="nt"><species</span> <span class="na">id=</span><span class="s">"S"</span> <span class="na">compartment=</span><span class="s">"compartment"</span> <span class="na">hasOnlySubstanceUnits=</span><span class="s">"false"</span> 345 <span class="na">boundaryCondition=</span><span class="s">"false"</span> <span class="na">constant=</span><span class="s">"false"</span><span class="nt">/></span> 346 <span class="nt"><species</span> <span class="na">id=</span><span class="s">"E"</span> <span class="na">compartment=</span><span class="s">"compartment"</span> <span class="na">hasOnlySubstanceUnits=</span><span class="s">"false"</span> 347 <span class="na">boundaryCondition=</span><span class="s">"false"</span> <span class="na">constant=</span><span class="s">"false"</span><span class="nt">/></span> 348 <span class="nt"><species</span> <span class="na">id=</span><span class="s">"D"</span> <span class="na">compartment=</span><span class="s">"compartment"</span> <span class="na">hasOnlySubstanceUnits=</span><span class="s">"false"</span> 349 <span class="na">boundaryCondition=</span><span class="s">"false"</span> <span class="na">constant=</span><span class="s">"false"</span><span class="nt">/></span> 350 <span class="nt"><species</span> <span class="na">id=</span><span class="s">"ES"</span> <span class="na">compartment=</span><span class="s">"compartment"</span> <span class="na">hasOnlySubstanceUnits=</span><span class="s">"false"</span> 351 <span class="na">boundaryCondition=</span><span class="s">"false"</span> <span class="na">constant=</span><span class="s">"false"</span><span class="nt">/></span> 352 <span class="nt"></listOfSpecies></span> 353 <span class="nt"><listOfReactions></span> 354 <span class="nt"><reaction</span> <span class="na">id=</span><span class="s">"J0"</span> <span class="na">reversible=</span><span class="s">"true"</span> <span class="na">fast=</span><span class="s">"false"</span><span class="nt">></span> 355 <span class="nt"><listOfReactants></span> 356 <span class="nt"><speciesReference</span> <span class="na">species=</span><span class="s">"S"</span> <span class="na">stoichiometry=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">/></span> 357 <span class="nt"><speciesReference</span> <span class="na">species=</span><span class="s">"E"</span> <span class="na">stoichiometry=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">/></span> 358 <span class="nt"></listOfReactants></span> 359 <span class="nt"><listOfProducts></span> 360 <span class="nt"><speciesReference</span> <span class="na">species=</span><span class="s">"ES"</span> <span class="na">stoichiometry=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">/></span> 361 <span class="nt"></listOfProducts></span> 362 <span class="nt"></reaction></span> 363 <span class="nt"><reaction</span> <span class="na">id=</span><span class="s">"J1"</span> <span class="na">reversible=</span><span class="s">"true"</span> <span class="na">fast=</span><span class="s">"false"</span><span class="nt">></span> 364 <span class="nt"><listOfReactants></span> 365 <span class="nt"><speciesReference</span> <span class="na">species=</span><span class="s">"ES"</span> <span class="na">stoichiometry=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">/></span> 366 <span class="nt"></listOfReactants></span> 367 <span class="nt"><listOfProducts></span> 368 <span class="nt"><speciesReference</span> <span class="na">species=</span><span class="s">"E"</span> <span class="na">stoichiometry=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">/></span> 369 <span class="nt"><speciesReference</span> <span class="na">species=</span><span class="s">"D"</span> <span class="na">stoichiometry=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">/></span> 370 <span class="nt"></listOfProducts></span> 371 <span class="nt"></reaction></span> 372 <span class="nt"></listOfReactions></span> 373 <span class="nt"></comp:modelDefinition></span> 374 <span class="nt"></comp:listOfModelDefinitions></span> 375<span class="nt"></sbml></span> 376</pre></div> 377 378 <p> 379 * Also suppose we have the following SBML Level 3 model stored 380 * in a file called <code>'main.xml'</code> in the same directory as the 381 * file above. The model below imports the model <code>'enzyme'</code> from 382 * the model file above twice; this is used to create two submodels 383 * whose identifiers are <code>'A'</code> and <code>'B'.</code> 384 <p> 385 * <div class="highlight"><pre class="fragment"><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span> 386<span class="nt"><sbml</span> <span class="na">xmlns=</span><span class="s">"http://www.sbml.org/sbml/level3/version1/core"</span> <span class="na">level=</span><span class="s">"3"</span> <span class="na">version=</span><span class="s">"1"</span> 387 <span class="na">xmlns:comp=</span><span class="s">"http://www.sbml.org/sbml/level3/version1/comp/version1"</span> <span class="na">comp:required=</span><span class="s">"true"</span><span class="nt">></span> 388 <span class="nt"><model></span> 389 <span class="nt"><listOfCompartments></span> 390 <span class="nt"><compartment</span> <span class="na">id=</span><span class="s">"compartment"</span> <span class="na">spatialDimensions=</span><span class="s">"3"</span> <span class="na">size=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">></span> 391 <span class="nt"><comp:listOfReplacedElements></span> 392 <span class="nt"><comp:replacedElement</span> <span class="na">comp:idRef=</span><span class="s">"compartment"</span> <span class="na">comp:submodelRef=</span><span class="s">"A"</span><span class="nt">/></span> 393 <span class="nt"><comp:replacedElement</span> <span class="na">comp:idRef=</span><span class="s">"compartment"</span> <span class="na">comp:submodelRef=</span><span class="s">"B"</span><span class="nt">/></span> 394 <span class="nt"></comp:listOfReplacedElements></span> 395 <span class="nt"></compartment></span> 396 <span class="nt"></listOfCompartments></span> 397 <span class="nt"><listOfSpecies></span> 398 <span class="nt"><species</span> <span class="na">id=</span><span class="s">"S"</span> <span class="na">compartment=</span><span class="s">"compartment"</span> <span class="na">hasOnlySubstanceUnits=</span><span class="s">"false"</span> 399 <span class="na">boundaryCondition=</span><span class="s">"false"</span> <span class="na">constant=</span><span class="s">"false"</span><span class="nt">></span> 400 <span class="nt"><comp:listOfReplacedElements></span> 401 <span class="nt"><comp:replacedElement</span> <span class="na">comp:idRef=</span><span class="s">"S"</span> <span class="na">comp:submodelRef=</span><span class="s">"A"</span><span class="nt">/></span> 402 <span class="nt"><comp:replacedElement</span> <span class="na">comp:idRef=</span><span class="s">"S"</span> <span class="na">comp:submodelRef=</span><span class="s">"B"</span><span class="nt">/></span> 403 <span class="nt"></comp:listOfReplacedElements></span> 404 <span class="nt"></species></span> 405 <span class="nt"></listOfSpecies></span> 406 <span class="nt"><comp:listOfSubmodels></span> 407 <span class="nt"><comp:submodel</span> <span class="na">comp:id=</span><span class="s">"A"</span> <span class="na">comp:modelRef=</span><span class="s">"ExtMod1"</span><span class="nt">/></span> 408 <span class="nt"><comp:submodel</span> <span class="na">comp:id=</span><span class="s">"B"</span> <span class="na">comp:modelRef=</span><span class="s">"ExtMod1"</span><span class="nt">/></span> 409 <span class="nt"></comp:listOfSubmodels></span> 410 <span class="nt"></model></span> 411 <span class="nt"><comp:listOfExternalModelDefinitions></span> 412 <span class="nt"><comp:externalModelDefinition</span> <span class="na">comp:id=</span><span class="s">"ExtMod1"</span> <span class="na">comp:source=</span><span class="s">"enzyme_model.xml"</span> 413 <span class="na">comp:modelRef=</span><span class="s">"enzyme"</span><span class="nt">/></span> 414 <span class="nt"></comp:listOfExternalModelDefinitions></span> 415<span class="nt"></sbml></span> 416</pre></div> 417 418 <p> 419 * Finally, invoking the example program developed the previous section on the 420 * file <code>'main.xml'</code>, we would obtain the following XML output as result a 421 * result 422 <p> 423 * <div class="highlight"><pre class="fragment"><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span> 424<span class="nt"><sbml</span> <span class="na">xmlns=</span><span class="s">"http://www.sbml.org/sbml/level3/version1/core"</span> <span class="na">level=</span><span class="s">"3"</span> <span class="na">version=</span><span class="s">"1"</span><span class="nt">></span> 425 <span class="nt"><model></span> 426 <span class="nt"><listOfCompartments></span> 427 <span class="nt"><compartment</span> <span class="na">id=</span><span class="s">"compartment"</span> <span class="na">spatialDimensions=</span><span class="s">"3"</span> <span class="na">size=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">/></span> 428 <span class="nt"></listOfCompartments></span> 429 <span class="nt"><listOfSpecies></span> 430 <span class="nt"><species</span> <span class="na">id=</span><span class="s">"S"</span> <span class="na">compartment=</span><span class="s">"compartment"</span> <span class="na">hasOnlySubstanceUnits=</span><span class="s">"false"</span> 431 <span class="na">boundaryCondition=</span><span class="s">"false"</span> <span class="na">constant=</span><span class="s">"false"</span><span class="nt">/></span> 432 <span class="nt"><species</span> <span class="na">id=</span><span class="s">"A__E"</span> <span class="na">compartment=</span><span class="s">"compartment"</span> <span class="na">hasOnlySubstanceUnits=</span><span class="s">"false"</span> 433 <span class="na">boundaryCondition=</span><span class="s">"false"</span> <span class="na">constant=</span><span class="s">"false"</span><span class="nt">/></span> 434 <span class="nt"><species</span> <span class="na">id=</span><span class="s">"A__D"</span> <span class="na">compartment=</span><span class="s">"compartment"</span> <span class="na">hasOnlySubstanceUnits=</span><span class="s">"false"</span> 435 <span class="na">boundaryCondition=</span><span class="s">"false"</span> <span class="na">constant=</span><span class="s">"false"</span><span class="nt">/></span> 436 <span class="nt"><species</span> <span class="na">id=</span><span class="s">"A__ES"</span> <span class="na">compartment=</span><span class="s">"compartment"</span> <span class="na">hasOnlySubstanceUnits=</span><span class="s">"false"</span> 437 <span class="na">boundaryCondition=</span><span class="s">"false"</span> <span class="na">constant=</span><span class="s">"false"</span><span class="nt">/></span> 438 <span class="nt"><species</span> <span class="na">id=</span><span class="s">"B__E"</span> <span class="na">compartment=</span><span class="s">"compartment"</span> <span class="na">hasOnlySubstanceUnits=</span><span class="s">"false"</span> 439 <span class="na">boundaryCondition=</span><span class="s">"false"</span> <span class="na">constant=</span><span class="s">"false"</span><span class="nt">/></span> 440 <span class="nt"><species</span> <span class="na">id=</span><span class="s">"B__D"</span> <span class="na">compartment=</span><span class="s">"compartment"</span> <span class="na">hasOnlySubstanceUnits=</span><span class="s">"false"</span> 441 <span class="na">boundaryCondition=</span><span class="s">"false"</span> <span class="na">constant=</span><span class="s">"false"</span><span class="nt">/></span> 442 <span class="nt"><species</span> <span class="na">id=</span><span class="s">"B__ES"</span> <span class="na">compartment=</span><span class="s">"compartment"</span> <span class="na">hasOnlySubstanceUnits=</span><span class="s">"false"</span> 443 <span class="na">boundaryCondition=</span><span class="s">"false"</span> <span class="na">constant=</span><span class="s">"false"</span><span class="nt">/></span> 444 <span class="nt"></listOfSpecies></span> 445 <span class="nt"><listOfReactions></span> 446 <span class="nt"><reaction</span> <span class="na">id=</span><span class="s">"A__J0"</span> <span class="na">reversible=</span><span class="s">"true"</span> <span class="na">fast=</span><span class="s">"false"</span><span class="nt">></span> 447 <span class="nt"><listOfReactants></span> 448 <span class="nt"><speciesReference</span> <span class="na">species=</span><span class="s">"S"</span> <span class="na">stoichiometry=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">/></span> 449 <span class="nt"><speciesReference</span> <span class="na">species=</span><span class="s">"A__E"</span> <span class="na">stoichiometry=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">/></span> 450 <span class="nt"></listOfReactants></span> 451 <span class="nt"><listOfProducts></span> 452 <span class="nt"><speciesReference</span> <span class="na">species=</span><span class="s">"A__ES"</span> <span class="na">stoichiometry=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">/></span> 453 <span class="nt"></listOfProducts></span> 454 <span class="nt"></reaction></span> 455 <span class="nt"><reaction</span> <span class="na">id=</span><span class="s">"A__J1"</span> <span class="na">reversible=</span><span class="s">"true"</span> <span class="na">fast=</span><span class="s">"false"</span><span class="nt">></span> 456 <span class="nt"><listOfReactants></span> 457 <span class="nt"><speciesReference</span> <span class="na">species=</span><span class="s">"A__ES"</span> <span class="na">stoichiometry=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">/></span> 458 <span class="nt"></listOfReactants></span> 459 <span class="nt"><listOfProducts></span> 460 <span class="nt"><speciesReference</span> <span class="na">species=</span><span class="s">"A__E"</span> <span class="na">stoichiometry=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">/></span> 461 <span class="nt"><speciesReference</span> <span class="na">species=</span><span class="s">"A__D"</span> <span class="na">stoichiometry=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">/></span> 462 <span class="nt"></listOfProducts></span> 463 <span class="nt"></reaction></span> 464 <span class="nt"><reaction</span> <span class="na">id=</span><span class="s">"B__J0"</span> <span class="na">reversible=</span><span class="s">"true"</span> <span class="na">fast=</span><span class="s">"false"</span><span class="nt">></span> 465 <span class="nt"><listOfReactants></span> 466 <span class="nt"><speciesReference</span> <span class="na">species=</span><span class="s">"S"</span> <span class="na">stoichiometry=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">/></span> 467 <span class="nt"><speciesReference</span> <span class="na">species=</span><span class="s">"B__E"</span> <span class="na">stoichiometry=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">/></span> 468 <span class="nt"></listOfReactants></span> 469 <span class="nt"><listOfProducts></span> 470 <span class="nt"><speciesReference</span> <span class="na">species=</span><span class="s">"B__ES"</span> <span class="na">stoichiometry=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">/></span> 471 <span class="nt"></listOfProducts></span> 472 <span class="nt"></reaction></span> 473 <span class="nt"><reaction</span> <span class="na">id=</span><span class="s">"B__J1"</span> <span class="na">reversible=</span><span class="s">"true"</span> <span class="na">fast=</span><span class="s">"false"</span><span class="nt">></span> 474 <span class="nt"><listOfReactants></span> 475 <span class="nt"><speciesReference</span> <span class="na">species=</span><span class="s">"B__ES"</span> <span class="na">stoichiometry=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">/></span> 476 <span class="nt"></listOfReactants></span> 477 <span class="nt"><listOfProducts></span> 478 <span class="nt"><speciesReference</span> <span class="na">species=</span><span class="s">"B__E"</span> <span class="na">stoichiometry=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">/></span> 479 <span class="nt"><speciesReference</span> <span class="na">species=</span><span class="s">"B__D"</span> <span class="na">stoichiometry=</span><span class="s">"1"</span> <span class="na">constant=</span><span class="s">"true"</span><span class="nt">/></span> 480 <span class="nt"></listOfProducts></span> 481 <span class="nt"></reaction></span> 482 <span class="nt"></listOfReactions></span> 483 <span class="nt"></model></span> 484<span class="nt"></sbml></span> 485</pre></div> 486 487 <p> 488 * The final model is a concrete realization of the effective 489 * model defined by <code>'main.xml'</code>, with a single compartment and two 490 * reactions; the species <code>'S'</code> can either bind with enzyme <code>'E'</code> (from 491 * submodel <code>'A'</code>) to form <code>'D'</code> (from submodel <code>'A'</code>), or with enzyme 492 * <code>'E'</code> (from submodel <code>'B'</code>) to form <code>'D'</code> (from submodel <code>'B'</code>). 493 * In the flattened model above, note how the identifiers of components 494 * inside the {@link ModelDefinition} objects <code>'A'</code> and <code>'B'</code> of our file @c 495 * 'enzyme_model.xml' have been rewritten as (for example) <code>'A__E'</code> @c 496 * 'B__E', etc. 497 <p> 498 * <p> 499 * <h2>General information about the use of SBML converters</h2> 500 <p> 501 * The use of all the converters follows a similar approach. First, one 502 * creates a {@link ConversionProperties} object and calls 503 * {@link ConversionProperties#addOption(ConversionOption)} 504 * on this object with one arguments: a text string that identifies the desired 505 * converter. (The text string is specific to each converter; consult the 506 * documentation for a given converter to find out how it should be enabled.) 507 <p> 508 * Next, for some converters, the caller can optionally set some 509 * converter-specific properties using additional calls to 510 * {@link ConversionProperties#addOption(ConversionOption)}. 511 * Many converters provide the ability to 512 * configure their behavior to some extent; this is realized through the use 513 * of properties that offer different options. The default property values 514 * for each converter can be interrogated using the method 515 * {@link SBMLConverter#getDefaultProperties()} on the converter class in question . 516 <p> 517 * Finally, the caller should invoke the method 518 * {@link SBMLDocument#convert(ConversionProperties)} 519 * with the {@link ConversionProperties} object as an argument. 520 <p> 521 * <h3>Example of invoking an SBML converter</h3> 522 <p> 523 * The following code fragment illustrates an example using 524 * {@link SBMLReactionConverter}, which is invoked using the option string 525 * <code>'replaceReactions':</code> 526 <p> 527<pre class='fragment'> 528{@link ConversionProperties} props = new {@link ConversionProperties}(); 529if (props != null) { 530 props.addOption('replaceReactions'); 531} else { 532 // Deal with error. 533} 534</pre> 535<p> 536 * In the case of {@link SBMLReactionConverter}, there are no options to affect 537 * its behavior, so the next step is simply to invoke the converter on 538 * an {@link SBMLDocument} object. Continuing the example code: 539 <p> 540<pre class='fragment'> 541 // Assume that the variable 'document' has been set to an {@link SBMLDocument} object. 542 status = document.convert(config); 543 if (status != libsbml.LIBSBML_OPERATION_SUCCESS) 544 { 545 // Handle error somehow. 546 System.out.println('Error: conversion failed due to the following:'); 547 document.printErrors(); 548 } 549</pre> 550<p> 551 * Here is an example of using a converter that offers an option. The 552 * following code invokes {@link SBMLStripPackageConverter} to remove the 553 * SBML Level 3 <em>Layout</em> package from a model. It sets the name 554 * of the package to be removed by adding a value for the option named 555 * <code>'package'</code> defined by that converter: 556 <p> 557<pre class='fragment'> 558{@link ConversionProperties} config = new {@link ConversionProperties}(); 559if (config != None) { 560 config.addOption('stripPackage'); 561 config.addOption('package', 'layout'); 562 status = document.convert(config); 563 if (status != LIBSBML_OPERATION_SUCCESS) { 564 // Handle error somehow. 565 System.out.println('Error: unable to strip the {@link Layout} package'); 566 document.printErrors(); 567 } 568} else { 569 // Handle error somehow. 570 System.out.println('Error: unable to create {@link ConversionProperties} object'); 571} 572</pre> 573<p> 574 * <h3>Available SBML converters in libSBML</h3> 575 <p> 576 * LibSBML provides a number of built-in converters; by convention, their 577 * names end in <em>Converter</em>. The following are the built-in converters 578 * provided by libSBML 5.12.0 579: 580 <p> 581 * <p> 582 * <ul> 583 * <li> {@link CobraToFbcConverter} 584 * <li> {@link CompFlatteningConverter} 585 * <li> {@link FbcToCobraConverter} 586 * <li> {@link FbcV1ToV2Converter} 587 * <li> {@link FbcV2ToV1Converter} 588 * <li> {@link SBMLFunctionDefinitionConverter} 589 * <li> {@link SBMLIdConverter} 590 * <li> {@link SBMLInferUnitsConverter} 591 * <li> {@link SBMLInitialAssignmentConverter} 592 * <li> {@link SBMLLevel1Version1Converter} 593 * <li> {@link SBMLLevelVersionConverter} 594 * <li> {@link SBMLLocalParameterConverter} 595 * <li> {@link SBMLReactionConverter} 596 * <li> {@link SBMLRuleConverter} 597 * <li> {@link SBMLStripPackageConverter} 598 * <li> {@link SBMLUnitsConverter} 599 * 600 * </ul> 601 */ 602 603public class CompFlatteningConverter extends SBMLConverter { 604 private long swigCPtr; 605 606 protected CompFlatteningConverter(long cPtr, boolean cMemoryOwn) 607 { 608 super(libsbmlJNI.CompFlatteningConverter_SWIGUpcast(cPtr), cMemoryOwn); 609 swigCPtr = cPtr; 610 } 611 612 protected static long getCPtr(CompFlatteningConverter obj) 613 { 614 return (obj == null) ? 0 : obj.swigCPtr; 615 } 616 617 protected static long getCPtrAndDisown (CompFlatteningConverter obj) 618 { 619 long ptr = 0; 620 621 if (obj != null) 622 { 623 ptr = obj.swigCPtr; 624 obj.swigCMemOwn = false; 625 } 626 627 return ptr; 628 } 629 630 protected void finalize() { 631 delete(); 632 } 633 634 public synchronized void delete() { 635 if (swigCPtr != 0) { 636 if (swigCMemOwn) { 637 swigCMemOwn = false; 638 libsbmlJNI.delete_CompFlatteningConverter(swigCPtr); 639 } 640 swigCPtr = 0; 641 } 642 super.delete(); 643 } 644 645 646/** * @internal */ public 647 static void init() { 648 libsbmlJNI.CompFlatteningConverter_init(); 649 } 650 651 652/** 653 * Creates a new {@link CompFlatteningConverter} object. 654 */ public 655 CompFlatteningConverter() { 656 this(libsbmlJNI.new_CompFlatteningConverter__SWIG_0(), true); 657 } 658 659 660/** 661 * Copy constructor. 662 <p> 663 * This creates a copy of a {@link CompFlatteningConverter} object. 664 <p> 665 * @param orig the {@link CompFlatteningConverter} instance to copy. 666 */ public 667 CompFlatteningConverter(CompFlatteningConverter orig) { 668 this(libsbmlJNI.new_CompFlatteningConverter__SWIG_1(CompFlatteningConverter.getCPtr(orig), orig), true); 669 } 670 671 672/** 673 * Creates and returns a deep copy of this {@link CompFlatteningConverter}. 674 <p> 675 * @return a (deep) copy of this {@link CompFlatteningConverter}. 676 */ public 677 SBMLConverter cloneObject() { 678 long cPtr = libsbmlJNI.CompFlatteningConverter_cloneObject(swigCPtr, this); 679 return (cPtr == 0) ? null : new CompFlatteningConverter(cPtr, true); 680 } 681 682 683/** 684 * Returns <code>true</code> if this converter matches the given properties. 685 <p> 686 * Given a {@link ConversionProperties} object <code>props</code>, this method checks that @p 687 * props possesses an option value to enable the {@link CompFlatteningConverter}. If 688 * it does, this method returns <code>true.</code> 689 <p> 690 * @param props the properties to match. 691 <p> 692 * @return <code>true</code> if the properties <code>props</code> would match the necessary 693 * properties for {@link CompFlatteningConverter} type of converter, <code>false</code> 694 * otherwise. 695 */ public 696 boolean matchesProperties(ConversionProperties props) { 697 return libsbmlJNI.CompFlatteningConverter_matchesProperties(swigCPtr, this, ConversionProperties.getCPtr(props), props); 698 } 699 700 701/** 702 * Performs the conversion. 703 <p> 704 * This method causes {@link CompFlatteningConverter} to do the actual conversion 705 * work, that is, to convert the {@link SBMLDocument} object set by 706 * {@link SBMLConverter#setDocument(SBMLDocument)} and with 707 * the configuration options set by {@link SBMLConverter#setProperties(ConversionProperties)}. 708 <p> 709 * <p> 710 * @return integer value indicating success/failure of the 711 * function. The possible values 712 * returned by this function are: 713 * <ul> 714 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 715 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 716 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT} 717 * </ul> 718 */ public 719 int convert() { 720 return libsbmlJNI.CompFlatteningConverter_convert(swigCPtr, this); 721 } 722 723 724/** * @internal */ public 725 int performConversion() { 726 return libsbmlJNI.CompFlatteningConverter_performConversion(swigCPtr, this); 727 } 728 729 730/** 731 * Returns the default properties of this converter. 732 <p> 733 * A given converter exposes one or more properties that can be adjusted in 734 * order to influence the behavior of the converter. This method returns 735 * the <em>default</em> property settings for {@link CompFlatteningConverter}. It is 736 * meant to be called in order to be able to programmatically discover all 737 * the settings for the converter object. 738 <p> 739 * <p> 740 * {@link CompFlatteningConverter} is enabled by creating a {@link ConversionProperties} 741 * object with the option <em>'flatten</em> comp', and passing this 742 * {@link ConversionProperties} object to {@link SBMLDocument#convert(ConversionProperties)}. The {@link CompFlatteningConverter} converter 743 * accepts numerous options influencing its behavior. The following list 744 * briefly summarizes the options: 745 * <ul> 746 * <li> <em>'flatten comp'</em>: Possible values are <code>'true'</code> or <code>'false'.</code> 747 * Setting the option to <code>true</code> (the default) means enable the flattening 748 * converter. 749 <p> 750 * <li> <em>'abortIfUnflattenable'</em>: Possible values are <code>'all'</code>, @c 751 * 'requiredOnly' (the default), or <code>'none'.</code> Controls what happens upon 752 * encountering an SBML Level 3 package with no flattener 753 * implementation. 754 <p> 755 * <li> <em>'stripUnflattenablePackages'</em>: Possible values are <code>'true'</code> or @c 756 * 'false' (the default). Controls whether the constructs of Level 3 757 * packages with no flattener implementation are stripped from the output. 758 <p> 759 * <li> <em>'stripPackages'</em>: The value must be a string representing a 760 * comma-separated list of SBML Level 3 packages to be stripped before 761 * conversion. (Default value: empty string, meaning, no packages.) 762 <p> 763 * <li> <em>'basePath'</em>: The value must be a string representing the path where 764 * the converter should search for any {@link ExternalModelDefinition} objects. 765 * (Default value: '.', meaning, the current directory.) 766 <p> 767 * <li> <em>'leavePorts'</em>: Possible values are <code>'true'</code> or <code>'false'</code> (the 768 * default). Controls what happens to {@link Port} constructs in the output. 769 <p> 770 * <li> <em>'listModelDefinitions'</em>: Possible values are <code>'true'</code> or @c 771 * 'false' (the default). Controls what happens to {@link ModelDefinition} and 772 * {@link ExternalModelDefinition} objects in the final output. 773 <p> 774 * <li> <em>'performValidation'</em>: Possible values are <code>'true'</code> (the default) 775 * or <code>'false'.</code> Controls whether whether libSBML validates the model 776 * before attempting to flatten it. 777 * </ul> 778 <p> 779 * @return the {@link ConversionProperties} object describing the default properties 780 * for this converter. 781 <p> 782 * @note Previously, {@link CompFlatteningConverter} also offered an <em></em> 783 * 'ignorePackages' option, whose name proved to be confusing. This option 784 * has been deprecated and replaced by the <em>'stripUnflattenablePackages'</em> 785 * option. 786 */ public 787 ConversionProperties getDefaultProperties() { 788 return new ConversionProperties(libsbmlJNI.CompFlatteningConverter_getDefaultProperties(swigCPtr, this), true); 789 } 790 791}