Topic
  • 2 replies
  • Latest Post - ‏2012-11-22T08:55:09Z by SystemAdmin
SystemAdmin
SystemAdmin
7929 Posts

Pinned topic cplexx.h (CPXX-methods) vs cplex.h

‏2012-11-21T18:16:07Z |
Hi,

would anyone want to share experiences or recommendations regarding the use the the new-style C-API in cplexx.h? I gather that it's mandatory for very large models, that would need 64bit index values. There's added functionality, e.g. MICQP, that I might want to use. Other than that, the CPXX-methods seem to be drop-in replacements for the true-and-tested CPX-methods. But should I convert all my applications to CPXX just yet? The documentation is not very forthcoming on that issue and cautions at places against indiscriminate use.

So I would appreciate any insight on CPX-vs-CPXX in the C-API.

Thank you very much,
MCM
Updated on 2012-11-22T08:55:09Z at 2012-11-22T08:55:09Z by SystemAdmin
  • SystemAdmin
    SystemAdmin
    7929 Posts

    Re: cplexx.h (CPXX-methods) vs cplex.h

    ‏2012-11-22T07:39:04Z  
    For writing new applications I strongly recommend using the CPXX functions.

    For each CPX function there should be a CPXX function with the exact same semantics and almost the exact same signature. One exception are CPX functions that were deprecated when the CPXX functions were introduced. For those functions there is no CPXX function.
    Here are some details about the differences between CPX and CPXX: The CPLEX callable library uses three different integer data types (these types were introduced when the CPXX functions were introduced):
    • CPXDIM This integer type is used to specify model dimensions, such as number of rows and columns. This type is currently a 32bit signed integer on all platforms.
    • CPXNNZ This integer type is used to specify non-zero counts. On 64bit platforms this is a 64bit integer (allowing very big models on 64bit platforms), on 32bit platforms it is a 32bit integer.
    • CPXCNT This integer type is used to specify counters that can get very large, for example node or iteration counts.
    There are basically three major "components" of the CPLEX callable library to consider here: The core library, the CPX API and the CPXX API:
    
    +----------+         +---------+ | CPX API  |  <--->  |         | +----------+         |  core   | | library | +----------+         |         | | CPXX API |  <--->  |         | +----------+         +---------+
    

    The CPX and CPXX API are very thin layers that just do some parameter validation/transformation (see below) and then call into the core library. The core library always uses the data types described above (CPXDIM is 32bit, CPXNNZ is 32bit or 64bit depending on the platform, CPXCNT is 64bit). The CPXX API also uses these types of parameters. The legacy CPX API however, uses plain 'int' instead of CPXDIM, CPXNNZ and CPXCNT, that is 32bit for every integer data type. This implies that on 64bit platforms the CPX API layer may have to expand CPXNNZ and CPXCNT values from 32bit to 64bit when calling into the core library and unexpand them when returning results. This may of course fail (because a number larger than 2^31-1 cannot be represented as an int) and then return CPXERR_OVERFLOW.
    Consequently, the CPXX API has several advantages over the CPX API:
    • No data transformation occurs when calling into the callable library. Thus there is no additional overhead. The overhead that using the CPX API incurs here is usually negligible but it is there.
    • If you use CPXDIM, CPXNNZ and CPXCNT consistently in your code then you always use the same data types that the core library uses. This means your are talking in the "same language" as the core library, which is a good idea. This also means that your code will compile properly on 32bit and 64bit.
    • If you want to solve models with more than 2^31-1 non-zeros or anticipate node or iteration counts that are larger than 2^31-1 then there are some hacks to get this done with the CPX API but it is much easier to do this with the CPXX API.
    • The CPXX API is a little "cleaner" than the CPX API. For example, the legacy CPX API misses 'const' qualifiers in some places. The CPXX API fixed this kind of stuff.

    Porting existing applications is another kind of story and really depends on how much time you have available and what the expected lifetime of your application is. With the exception of functions that have been deprecated a long time ago the CPX and CPXX API offer the same set of functionality. So sticking with CPX will not make it impossible to use certain features. If an existing application does not use very large models or node/iteration counts then I think it is fine to stick with the CPX API. I think it is also safe to assume that the CPX API will not go away in the near future (if ever).
    Note that it is possible (though not recommended) to mix the CPX and CPXX API. So it is possible to port existing applications module by module.
    Concerning "true-and-tested": As I said above, the CPX and CPXX functions are just a very thin layer that performs parameter checking/transformation and then invoke the core library. Internally we give both functions the exact same testing, so I don't think that one of them is "more reliable" than the other. In fact, since CPX functions have to transform parameters in some cases, internal errors are more likely to happen in CPX functions than in CPXX functions :-) But from a software quality point of view I don't think it makes any difference whether you use CPX or CPXX.

    I hope this helps and answers your questions?
  • SystemAdmin
    SystemAdmin
    7929 Posts

    Re: cplexx.h (CPXX-methods) vs cplex.h

    ‏2012-11-22T08:55:09Z  
    For writing new applications I strongly recommend using the CPXX functions.

    For each CPX function there should be a CPXX function with the exact same semantics and almost the exact same signature. One exception are CPX functions that were deprecated when the CPXX functions were introduced. For those functions there is no CPXX function.
    Here are some details about the differences between CPX and CPXX: The CPLEX callable library uses three different integer data types (these types were introduced when the CPXX functions were introduced):
    • CPXDIM This integer type is used to specify model dimensions, such as number of rows and columns. This type is currently a 32bit signed integer on all platforms.
    • CPXNNZ This integer type is used to specify non-zero counts. On 64bit platforms this is a 64bit integer (allowing very big models on 64bit platforms), on 32bit platforms it is a 32bit integer.
    • CPXCNT This integer type is used to specify counters that can get very large, for example node or iteration counts.
    There are basically three major "components" of the CPLEX callable library to consider here: The core library, the CPX API and the CPXX API:
    <pre class="jive-pre"> +----------+ +---------+ | CPX API | <---> | | +----------+ | core | | library | +----------+ | | | CPXX API | <---> | | +----------+ +---------+ </pre>
    The CPX and CPXX API are very thin layers that just do some parameter validation/transformation (see below) and then call into the core library. The core library always uses the data types described above (CPXDIM is 32bit, CPXNNZ is 32bit or 64bit depending on the platform, CPXCNT is 64bit). The CPXX API also uses these types of parameters. The legacy CPX API however, uses plain 'int' instead of CPXDIM, CPXNNZ and CPXCNT, that is 32bit for every integer data type. This implies that on 64bit platforms the CPX API layer may have to expand CPXNNZ and CPXCNT values from 32bit to 64bit when calling into the core library and unexpand them when returning results. This may of course fail (because a number larger than 2^31-1 cannot be represented as an int) and then return CPXERR_OVERFLOW.
    Consequently, the CPXX API has several advantages over the CPX API:
    • No data transformation occurs when calling into the callable library. Thus there is no additional overhead. The overhead that using the CPX API incurs here is usually negligible but it is there.
    • If you use CPXDIM, CPXNNZ and CPXCNT consistently in your code then you always use the same data types that the core library uses. This means your are talking in the "same language" as the core library, which is a good idea. This also means that your code will compile properly on 32bit and 64bit.
    • If you want to solve models with more than 2^31-1 non-zeros or anticipate node or iteration counts that are larger than 2^31-1 then there are some hacks to get this done with the CPX API but it is much easier to do this with the CPXX API.
    • The CPXX API is a little "cleaner" than the CPX API. For example, the legacy CPX API misses 'const' qualifiers in some places. The CPXX API fixed this kind of stuff.

    Porting existing applications is another kind of story and really depends on how much time you have available and what the expected lifetime of your application is. With the exception of functions that have been deprecated a long time ago the CPX and CPXX API offer the same set of functionality. So sticking with CPX will not make it impossible to use certain features. If an existing application does not use very large models or node/iteration counts then I think it is fine to stick with the CPX API. I think it is also safe to assume that the CPX API will not go away in the near future (if ever).
    Note that it is possible (though not recommended) to mix the CPX and CPXX API. So it is possible to port existing applications module by module.
    Concerning "true-and-tested": As I said above, the CPX and CPXX functions are just a very thin layer that performs parameter checking/transformation and then invoke the core library. Internally we give both functions the exact same testing, so I don't think that one of them is "more reliable" than the other. In fact, since CPX functions have to transform parameters in some cases, internal errors are more likely to happen in CPX functions than in CPXX functions :-) But from a software quality point of view I don't think it makes any difference whether you use CPX or CPXX.

    I hope this helps and answers your questions?
    Hi Daniel,

    thanks a lot, that's comprehensive and very helpfull. I think we'll go with you recommendation and use CPXX from now on.

    Again,
    thank you for your prompt and kind answering,
    best regards,
    MCM