- Sphere Engine overview
- Programming languages
- Modules comparison
- Infrastructure management
- API changelog
Browse through the Sphere Engine frequently asked questions section and if you will not be able to find the answers you are looking for, feel free to contact us.
Sphere Engine modules
What is the difference between the Sphere Engine modules?
The Sphere Engine Compilers module is a service that enables remote execution of computer programs and retrieving the results of their execution.
The Sphere Engine Problems module enables the automated verification of submissions to programming problems. It includes a Problems Manager feature for efficient programming problem creation and testing.
The Sphere Engine Containers module allows executing complex, multi-component programming projects. It supports a vast scope of modern technologies and will bring the source code execution and skill-assessment features to your system effectively, securely, and with large-scaling, future-proofing, and customizability.
Which module should I choose?
If your project primarily involves running computer programs, such as executing sample source code within a programming course, we recommend selecting the Compilers module.
For scenarios where you need to assess programs, like solutions to programming challenges within a recruitment platform, the Problems module is the ideal choice.
If your project entails running or evaluating complex, multi-stack software projects, such as a web framework with a database, the Workspace module is the most suitable option.
Feel free to mix and match these modules within your application as needed.
More information about the differences between the modules can be found in this module comparison table.
What is the Sphere Engine Compilers Widget?
What is the Sphere Engine Problems Widget?
What is the Sphere Engine Containers Workspace?
Are there any sample programming problems in the Sphere Engine Problems module?
Yes - the
Problems section of the Problems Manager available after logging in to the Sphere Engine client
Editor) allows you to filter the problems list by pressing the
button. The displayed list contains sample programming problems that can be used inside your system right away
or for testing purposes.
Are there any sample programming projects in the Sphere Engine Containers module?
Yes, on the
Projects page, which can be accessed after logging in to the Sphere Engine Client Panel
Projects), you'll find a wide array of samples that cover a diverse range of
technologies. These samples serve as an excellent starting point for developing your own customized projects.
Is my system compatible with the Sphere Engine API?
How does integration with the Sphere Engine service work?
The following integration methods are available for the Sphere Engine modules:
- RESTful API (available for all modules) - is a highly configurable integration method, recommended for building dedicated applications from the ground up,
- Widget integration (available for Compilers and Problems modules) - offers a quick and easy integration method, ideal for expanding existing projects,
- Workspace integration (available for Containers module) - is a convenient and powerful method for integrating an interactive, full-fledged development environment,
- Webhooks (available for all modules) - complement all the aforementioned methods, providing an optimal way to extract information from Sphere Engine.
Which API version should I use?
How do I use Sphere Engine - offline or as an on-premise solution?
How do I integrate with Sphere Engine without much interference in the existing system?
How can I share access to the API with the development team without revealing the login credentials for the Sphere Engine account?
Access to the Sphere Engine API is implemented using access tokens.
After logging in to the Sphere Engine client panel, the tokens management section (
API Tokens) allows
you to generate any number of access tokens that can be passed to your development team.
Alternatively, go to
Users and create a sub-account with a
How do I remove the Sphere Engine logo displayed in the widget or the workspace?
How do I use Sphere Engine API methods directly from the front-end of my web application?
While it may be tempting to integrate with an API in such a way, there are at least two reasons for not doing so:
- CORS and the Same-origin policy limitations
- security violation by revealing the API access token that should remain secret
CORS mechanism enables the communication between two mutually trusted servers hosted on different domains. The
server which handles cross-origin requests (in our scenario it is the Sphere Engine API) should send a proper
HTTP header (i.e.,
Access-Control-Allow-Origin) allowing the request to be handled. Sphere Engine API denies
this kind of requests for security reasons.
The mechanism of the API access tokens is the only method of API call authorization. Revealing the access token that is connected to your account will enable everyone to use Sphere Engine API on your credit. Access tokens should remain secret and if they leak out, they should be changed immediately. More precisely: compromised access tokens should be disabled in the proper panel where you can also generate fresh access tokens.
We recommend designing your web applications in such a way that they make Sphere Engine API calls in the back-end. If the front-end layer of your application requires asynchronous communication, please consider creating a custom layer designated to handling the Sphere Engine API (i.e. asynchronous calls should target your back-end application and then your back-end makes the Sphere Engine API call; then pass the response back in the opposite direction).
Cross-Origin Request Blocked error when trying to use Sphere Engine API, what happened?
Most likely you are trying to make an API call directly from the front-end of your web application. This is not possible due to the Same-origin policy. Please refer to the Can I use Sphere Engine API methods directly from the front-end of my web application? question to learn more.
Sphere Engine features
What programming languages does Sphere Engine Compilers and Sphere Engine Problems modules support?
What technologies does Sphere Engine Containers module support?
The high level of customizability offered by the Containers module enables you to utilize a vast array of existing technologies. This includes:
- classical programming languages (like Java, Python),
- multi-stack applications (e.g., Node.js+React+MySQL),
- data science and machine learning (e.g, Pandas, TensorFlow, Jupyter Notebook),
- mobile technologies (e.g., Flutter, React Native),
- databases (e.g., MySQL, MongoDB),
- tools (e.g., git, ansible).
Can my Sphere Engine program operate on files and directories?
For the Compilers and Problems modules, you can perform disk operations within an isolated workspace dedicated to a single submission. Find out more about performing disk operations from the disk operations article.
With the Containers module, there's no need for specific configurations. Your programs can freely perform disk operations just as they would in a local or server environment.
Which data streams and for what purpose are used when processing the submission inside Sphere Engine?
Can I connect my Sphere Engine program to the Internet?
How long does it take to run a program in the Sphere Engine system?
Multiple factors affect the program's execution time, for example:
- the programming language,
- the complexity of the program,
- the size of input data,
- time limits,
- the number of test cases (only Sphere Engine Problems).
A typical submission is executed within a few seconds. Long execution times are typically associated with the complexity of the program, not with the Sphere Engine infrastructure.
What happens to my Sphere Engine submission when there is temporarily no computing power at the moment of sending it?
There is nothing to worry about. Each correctly sent submission is stored in a database. If there are no free resources to execute the submission immediately, it waits in the submission queue. You do not need to implement a queue of submissions in your system - Sphere Engine handles that for you.
How do I execute a program consisting of multiple files?
For the Compilers and the Problems modules using integration through RESTful API it is possible to run multi-file projects.
In the Containers module, this is the typical use case. When working in the Workspace, you have convenient
access to the directory tree. When making API submissions, you always send a
tar.gz archive that can include
multiple files or even an entire directory structure. You can find more information about the structure of such
tar.gz archive here.
Is it possible to provide support for a new programming language or an additional library in Sphere Engine?
Is it possible to expand the Sphere Engine system with additional features?
Is Sphere Engine a platform where I can organize a programmer's recruitment, contests or hackathons?
The Sphere Engine Problems module equips you with all the necessary tools to create your online programming competition or recruitment platform. However, it is not designed to directly support or host such an event.
Similarly, the Sphere Engine Containers module provides you with essential tools for constructing a platform to manage such events. Yet, as middleware, it is not designed to independently host or manage these scenarios.
For running online contests and hackathons, you can also use Spoj (Sphere Engine Online Judge) platform.
Sphere Engine limitations
What is the default limit of submissions (programs) sent to Sphere Engine?
What is the default program execution time limit?
In the case of the Compilers module, the default limitation for the program execution time depends on the configuration and can range from 1 to 15 seconds.
In the Problems module, the default program execution time limit results from the test case parameters and can also range from 1 to 60 seconds.
In the Containers module, the default time limit can be set arbitrally in the project configuration for each execution stage. You can read on about the timeout parameter here.
Note: The limit value for execution time applies only to the actual time it takes to run the program. Each time the submission is executed, many routine operations are performed (e.g. program compilation and preparation of the runtime environment), which affect the total time required to run the submission. These are not taken into account in the program's execution time limit.
What is the default limit of the number of test cases in a single programming problem in the Sphere Engine Problems module?
The default maximum number of test cases is 16. If the test case construction is correct, this number should be sufficient. Please refer to the "Good test case design article" from the content manager's handbook which explains how to create correct and valuable test cases for problems.
It is also possible to increase the maximum number of test cases - please contact us if you feel that this is what you need.
What is the default size limit of the source code submitted to Sphere Engine?
The maximum size of uploaded source files as part of a single submission is:
- 64kB for the Sphere Engine Compilers module,
- 32kB for the Sphere Engine Problems module,
- 256kB for the Sphere Engine Containers module.
What is the default size limit of input data in Sphere Engine Compilers?
The maximum size of the input data file in the Sphere Engine Compilers service is 64kB.
What is the default size limit of the data streams generated when executing the submission?
Data generated when executing submissions can have any size (OS limitations may apply). However, Sphere Engine saves only a shortened data stream of the maximum allowed stream size.
For the Sphere Engine Compilers module, the maximum stream size is 1MB for both streams.
For the Sphere Engine Problems module, the maximum stream size is:
- 5kB for the "stdout" stream (for each test case),
- 1kB for the "stderr" stream (for each test case),
- 64kB for the "psinfo" stream.
For the Sphere Engine Containers module, the maximum stream sizes are:
- 100kB for each stage output stream,
- 100kB for each stage error stream,
- 1MB for the tests report stream,
- 1MB for the auxiliary data stream (please note that this stream always consists of a
tar.gzarchive, and if truncated, it is highly likely to become corrupted),
- 100kB for the debug logs stream,
- 100kB for the workspace initialization process output stream,
- 100kB for the workspace initialization process error stream,
Note: The verification procedure conducted during the evaluation of the user's submission uses complete stream data.
What is the default size limit for test case files in the Sphere Engine Problems (e.g., input data and reference output data)?
What is the default operational memory (RAM) limit for running the program in Sphere Engine?
For the Compilers and the Problems modules, the program has access to 1.5GB of RAM. If this limit is exceeded, the execution of the program is interrupted.
In the Containers module, the amount of RAM memory available depends on the number of "slots" assigned to the
project. Each slot grants access to 2GB of RAM for execution. For different slot values,
the RAM allocation is proportional, for example, 512MB for
0.5 slots, and
In case of integration through the API, the Sphere Engine Compilers module offers the ability to set the memory limit.
What is the number of CPUs for running the program in Sphere Engine?
For the Compilers and Problems modules, each program is allocated access to a single physical CPU core, providing exclusive usage during execution.
In the Containers module, the number of CPU cores accessible is contingent upon the number of 'slots' assigned
to the project. Each slot provides access to
1 CPU for execution. For varying slot
values, the CPU allocation scales proportionally; for instance,
0.5 CPU for
4 CPUs for
Is there the default limit on the number of programming problems that I can create as part of the Sphere Engine Problems module?
What happens after I send my submission?
After submitting the source code, it is placed in a queue and awaits execution by the checker machine, which is responsible for running the submitted programs.
For the Compilers module, the checker machine processes the submission by following these steps:
- compilation of the program (applies only to compiled languages like C++),
- execution of the program,
- provision of input data to the executing program (if applicable),
- generation and storage of output data, such as
stderrstreams, and execution results, including status (e.g., "successful" or "not successful"), exit code, and execution time.
In the Problems module, the checker machine processes the submission as follows:
- compilation of the program (applies only to compiled languages like C++),
- execution of the program, performed independently for each test case,
- verification of the results of each test case execution by the "test case judge",
- summarization of the results from all test cases by the "master judge",
- generation and storage of output data, such as
stderrstreams, and execution results, including status, score, and execution time.
For the Containers module, the checker machine processes the submission by executing a scenario defined in the project configuration. This involves:
- initializing the environment using the
- executing a sequence of stages in the following order:
initstage for project initialization,
buildstage for building the project,
runstage for executing the project,
testfor testing or assessment procedures,
postfor cleanup, summaries, output gathering, and other post-execution operations,
- generating and storing output data, such as output from stages, test results, and execution results, including status, score, and execution time.
Note: The status of the submission is being updated in real-time during execution.
Why doesn't a submission sent to the Sphere Engine Problems receive the maximum number of points?
There are many reasons why a seemingly correct submission may not get the maximum points.
First, it is worth verifying the following aspects of the submission:
- the correctness of handling edge cases,
- program's performance for large input data,
- the correctness of the program for atypical input data,
- the correctness of the program for input data realizing maximum ranges for variables occurring in input data.
Why the submission sent to Sphere Engine does not execute correctly?
There are many reasons why a program sent to Sphere Engine does not run correctly.
After executing the submission, information that can help identify the right reason is available in:
- the status of the submission (e.g. "compilation error"/"build error", "run-time error", "wrong answer"),
- the content of data streams (e.g. compilation errors and run-time errors).
Why do I receive a compilation error indicating a lack of function/module/class/procedure?
Some code written in the languages supported by Sphere Engine requires specific naming or structure for the Compilers and the Problems modules. For example, a Java application should contain a public class named Main (or a private class named as you desire).
Familiarizing yourself with sample source code files for the selected programming language (available in the public GitHub repository with common configuration for programming languages) may be useful in identifying the reason for the error.
Why does the processing of submission inside Sphere Engine finish with the "Compilation Error" (CE) status?
Data regarding compilation errors can be found in the stream containing the compilation errors.
Why does the processing of submission inside Sphere Engine Containers finish with the "Build Error" (BE) status?
Data regarding build errors can be found in the output stream and error stream of the
Why does the processing of submission inside Sphere Engine finish with the "Time Limit Exceeded" (TLE) status?
If the program has been running for too long (i.e. longer than the execution time limit), its execution was interrupted by the system. In this situation, the submission (or a single test case in case of the Problems module) receives the TLE status.
Examples of reasons why a program might be executing for a long time:
- the occurrence of infinite loops,
- the high computational complexity of the algorithm used in the program,
- a large amount of data processed by the program.
Why does the processing of a submission inside Sphere Engine finish with the "Wrong Answer" (WA) status?
The most common reason is an error in solving the problem. First of all, check the correctness of handling edge cases and tricky, rare or specific data. Next, it is recommended to read the description of the problem again, to make sure that the answer is correct.
Why does the processing of submission inside Sphere Engine finish with the "Runtime Error" (RE) status?
How does the Problems module verify the correctness of a submission?
The most important components of a programming problem are its test cases. Test cases consist of input data and reference output data. The submitted program is executed with the input data of the test case and then the output data it generates is compared to the reference output data.
How does the Containers module verify the correctness of a submission?
There are various approaches to verify the correctness of submissions in the Containers module. The most straightforward, similar to the one used in the Problems module, involves comparing the produced output data with the expected output data of the application.
An alternative approach is based on unit testing, where the submission comprises the application's source code, and predefined unit tests are executed to check if the application passes them.
In another scenario, the reverse approach to unit testing is employed. Here, the task involves writing unit tests, and the verification process checks whether these tests correctly identify injected issues in the predefined application.
One of the advantages of the Sphere Engine Containers module is its high customizability. The list of
verification methods is not limited to the ones mentioned above. Any type of verification can be implemented as
part of the
test stage in the project's scenario.
How is the score of a submission to a programming problem determined in the Problems module?
For each test case, the "test case judge" sets a partial score. Then, after running the program for all test cases, the "master judge" summarizes the partial results and determines the final result.
Both the "test case judge" and the "master judge" operate in a way designed by the author.
Note: Both "test case judges" and "master judges", are built-in components of Sphere Engine. Usually, the use of these built-in judges is sufficient, i.e. the implementation of your judging programs is not required.
Master judge "Score is % of correctly solved sets" gives a score proportional to the number of correctly solved test cases. For a problem with five test cases, a user's submission that correctly solves three test cases will receive a final result of 60, which should be interpreted as 60% (3 out of 5 = 60%).
How is the score of a submission to a programming problem determined in the Containers module?
The score is determined during the
test stage of the project's scenario. While it can be set arbitrarily, there
are some common and useful approaches.
For example, in projects where correctness verification is based on the results of a unit testing procedure, a reasonable score is the percentage of passed unit tests. Alternatively, when the difficulty of unit tests varies, one can apply a modified approach by assigning weights to each unit test.
How long are the submissions and execution results stored on the Sphere Engine servers?
All data related to submissions (such as source code and data streams) in the Compilers and Problems modules is stored on Sphere Engine servers for one month. If you require data storage for a longer duration, please don't hesitate to contact us.
For the Containers module, the availability of data varies based on the stream:
- data is stored for 30 days for the following:
- source code,
- stage streams (stage output and error stream),
- debug log
- test report,
- workspace initialization data (output and error streams),
- custom files, also known as "auxiliary data streams", for API submissions,
- custom files ("auxiliary data streams") for webhooks from Workspace actions are stored for 24 hours.